@sema-agent/core 5.22.0 → 5.24.0

package/dist/core/memory-engine/engine.js

@@ -6,7 +6,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./file-backend.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -173,7 +173,9 @@ export class MemoryEngine {
     challengeAndAnnounce(events) {
         if (events.length === 0)
             return [];
-        const assigned = appendChallengeEvents(this.controlDir, events, this.now);
+        const { assignments: assigned, eventCount } = appendChallengeEvents(this.controlDir, events, this.now);
+        if (eventCount !== undefined)
+            this.discloseChallengeLedgerSize(eventCount);
         const fresh = assigned.filter((a) => !a.replayed);
         if (fresh.length > 0) {
             try {
@@ -189,6 +191,60 @@ export class MemoryEngine {
         }
         return assigned;
     }
+    challengeLedgerSizeDisclosed = false;
+    discloseChallengeLedgerSize(eventCount) {
+        if (this.challengeLedgerSizeDisclosed || eventCount <= CHALLENGE_LEDGER_MAX_EVENTS)
+            return;
+        this.challengeLedgerSizeDisclosed = true;
+        const sink = this.onIncident;
+        if (sink === undefined)
+            return;
+        try {
+            const err = new Error(`memory challenge ledger holds ${eventCount} events, past the calibrated bound of ${CHALLENGE_LEDGER_MAX_EVENTS}: ` +
+                `the whole file is rewritten on every challenge and parsed on every model-visible read (index rebuild, memory tools), ` +
+                `so this account now costs the session latency. It is NOT rotated — dropping events would un-withhold their entries — ` +
+                `so the deployment resolves the settled generations or archives the account deliberately.`);
+            err.code = "memory.challenge_ledger_oversize";
+            sink(err);
+        }
+        catch {
+        }
+    }
+    rebuildCorruptControlPlaneLedger(ledger, reason) {
+        if (typeof reason !== "string" || reason.trim() === "") {
+            const e = new Error("rebuildCorruptControlPlaneLedger: a non-empty reason is required (this call drops taint evidence — it is recorded, never implicit)");
+            e.code = "config.memory_rebuild_reason";
+            throw e;
+        }
+        if (!isStrictControlPlaneLedgerCorrupt(this.controlDir, ledger)) {
+            const e = new Error(`${ledger === "challenges" ? "memory challenge ledger" : "memory lineage ledger"} reads cleanly — refusing to rebuild it. This call exists to recover a ledger whose corruption already refuses every read; resetting a healthy one would drop taint evidence that is still doing its job.`);
+            e.code = "memory.control_plane_not_corrupt";
+            throw e;
+        }
+        enqueueMemoryAnnouncement(this.controlDir, {
+            kind: "gate",
+            at: this.now(),
+            items: [
+                ledger === "challenges"
+                    ? `memory control plane: the challenge ledger was found CORRUPT and a deployment-initiated reset to empty was requested — entries that were withheld by an unresolved challenge may no longer be withheld. Treat facts recalled from memory as unverified until confirmed with the user.`
+                    : `memory control plane: the harvest lineage ledger was found CORRUPT and a deployment-initiated reset to empty was requested — which session contributed which entry may no longer be recorded for anything written before this point.`,
+            ],
+        });
+        const receipt = rebuildStrictControlPlaneLedger(this.controlDir, ledger, this.now);
+        const sink = this.onIncident;
+        if (sink !== undefined) {
+            try {
+                const err = new Error(`memory control plane: ${ledger} ledger rebuilt after corruption (reason: ${reason}). ` +
+                    `The corrupt bytes are quarantined at ${receipt.quarantinedTo.join(", ") || "(no file existed)"} — ` +
+                    `they are the only remaining record of what this account held.`);
+                err.code = "memory.control_plane_rebuilt";
+                sink(err);
+            }
+            catch {
+            }
+        }
+        return receipt;
+    }
     challengeEntries(ids, reason, requestId) {
         if (typeof requestId !== "string" || requestId === "") {
             const e = new Error("challengeEntries: requestId is required (idempotency identity — retries must reuse it; the engine does not mint one)");
@@ -207,7 +263,10 @@ export class MemoryEngine {
         return this.challengeAndAnnounce(contributions.map((c) => ({ eventId: `${requestId}:${c.entryId}`, entryId: c.entryId, reason, challengedRev: c.lastRev })));
     }
     resolveChallenge(entryId, generation, reason, requestId) {
-        return resolveChallengeEvent(this.controlDir, entryId, generation, reason, this.now, requestId);
+        const { resolved, eventCount } = resolveChallengeEvent(this.controlDir, entryId, generation, reason, this.now, requestId);
+        if (eventCount !== undefined)
+            this.discloseChallengeLedgerSize(eventCount);
+        return resolved;
     }
     adjudicatePendingLineage(txnId, action) {
         const promoted = adjudicateLineagePending(this.controlDir, txnId, action, this.now);

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

@@ -2,7 +2,7 @@ export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";
-export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, } from "./layout.js";
+export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAppendResult, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, } from "./layout.js";
 export { readV2HeaderHints, type V2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, type ParsedEntryFile } from "./frontmatter.js";
 export type { MemoryBackend, MemoryEntry, MemoryEntryFrontmatter, MemoryEntryHeader, ScoredMemoryEntry, NotePatch, PatchReport, MaterializedFile, MemorySessionHandle, HarvestReport, HarvestRejection, HarvestRejectionCode, MemoryAnnouncement, ScanFinding, } from "./types.js";

package/dist/core/memory-engine/index.js

@@ -2,7 +2,7 @@ export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";
-export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, } from "./layout.js";
+export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, } from "./layout.js";
 export { readV2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile } from "./frontmatter.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, } from "./memory-backend-contract.js";

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

@@ -402,6 +402,33 @@ export interface ChallengeAssignment {
     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). */
@@ -410,11 +437,20 @@ export declare function appendChallengeEvents(controlDir: string, events: Readon
     entryId: string;
     reason: string;
     challengedRev?: string;
-}>, now: () => number): ChallengeAssignment[];
+}>, 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. Returns false ⇔ no such open generation existed. */
-export declare function resolveChallengeEvent(controlDir: string, entryId: string, generation: number, reason: string, now: () => number, requestId?: string): boolean;
+ *  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). */
@@ -424,6 +460,36 @@ export declare function challengedEntryIds(controlDir: string): Map<string, {
 }>;
 /** 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;

package/dist/core/memory-engine/layout.js

@@ -1,4 +1,4 @@
-import { closeSync, constants as fsConstants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
@@ -984,9 +984,10 @@ function coerceChallenges(raw) {
     }
     return raw;
 }
+export const CHALLENGE_LEDGER_MAX_EVENTS = 10_000;
 export function appendChallengeEvents(controlDir, events, now) {
     if (events.length === 0)
-        return [];
+        return { assignments: [], eventCount: undefined };
     return lockedStrictUpdate(controlDir, CHALLENGES_FILE, "memory challenge ledger", coerceChallenges, (rec) => {
         const byEventId = new Map(rec.events.map((e) => [e.eventId, e]));
         const maxGen = new Map();
@@ -1020,17 +1021,17 @@ export function appendChallengeEvents(controlDir, events, now) {
             out.push({ entryId: ev.entryId, eventId: ev.eventId, generation, at: ev.at, replayed: false });
             changed = true;
         }
-        return { ...(changed ? { next: rec } : {}), result: out };
+        return { ...(changed ? { next: rec } : {}), result: { assignments: out, eventCount: rec.events.length } };
     });
 }
 export function resolveChallengeEvent(controlDir, entryId, generation, reason, now, requestId) {
     return lockedStrictUpdate(controlDir, CHALLENGES_FILE, "memory challenge ledger", coerceChallenges, (rec) => {
         const opened = rec.events.some((e) => e.kind === "challenge" && e.entryId === entryId && e.generation === generation);
         if (!opened)
-            return { result: false };
+            return { result: { resolved: false, eventCount: undefined } };
         const alreadyResolved = rec.events.some((e) => e.kind === "resolve" && e.entryId === entryId && e.generation === generation);
         if (alreadyResolved)
-            return { result: true };
+            return { result: { resolved: true, eventCount: undefined } };
         rec.events.push({
             eventId: requestId !== undefined && requestId !== "" ? `${requestId}:${entryId}` : `resolve:${entryId}:${generation}`,
             entryId,
@@ -1039,7 +1040,7 @@ export function resolveChallengeEvent(controlDir, entryId, generation, reason, n
             at: now(),
             reason,
         });
-        return { next: rec, result: true };
+        return { next: rec, result: { resolved: true, eventCount: rec.events.length } };
     });
 }
 export function challengedEntryIds(controlDir) {
@@ -1061,6 +1062,74 @@ export function challengedEntryIds(controlDir) {
 export function readChallengeEvents(controlDir) {
     return coerceChallenges(readStrictSidecar(controlDir, CHALLENGES_FILE, "memory challenge ledger")).events;
 }
+export function isStrictControlPlaneLedgerCorrupt(controlDir, ledger) {
+    const fileName = ledger === "lineage" ? LINEAGE_FILE : CHALLENGES_FILE;
+    const what = ledger === "lineage" ? "memory lineage ledger" : "memory challenge ledger";
+    const coerce = ledger === "lineage" ? coerceLineage : coerceChallenges;
+    try {
+        coerce(readStrictSidecar(controlDir, fileName, what));
+        return false;
+    }
+    catch (err) {
+        if (err instanceof ControlPlaneCorruptError)
+            return true;
+        throw err;
+    }
+}
+export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
+    const fileName = ledger === "lineage" ? LINEAGE_FILE : CHALLENGES_FILE;
+    const what = ledger === "lineage" ? "memory lineage ledger" : "memory challenge ledger";
+    const coerce = ledger === "lineage" ? coerceLineage : coerceChallenges;
+    const empty = ledger === "lineage" ? { version: 1, committed: {}, pending: {} } : { version: 1, events: [] };
+    ensureDirExists(controlDir);
+    const file = join(controlDir, fileName);
+    const journal = `${file}.journal`;
+    const lock = `${file}.lock`;
+    const token = acquireSidecarLock(lock, { onDeadline: "throw" });
+    try {
+        let healthy = false;
+        try {
+            coerce(readStrictSidecar(controlDir, fileName, what));
+            healthy = true;
+        }
+        catch (err) {
+            if (!(err instanceof ControlPlaneCorruptError))
+                throw err;
+        }
+        if (healthy) {
+            const e = new Error(`${what} reads cleanly — refusing to rebuild it. This call exists to recover a ledger whose corruption already refuses every read; resetting a healthy one would drop taint evidence that is still doing its job.`);
+            e.code = "memory.control_plane_not_corrupt";
+            throw e;
+        }
+        const at = now();
+        const quarantinedTo = [];
+        assertSidecarLockOwnership(lock, token, what);
+        for (const path of [file, journal]) {
+            if (!existsSync(path))
+                continue;
+            let dest = `${path}.corrupt-${at}`;
+            for (let n = 2;; n++) {
+                try {
+                    copyFileSync(path, dest, fsConstants.COPYFILE_EXCL);
+                    break;
+                }
+                catch (err) {
+                    if (err.code !== "EEXIST")
+                        throw err;
+                    dest = `${path}.corrupt-${at}-${n}`;
+                }
+            }
+            quarantinedTo.push(dest);
+        }
+        assertSidecarLockOwnership(lock, token, what);
+        atomicWriteFileSync(file, `${JSON.stringify(empty, null, 2)}\n`);
+        rmSync(journal, { force: true });
+        return { ledger, quarantinedTo, at };
+    }
+    finally {
+        releaseSidecarLock(lock, token);
+    }
+}
 function coerceChallengedHistory(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return {};

package/dist/core/permission-rule-consent.js

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { parseAllowRuleText, suggestRulesForCommand } from "./permission-rule-model.js";
 import { errText, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
@@ -28,7 +29,7 @@ function nowIso(deps) {
 function mintId(deps, prefix) {
     if (deps.newId !== undefined)
         return deps.newId();
-    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+    return `${prefix}_${Date.now().toString(36)}_${randomBytes(9).toString("base64url")}`;
 }
 function requirePrincipal(principal, entry) {
     if (typeof principal !== "string" || principal === "") {

package/dist/core/permission-rule-org.d.ts

@@ -80,8 +80,42 @@ export interface OrgRuleStatePersistence {
 /** Duck-typed discovery of the persistence face on a store backend, `writerOf` style. */
 export declare function orgRuleStatePersistenceOf(store: PermissionRuleStore): OrgRuleStatePersistence | undefined;
 /** The `decisionReason` the consuming gate stamps on the synthetic asks it mints while org adjudication
- *  is unavailable. Exported so the gate integration and its tests share one spelling. */
-export declare const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
+ *  is unavailable. Exported so the gate integration and its tests share one spelling — and TYPED as the
+ *  member of {@link import("./tool-policy.js").DecisionReason} it must equal, so the constant and the
+ *  vocabulary cannot drift into two spellings of one word. */
+export declare const ORG_UNAVAILABLE_DECISION_REASON: Extract<import("./tool-policy.js").DecisionReason, "org_unavailable">;
+/**
+ * How long a single org adjudication may take before the consuming gate stops waiting and reads the
+ * answer as UNAVAILABLE (its fail-closed word).
+ *
+ * A bound is MANDATORY rather than optional because of where this call sits: on the hot path of every
+ * governed tool call, and — on the durable resume leg — after the checkpoint has been consumed and the
+ * start frame emitted. A provider that never settles would otherwise wedge the call past any task
+ * deadline (tasks carry no walltime by default), leaving the frame unpaired and the approval spent with
+ * nothing retryable. A hang is the one outcome worse than either verdict.
+ *
+ * The value matches the auto-mode classifier's per-round-trip cap — the other model/network call the
+ * permission path makes — because the reasoning is the same: a governance lookup that takes longer than
+ * this is indistinguishable from an outage, and an outage is exactly what the unavailable arm is for.
+ * The task's own abort signal still applies in parallel; whichever fires first ends the wait.
+ */
+export declare const ORG_ADJUDICATION_TIMEOUT_MS = 15000;
+/**
+ * Await `p`, but settle with `fallback` if the deadline elapses or the signal fires first.
+ *
+ * Shared by both org consumption sites so one bound cannot drift into two. Deliberately NOT `.unref()`
+ * on the timer: this is a foreground rescue timer, and the caller is awaiting it inside the control
+ * flow — an unref'd timer stops firing in exactly the situation it exists for (an otherwise idle loop).
+ * A rejecting `p` also lands on the fallback: the callers' fail-closed word is the same either way, and
+ * an escaping rejection here would turn a dependency failure into a task crash.
+ */
+export declare function settleOrgVerdictWithin<T>(p: Promise<T>, fallback: T, opts: {
+    signal?: AbortSignal;
+    timeoutMs: number;
+}): Promise<T>;
+/** The `decisionReason` of a decision an ORG RULE produced (a deny, or a non-dismissable ask). Same
+ *  single-spelling contract as {@link ORG_UNAVAILABLE_DECISION_REASON}. */
+export declare const ORG_RULE_DECISION_REASON: Extract<import("./tool-policy.js").DecisionReason, "org_rule">;
 /** How far into the future a snapshot's `fetchedAtMs` may sit before it is refused — ordinary NTP-level
  *  clock skew passes; a far-future timestamp (which would satisfy the staleness bound INDEFINITELY,
  *  turning fail-closed into evergreen freshness) does not. */

package/dist/core/permission-rule-org.js

@@ -7,6 +7,29 @@ export function orgRuleStatePersistenceOf(store) {
         : undefined;
 }
 export const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
+export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
+export function settleOrgVerdictWithin(p, fallback, opts) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve(v);
+        };
+        const onAbort = () => finish(fallback);
+        const timer = setTimeout(() => finish(fallback), opts.timeoutMs);
+        if (opts.signal?.aborted === true) {
+            finish(fallback);
+            return;
+        }
+        opts.signal?.addEventListener("abort", onAbort);
+        p.then(finish, () => finish(fallback));
+    });
+}
+export const ORG_RULE_DECISION_REASON = "org_rule";
 export const ORG_FETCHED_AT_SKEW_ALLOWANCE_MS = 5 * 60_000;
 export function createOrgRuleOverlay(cfg) {
     if (cfg.governed !== true) {

package/dist/core/permission-rule-store.d.ts

@@ -1,11 +1,14 @@
 /**
- * design/179 §8 — the persisted allow-rule store seam, its core-private write face, and the removal entry.
+ * design/179 §8 — the persisted allow-rule store seam, its backend write face, and the removal entry.
  *
  * ## Two faces, deliberately unequal
  *
- * A deployment sees a READ face: `list()`, scoped to one verified principal by a factory. There is no
- * exported write API at all — the only way a rule enters the store through the engine is the core-private
- * redemption path (`permission-rule-consent.ts`), which requires an approved durable approval record.
+ * A deployment sees a READ face: `list()`, scoped to one verified principal by a factory. The write face
+ * is a BACKEND CONTRACT (ruled 2026-08-10: exported so an out-of-repo store twin builds against the same
+ * definitions instead of mirroring them), not a host write API — the only way a rule enters the store
+ * through the ENGINE is the redemption path (`permission-rule-consent.ts`), which requires an approved
+ * durable approval record; that invariant lives in the engine's wiring and is pinned by the
+ * writer-caller registry test, not in type visibility.
  * `expectedRev` is concurrency control, not authorization, so "hold a put API and skip the ticket" is not
  * a shape that exists here rather than a rule someone must remember.
  *
@@ -156,15 +159,19 @@ export interface RuleSyncJoinDelta {
  * What a write may say. Authorization discriminates on the DELTA SHAPE, not on a full snapshot: only the
  * add arm can introduce a dot, and the delete arm carries a tombstone and no adds. A backend additionally
  * REFUSES at runtime any delete that would introduce a new add dot — structure and runtime check together,
- * so "pick the delete arm and smuggle an add" is neither expressible nor accepted. The `sync-join` arm is
- * constructible only by core (the writer is never exported), and every inbound record inside it passes the
- * single validator again AT THE BACKEND — the fifth door of design/179 §4's validator list closes here,
- * not at the calling layer.
+ * so "pick the delete arm and smuggle an add" is neither expressible nor accepted. The `sync-join` arm's
+ * safety does not rest on hiding the type (ruled 2026-08-10: the backend contract IS exported for
+ * out-of-repo store twins) — it rests on every inbound record inside it passing the single validator
+ * again AT THE BACKEND: the fifth door of design/179 §4's validator list closes here, not at the
+ * calling layer, and closes identically for every caller.
  */
 export type RuleWriteDelta = RuleAddDelta | RuleDeleteDelta | RuleSyncJoinDelta;
 /**
- * The core-private write face. Deliberately absent from the package's public exports: a host cannot hold
- * one, so no API-level path to the store bypasses the consent protocol.
+ * The backend write face. Exported as part of the BACKEND CONTRACT (ruled 2026-08-10) so an
+ * out-of-repo store implementation hangs the same face the file backend does, instead of mirroring the
+ * types. The consent boundary is unchanged by the export: the ENGINE reaches a writer only through the
+ * consent protocol's redemption (and the sync client's join) — a property of the engine's wiring —
+ * and a deployment always owned its own storage bytes, so type visibility grants nothing new.
  */
 export interface PermissionRuleWriter {
     /** Mint the next dot for this replica. Counters need only be unique and monotonic, so a dot minted for
@@ -198,11 +205,11 @@ export interface RawRuleSyncState {
     quarantined?: QuarantinedRuleAdd[];
 }
 /**
- * The internal handle a writable backend hangs its write face on. Not exported from the package index —
- * that omission IS the boundary described in the module doc.
+ * The handle a writable backend hangs its write face on (exported with the backend contract, ruled 2026-08-10;
+ * the consent boundary lives in the engine's wiring, not in this key's visibility).
  */
 export declare const PERMISSION_RULE_WRITER = "__semaPermissionRuleWriter";
-/** A store that also carries the core-private write face. */
+/** A store that also carries the backend write face. */
 export interface WritablePermissionRuleStore extends PermissionRuleStore {
     readonly [PERMISSION_RULE_WRITER]: PermissionRuleWriter;
 }
@@ -419,7 +426,11 @@ export type RemoveResult =
 export declare function removePersistedRule(opts: {
     rule: string;
     scope: RuleScope;
-    principal: string;
+    /** Whose bucket. A bare string stays the principal shorthand (unchanged callers); the structural
+     *  {@link RuleOwner} form adds the local-owner bucket (downstream request, 2026-08-10 — design/182 §4.5's
+     *  `forLocalOwner()` face existed, but removal could not name it, so a local-owner rule was
+     *  unrevokable through this entry). Same observed-remove/add-wins/stillLive semantics either way. */
+    principal: string | RuleOwner;
     provider: PermissionRuleStoreProvider;
 }): Promise<RemoveResult>;
 export declare function errText(err: unknown): string;

package/dist/core/permission-rule-store.js

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
 import { isRuleLive, parseAllowRuleText } from "./permission-rule-model.js";
 export function sameRuleOwner(a, b) {
@@ -326,7 +327,11 @@ export async function ruleStoreChecksum(payload) {
 }
 const REMOVE_MAX_ATTEMPTS = 8;
 export async function removePersistedRule(opts) {
-    const store = opts.provider.forPrincipal(opts.principal);
+    const owner = typeof opts.principal === "string" ? { kind: "principal", principal: opts.principal } : opts.principal;
+    if (owner.kind === "local-owner" && opts.provider.forLocalOwner === undefined) {
+        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be removed through it" };
+    }
+    const store = owner.kind === "local-owner" ? opts.provider.forLocalOwner() : opts.provider.forPrincipal(owner.principal);
     const writer = writerOf(store);
     if (writer === undefined) {
         return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be removed through it" };
@@ -396,7 +401,7 @@ export class InMemoryPermissionRuleStore {
     observedVector;
     rev = 0;
     counter = 0;
-    constructor(actor = `mem-${Math.random().toString(36).slice(2, 10)}`, now = Date.now) {
+    constructor(actor = `mem-${randomBytes(6).toString("base64url")}`, now = Date.now) {
         this.actor = actor;
         this.now = now;
     }

package/dist/core/permission-rule-sync.d.ts

@@ -27,6 +27,7 @@
  */
 import type { PersistedAllowRule, RuleDot, RuleScope, RuleTombstone } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner, RuleSyncDrop, RuleSyncFrontier, RuleSyncState } from "./permission-rule-store.js";
+import { type TracerHook } from "./trace.js";
 /** The injected HTTP seam — core never bundles a fetch. The deployment owns base URL, auth, TLS and
  *  retries; a non-2xx / network failure should THROW (the round then aborts with zero local effects —
  *  the transport runs before any local write). */
@@ -103,6 +104,13 @@ export declare function syncPermissionRules(opts: {
     transport: PermissionRuleSyncTransport;
     /** Injected clock — observation timestamps only, never adjudication input. */
     now?: () => number;
+    /** design/182 §4.6 — optional trace sink for the round's DISCLOSURES: one
+     *  `permission.rule_sync_resurrected` per removed→live transition and one
+     *  `permission.rule_sync_dropped` per refused/quarantined row. The same facts are already on the
+     *  returned result; this is the operator channel for a deployment that drives sync outside a task
+     *  (where there is no `RunnerDeps.tracer` in scope) and does not read the result itself. Absent ⇒ no
+     *  events, and the round is byte-identical. */
+    tracer?: TracerHook;
 }): Promise<PermissionRuleSyncResult>;
 interface ParsedRuleSyncResponse {
     principal: string;