@sema-agent/core 7.49.5 → 7.50.1

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

@@ -11,6 +11,7 @@ import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "
 import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, anchorStoreRoot, effectiveControlRootOf, ensureDirExists, LEDGER_FILE, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, permissionRemedyOf, withPermissionRemedy, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, writeAllSync, STORE_JOURNAL_FILE, STORE_TXN_LOCK_DIR, TXN_LOCK_STALE_MS, acquireStoreTxnLock, assertStoreTxnLockOwnership, tryStoreTxnLock, } from "./layout.js";
 import { screenInboundEntries } from "./data-plane.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
+import { admittingLandings, cutPerLanding, LandingsNeedAdmission, requireLandingsAdmitted } from "./landing-admission.js";
 import { thrownText } from "../thrown-value.js";
 export { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./entry-scan.js";
 export function canonicalJsonStringify(value) {
@@ -526,6 +527,7 @@ export class FileMemoryEngineBackend {
     unboundRowsKnown = false;
     adoptionNoticeKeys = new Set();
     transfersAppendFault;
+    landingFault;
     recoveryCommitProbe;
     chainHealProbe;
     exportFaceProbe;
@@ -2111,17 +2113,20 @@ export class FileMemoryEngineBackend {
         return scored.slice(0, limit);
     }
     async applyPatches(patches, opts) {
-        const lock = await this.acquireTxnLock();
-        try {
-            return await this.applyPatchesLocked(patches, lock.token, opts?.anchoredRoot);
-        }
-        catch (err) {
-            throw withPermissionRemedy(err, this.directoryRoot);
-        }
-        finally {
-            lock.release();
-        }
+        return admittingLandings(opts?.admit, async (admitted) => {
+            const lock = await this.acquireTxnLock();
+            try {
+                return await this.applyPatchesLocked(patches, lock.token, opts?.anchoredRoot, admitted, opts?.confirm);
+            }
+            catch (err) {
+                throw err instanceof LandingsNeedAdmission ? err : withPermissionRemedy(err, this.directoryRoot);
+            }
+            finally {
+                lock.release();
+            }
+        });
     }
+    admitsLandings = true;
     txnLockDir() {
         return join(this.controlPlaneRoot, STORE_TXN_LOCK_DIR);
     }
@@ -2131,7 +2136,7 @@ export class FileMemoryEngineBackend {
     assertTxnLockOwnership(token) {
         assertStoreTxnLockOwnership(this.controlPlaneRoot, token);
     }
-    async applyPatchesLocked(patches, lockToken, anchoredRoot) {
+    async applyPatchesLocked(patches, lockToken, anchoredRoot, admitted, confirm) {
         this.assertTxnLockOwnership(lockToken);
         if (anchoredRoot !== undefined)
             this.assertRootAnchored(anchoredRoot);
@@ -2146,9 +2151,12 @@ export class FileMemoryEngineBackend {
         const plannedTargets = new Set();
         const nonDeleteIds = new Set();
         const plannedDeletes = new Map();
+        const landings = [];
+        const shares = [];
         this.batchScan = new Map();
         try {
             for (const patch of patches) {
+                const landingsBefore = landings.length;
                 try {
                     if (patch.op !== "delete") {
                         if (patch.entry !== undefined && patch.entry.id !== patch.id) {
@@ -2161,11 +2169,13 @@ export class FileMemoryEngineBackend {
                         }
                         nonDeleteIds.add(patch.id);
                     }
-                    this.planOne(patch, report, ops, rows, plannedTargets, plannedDeletes, transfers);
+                    this.planOne(patch, report, ops, rows, plannedTargets, plannedDeletes, transfers, landings);
                 }
                 catch (err) {
                     report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${thrownText(err)}` });
                 }
+                if (admitted !== undefined)
+                    shares.push({ opsEnd: ops.length, evidenceEnd: transfers.length, ...(landings.length > landingsBefore ? { landed: cloneRows(rows) } : {}) });
             }
         }
         finally {
@@ -2174,6 +2184,15 @@ export class FileMemoryEngineBackend {
         if (ops.length === 0) {
             return report;
         }
+        if (admitted !== undefined)
+            requireLandingsAdmitted(admitted, landings);
+        for (const cut of admitted === undefined ? [{ ops, evidence: transfers, account: rows }] : cutPerLanding(ops, transfers, shares, rows)) {
+            confirm?.();
+            this.commitCut(cut, lockToken, anchoredRoot);
+        }
+        return report;
+    }
+    commitCut({ ops, evidence: transfers, account: rows }, lockToken, anchoredRoot) {
         const txn = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         const stagedFiles = [];
         const refuseUnstaging = (batch, at) => {
@@ -2229,6 +2248,7 @@ export class FileMemoryEngineBackend {
             this.refuseEscapingTargets([op], "applyPatches (after the commit point; the journal is kept)");
             if (op.kind === "write" && op.staged) {
                 renameSync(op.staged, op.target);
+                this.landingFault?.(op.target);
             }
             else if (op.kind === "delete") {
                 rmSync(op.target, { force: true });
@@ -2244,7 +2264,6 @@ export class FileMemoryEngineBackend {
         this.saveLedger();
         this.appendTransfers(coherentTransfers);
         this.closeJournalIfOurs(txn);
-        return report;
     }
     closeJournalIfOurs(txn) {
         const jp = join(this.controlPlaneRoot, STORE_JOURNAL_FILE);
@@ -2265,7 +2284,7 @@ export class FileMemoryEngineBackend {
         }
         rmSync(jp, { force: true });
     }
-    planOne(patch, report, ops, rows, plannedTargets, plannedDeletes, transfers) {
+    planOne(patch, report, ops, rows, plannedTargets, plannedDeletes, transfers, landings) {
         if (!isValidEntryId(patch.id)) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: `invalid_id_shape (id ${JSON.stringify(patch.id)} fails the frontmatter id contract — the read side would drop it, leaving an applied-but-invisible entry)` });
             return;
@@ -2336,6 +2355,7 @@ export class FileMemoryEngineBackend {
             }
             if (existingAnywhere !== undefined && existingAnywhere.entry.slug !== entry.slug) {
                 ops.push({ kind: "delete", target: existingAnywhere.path });
+                landings.push({ id: entry.id, scope: existingAnywhere.entry.scope, slug: existingAnywhere.entry.slug });
             }
             const dir = this.scopeDir(entry.scope);
             let slug = entry.slug;
@@ -2356,6 +2376,7 @@ export class FileMemoryEngineBackend {
             plannedTargets.add(target);
             ops.push({ kind: "write", target, content });
             ops.push({ kind: "shadow-write", target: entry.id, content });
+            landings.push({ id: entry.id, scope: entry.scope, slug });
             const now = this.now();
             bindRowTracked(rows, entry.id, { rev: computeEntryRev(entry), scope: entry.scope, slug, at: now }, transfers, "applyPatches-move");
             const priorBinding = plannedDeletes.get(entry.id);
@@ -2413,17 +2434,21 @@ export class FileMemoryEngineBackend {
             const shadowText = this.readCommittedShadow(patch.id);
             if (shadowText !== undefined && shadowText !== serializeEntryFile(found.entry)) {
                 ops.push({ kind: "write", target: found.path, content: shadowText });
+                landings.push({ id: patch.id, scope: found.entry.scope, slug: found.entry.slug });
             }
             return;
         }
         if (patch.op === "delete") {
             ops.push({ kind: "delete", target: found.path });
             ops.push({ kind: "shadow-delete", target: patch.id });
+            landings.push({ id: patch.id, scope: found.entry.scope, slug: found.entry.slug });
             const deletedBinding = rowsBinding(rows, patch.id);
             if (deletedBinding !== undefined) {
                 const derived = this.bindingAbsPath(deletedBinding);
-                if (derived !== found.path)
+                if (derived !== found.path) {
                     ops.push({ kind: "delete", target: derived });
+                    landings.push({ id: patch.id, scope: deletedBinding.scope, slug: deletedBinding.slug });
+                }
             }
             transfers.push({
                 ev: randomUUID(),
@@ -2446,11 +2471,14 @@ export class FileMemoryEngineBackend {
         const dir = this.scopeDir(entry.scope);
         const target = join(dir, `${entry.slug}.md`);
         const content = serializeEntryFile(entry);
-        if (target !== found.path)
+        if (target !== found.path) {
             ops.push({ kind: "delete", target: found.path });
+            landings.push({ id: entry.id, scope: found.entry.scope, slug: found.entry.slug });
+        }
         plannedTargets.add(target);
         ops.push({ kind: "write", target, content });
         ops.push({ kind: "shadow-write", target: entry.id, content });
+        landings.push({ id: entry.id, scope: entry.scope, slug: entry.slug });
         bindRowTracked(rows, entry.id, { rev: computeEntryRev(entry), scope: entry.scope, slug: entry.slug, at: this.now() }, transfers, "applyPatches-move");
         report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
     }

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

@@ -10,9 +10,9 @@ export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, com
 export { consolidationExposedFrontmatter } from "./frontmatter.js";
 export { committedDistilledOf, distilledEquals } from "./frontmatter.js";
 export { deriveShadowedSet } from "./shadowing.js";
-export { CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type MemoryConsolidationOptions, CONSOLIDATION_RUN_STOP_REASONS, type ConsolidationRunStopReason, } from "./consolidation.js";
+export { CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type ConsolidationWriteGate, type MemoryConsolidationOptions, CONSOLIDATION_RUN_STOP_REASONS, type ConsolidationRunStopReason, } from "./consolidation.js";
 export { DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, type CleanArmLeakFinding, type CleanArmLeakVerdict, type MemoryDistillerPurityContract, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, type ConsolidationDistillFn, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationDriveResult, type ConsolidationFoldState, type DistillerCandidate, type DistillerChatAnswer, type DistillerChatFn, type DistillerChatRequest, type FuseSchedule, type LlmConsolidationPlan, type LlmConsolidationPlanArm, type LlmConsolidationPlanProduct, type LlmDistillerContract, type MintLlmConsolidationPlanResult, type PlanParseRepairs, type SanitizedLlmGroups, } from "./distiller.js";
-export { CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type RunMemoryConsolidationOptions, } from "./consolidation-driver.js";
+export { CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, CONSOLIDATION_WRITE_REFUSED_CODE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type ConsolidationWriteJudge, type ConsolidationWriteTarget, type RunMemoryConsolidationOptions, } from "./consolidation-driver.js";
 export type { OriginClearanceRow, OriginClearanceEvent, OriginClearanceShadow } from "./origin-clearance.js";
 export { MEMORY_ORIGIN_CAUSES, writableRootOf } from "./types.js";
 export type { MemoryBackend, MemoryEntry, MemoryEntryFrontmatter, MemoryEntryOrigin, MemoryOriginCause, MemoryScopeEnumeration, MemoryEntryDistilled, MemoryEntryDistilledInput, MemoryEntryHeader, ScoredMemoryEntry, NotePatch, PatchReport, MaterializedFile, MemorySessionHandle, HarvestReport, HarvestRejection, HarvestRejectionCode, MemoryAnnouncement, ScanFinding, } from "./types.js";

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

@@ -12,7 +12,7 @@ export { committedDistilledOf, distilledEquals } from "./frontmatter.js";
 export { deriveShadowedSet } from "./shadowing.js";
 export { CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, CONSOLIDATION_RUN_STOP_REASONS, } from "./consolidation.js";
 export { DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, } from "./distiller.js";
-export { CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, } from "./consolidation-driver.js";
+export { CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, CONSOLIDATION_WRITE_REFUSED_CODE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, } from "./consolidation-driver.js";
 export { MEMORY_ORIGIN_CAUSES, writableRootOf } from "./types.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, } from "./memory-backend-contract.js";
 export { SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, isOrgScopeKey, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, } from "./scope-contract.js";

package/dist/core/memory-engine/landing-admission.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The landing-admission protocol: a caller that holds authority over WHERE notes may land (the consolidation run's write
+ * judge) and a backend that names the landings (it alone knows the final spelling — a collision suffix is its decision, taken
+ * under its transaction lock against the files as they are at that moment).
+ *
+ * A LANDING is every entry file a patch writes or removes: an add's final spelling, an update's target, the file a delete
+ * removes, and the old file a rename leaves. The backend plans a batch under its lock, finds every landing, and — before it
+ * stages anything — leaves the lock to put the ones the caller has not yet been told of to `admit`; it then plans again and
+ * writes only when every landing is one `admit` resolved. A spelling that moved in between (a rival writer took the name) is
+ * asked about again; it is never renamed after it was judged. The judgment is awaited outside the lock: it may wait on a rule store.
+ *
+ * An admitted batch is asked whole and committed one landing at a time ({@link cutPerLanding}): a backend's commit record is
+ * replayed by its crash recovery without anyone to ask, so it never carries a landing behind another one. A crash between two
+ * landings leaves the earlier landed and the later uncommitted, to be asked again by whoever applies it next; recovery only
+ * ever completes the one landing whose commit had begun.
+ */
+import type { MemoryBackend, NotePatch, PatchReport } from "./types.js";
+/** One landing: the entry's id and the scope directory and slug of the file it writes or removes. */
+export interface PatchLanding {
+    readonly id: string;
+    readonly scope: string;
+    readonly slug: string;
+}
+/** Resolves ⇒ the landings may be written; rejects ⇒ nothing is written and the rejection propagates unchanged. */
+export type AdmitLandings = (landings: readonly PatchLanding[]) => Promise<void>;
+/** Rounds of "plan, ask, plan again" a batch gets before the backend gives up on a name that keeps moving. */
+export declare const MAX_LANDING_ADMISSION_ROUNDS = 4;
+/** Thrown from inside the lock, before anything is staged: these landings have not been admitted yet. */
+export declare class LandingsNeedAdmission extends Error {
+    readonly landings: readonly PatchLanding[];
+    constructor(landings: readonly PatchLanding[]);
+}
+/**
+ * Inside the lock, once the batch is planned with its `landings`: throw {@link LandingsNeedAdmission} naming the ones not in
+ * `admitted`. Nothing is on disk yet, so the throw is a clean exit.
+ */
+export declare function requireLandingsAdmitted(admitted: ReadonlySet<string>, landings: readonly PatchLanding[]): void;
+/** One planned patch's share of an admitted batch: where its operations and evidence end in the batch's lists, and — iff it has
+ *  a landing — the account as it stands after it. */
+export interface PatchShare<R> {
+    readonly opsEnd: number;
+    readonly evidenceEnd: number;
+    readonly landed?: R;
+}
+/** One transaction of an admitted batch: the operations and evidence it commits and the account it leaves. */
+export interface LandingCut<O, E, R> {
+    ops: O[];
+    evidence: E[];
+    account: R;
+}
+/**
+ * The commit cuts of an admitted batch, in order: a cut closes at each patch that has a landing, so no cut carries two patches'
+ * landings (a rename's two files are one patch's, committed together; a patch with operations but no landing — a conflict's restore
+ * of committed bytes — rides with the next). A cut leaves the account as it stood after its landing; the last cut leaves
+ * `finalAccount`, the batch's (whatever the patches after the last landing changed rides with it).
+ */
+export declare function cutPerLanding<O, E, R>(ops: readonly O[], evidence: readonly E[], shares: readonly PatchShare<R>[], finalAccount: R): Array<LandingCut<O, E, R>>;
+/** A backend that cannot admit is handed the landings its caller admitted one call each, so none of its commits carries a landing
+ *  behind another whatever its own commit unit is; `before` (the caller's holder check) runs ahead of each call. */
+export declare function applyEachAlone(backend: Pick<MemoryBackend, "applyPatches">, patches: readonly NotePatch[], before: () => void): Promise<PatchReport>;
+/**
+ * The backend's side of the loop. `run(admitted)` plans and applies one locked attempt (it throws
+ * {@link LandingsNeedAdmission} when the plan names a spelling not in `admitted`); with no `admit` it runs once, unconditioned.
+ */
+export declare function admittingLandings<T>(admit: AdmitLandings | undefined, run: (admitted: ReadonlySet<string> | undefined) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,68 @@
+export const MAX_LANDING_ADMISSION_ROUNDS = 4;
+export class LandingsNeedAdmission extends Error {
+    landings;
+    constructor(landings) {
+        super("memory landings need admission");
+        this.landings = landings;
+    }
+}
+const landingKey = (l) => `${l.scope}\u0000${l.slug}`;
+export function requireLandingsAdmitted(admitted, landings) {
+    const pending = landings.filter((l) => !admitted.has(landingKey(l)));
+    if (pending.length > 0)
+        throw new LandingsNeedAdmission(pending);
+}
+export function cutPerLanding(ops, evidence, shares, finalAccount) {
+    const cuts = [];
+    let open;
+    let opsAt = 0;
+    let evidenceAt = 0;
+    for (const s of shares) {
+        if (s.opsEnd > opsAt || s.evidenceEnd > evidenceAt) {
+            if (open === undefined)
+                cuts.push((open = { ops: [], evidence: [], account: finalAccount }));
+            open.ops.push(...ops.slice(opsAt, s.opsEnd));
+            open.evidence.push(...evidence.slice(evidenceAt, s.evidenceEnd));
+            opsAt = s.opsEnd;
+            evidenceAt = s.evidenceEnd;
+        }
+        if (s.landed !== undefined && open !== undefined) {
+            open.account = s.landed;
+            open = undefined;
+        }
+    }
+    const last = cuts[cuts.length - 1];
+    if (last !== undefined)
+        last.account = finalAccount;
+    return cuts;
+}
+export async function applyEachAlone(backend, patches, before) {
+    const report = { applied: [], conflicts: [] };
+    for (const p of patches) {
+        before();
+        const r = await backend.applyPatches([p]);
+        report.applied.push(...r.applied);
+        report.conflicts.push(...r.conflicts);
+    }
+    return report;
+}
+export async function admittingLandings(admit, run) {
+    if (admit === undefined)
+        return run(undefined);
+    const admitted = new Set();
+    for (let round = 0;; round++) {
+        try {
+            return await run(admitted);
+        }
+        catch (err) {
+            if (!(err instanceof LandingsNeedAdmission))
+                throw err;
+            if (round >= MAX_LANDING_ADMISSION_ROUNDS) {
+                throw Object.assign(new Error(`memory landings kept moving: ${err.landings.length} spelling(s) were still unadmitted after ${MAX_LANDING_ADMISSION_ROUNDS} rounds, nothing was written`), { code: "memory.landing_unstable" });
+            }
+            await admit(err.landings);
+            for (const l of err.landings)
+                admitted.add(landingKey(l));
+        }
+    }
+}

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

@@ -379,10 +379,33 @@ export interface MemoryBackend {
      * the whole batch with `memory.target_outside_store` when the anchor is another root (`detail.recorded`
      * = the anchor, `detail.now` = `anchoredRoot`): a session mounted before a re-anchor commits nothing
      * into the re-anchored store. A backend without a directory ignores it.
+     *
+     * `opts.admit` is the caller's authority over WHERE the batch lands, asked at the spelling each ADD will finally take (after
+     * the backend's own collision suffix). A backend that declares {@link admitsLandings} resolves every add's final landing
+     * `{ id, scope, slug }`, calls `admit` with ALL the ones it has not yet been told of BEFORE it writes any of them (never while
+     * it holds its own transaction lock: the caller's judgment may wait on a store), and writes only spellings `admit` has
+     * resolved: a spelling that moves after `admit` returned (a rival writer took the name) is asked about again before anything is
+     * written, never renamed after the judgment. A rejection from `admit` writes nothing and propagates unchanged. Asked whole, an
+     * admitted batch commits one landing at a time: whatever the backend's crash recovery replays without asking (its commit
+     * record) never carries a landing behind another one, so a crash between two landings leaves the later one unwritten until
+     * its next apply asks again. A backend that does not declare it is handed neither `admit` nor `confirm`: the caller asks about
+     * the spellings it froze, all of them, just before the batch, and hands it the writes one call each, its own check before each.
+     * `opts.confirm` is the caller's last word, called synchronously under the transaction lock before each commit of the batch
+     * (once every spelling is admitted, before anything of that commit is staged), with or without `admit`; a throw aborts what is
+     * not yet committed and propagates unchanged.
      */
     applyPatches(patches: readonly NotePatch[], opts?: {
         readonly anchoredRoot?: string;
+        readonly admit?: (landings: readonly {
+            readonly id: string;
+            readonly scope: string;
+            readonly slug: string;
+        }[]) => Promise<void>;
+        readonly confirm?: () => void;
     }): Promise<PatchReport>;
+    /** `true` ⇔ {@link applyPatches} honors `opts.admit` and `opts.confirm` (the File backend does). Absent ⇒ the caller admits the frozen
+     *  spellings itself and sends the writes one call each. */
+    readonly admitsLandings?: true;
     /** design/84 Seam B cursor pair, migrated verbatim onto the entry-id plane (S2 rewires consolidation). */
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;

package/dist/core/mode-policy.d.ts

@@ -165,7 +165,8 @@ export declare function refusePermissionModeDoors(spec: Pick<TaskSpec, "permissi
  * The doors a RESUMED leg's prepare refuses at, read as one screen for the resume ladder to run BEFORE the claim: the mode
  * doors on the re-supplied config ({@link refusePermissionModeDoors}), its output-style seat (`resolveOutputStyleFrame`), its
  * approval-reach declaration (`screenApprovalReach`), the skills it invokes by name (`screenUserInvokedSkills` — the part no
- * roster changes; a name the leg's roster reads as nothing is prepare's) and the mode words the checkpoint row recorded (`recordedModeSeed`) — prepare's own functions, so the refusal carries the very
+ * roster changes; a name the leg's roster reads as nothing is prepare's), its attachments (`screenUserAttachments` — a resume
+ * sends no new human message, so any entry is refused) and the mode words the checkpoint row recorded (`recordedModeSeed`) — prepare's own functions, so the refusal carries the very
  * sentence and code prepare would throw. It leaves by the resume's ONE refusal channel, `CheckpointError`
  * `checkpoint.config_refused` (`message` = prepare's sentence, `detail.code` = prepare's code, `detail.field` = the input that
  * carries it: `"taskConfig"` or `"inheritedGate"`), where prepare itself would end the run `failed` after the claim — a
@@ -174,7 +175,7 @@ export declare function refusePermissionModeDoors(spec: Pick<TaskSpec, "permissi
  * corrected resume. A throw that is not one of prepare's five codes (a caller's accessor failing) is not a refusal and leaves
  * as it was thrown.
  */
-export declare function refuseResumeDoors(config: Pick<TaskSpec, "permissionMode" | "shellGate" | "outputStyle" | "approvalReach" | "skills" | "userInvokedSkills">, recordedGate: Parameters<typeof recordedModeSeed>[0]): void;
+export declare function refuseResumeDoors(config: Pick<TaskSpec, "permissionMode" | "shellGate" | "outputStyle" | "approvalReach" | "skills" | "userInvokedSkills" | "userAttachments">, recordedGate: Parameters<typeof recordedModeSeed>[0]): void;
 /** The three-member answer every mode question gets — the manifest member, the steer verb's return value and the
  *  fold notice's detail share it. `requested` is absent when the caller declared nothing (a root inherits `default`,
  *  a child inherits its parent). */

package/dist/core/mode-policy.js

@@ -8,6 +8,7 @@ import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { assertNoRetiredKeys, RETIRED_TASK_SPEC_KEYS } from "./retired-keys.js";
 import { resolveOutputStyleFrame } from "./output-style.js";
+import { screenUserAttachments } from "./user-attachment.js";
 import { CheckpointError, isCheckpointConfigRefusalCode, recordedModeSeed } from "./checkpoint-store.js";
 import { screenApprovalReach } from "./wiring-manifest.js";
 import { screenUserInvokedSkills } from "./skill-grant.js";
@@ -116,6 +117,7 @@ export function refuseResumeDoors(config, recordedGate) {
         resolveOutputStyleFrame(config.outputStyle);
         screenApprovalReach(config.approvalReach);
         screenUserInvokedSkills(config);
+        screenUserAttachments(config.userAttachments, { resumeLeg: true });
     });
     screenAs("inheritedGate", () => void recordedModeSeed(recordedGate));
 }

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

@@ -75,7 +75,7 @@
 import { type DenyFace } from "../tools/fs/read-deny.js";
 import type { AssertAllKeysHandled } from "./ask-origin.js";
 import { type ToolCallLike } from "./tool-registry.js";
-import { type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
+import { type PathDenialEvidence, type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
 import { type TargetViews } from "./path-rule-binding.js";
 /**
  * The closed set of rule BEHAVIORS — what a matching rule says about the call. The upstream vocabulary
@@ -141,11 +141,12 @@ export declare const READ_RULE_TOOL = "Read";
  * roots, the write tools — judged on the path that call reads, searches or writes. A path rule on any other tool keeps
  * its tool's name as its reach (`Write(<path>)` is judged on the Write tool, a stricter reading the reference does not make).
  *
- * The two columns are enforced where each behavior can be: a deny row is exported to the engine's deny tables
- * (`ToolPolicy.pathRules` bound where the policy is installed, the person's rows at prepare), which refuse inside the tool, descend into a search's
- * results and reach the shell's file commands; an ask is a question asked at the gate before the call runs, so it is
- * judged there, on the call's own path target only — it does not descend (a search rooted above the asked path is not
- * asked, and its results are not filtered).
+ * Both tightening columns are judged at the gate, on the call's own path target, before the call runs — by the rule
+ * policy's lane and by the persisted lane alike, one column read for deny and for ask. A deny row is exported to the
+ * engine's deny tables as well (`ToolPolicy.pathRules` bound where the policy is installed, the person's rows at
+ * prepare), which do what the gate cannot: refuse inside the tool at execution time, descend into a search's results,
+ * reach the shell's file commands' operands, and keep a refused target out of the out-of-root question. An ask does not
+ * descend (a search rooted above the asked path is not asked, and its results are not filtered).
  *
  * The ALLOW column is the reference's too: an allow by path is read on these two tools only — a `Read(<path>)` allow speaks
  * for the read face, an `Edit(<path>)` allow for the write face and the read face (an edit allowed is a read allowed) — and
@@ -156,9 +157,9 @@ export declare const PATH_RULE_FACES: Readonly<Record<string, Readonly<Partial<R
 /** The face a call's protective path target is on: `read` for a read slot, `write` for every other access; none without
  *  one — the face a {@link PATH_RULE_FACES} rule is judged against, in a rule policy and in the persisted rule lane alike. */
 export declare function callPathFaceOf(call: ToolCallLike): DenyFace | undefined;
-/** Does some {@link PATH_RULE_FACES} ask column hold `face` — may a face-keyed ask row speak for a call on it, whatever
- *  the call's tool is called (a caller's tool declaring a read path target is on the read face too)? */
-export declare function faceAskSpeaksFor(face: DenyFace | undefined): boolean;
+/** Does some {@link PATH_RULE_FACES} tightening column (deny or ask) hold `face` — may a face-keyed row speak for a call on
+ *  it, whatever the call's tool is called (a caller's tool declaring a read path target is on the read face too)? */
+export declare function faceRowsSpeakFor(face: DenyFace | undefined): boolean;
 /**
  * The tools whose rule content NAMES THE VALUE of one parameter instead of a command or a path — the reference's `Skill(<name>)`
  * form, one row per tool: `param` is the argument the rule's content is read against, `params` every scalar argument the tool
@@ -949,6 +950,9 @@ export interface PersistedRuleVerdict {
      *  the lexer's reason. The lane projects it as an UNREADABLE answer carrying that reason (it fails closed)
      *  — never as a matched ask rule. */
     readonly unreadable?: string;
+    /** A path DENY's coordinates: the view of the target the reaching row met and the face the call is on. Minted here,
+     *  with the verdict; the gate's exits mint the refusal's card from it and judge nothing a second time. */
+    readonly denial?: PathDenialEvidence;
 }
 /**
  * The ONE adjudication over a MIXED persisted-rule table for a shell call: walk the behaviors in
@@ -991,10 +995,12 @@ export declare function adjudicatePersistedRules(rules: readonly PersistedRule[]
  *
  * A row is anchored by `anchorsOf` (the person's rows: a project row at its scope root, the rest at the chain's top leg).
  *
- * `call.face` is the face the call's protective target is on (`read` / `write`): an ASK row speaks for the call when it
- * is the call's tool's row, or when {@link PATH_RULE_FACES} puts that face in the row's ask column (a `Read(<path>)` ask
- * row asks for a Grep / Glob searching under the path). A deny row's reach beyond its tool is not judged here: it is the
- * run's deny tables, taken at prepare, which refuse inside the tool and descend into a search's results.
+ * `call.face` is the face the call's protective target is on (`read` / `write`): a tightening row (deny or ask) speaks for
+ * the call when it is the call's tool's row, or when {@link PATH_RULE_FACES} puts that face in the row's column of THAT
+ * behavior (a `Read(<path>)` deny row refuses, a `Read(<path>)` ask row asks for, a Grep / Glob / RepoMap / caller's reader
+ * searching or reading under the path) — the one sentence the rule policy's lane speaks too. Both directions judge the call's
+ * own target here; the run's deny tables are a different job (a search's results, a shell command's operands, the
+ * execution-time re-judgment).
  */
 export declare function adjudicatePersistedPathRules(rules: readonly PersistedRule[], call: {
     tool: string;

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

@@ -38,8 +38,8 @@ export function callPathFaceOf(call) {
     const target = protectivePathTargetOf(call);
     return target === undefined ? undefined : target.access === "read" ? "read" : "write";
 }
-export function faceAskSpeaksFor(face) {
-    return face !== undefined && Object.values(PATH_RULE_FACES).some((columns) => columns.ask?.includes(face) === true);
+export function faceRowsSpeakFor(face) {
+    return face !== undefined && Object.values(PATH_RULE_FACES).some((columns) => columns.deny?.includes(face) === true || columns.ask?.includes(face) === true);
 }
 export const NAME_RULE_FACES = Object.freeze({
     Skill: Object.freeze({ param: "skill", params: Object.freeze(["skill", "args"]) }),
@@ -1000,7 +1000,7 @@ export function adjudicatePersistedRules(rules, call) {
 }
 export function adjudicatePersistedPathRules(rules, call, views, anchorsOf, leads) {
     const speaks = (rule, behavior) => eligiblePersisted(rule, call, behavior) ||
-        (behavior === "ask" && call.face !== undefined && PATH_RULE_FACES[rule.tool]?.ask?.includes(call.face) === true && eligiblePersisted(rule, { ...call, tool: rule.tool }, behavior));
+        (call.face !== undefined && PATH_RULE_FACES[rule.tool]?.[behavior]?.includes(call.face) === true && eligiblePersisted(rule, { ...call, tool: rule.tool }, behavior));
     const bind = (rows) => bindPathRules(rows.map((rule) => ({ parsed: rule, ruleText: rule.rule, rule })), (s) => anchorsOf(s.rule));
     for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
         if (behavior === "allow") {
@@ -1021,7 +1021,10 @@ export function adjudicatePersistedPathRules(rules, call, views, anchorsOf, lead
         const hit = judgeRuleRows(rowsWhereTheyLead(bind(rows), leads), views.tighten, "tighten");
         if (hit === undefined)
             continue;
-        return hit.unreadable !== undefined ? { behavior: "ask", rules: [hit.row.spec.rule], unreadable: hit.unreadable } : { behavior, rules: [hit.row.spec.rule] };
+        const rule = hit.row.spec.rule;
+        if (hit.unreadable !== undefined)
+            return { behavior: "ask", rules: [rule], unreadable: hit.unreadable };
+        return { behavior, rules: [rule], ...(behavior === "deny" && hit.view !== undefined && call.face !== undefined ? { denial: { rule: rule.rule, view: hit.view, face: call.face } } : {}) };
     }
     return undefined;
 }

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

@@ -61,6 +61,17 @@ export interface RemovedPermissionRule {
     source: "user" | "project";
     status: "removed";
 }
+/** One read of the person's store as every consumer of it reads it, the failure law applied (a run's one reader of it,
+ *  `person-path-rows.ts`, takes it; the rule lanes and the read station read it). */
+export interface PersonRowsRead {
+    /** The rows this read stands on: each partition it read, as read; each it could not read, the deny and ask rows of the
+     *  run's last successful read of that partition (none before one). This session's rows first. */
+    readonly rules: readonly EffectivePermissionRule[];
+    /** The org partition's resolution off this read. Absent when the whole read failed — {@link unreadable} says why. */
+    readonly org?: OrgRuleResolution;
+    /** Present iff a personal partition (or the whole read) could not be read: the failure's line. */
+    readonly unreadable?: string;
+}
 /** THE answer of the store's one read query. */
 export interface EffectivePermissionRules {
     /** Live personal rows, in reporting order: this session's rows first (the narrowest standing yes), then

package/dist/core/permission-rules.d.ts

@@ -57,7 +57,7 @@
  *    匹配,不是 shell AST / 前缀 lane —— `Bash(command:git push*)` 匹配不了 `cd /x && git push`,
  *    「以为挡住了」比没挡更危险。`primaryFieldGeneric:"allow-lexical"` 显式解锁。
  */
-import type { NamedToolPolicy } from "./tool-policy.js";
+import { type NamedToolPolicy } from "./tool-policy.js";
 import { parsePermissionRule, type ParsedPermissionRule } from "./permission-rule-syntax.js";
 import { type PathRuleBases } from "./permission-rule-model.js";
 export { parsePermissionRule, type ParsedPermissionRule };

package/dist/core/permission-rules.js

@@ -1,3 +1,4 @@
+import { attest } from "./tool-policy.js";
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
@@ -348,7 +349,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 const hit = judgeRuleRows(rows, views, "tighten");
                 const rule = hit === undefined ? undefined : pathLane.find((r) => of.get(r).spec === hit.row.spec);
                 if (hit !== undefined && hit.unreadable === undefined)
-                    return { rule: rule };
+                    return { rule: rule, ...(hit.view !== undefined ? { view: hit.view } : {}) };
                 if (hit !== undefined)
                     return judgeOthers(lane.filter((r) => !pathRuleOf.has(r)), req) ?? { rule: rule, unreadable: hit.unreadable };
             }
@@ -416,7 +417,9 @@ export function createPermissionRulePolicy(rules, opts) {
             const denyLane = contentLaneOf("deny", entry, shellCall, callFace);
             const contentDeny = denyLane.length > 0 ? contentHit(denyLane, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
-                return { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
+                const denied = { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
+                const face = contentDeny.view !== undefined ? callPathFaceOf(req) : undefined;
+                return face !== undefined ? attest(denied, req, { pathDenial: { rule: contentDeny.rule.ruleText, view: contentDeny.view, face } }) : denied;
             }
             if (entry) {
                 const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);

package/dist/core/persisted-rule-arms.d.ts

@@ -11,14 +11,15 @@
  * the read closes over the gate input, and the allow arm is a conjunction over the gate's own state
  * (mandates, the org latch, the marked-call seat) rather than a function of the answer alone.
  */
-import type { PermissionResult } from "./tool-policy.js";
+import { type PermissionResult, type ToolCallRequest } from "./tool-policy.js";
 import type { PersistedRuleAnswer, PersistedRuleHit, PersistedRuleHitRule } from "./hooks.js";
 /** The lane's one read, normalized: at most one of `hit` / `unreadable` / `coverage` (the gate's reader
  *  produces it; the arms below read it). */
 export interface PersistedRuleRead {
     readonly hit?: PersistedRuleHit;
     /** The lane could not answer: with `reason`, the CALL could not be read against the person's deny/ask rows;
-     *  without, the store could not be read — its rows take no part in the decision (the record says so). */
+     *  without, a partition of the store (or all of it) could not be read — a deny / ask row inside it may forbid this call,
+     *  so no allow beside it is a yes (the lane has already folded that: an allow, a coverage or nothing reads as this). */
     readonly unreadable?: true;
     /** The lexer's reason when the CALL could not be read against the person's deny/ask rows. */
     readonly reason?: string;
@@ -42,7 +43,9 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *  · DENY — the call is refused outright, with `decisionReason: "persisted_rule"` (the same word the
  *    lane's allow carries: one authority, one word) and the rule text disclosed through the display
  *    transform; the STATION attributes the refusal (`tightened: "deny"` ⇒ it writes the pass's refusing
- *    layer — the attribution is a station's word and lives in the station file).
+ *    layer — the attribution is a station's word and lives in the station file). A path row's hit reports where
+ *    it met the call; with `call` given and the face the call's own, the deny carries that as its attested `pathDenial`, so every exit that
+ *    reads the deny (the gate's exit, the approved-edit re-check, a resumed leg's belt) mints the same card from the same fact.
  *  · ASK — on an allow, a fresh ask is minted carrying `matchedAskRule` (the marker an explicit `ask`
  *    permission rule stamps, so the ask's origin derives as `ask_rule`: the classifier never answers
  *    it, the persisted ALLOW arm never clears it, and the rule-offer face reports `shadowed`); on an
@@ -55,11 +58,16 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *    an allow tightens to an ask carrying `requiresRealApproval` (no automatic lane clears it; the gate
  *    derives the origin `rule_store_unavailable` from its own record of the read), an ask acquires the
  *    bit, a deny stays a deny.
- * A store that could not be READ (`unreadable` without a `reason`) contributes no row: the decision is returned
- * untouched, as for no hit — the lane announces the skipped store, and the rows apply again once a read succeeds.
+ *  · UNREADABLE STORE — a partition of the store (or all of it) could not be READ (`unreadable` without a `reason`): a deny
+ *    or ask row inside it may forbid this call and nobody can tell, so it fails CLOSED the same way, to the question
+ *    only a person answers — an allow becomes an ask carrying `requiresRealApproval`, an ask acquires the bit, a deny stays
+ *    a deny. Every call the lane judges is in this state until a read succeeds again (the lane announces the skipped store,
+ *    once per run, and reads again on the next call). The two forms differ in WHICH fact the gate records (the call form
+ *    is the class `rule_unreadable`; the store form `governance_unavailable` — both bypass-immune) and in the
+ *    resumed-call belt, which vetoes only the call form: a person already answered that call's question.
  * An allow hit (or no hit) returns the decision untouched: the allow arm is the station's.
  */
-export declare function applyPersistedTightening(decision: PermissionResult, read: PersistedRuleRead | undefined): {
+export declare function applyPersistedTightening(decision: PermissionResult, read: PersistedRuleRead | undefined, call?: ToolCallRequest): {
     decision: PermissionResult;
-    tightened?: "deny" | "ask" | "unreadable";
+    tightened?: "deny" | "ask" | "unreadable" | "store_unreadable";
 };