feat(memory): harden the memory-integrity invariant under concurrency + adversarial edits

Bulletproof OpenLore's one defensible promise — never serve an unverified or
stale fact as authoritative — across durability, concurrency, and freshness.

Invariant (tests):
- Name and property-test the AuthoritativeRecallInvariant over recall + orient:
  no drifted/orphaned memory ever sits in an authoritative set unlabeled
  (memory-invariant.test.ts, generated memories × generated code mutations).
- Adversarial freshness suite (anchor-adversarial.test.ts): rename/move/delete
  → orphaned; whitespace/comment-only edits → drifted; multibyte UTF-8 span
  boundaries hash byte-correctly; truncated-hash collision-freedom property.
  Governing rule: a false-fresh fails the suite; a false-orphaned is acceptable.

Durability (atomic-store.ts):
- Atomic temp-write + fsync + rename for notes.json and pending.json — a crash
  mid-write leaves the prior committed store intact, never a torn file.
- Monotonic `sequence` field (additive, defaults 0) + compare-and-swap on save:
  on conflict, re-read and re-apply the id-keyed merge instead of clobbering.
  remember and record_decision now lose zero writes under concurrency.
- Corrupt-store quarantine: a store that fails validation is moved to
  *.corrupt-<n> (deterministic suffix, not wall-clock) and signaled, never
  silently substituted with empty.

Gate (gate-state.ts):
- Extract the pre-commit gate reason machine into a pure classifier and
  property-test it: total (every state → one reason), deterministic/idempotent,
  deadlock-free. decisions.ts delegates to it (behavior-preserving).

Specs: AuthoritativeRecallInvariant / FreshnessFailsSafeTowardDistrust /
ConcurrentMemoryWriteSafety added to mcp-handlers; DurableAtomicStorePersistence /
CorruptStoreQuarantineNotSilentEmpty added to architecture; linked from CODEBASE.md.

No new dependency, no LLM, schema extended additively. Full suite: 3732 passing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: clay-good

openspec/specs/architecture/spec.md

@@ -38,6 +38,44 @@ The system SHALL implement security via: API key-based authentication for LLM pr
 - **WHEN** accessing protected resources
 - **THEN** access is denied
 
+### Requirement: DurableAtomicStorePersistence
+
+The persisted memory and decision stores (`.openlore/memory/notes.json`,
+`.openlore/decisions/pending.json`) SHALL be written atomically: a write goes to a temporary
+file and is moved into place with an atomic rename (after `fsync`), so a crash or
+interruption mid-write leaves the previously committed store intact and never a partially
+written (torn) file. Each store SHALL carry a monotonic `sequence` field used to order writes
+and detect conflicts; the field defaults to `0` for legacy stores. Saves use compare-and-swap
+on `sequence`: on a conflict the save re-reads the current store and re-applies the pending
+append/upsert rather than overwriting a competing write. Implemented in
+`src/core/decisions/atomic-store.ts`; guarded by `atomic-store.test.ts`.
+
+#### Scenario: A crash mid-write preserves the prior store
+- **GIVEN** a store write interrupted between writing the temporary file and the rename
+- **WHEN** the store is next loaded
+- **THEN** the previously committed store is returned intact, with no torn or partial content
+
+#### Scenario: Save uses compare-and-swap on sequence
+- **GIVEN** a store loaded at sequence S
+- **WHEN** a save is attempted but the on-disk sequence is no longer S
+- **THEN** the save re-reads the current store, re-applies the pending change, and writes at
+  the new sequence instead of overwriting
+
+### Requirement: CorruptStoreQuarantineNotSilentEmpty
+
+When a persisted store fails validation on load, the system SHALL move the unreadable file
+aside to a quarantine path (`*.corrupt-<n>`) and emit a recoverable signal. The system SHALL
+NOT silently substitute an empty store for a corrupt one, because silently losing persisted
+memory presents absence as current fact and violates the authoritative-recall invariant. The
+quarantine suffix SHALL be derived from on-disk state (the next free index), not wall-clock
+time, to keep recovery reproducible.
+
+#### Scenario: A malformed store is quarantined, not silently emptied
+- **GIVEN** a store file that fails schema or JSON validation
+- **WHEN** the store is loaded
+- **THEN** the file is moved to `*.corrupt-<n>` and a recoverable signal is emitted, rather
+  than an empty store being returned silently
+
 ## System Diagram
 
 ```mermaid

openspec/specs/mcp-handlers/spec.md

@@ -116,6 +116,72 @@ The system SHALL The recall tool SHALL partition returned memories into authorit
 
 > Decision recorded: dbe6a95e
 > Date: 2026-06-16
+
+### Requirement: AuthoritativeRecallInvariant
+
+The system SHALL guarantee, as a single named and test-enforced invariant, that **no
+memory whose freshness verdict is `drifted` or `orphaned` ever appears in an authoritative
+recall path unlabeled**. The authoritative recall paths are the `recall` tool and the
+memory (decision) section of `orient`. An `orphaned` memory SHALL be fully withheld from
+the authoritative set (surfaced only under `needsReanchoring` / `staleDecisions`); a
+`drifted` memory MAY remain in the authoritative set only when it carries an explicit
+`verify` label. This invariant is the operational definition of the project promise:
+*OpenLore never serves an unverified or stale fact as authoritative.* It SHALL be enforced
+by a property-based test (`memory-invariant.test.ts`) that generates arbitrary memories and
+arbitrary code mutations and asserts the property holds for every generated case.
+
+#### Scenario: A drifted memory is excluded from the authoritative set unlabeled
+
+- **GIVEN** a memory whose anchor verdict is `drifted`
+- **WHEN** `recall` or `orient` produces its response
+- **THEN** the memory does not appear in the authoritative set unlabeled; it is withheld or
+  carries an explicit verify/non-authoritative label
+
+#### Scenario: The invariant holds under generated mutation
+
+- **GIVEN** an arbitrary memory and an arbitrary mutation to the code it anchors
+- **WHEN** the authoritative recall path is computed
+- **THEN** the authoritative set contains only `fresh` memories and explicitly-labeled
+  `drifted` ones, never an `orphaned` memory
+
+### Requirement: FreshnessFailsSafeTowardDistrust
+
+The freshness computation (`anchorFreshness`, `hashSpan`) SHALL fail safe toward distrust:
+any ambiguity, hash collision, or boundary error SHALL bias the verdict toward `drifted` or
+`orphaned`, never toward a false `fresh`. A renamed, moved, or deleted symbol SHALL yield
+`orphaned` (or `drifted` only when a confident relocation is established). `hashSpan` SHALL
+slice spans by byte offset so multibyte UTF-8 boundaries hash correctly. A test that
+produces a false `fresh` SHALL be treated as a correctness failure; a false `orphaned` is
+acceptable. This is guarded by the adversarial suite (`anchor-adversarial.test.ts`).
+
+#### Scenario: A forced collision does not produce false fresh
+
+- **GIVEN** two distinct source spans
+- **WHEN** freshness is computed for a memory anchored to one after the other replaces it
+- **THEN** the verdict is `drifted` or `orphaned`, never `fresh` (distinct spans do not
+  collide on the truncated content hash; a collision would fail the suite loudly)
+
+#### Scenario: A multibyte span boundary hashes correctly
+
+- **GIVEN** an anchored span whose start or end falls on a multibyte UTF-8 boundary
+- **WHEN** `hashSpan` computes the content hash before and after an unrelated edit elsewhere
+- **THEN** the hash is byte-correct and stable, producing `fresh` only when the span bytes
+  are unchanged
+
+### Requirement: ConcurrentMemoryWriteSafety
+
+The `remember` and `record_decision` tools SHALL be safe under concurrent invocation: two
+concurrent writes to the same store SHALL NOT cause either write to be lost. On a write
+conflict the system SHALL re-read the current store and re-apply the pending
+append/upsert (compare-and-swap on a monotonic `sequence`), rather than overwrite the
+competing write.
+
+#### Scenario: Concurrent remember calls lose no write
+
+- **GIVEN** N concurrent `remember` calls against the same memory store
+- **WHEN** all calls complete
+- **THEN** the persisted store contains all N memories
+
 ### Requirement: DecisionsCarryStructuralAnchorsForSelfinvalidation
 
 The system SHALL resolve structural anchors against the call graph when recording a decision, falling back to file-level anchors when no analysis is available.

src/cli/commands/decisions.ts

@@ -29,6 +29,7 @@ import {
   INACTIVE_STATUSES,
 } from '../../core/decisions/store.js';
 import { consolidateDrafts } from '../../core/decisions/consolidator.js';
+import { classifyGateState } from '../../core/decisions/gate-state.js';
 import { acquireDecisionsLock } from '../../core/decisions/lock.js';
 import { extractFromDiff } from '../../core/decisions/extractor.js';
 import { verifyDecisions } from '../../core/decisions/verifier.js';
@@ -769,9 +770,49 @@ Examples:
 
     // ── Gate only (no consolidation — consolidation happens on record_decision) ──
     if (options.gate && !options.consolidate) {
-      // Block if approved decisions haven't been synced to spec files yet.
       const approved = getDecisionsByStatus(store, 'approved');
-      if (approved.length > 0) {
+      const verified = getDecisionsByStatus(store, 'verified');
+      const drafts = getDecisionsByStatus(store, 'draft');
+      const missing: Array<{ file: string; description: string }> = [];
+
+      // Phantom decisions ("recorded but no code evidence") are excluded — stale
+      // phantoms from previous sessions would otherwise silently bypass the gate.
+      const activeCount = store.decisions.filter((d) => !INACTIVE_STATUSES.has(d.status)).length;
+      const consolidatedRecently = !!store.lastConsolidatedAt
+        && (Date.now() - new Date(store.lastConsolidatedAt).getTime()) < CONSOLIDATION_GRACE_PERIOD_MS;
+
+      // The staged-source check is the only input requiring git; resolve it lazily,
+      // only in the state where it can change the outcome (nothing else gates).
+      let isGitRepo = false;
+      let hasStagedSourceChanges = false;
+      if (approved.length === 0 && verified.length === 0 && drafts.length === 0
+          && !consolidatedRecently && activeCount === 0) {
+        isGitRepo = await isGitRepository(rootPath);
+        if (isGitRepo) {
+          try {
+            const { stdout } = await execFileAsync(
+              'git', ['diff', '--cached', '--name-only', '--diff-filter=ACDMR'],
+              { cwd: rootPath },
+            );
+            const stagedFiles = stdout.trim().split('\n').filter(Boolean);
+            const SOURCE_EXTS = /\.(ts|js|tsx|jsx|py|go|rs|rb|java|cpp|cc|swift)$/;
+            hasStagedSourceChanges = stagedFiles.some((f) => SOURCE_EXTS.test(f));
+          } catch { /* git unavailable — skip */ }
+        }
+      }
+
+      // The pure reason machine is the single arbiter of which reason applies.
+      const outcome = classifyGateState({
+        approvedCount: approved.length,
+        verifiedCount: verified.length,
+        draftCount: drafts.length,
+        consolidatedRecently,
+        activeCount,
+        isGitRepo,
+        hasStagedSourceChanges,
+      });
+
+      if (outcome.reason === GATE_REASONS.APPROVED_NOT_SYNCED) {
         const payload = {
           gated: true,
           reason: GATE_REASONS.APPROVED_NOT_SYNCED,
@@ -784,74 +825,48 @@ Examples:
         return;
       }
 
-      const verified = getDecisionsByStatus(store, 'verified');
-      const missing: Array<{ file: string; description: string }> = [];
-
-      if (verified.length === 0) {
-        const drafts = getDecisionsByStatus(store, 'draft');
-        if (drafts.length > 0) {
-          // Drafts recorded but consolidation never completed.
-          // Output structured JSON so the agent can relay to the user and act on the answer.
-          const payload = {
-            gated: true,
-            reason: GATE_REASONS.DRAFTS_PENDING_CONSOLIDATION,
-            message: `${drafts.length} draft decision(s) were recorded but never consolidated.`,
-            drafts: drafts.map((d) => ({ id: d.id, title: d.title, recordedAt: d.recordedAt })),
-            actions: {
-              consolidate: 'openlore decisions --consolidate',
-              consolidateAndGate: 'openlore decisions --consolidate --gate',
-              skip: 'git commit --no-verify',
-            },
-          };
-          process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-          process.exitCode = 1;
-          return;
-        }
+      if (outcome.reason === GATE_REASONS.DRAFTS_PENDING_CONSOLIDATION) {
+        // Drafts recorded but consolidation never completed.
+        // Output structured JSON so the agent can relay to the user and act on the answer.
+        const payload = {
+          gated: true,
+          reason: GATE_REASONS.DRAFTS_PENDING_CONSOLIDATION,
+          message: `${drafts.length} draft decision(s) were recorded but never consolidated.`,
+          drafts: drafts.map((d) => ({ id: d.id, title: d.title, recordedAt: d.recordedAt })),
+          actions: {
+            consolidate: 'openlore decisions --consolidate',
+            consolidateAndGate: 'openlore decisions --consolidate --gate',
+            skip: 'git commit --no-verify',
+          },
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+        process.exitCode = 1;
+        return;
+      }
 
-        // If consolidation already ran recently, trust it found nothing — skip the warning.
-        const consolidatedRecently = store.lastConsolidatedAt
-          && (Date.now() - new Date(store.lastConsolidatedAt).getTime()) < CONSOLIDATION_GRACE_PERIOD_MS;
-        if (consolidatedRecently) {
-          process.exitCode = 0;
-          return;
-        }
+      if (outcome.reason === GATE_REASONS.NO_DECISIONS_RECORDED) {
+        // Source files staged but nothing recorded — output JSON for agent to relay.
+        const payload = {
+          gated: true,
+          reason: GATE_REASONS.NO_DECISIONS_RECORDED,
+          message: 'Source files are staged but no architectural decisions were recorded.',
+          actions: {
+            consolidateAndGate: 'openlore decisions --consolidate --gate',
+            skip: 'git commit --no-verify',
+          },
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+        process.exitCode = 1;
+        return;
+      }
 
-        // If source files are staged but nothing was recorded, offer to run the fallback extractor.
-        // Phantom decisions ("recorded but no code evidence") are excluded — stale phantoms from
-        // previous sessions would otherwise silently bypass the gate for all future commits.
-        const activeDecisions = store.decisions.filter(
-          (d) => !INACTIVE_STATUSES.has(d.status),
-        );
-        if (activeDecisions.length === 0 && await isGitRepository(rootPath)) {
-          try {
-            const { stdout } = await execFileAsync(
-              'git', ['diff', '--cached', '--name-only', '--diff-filter=ACDMR'],
-              { cwd: rootPath },
-            );
-            const stagedFiles = stdout.trim().split('\n').filter(Boolean);
-            const SOURCE_EXTS = /\.(ts|js|tsx|jsx|py|go|rs|rb|java|cpp|cc|swift)$/;
-            const hasSourceChanges = stagedFiles.some((f) => SOURCE_EXTS.test(f));
-            if (hasSourceChanges) {
-              // Source files staged but nothing recorded — output JSON for agent to relay.
-              const payload = {
-                gated: true,
-                reason: GATE_REASONS.NO_DECISIONS_RECORDED,
-                message: 'Source files are staged but no architectural decisions were recorded.',
-                actions: {
-                  consolidateAndGate: 'openlore decisions --consolidate --gate',
-                  skip: 'git commit --no-verify',
-                },
-              };
-              process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-              process.exitCode = 1;
-              return;
-            }
-          } catch { /* git unavailable — skip */ }
-        }
+      if (!outcome.gated) {
+        // Clean commit — nothing to review.
         process.exitCode = 0;
         return;
       }
 
+      // outcome.reason === GATE_REASONS.VERIFIED — verified decisions await review.
       // TTY: interactive TUI
       if (process.stdin.isTTY && process.stdout.isTTY && verified.length > 0) {
         const results = await runTuiApproval(verified);