@sema-agent/core 5.39.0 → 5.41.0

package/dist/core/memory-engine/file-backend.d.ts

@@ -1,4 +1,5 @@
-import { scopeDirName, type MemoryPartitionIncidentSink } from "./layout.js";
+import { scopeDirName, type ChallengeEvent, type MemoryPartitionIncidentSink } from "./layout.js";
+import type { MemoryBundleImportPlan, MemoryImportReport } from "./export-bundle.js";
 import type { HarvestRejection, MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "./types.js";
 /** Files/dirs the entry scan never treats as entries: the derived index, dotfiles (`.hydrate`,
  *  transaction staging files), and anything not `.md`. */
@@ -288,6 +289,55 @@ export interface EntryCustodyReport {
     events: TransferEvidence[];
     reason?: string;
 }
+/**
+ * design/178 v2-c §3 — what the ONE-LOCK export composite ({@link FileMemoryEngineBackend.exportSnapshotOf})
+ * answers: every face of the store the bundle needs, read inside a single txn-mutex hold (see the
+ * method doc for the fence law). Entries carry committed content only; a bound row whose committed
+ * carrier cannot be served is enumerated under `contentUnavailable` instead (never silently
+ * dropped, never dressed as content). `unbound`/`pendingLatch` are STORE-LEVEL residual sets (no
+ * tenant to belong to); the bundle assembly decides whether their id lists travel (full-store
+ * export) or only their counts (subset export). `challenges`/`lineage`/`pollutedSessions` are the
+ * RAW governance faces — the (pure) bundle assembly slices them to the exported entry/session
+ * sets; `custody` is already sliced (the slicing consumes row-level scope fields this module owns).
+ */
+export interface MemoryExportSnapshot {
+    storeId: string;
+    /** True ⇔ the requested scopes cover every registered scope (one trust domain — the residual id
+     *  lists and unbound-deletion custody rows may travel). */
+    fullStore: boolean;
+    entries: MemoryEntry[];
+    contentUnavailable: Array<{
+        id: string;
+        scope: string;
+        slug: string;
+        rev: string;
+        reason: string;
+    }>;
+    unbound: string[];
+    pendingLatch: string[];
+    custody: TransferEvidence[];
+    unsliceableCustody: number;
+    challenges: ChallengeEvent[];
+    lineage: Array<{
+        entryId: string;
+        sessionId: string;
+        lastRev: string;
+        lastAt: number;
+    }>;
+    pollutedSessions: Array<{
+        sessionId: string;
+        at: number;
+        reason: string;
+    }>;
+    quarantined: string[];
+    quarantineOpaque: number;
+}
+/** Test hook (证伪式复审 L3): small constants so the crash-window leg does not really wait 15-30s. */
+interface TxnLockTimings {
+    staleMs?: number;
+    waitMs?: number;
+    stealGraceMs?: number;
+}
 /** Construction options for {@link FileMemoryEngineBackend}. */
 export interface FileMemoryEngineBackendOptions {
     /** ⚠️ 分家坑(service 报告 2026-07-09):不显式传时,控制平面按无参 `resolveMemoryEngineRoot()`
@@ -369,6 +419,10 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private adoptionNoticeKeys;
     /** Test seam (§7.4 r4-④ arm): force a post-commit-point transfer-append failure. */
     private transfersAppendFault?;
+    /** Test seam (v2-c §3-2 fence pins): runs INSIDE the export composite's mutex hold, after the
+     *  data reads and before the second fingerprint — a test injects a governance-face write here to
+     *  exercise the drift-retry and the three-round refusal. Production leaves it unset. */
+    private exportFaceProbe?;
     /** v2-b §3-4 — the resurrection backstop's chain digest, keyed by the evidence log's stat
      *  fingerprint (size + mtimeMs — append-only growth and a torn-tail shrink both move `size`).
      *  NEVER a mount-lifetime cache: the fingerprint is re-verified under the txn mutex on every
@@ -972,6 +1026,129 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** The pure open-form evidence read behind {@link custodyOf} (no healing, no writes). `raw` is
      *  the caller's already-fenced read of the log (undefined = absent). */
     private custodyReadPure;
+    /** design/178 v2-c §4 — the export/import refusal code (engine coded-error family, deliberately
+     *  outside the governance registry: a store-state refusal, not a per-principal verdict). */
+    private static readonly EXPORT_INCOMPLETE;
+    /** The durable store identity (§6.2): read it, or mint it (`wx`) on first need — the txn mutex is
+     *  held by every caller, so the exclusive create cannot race in-process; a cross-process EEXIST
+     *  loser adopts the winner's identity. Corrupt/unreadable identity is fail-closed. */
+    private storeIdentityLocked;
+    /** One consistency fingerprint over the three ENGINE governance faces (challenge ledger, lineage
+     *  ledger, pollution markers) — raw bytes, journal included. The two strict sidecars' JOURNAL
+     *  reads are wrapped FAIL-CLOSED here (§4-6): the shared strict reader folds a journal read
+     *  error into absence, and an export that read a stale main file over an unreadable journal
+     *  would seal stale governance under an honest hash. Marker files that exist but cannot be read
+     *  fingerprint their error code (a stable fault stays stable; a flapping one drifts the fence). */
+    private exportGovernanceFingerprint;
+    /**
+     * The export chain read: PURE INSPECTION (never heals, never quarantines, never truncates — C-8
+     * pins the file byte-identical across a refused export). A torn tail refuses the export
+     * (`memory.export_incomplete`; the deployment heals it by running any locked mutation entry,
+     * then re-exports); an unknown channel refuses too (T-14: a row whose slicing rules this build
+     * does not know can neither be carried — possible cross-tenant leak — nor silently dropped —
+     * lost mandatory governance); one ev under two different payloads refuses (spliced chain);
+     * non-tail corruption stays the fail-closed {@link ControlPlaneCorruptError}. Byte-equal
+     * duplicates collapse (append-idempotency residue).
+     */
+    private readExportChainRowsPure;
+    /**
+     * v2-c §2 — the tenant-slicing table over validated chain rows (T-6..T-11; T-9/T-10 refusals,
+     * T-14 already refused by the reader). `storeId` is a thunk so the identity mints only when a
+     * redaction actually needs the provenance stamp.
+     */
+    private sliceCustodyForScopes;
+    /** T-12 — quarantine residual enumeration for an id set (names for attributable hits, an opaque
+     *  count for the rest — same honest bound the erasure attestation uses). */
+    private enumerateQuarantineFor;
+    /**
+     * design/178 v2-c §3 — the ONE-LOCK export composite (capability face; probe with
+     * `typeof backend.exportSnapshotOf === "function"`). All five reads — entries (ledger-driven,
+     * committed content), custody chain, challenge ledger, lineage ledger, pollution markers — happen
+     * inside a single txn-mutex hold: the two backend faces are writer-serialized by the mutex
+     * itself; the three engine faces (written under their own sidecar locks, not the mutex) are
+     * fenced by a byte-level double fingerprint around the reads (≤3 rounds, then a loud refusal —
+     * a store too hot to snapshot answers `memory.export_incomplete`, never a mixed-epoch bundle).
+     * The terminal ownership assertion turns a stolen lock (stale-steal past the 30s line during a
+     * long assembly) into a refusal: an unstolen lock means no writer entered, which IS the
+     * consistency proof — no lease machinery needed. The chain read is pure inspection (a torn tail
+     * refuses with the file byte-untouched); `complete:false`-class scenes all refuse loudly — there
+     * is no degraded bundle shape, by design (§4).
+     */
+    exportSnapshotOf(scopes: readonly string[], timings?: TxnLockTimings): Promise<MemoryExportSnapshot>;
+    /**
+     * design/178 v2 §4.3 — the single-item governance slice face (parent-design form, kept for
+     * NON-export consumers: erasure resolution, per-id inspection tooling). Answers
+     * `complete: false` + reason instead of a bundle-shaped refusal (its callers fail closed on the
+     * flag); definite corruption still throws. The export path deliberately does NOT use this face —
+     * two independently-locked single faces are exactly the cross-face tear the composite closes.
+     */
+    governanceExport(scopes: readonly string[], timings?: TxnLockTimings): Promise<{
+        custody: TransferEvidence[];
+        unbound: string[];
+        complete: boolean;
+        unsliceableCustody: number;
+        reason?: string;
+    }>;
+    /**
+     * design/178 v2-c §5.4 — custody carriage onto THIS chain (capability face). Rows land under the
+     * import namespace — `ev = imp:<bundleHash>:<source ev>` (full-hash salt: deterministic per
+     * bundle, chain-deterministic across hops — a re-exported imported row salts its CURRENT ev
+     * next hop), `origin` kept when present (multi-hop provenance) else stamped with the source
+     * store's identity, `srcEv` kept else stamped with the source ev — so an imported row is ALWAYS
+     * origin-bearing and the local replay/anchor judgments structurally never read it. Unknown
+     * channels and rows failing this store's own validation are WITHHELD and reported (never
+     * appended verbatim — an unvalidatable row would poison the fail-closed chain — and never a
+     * whole-package refusal — a newer exporter must not brick an older importer). Appends are
+     * idempotent by ev with canonical-payload comparison (same-bundle re-import converges; a
+     * different payload under an existing ev is fail-closed corruption). Direct chain append, no
+     * journal: custody carriage is not a ledger mutation, and origin-bearing rows are forbidden in
+     * journals by the recovery leg's own validation.
+     */
+    custodyImport(rows: ReadonlyArray<Record<string, unknown>>, opts: {
+        bundleHash: string;
+        sourceStoreId: string;
+    }, timings?: TxnLockTimings): Promise<{
+        appended: number;
+        withheld: Array<{
+            srcEv: string;
+            channel: string;
+        }>;
+    }>;
+    /** The in-lock custody carriage body ({@link custodyImport}'s and the import composite's shared
+     *  leg — the composite already holds the mutex and must not re-enter the acquisition). */
+    private custodyImportLocked;
+    /** Append import-namespace challenge events and VERIFY every key-idempotent replay by reading
+     *  the full payload back (§5.2 defense ③): `appendChallengeEvents` is key-idempotent, not
+     *  payload-idempotent — a pre-planted same-key event (a resolve, or a same-entry different-
+     *  reason challenge) would silently swallow the imported challenge while the return echoes a
+     *  plausible assignment. A mismatch ABORTS the import (the latch stays; the account is not
+     *  silently short). */
+    private appendImportChallengesVerified;
+    /**
+     * design/178 v2-c §1 — the IMPORT COMPOSITE (capability face; the engine's `importMemoryBundle`
+     * is its validating membrane). One txn-mutex hold end to end:
+     *  ①b destination-chain completeness precheck (torn/degraded ⇒ whole package refused with ZERO
+     *     side effects — before the latch, "reject before landing" made literal);
+     *  ②  the synthetic latch (durable pending lineage txn over every bundle entry id — from here
+     *     to release, those ids are withheld on every model-visible read face; crash-safe);
+     *  ③  authoritative in-lock judgment (the five import rules — a pre-lock classification would
+     *     only be advisory, so there is none: the lock-held pass IS the classification);
+     *  ④  entry landing through {@link applyPatchesLocked} (same skeleton, same lock, same recovery
+     *     leg — never a second transaction protocol; `guard:"absent"` adjudicates the residual
+     *     same-id arms);
+     *  ⑤  governance legs, custody FIRST unconditionally (chain facts are exempt from the
+     *     entry-eligibility rule — an absent-id delete row is exactly the anti-resurrection
+     *     payload), then entry-attached lineage/challenges for landed ∪ already-present ids only,
+     *     then pollution (retroactive sweep DURABLE BEFORE the marker — the crash between them
+     *     leaves contributions challenged and the marker converging on re-import, never the
+     *     reverse);
+     *  ⑥  the durable completion receipt (`wx`, carrying the report) and the latch release —
+     *     receipt-gated, the ONLY release channel.
+     * Any failure past ② leaves the latch standing: re-importing the SAME bundle converges every
+     * crash window (idempotent latch, idempotent judgments, ev/key-idempotent governance legs,
+     * receipt short-circuit).
+     */
+    importBundleCommit(plan: MemoryBundleImportPlan, timings?: TxnLockTimings): Promise<MemoryImportReport>;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;
     private readCursors;