@sema-agent/core 5.21.1 → 5.23.0

package/dist/core/memory-engine/layout.d.ts

@@ -273,6 +273,238 @@ export declare function recordRetrievedAccount(controlDir: string, ids: readonly
 export declare function readRetrievedAccount(controlDir: string): Record<string, RetrievedAccountRow>;
 /** S2-C — clear the fuse for files harvest just ACCEPTED (a committed write resets the strike count). */
 export declare function clearScanFuse(controlDir: string, keys: Iterable<string>): void;
+/** The write-ahead harvest lineage ledger (control plane, fail-closed). */
+export declare const LINEAGE_FILE = "lineage.json";
+/** The challenge generation-event ledger (control plane, fail-closed). */
+export declare const CHALLENGES_FILE = "challenges.json";
+/** Per-commit lineage AUDIT history (bookkeeping, fail-open, bounded rotation) — the load-bearing
+ *  queries never read it; it exists so the deduped contribution set is not the only trace. */
+export declare const LINEAGE_AUDIT_FILE = "lineage-audit.json";
+/** Bound on retained audit rows (oldest rotated out first). */
+export declare const LINEAGE_AUDIT_MAX_ROWS = 2048;
+/** The challenged-history account (design/180 B-3: collect-only, fail-open bookkeeping —
+ *  the mechanical shadow of "user saw a retrieved entry and corrected it in the same session"). */
+export declare const CHALLENGED_HISTORY_FILE = "usage-challenged-history.json";
+/** One committed contribution: session → entry, latest rev/at only (the load-bearing invariant is
+ *  "which sessions contributed this id", not the per-commit history — that is the audit account). */
+export interface LineageContribution {
+    lastRev: string;
+    lastAt: number;
+}
+/** One staged (pre-commit) row: an entry this transaction WOULD commit. */
+export interface LineagePendingRow {
+    entryId: string;
+    rev: string;
+}
+/** One staged transaction: rows land BEFORE `applyPatches`; the commit credential lands after it
+ *  succeeds; promotion consumes both. A pending txn without a credential is the crash window —
+ *  it is NEVER auto-discarded (design/180 r5: the applyPatches-success→credential-write gap is
+ *  undecidable on the pinned backend contract; the host adjudicates via the explicit API). */
+export interface LineagePendingTxn {
+    sessionId: string;
+    at: number;
+    rows: LineagePendingRow[];
+    /** Present ⇔ `applyPatches` returned and its applied set was durably recorded. */
+    credential?: {
+        appliedIds: string[];
+        at: number;
+    };
+}
+/** Stage this transaction's would-commit rows BEFORE `applyPatches` (write-ahead). Throws on any
+ *  write/lock/corruption failure — the caller refuses the whole harvest (fail-closed). */
+export declare function stageLineagePending(controlDir: string, txnId: string, sessionId: string, rows: readonly LineagePendingRow[], now: () => number): void;
+/** Discard a staged transaction that never reached `applyPatches` (the pre-commit abort path —
+ *  step ③ of the handshake, or a refused commit). Safe by construction: nothing was committed. */
+export declare function discardLineagePending(controlDir: string, txnId: string): void;
+/** Record the commit credential — `applyPatches` returned, these ids were APPLIED (non-delete ops).
+ *  Written before promotion so a crash between the two converges by credential, never by reading
+ *  the backend's current state back (design/180 r4: later syncs/updates rewrite that scene). */
+export declare function recordLineageCredential(controlDir: string, txnId: string, appliedIds: readonly string[], now: () => number): void;
+/** What one promotion moved into the committed set. */
+export interface LineagePromotion {
+    entryId: string;
+    sessionId: string;
+    rev: string;
+}
+/** Promote a CREDENTIALED pending transaction: rows named by the credential's applied set join the
+ *  committed contribution set (deduped by (entryId, sessionId) — a repeat pair refreshes
+ *  lastRev/lastAt, never grows the set); rows NOT in the applied set (conflicted/refused ops) are
+ *  dropped without ever becoming ancestry. Throws when the txn is unknown or uncredentialed. */
+export declare function promoteLineagePending(controlDir: string, txnId: string, now: () => number): LineagePromotion[];
+/** The host adjudication for the UNDECIDABLE crash window (a pending txn with no credential —
+ *  design/180 r5: never auto-discarded). `"promote"` = the host verified the commit landed (all
+ *  staged rows join the committed set); `"discard"` = the host verified it did not. Idempotent on
+ *  an unknown txn. Also accepts a credentialed txn (then `"promote"` follows the credential). */
+export declare function adjudicateLineagePending(controlDir: string, txnId: string, action: "promote" | "discard", now: () => number): LineagePromotion[];
+/** Reconciliation (harvest-opening / host-triggered): promote every CREDENTIALED orphan pending
+ *  txn; report the uncredentialed ones (their latch stays until the host adjudicates). */
+export declare function reconcileLineage(controlDir: string, now: () => number): {
+    promoted: LineagePromotion[];
+    undecidable: Array<{
+        txnId: string;
+        sessionId: string;
+        entryIds: string[];
+    }>;
+};
+/** The DIRTY-LATCH set: every entry id named by ANY pending row (credentialed or not). While an id
+ *  is latched, its model-visible read faces (index mechanical rows / memory_search / memory_get)
+ *  refuse — "the account is not settled, the content does not go on the table". Throws on a
+ *  corrupt ledger (integrity unknown ≠ no latch). */
+export declare function lineageLatchedIds(controlDir: string): Set<string>;
+/** Every committed contribution of `sessionId` (the pollution-retroaction sweep input). Throws on
+ *  a corrupt ledger. */
+export declare function lineageContributionsOfSession(controlDir: string, sessionId: string): Array<{
+    entryId: string;
+    lastRev: string;
+}>;
+/** Drop an entry's lineage rows once the entry is DELETED (an applied tombstone) — space hygiene
+ *  only, taken at the harvest that saw the applied delete (design/180 §10). */
+export declare function clearLineageForEntries(controlDir: string, entryIds: readonly string[]): void;
+/** Full-ledger read (tests / host observability). Throws on corruption. */
+export declare function readLineageRecord(controlDir: string): {
+    committed: Record<string, Record<string, LineageContribution>>;
+    pending: Record<string, LineagePendingTxn>;
+};
+/** Fail-open per-commit AUDIT history (bounded rotation) — never consulted by the load-bearing
+ *  queries; a broken audit account degrades silently, exactly like the retrieved account. */
+export declare function appendLineageAudit(controlDir: string, rows: ReadonlyArray<{
+    entryId: string;
+    sessionId: string;
+    rev: string;
+    at: number;
+}>): void;
+/** One challenge/resolve event. Append-only; the exclusion predicate is DERIVED ("any unresolved
+ *  challenge generation exists"), never stored as a mutable flag. */
+export interface ChallengeEvent {
+    /** Stable identity for idempotent replay: the automatic arm derives it from the pollution event
+     *  anchor (`pollution:<sessionId>:<markedAt>:<entryId>`); the host arm derives it from the
+     *  caller's requestId (`<requestId>:<entryId>`). Same eventId replayed = same generation (a lost
+     *  ack retried never opens a second generation); a DIFFERENT eventId with the same reason is a
+     *  genuinely new event and opens a new generation (no immunity hole). */
+    eventId: string;
+    entryId: string;
+    kind: "challenge" | "resolve";
+    /** The generation this event opened (challenge) or closed (resolve). */
+    generation: number;
+    at: number;
+    reason: string;
+    /** Evidence grade — v2 mints only "S" (structural) events. */
+    grade?: "S";
+    /** Audit record only (the exclusion predicate keys the entry ID, never the rev). */
+    challengedRev?: string;
+}
+/** One challenge assignment {@link appendChallengeEvents} returns. `replayed` = the eventId already
+ *  existed (idempotent retry — the ORIGINAL generation is returned, no new one opens). */
+export interface ChallengeAssignment {
+    entryId: string;
+    eventId: string;
+    generation: number;
+    at: number;
+    replayed: boolean;
+}
+/**
+ * design/180 §10 — the challenge ledger's SIZE CALIBRATION.
+ *
+ * The ledger is append-only and cannot be rotated: the exclusion predicate is DERIVED from the events
+ * ("a challenge generation with no matching resolve"), so dropping the oldest rows would silently
+ * un-withhold their entries — taint laundering, the exact failure the fail-closed family exists to
+ * prevent. The bound is therefore a DISCLOSURE threshold, not a cap: crossing it changes nothing about
+ * what the ledger holds, it tells the deployment the account needs attention.
+ *
+ * Calibrated against what actually degrades, which is not disk: every append REWRITES the whole file
+ * under the strict lock, and every model-visible read path ({@link challengedEntryIds}, called on each
+ * index rebuild and each memory tool call) PARSES it whole. At ~200 bytes per event, 10k events is a
+ * ~2 MB parse on a read path that runs per tool call — the point where "an audit account nobody looks
+ * at" becomes a latency the session feels. A deployment reaching it should resolve the settled
+ * generations (they stay in the file, and that is the point) or archive the account deliberately.
+ */
+export declare const CHALLENGE_LEDGER_MAX_EVENTS = 10000;
+/** What {@link appendChallengeEvents} returns: the per-request assignments plus the ledger's size
+ *  AFTER the append — the caller owns disclosure (this module has no sink), and reading the size here
+ *  costs nothing because the record is already in hand under the lock. */
+export interface ChallengeAppendResult {
+    assignments: ChallengeAssignment[];
+    /** Total events in the ledger after this append, or `undefined` when nothing was appended — the
+     *  empty-request fast path takes no lock and reads nothing, so it has no size to report and must not
+     *  report a made-up `0` (a caller comparing that against the bound would read "tiny", not "unknown"). */
+    eventCount: number | undefined;
+}
+/** Append S-grade challenge events (idempotent per eventId, generation allocation inside the strict
+ *  lock). Every NEW eventId opens a NEW generation for its entry — a resolve of an earlier
+ *  generation never immunizes the entry against later pollution (design/180 R-8). */
+export declare function appendChallengeEvents(controlDir: string, events: ReadonlyArray<{
+    eventId: string;
+    entryId: string;
+    reason: string;
+    challengedRev?: string;
+}>, now: () => number): ChallengeAppendResult;
+/** The trusted resolve: closes EXACTLY the named generation (a later challenge's generation stays
+ *  open — resolves never blanket-clear). Idempotent: resolving an already-resolved generation is a
+ *  no-op. `resolved` is false ⇔ no such open generation existed.
+ *
+ *  `eventCount` rides along for the same reason it does on {@link appendChallengeEvents}: a resolve
+ *  APPENDS an event too, so it crosses the size bound exactly as a challenge does (independent
+ *  adversarial review, verified — hanging the disclosure off the challenge writer alone leaves a ledger
+ *  that crossed the bound on a resolve silent until the next challenge, which may never come).
+ *  `undefined` when nothing was appended. */
+export declare function resolveChallengeEvent(controlDir: string, entryId: string, generation: number, reason: string, now: () => number, requestId?: string): {
+    resolved: boolean;
+    eventCount: number | undefined;
+};
+/** The exclusion predicate's input: entry id → its LATEST unresolved challenge generation. An entry
+ *  appears iff at least one challenge generation has no matching resolve. Throws on corruption —
+ *  consumers refuse service (integrity unknown ≠ clean). */
+export declare function challengedEntryIds(controlDir: string): Map<string, {
+    generation: number;
+    at: number;
+}>;
+/** Full event read (host audit / tests). Throws on corruption. */
+export declare function readChallengeEvents(controlDir: string): ChallengeEvent[];
+/** Which fail-closed control-plane ledger a rebuild targets. */
+export type StrictControlPlaneLedger = "lineage" | "challenges";
+/** What one rebuild did — the deployment's record of a taint-bearing account it chose to reset. */
+export interface ControlPlaneRebuildReceipt {
+    ledger: StrictControlPlaneLedger;
+    /** The corrupt file (and its journal, when one existed) moved aside — never deleted. */
+    quarantinedTo: string[];
+    at: number;
+}
+/**
+ * design/180 §10 — rebuild a CORRUPT fail-closed ledger, explicitly.
+ *
+ * The fail-closed family refuses service on corruption precisely because a silent "start fresh" would
+ * LAUNDER taint (a challenged entry re-enters the prompt; a polluted session's contributions become
+ * untraceable). That refusal is permanent by design — which left a deployment whose disk really did
+ * corrupt with no way back other than deleting engine files by hand. This is that way back, and its
+ * whole shape is "never automatic":
+ *  · the caller names the ledger — nothing in the engine calls this on its own;
+ *  · a HEALTHY ledger is REFUSED (`memory.control_plane_not_corrupt`) — a rebuild is only ever the
+ *    answer to a corruption that is already blocking every read, never a way to clear an account;
+ *  · the corrupt bytes are QUARANTINED beside the file, never deleted: what the ledger held is
+ *    exactly the evidence someone will want after a laundering decision;
+ *  · the caller (the engine's host API) announces the rebuild — a reset of this account changes what
+ *    the model may see, so it is not a silent repair.
+ */
+/** Lock-less probe: does this fail-closed ledger currently REFUSE reads? The rebuild's own check runs
+ *  again under the lock (this one is for a caller that must decide something — announce, refuse — before
+ *  taking the lock). `false` for a ledger that reads cleanly, including an absent one (genuinely empty). */
+export declare function isStrictControlPlaneLedgerCorrupt(controlDir: string, ledger: StrictControlPlaneLedger): boolean;
+export declare function rebuildStrictControlPlaneLedger(controlDir: string, ledger: StrictControlPlaneLedger, now: () => number): ControlPlaneRebuildReceipt;
+/** One challenged-history row: how often a retrieved-then-corrected event hit this entry. */
+export interface ChallengedHistoryRow {
+    count: number;
+    lastAt: number;
+    lastOp: "update" | "tombstone";
+}
+/** Record mechanical correction shadows (same-session retrieved → update/tombstone committed).
+ *  Collect-only by contract: NOTHING in the engine reads this back into any decision (v3 candidate
+ *  evidence only — design/178 ③-1 三级账 discipline). Throws propagate; callers treat fail-open. */
+export declare function recordChallengedHistory(controlDir: string, rows: ReadonlyArray<{
+    entryId: string;
+    op: "update" | "tombstone";
+}>, now: () => number): void;
+/** Journal-aware read (observability/tests only — no engine consumer exists, on purpose). */
+export declare function readChallengedHistory(controlDir: string): Record<string, ChallengedHistoryRow>;
 /**
  * REF-C6 — write EVERY byte of `data` to `fd`, looping until the OS has taken all of them.
  *