@sema-agent/core 6.0.0 → 7.0.1

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

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { escapeForDisclosure, hasUnrenderableCharacters, parseAllowRuleText, ruleAdmitsCommand, segmentCoverageOf, suggestRulesForCommand, translateImportedWildcardRule, } from "./permission-rule-model.js";
-import { errText, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
+import { errText, isValidConsentScope, normalizePersistedRule, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
     async get(id) {
@@ -121,6 +121,9 @@ function approvalRecordDamageOf(rec) {
             if (typeof cand !== "object" || cand === null || typeof cand.rule !== "string") {
                 return `offer ${at} references candidate ${member}, which is not a candidate row`;
             }
+            if (!isValidConsentScope(cand.scope)) {
+                return `offer ${at} references candidate ${member}, whose scope is not a consent-face scope (global, project, or session)`;
+            }
             if (seen.has(member))
                 return `batch offer ${at} references candidate ${member} twice`;
             seen.add(member);
@@ -196,11 +199,42 @@ export async function prepareCardApproval(opts) {
     }
     if (opts.toolName !== CARD_RULE_TOOL)
         return undefined;
-    const scope = opts.scope ?? { kind: "global" };
+    const scope = (() => {
+        if (opts.scope !== undefined) {
+            if (!isValidConsentScope(opts.scope)) {
+                const e = new Error("prepareCardApproval got a scope that is not a consent-face scope (global, project with a non-empty root, or session with a non-empty sessionId) — refusing to guess where this consent should land");
+                e.code = "config.invalid_argument";
+                throw e;
+            }
+            return opts.scope;
+        }
+        if (opts.cwd !== undefined) {
+            if (typeof opts.cwd !== "string" || opts.cwd === "") {
+                const e = new Error("prepareCardApproval got a cwd that is not a usable path — it cannot anchor the derived project scope, and refusing beats minting a rule scoped to garbage");
+                e.code = "config.invalid_argument";
+                throw e;
+            }
+            return { kind: "project", root: opts.cwd };
+        }
+        const e = new Error("prepareCardApproval was given neither a scope nor a cwd — there is nowhere for this consent to land, and no direction of silence is honest (config.missing_scope): pass an explicit scope, or thread the adjudicated call's cwd");
+        e.code = "config.missing_scope";
+        throw e;
+    })();
     let coverage;
     try {
         const listed = await storeForOwner(opts.deps.provider, owner).list();
-        coverage = segmentCoverageOf(opts.command, { persisted: listed.rules }, { tool: CARD_RULE_TOOL, cwd: opts.cwd });
+        let table = listed.rules;
+        const overlay = opts.deps.sessionRules;
+        if (overlay !== undefined && opts.sessionId !== undefined) {
+            const served = structuredClone(await overlay.read(opts.sessionId));
+            const sessionRows = served.filter((r) => {
+                const scope = r?.scope;
+                return scope?.kind === "session" && scope.sessionId === opts.sessionId && !("reject" in normalizePersistedRule(r));
+            });
+            if (sessionRows.length > 0)
+                table = [...sessionRows, ...listed.rules];
+        }
+        coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId });
     }
     catch {
         coverage = undefined;
@@ -497,6 +531,41 @@ async function applyRedemption(args) {
     if (writer === undefined)
         return { status: "refused", reason: "the resolved permission-rule store has no write face" };
     const origin = originOfRecordKind(args.kind);
+    if (args.candidate.scope.kind === "session") {
+        const overlay = args.deps.sessionRules;
+        if (overlay === undefined) {
+            return {
+                status: "refused",
+                reason: "this deployment wired no session-rule overlay (RuleConsentDeps.sessionRules) — a session-scope authorization has nowhere to land",
+            };
+        }
+        let outcome;
+        try {
+            outcome = await overlay.apply(args.candidate.scope.sessionId, {
+                rule: args.parsedRule.rule,
+                tool: args.parsedRule.tool,
+                match: args.parsedRule.match,
+                command: args.parsedRule.command,
+                add: { dot: args.dot, origin, createdAt: nowIso(args.deps) },
+            });
+        }
+        catch (err) {
+            return { status: "refused", reason: `the session-rule overlay refused the write: ${errText(err)}` };
+        }
+        if ("refused" in outcome) {
+            return {
+                status: "refused",
+                reason: "the session this authorization targets has ended — a session rule dies with its session, and a late or replayed redemption cannot revive it (re-trigger the command in a live session for a fresh card)",
+            };
+        }
+        let rev = 0;
+        try {
+            rev = (await store.list()).rev;
+        }
+        catch {
+        }
+        return { status: "redeemed", rule: args.parsedRule.rule, scope: args.candidate.scope, dot: args.dot, rev, alreadyRedeemed: args.replay };
+    }
     for (let attempt = 0; attempt < REDEEM_MAX_ATTEMPTS; attempt++) {
         let rev;
         try {
@@ -717,14 +786,27 @@ export async function redeemRuleBatch(opts) {
         const candidate = rec.candidates[candidateIndex];
         const row = { candidateIndex, rule: candidate.rule, scope: candidate.scope };
         let alreadyThere = false;
-        try {
-            const snap = await store.list();
-            rev = snap.rev;
-            alreadyThere = snap.rules.some((r) => r.rule === candidate.rule && sameScope(r.scope, candidate.scope));
+        if (candidate.scope.kind === "session") {
+            const sessionScope = candidate.scope;
+            try {
+                const overlayRows = opts.deps.sessionRules === undefined ? [] : await opts.deps.sessionRules.read(sessionScope.sessionId);
+                alreadyThere = overlayRows.some((r) => r.rule === candidate.rule && sameScope(r.scope, sessionScope));
+            }
+            catch (err) {
+                members.push({ ...row, status: "refused", reason: `could not read the session-rule overlay: ${errText(err)}` });
+                continue;
+            }
         }
-        catch (err) {
-            members.push({ ...row, status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` });
-            continue;
+        else {
+            try {
+                const snap = await store.list();
+                rev = snap.rev;
+                alreadyThere = snap.rules.some((r) => r.rule === candidate.rule && sameScope(r.scope, candidate.scope));
+            }
+            catch (err) {
+                members.push({ ...row, status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` });
+                continue;
+            }
         }
         const res = await redeemRuleTicket({
             ticket: mintRuleTicket(rec.id, candidateIndex),
@@ -735,7 +817,7 @@ export async function redeemRuleBatch(opts) {
             members.push({ ...row, status: "refused", reason: res.reason });
             continue;
         }
-        rev = res.rev;
+        rev = candidate.scope.kind === "session" ? Math.max(rev, res.rev) : res.rev;
         members.push({ ...row, status: alreadyThere ? "deduped" : "persisted", alreadyRedeemed: res.alreadyRedeemed, dot: res.dot });
     }
     return { members, rev };

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

@@ -69,18 +69,43 @@ export type PersistedRuleTool = "Bash";
 /** v1 match forms. `"wildcard"` is reserved for v2 and is not a value this version ever produces. */
 export type PersistedRuleMatch = "exact" | "prefix";
 /**
- * Where a rule applies. A rule read out of a project-local settings layer applies ONLY inside that
- * project's canonical root — project A's approval is not project B's. User-layer, starter and
- * user-minted rules are global.
- *
- * `root` is expected to be already canonicalized (realpath) by whoever constructs the scope; the
- * matcher compares with word-boundary containment, never a bare `startsWith` (`/a` must not reach `/ab`).
+ * Where a rule applies — design/382 §4.1, the THREE consent dimensions.
+ *
+ *  · `global` — the personal-global dimension: this OWNER's rules, everywhere (the bucket is already
+ *    per-owner, {@link import("./permission-rule-store.js").RuleOwner}). The member keeps its historical
+ *    spelling on purpose: renaming it `personal-global` would be a no-benefit migration of every stored
+ *    row; the "personal" half lives in documentation and card wording, not in the wire byte.
+ *  · `project` — applies ONLY inside `root`. `root` is expected to be already canonicalized (realpath)
+ *    by whoever constructs the scope; the matcher compares with word-boundary containment, never a bare
+ *    `startsWith` (`/a` must not reach `/ab`).
+ *  · `session` — applies ONLY to calls of the ONE session it names, and lives in that session's own
+ *    state (the host's session-rule overlay), NEVER in the persisted store: every durable entrance —
+ *    the write deltas, sync in both directions, at-rest bytes — refuses or drops a session row
+ *    (design/382 §4.3, the durable two-member face). `sessionId` uniqueness is the HOST's duty (the
+ *    `principal` posture): reusing an id is a declaration that it is the same session. A session row
+ *    cannot be individually deleted — it dies with its session (design/382 §10, ruled; the durable
+ *    removal entry refuses it rather than answering a false no-op).
+ *
+ * ORG is deliberately NOT a member (design/382 §4.1): an approval card must be structurally unable to
+ * spell an org-wide grant — org governance is a deny/ask snapshot published by an admin surface, with
+ * no allow bucket at all. Unspellable beats runtime-refused; the consent validators refuse the spelling
+ * anyway if a foreign writer plants it.
+ *
+ * TWO NAMED VALIDATION FACES read this union (design/382 §4.3): the CONSENT face (prepare candidates,
+ * approval records, confirm/redeem, batch outcomes) admits all three members
+ * ({@link import("./permission-rule-store.js").isValidConsentScope}); the DURABLE face (the persisted
+ * store's write deltas, rule-sync in both directions, at-rest decode) admits only
+ * `{global, project}` ({@link import("./permission-rule-store.js").isValidDurableScope}). One table
+ * "for both" is exactly what would let a session row leak into the store silently.
  */
 export type RuleScope = {
     kind: "global";
 } | {
     kind: "project";
     root: string;
+} | {
+    kind: "session";
+    sessionId: string;
 };
 /** The immutable causal identity of one add: a replica identity plus a monotonic counter. */
 export interface RuleDot {
@@ -441,9 +466,16 @@ export declare function ruleLaneSegmentsOf(command: string): readonly string[] |
  * not contain `/ab`. Both sides are expected to be canonical already.
  */
 export declare function pathWithinRoot(path: string, root: string): boolean;
-/** Does a rule's scope cover a task running in `cwd`? A project rule needs a cwd to compare against;
- *  without one it covers nothing (fail-closed). */
-export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined): boolean;
+/** Does a rule's scope cover a task running in `cwd` (and, for the session dimension, in the session
+ *  named by `sessionId`)? A project rule needs a cwd to compare against; without one it covers nothing
+ *  (fail-closed). A session rule (design/382 §4.3) covers a call iff the call's `sessionId` equals the
+ *  scope's — and a call that carries NO session identity is covered by no session rule, the same
+ *  fail-closed arm as project-without-cwd: an axis the caller did not thread is an axis the rule
+ *  cannot speak on. `sessionId` is threaded from the ORIGINAL call context by the caller (the 375
+ *  r3-② cwd posture), never inferred from the process. ONE function on purpose: this is the scope
+ *  conjunct of the single eligibility predicate ({@link eligibleContext}), and a sister predicate
+ *  would be the second fact source the 375 §5.1 discipline exists to forbid. */
+export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined, sessionId?: string): boolean;
 /** Is this rule live — i.e. does it still carry at least one add? Deleted adds are removed by the store
  *  when tombstones are applied, so a rule with an empty `adds` is a rule that no longer exists. */
 export declare function isRuleLive(rule: PersistedAllowRule): boolean;
@@ -459,6 +491,12 @@ export declare function isRuleLive(rule: PersistedAllowRule): boolean;
  *
  * `scope` rides beside the rule rather than inside it for the PROPOSED half's sake: a
  * {@link ParsedAllowRule} carries no scope, so a proposal is judged against the scope it would LAND in.
+ *
+ * design/382 §4.3 — the call context carries a THIRD axis, `sessionId` (optional: an existing caller
+ * that threads only `{tool, cwd}` still compiles and still means what it meant — no session rule can
+ * cover its calls, the fail-closed direction). It is the session dimension's whole eligibility story:
+ * every consumer of this ONE predicate (the gate's conjunction arm, the coverage table, the consent
+ * prepare) inherits it without a second judge existing anywhere.
  */
 export declare function eligibleContext(rule: {
     tool: string;
@@ -466,6 +504,7 @@ export declare function eligibleContext(rule: {
 }, call: {
     tool: string;
     cwd: string | undefined;
+    sessionId?: string;
 }): boolean;
 /**
  * design/375 §5.1 — MAY this PERSISTED rule participate in admitting this call at all? The liveness
@@ -481,6 +520,7 @@ export declare function eligibleContext(rule: {
 export declare function eligiblePersisted(rule: PersistedAllowRule, call: {
     tool: string;
     cwd: string | undefined;
+    sessionId?: string;
 }): boolean;
 /**
  * Find the rules that admit this command for a task in `cwd`, or `undefined`.
@@ -515,6 +555,7 @@ export declare function findAdmittingRule(rules: readonly PersistedAllowRule[],
     tool: string;
     command: string;
     cwd: string | undefined;
+    sessionId?: string;
 }): readonly PersistedAllowRule[] | undefined;
 /**
  * design/375 §5.2 — the per-segment coverage table for `command`: which segments an eligible rule
@@ -555,6 +596,7 @@ export declare function segmentCoverageOf(command: string, rules: {
 }, call: {
     tool: string;
     cwd: string | undefined;
+    sessionId?: string;
 }): readonly SegmentCoverage[] | undefined;
 /** One row of a per-segment coverage table (see {@link segmentCoverageOf}): the FOLDED, trimmed
  *  segment text (a display/correlation seat, never adjudication input) and whether an eligible rule

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

@@ -295,16 +295,18 @@ export function pathWithinRoot(path, root) {
     const base = root.endsWith("/") ? root : root + "/";
     return path.startsWith(base);
 }
-export function scopeCoversCwd(scope, cwd) {
+export function scopeCoversCwd(scope, cwd, sessionId) {
     if (scope.kind === "global")
         return true;
+    if (scope.kind === "session")
+        return sessionId !== undefined && sessionId === scope.sessionId;
     return cwd !== undefined && pathWithinRoot(cwd, scope.root);
 }
 export function isRuleLive(rule) {
     return rule.adds.length > 0;
 }
 export function eligibleContext(rule, call) {
-    return rule.tool === call.tool && scopeCoversCwd(rule.scope, call.cwd);
+    return rule.tool === call.tool && scopeCoversCwd(rule.scope, call.cwd, call.sessionId);
 }
 export function eligiblePersisted(rule, call) {
     return isRuleLive(rule) && eligibleContext(rule, call);

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

@@ -0,0 +1,124 @@
+/**
+ * design/382 §4.3 — the SESSION-RULE OVERLAY: where a `{kind:"session"}` scoped allow rule lives.
+ *
+ * A session authorization's home is the session's own state — never the persisted store. The rows are
+ * ordinary {@link PersistedAllowRule}s (scope `session`), so every read-side consumer — the gate's
+ * conjunction arm, the coverage table, the consent prepare — takes them through the ONE eligibility
+ * predicate with zero second judges: the merge point splices overlay rows IN FRONT of the persisted
+ * `list()` (the §4.1 narrowest-first reporting order: session > project > global), and everything
+ * downstream is unchanged.
+ *
+ * ## The contract (design/382 §8-Q6, settled here)
+ *
+ * TWO verbs, and deliberately no third:
+ *  · `read(sessionId)` — the live rows of ONE session, session-scoped, that session's only.
+ *  · `apply(sessionId, add)` — land one redeemed authorization. Idempotent BY DOT (the redemption
+ *    replay contract: `alreadyRedeemed` marks the dot as RECORDED, not the overlay as LANDED, so a
+ *    replay must RE-APPLY, and this verb is what makes re-applying safe); refuses `session_ended`
+ *    once the session's lifetime epoch is sealed — a late in-flight write after termination must not
+ *    revive an authorization for a session that no longer exists.
+ *
+ * There is deliberately NO delete verb: a session row is not individually deletable — it dies with
+ * its session (design/382 §10, ruled). Termination is the HOST's act on its own implementation (see
+ * {@link InMemorySessionRuleOverlay.endSession}), not an engine verb.
+ *
+ * ## Lifecycle and durability
+ *
+ * The overlay lives WITH the session: a host that parks/checkpoints a session serializes its rows
+ * beside it and rehydrates them on resume (`snapshotSession`/`restoreSession` on the reference
+ * implementation) — that is how a session authorization survives a park without ever touching the
+ * persisted store, and why it still ends when the session ends. `sessionId` uniqueness is the host's
+ * duty (the `principal` posture): reusing an id declares "the same session".
+ *
+ * ## What this is NOT
+ *
+ * Not a store backend: no dots are minted here (the redemption leg mints the audit dot exactly as the
+ * store leg does), no tombstones exist here, nothing here syncs. Every durable entrance — write
+ * deltas, sync in both directions, at-rest bytes — refuses or drops a session row
+ * (`permission-rule-store.ts`, the durable two-member face); this module is the OTHER side of that
+ * wall, and the wall is the design.
+ */
+import type { PersistedAllowRule, RuleAdd, PersistedRuleMatch, PersistedRuleTool } from "./permission-rule-model.js";
+/** One redeemed authorization landing in a session's overlay: the rule's canonical shape plus the
+ *  redemption's own add (dot + provenance) — the same fields a `redemption-add` delta carries, minus
+ *  the scope (the verb's `sessionId` IS the scope, constructed here so a caller cannot land a row
+ *  whose scope names a different session than the one it addressed). */
+export interface SessionRuleOverlayAdd {
+    rule: string;
+    tool: PersistedRuleTool;
+    match: PersistedRuleMatch;
+    command: string;
+    add: RuleAdd;
+}
+/** What one overlay apply answered. `session_ended` is the epoch fence speaking: the write arrived at
+ *  (or after) termination and landed nothing — the redemption reports the member `refused`. */
+export type SessionRuleOverlayApplyResult = {
+    landed: true;
+} | {
+    refused: "session_ended";
+};
+/**
+ * The host-provided seam the consent lane and the gate's rule lane consume
+ * (`RuleConsentDeps.sessionRules`, `RunnerDeps.sessionPermissionRules`). See the module doc for the
+ * contract; {@link InMemorySessionRuleOverlay} is the reference implementation and the semantics.
+ */
+export interface SessionRuleOverlay {
+    /** The live session-scoped rows of ONE session. An ended (or never-written) session reads as `[]`. */
+    read(sessionId: string): Promise<readonly PersistedAllowRule[]>;
+    /** Land one redeemed authorization — idempotent by dot, refused once the session ended. */
+    apply(sessionId: string, add: SessionRuleOverlayAdd): Promise<SessionRuleOverlayApplyResult>;
+}
+/**
+ * The reference overlay — in-memory, per-process, the semantics every host implementation must keep:
+ *
+ *  · APPLY is idempotent by dot identity (a replayed redemption re-submits its recorded dot and
+ *    changes nothing — the store's `foldDelta` discipline, verbatim);
+ *  · TERMINATION seals FIRST, clears SECOND ({@link endSession}): the sealed-set membership is the
+ *    session's lifetime epoch, flipped atomically before any state is dropped, so an in-flight write
+ *    that lost the race lands on the seal and answers `session_ended` — never on a half-cleared
+ *    session, and never as a row that outlives its session (design/382 §4.3, the r2-⑥ fence);
+ *  · a sealed session never reopens — `apply` and `restoreSession` both refuse it, so "session ended"
+ *    is a one-way fact exactly like a quarantined dot's;
+ *  · SNAPSHOT/RESTORE ({@link snapshotSession}/{@link restoreSession}) are the park/resume carriage:
+ *    the host serializes a session's rows into its checkpoint and rehydrates them on resume. Restore
+ *    is fail-closed on shape — every row must be a session row of THE session being restored (a
+ *    checkpoint is host-owned bytes, and a global row smuggled through this door would ride the
+ *    merge point straight into adjudication).
+ */
+export declare class InMemorySessionRuleOverlay implements SessionRuleOverlay {
+    private readonly rows;
+    private readonly sealed;
+    /** How many times one session's row set has CHANGED. Reading a caller-owned value runs caller code,
+     *  so a verb that reads its argument and then replaces a session's rows wholesale must be able to
+     *  tell that something landed in between — otherwise it overwrites a grant that was already answered
+     *  `landed:true`, and a consent nobody withdrew stops existing. Bumped by every landing, restore and
+     *  termination; read across `restoreSession`'s snapshot. */
+    private readonly epochs;
+    private bumpEpoch;
+    read(sessionId: string): Promise<readonly PersistedAllowRule[]>;
+    apply(sessionId: string, add: SessionRuleOverlayAdd): Promise<SessionRuleOverlayApplyResult>;
+    /**
+     * The termination transfer: SEAL the lifetime epoch first (one atomic membership flip — after this
+     * line every in-flight `apply` holding this id answers `session_ended`), THEN drop the rows. The
+     * order is the whole fence: clear-then-seal would leave a window in which a late write re-grows a
+     * rule set for a session that is already gone. Idempotent; a never-seen id seals to the same place.
+     */
+    endSession(sessionId: string): void;
+    /** The park half of the checkpoint carriage: this session's rows, serializable as-is. */
+    snapshotSession(sessionId: string): Promise<readonly PersistedAllowRule[]>;
+    /**
+     * The resume half. Fail-closed on every axis: a sealed session never rehydrates (termination is
+     * one-way), and every row must be a well-formed SESSION row of exactly this session — anything else
+     * in the checkpoint bytes is refused whole, loudly, because the merge point trusts this overlay to
+     * serve only what its contract says it holds.
+     *
+     * The rows also pass the SAME `normalizePersistedRule` re-projection the sync face runs on store
+     * rows (rule text parses, canonical spelling, stored tool/match/command agree with the text): this
+     * door takes host-owned checkpoint bytes with no redemption validator in front of them, and a row
+     * the engine could not re-project would otherwise sit one merge away from adjudication. Rows this
+     * overlay landed itself always pass — {@link InMemorySessionRuleOverlay.apply} runs the same screen,
+     * so the two doors agree on what a session row is and a snapshot of this overlay always restores —
+     * which is what makes a refusal here foreign damage, refused whole.
+     */
+    restoreSession(sessionId: string, rows: readonly PersistedAllowRule[]): Promise<void>;
+}

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

@@ -0,0 +1,121 @@
+import { isValidConsentScope, normalizePersistedRule } from "./permission-rule-store.js";
+function isValidOverlayAdd(add) {
+    const a = add;
+    if (typeof a?.dot?.actor !== "string" || a.dot.actor === "" || typeof a.dot.counter !== "number" || !Number.isFinite(a.dot.counter))
+        return false;
+    if (a.origin !== "user" && a.origin !== "imported-cc" && a.origin !== "starter")
+        return false;
+    return typeof a.createdAt === "string";
+}
+export class InMemorySessionRuleOverlay {
+    rows = new Map();
+    sealed = new Set();
+    epochs = new Map();
+    bumpEpoch(sessionId) {
+        this.epochs.set(sessionId, (this.epochs.get(sessionId) ?? 0) + 1);
+    }
+    async read(sessionId) {
+        return structuredClone(this.rows.get(sessionId) ?? []);
+    }
+    async apply(sessionId, add) {
+        if (this.sealed.has(sessionId))
+            return { refused: "session_ended" };
+        add = structuredClone(add);
+        if (this.sealed.has(sessionId))
+            return { refused: "session_ended" };
+        if (!isValidOverlayAdd(add?.add)) {
+            throw new Error("SessionRuleOverlay.apply was handed a malformed add (dot/origin/createdAt) — evidence this shape cannot vouch for must not install");
+        }
+        const scope = { kind: "session", sessionId };
+        if (!isValidConsentScope(scope)) {
+            throw new Error("SessionRuleOverlay.apply was addressed with an unusable session id — a session nobody can name is not a scope a grant can live under");
+        }
+        const projected = { rule: add.rule, tool: add.tool, match: add.match, command: add.command, scope, adds: [add.add] };
+        if ("reject" in normalizePersistedRule(projected)) {
+            throw new Error("SessionRuleOverlay.apply was handed a row whose text/metadata do not survive the canonical re-projection — a row the engine cannot re-project can never adjudicate, and would refuse its own restore");
+        }
+        const rows = this.rows.get(sessionId) ?? [];
+        if (!this.rows.has(sessionId))
+            this.rows.set(sessionId, rows);
+        const sameDotAs = (a) => a.dot.actor === add.add.dot.actor && a.dot.counter === add.add.dot.counter;
+        for (const [heldSession, heldRows] of this.rows) {
+            const holder = heldRows.find((r) => r.adds.some(sameDotAs));
+            if (holder !== undefined && (heldSession !== sessionId || holder.rule !== add.rule)) {
+                throw new Error(`SessionRuleOverlay.apply: dot ${add.add.dot.actor}#${add.add.dot.counter} already vouches for another grant — a dot identifies one add of one (rule, session), ever`);
+            }
+        }
+        const existing = rows.find((r) => r.rule === add.rule);
+        if (existing === undefined) {
+            rows.push({ rule: add.rule, tool: add.tool, match: add.match, command: add.command, scope, adds: [structuredClone(add.add)] });
+            this.bumpEpoch(sessionId);
+            return { landed: true };
+        }
+        if (!existing.adds.some((a) => a.dot.actor === add.add.dot.actor && a.dot.counter === add.add.dot.counter)) {
+            existing.adds.push(structuredClone(add.add));
+            this.bumpEpoch(sessionId);
+        }
+        return { landed: true };
+    }
+    endSession(sessionId) {
+        this.sealed.add(sessionId);
+        this.rows.delete(sessionId);
+        this.bumpEpoch(sessionId);
+    }
+    async snapshotSession(sessionId) {
+        return this.read(sessionId);
+    }
+    async restoreSession(sessionId, rows) {
+        if (this.sealed.has(sessionId)) {
+            throw new Error(`session "${sessionId}" has ended — a sealed session's authorizations cannot be restored (termination is one-way)`);
+        }
+        const epochBeforeRead = this.epochs.get(sessionId) ?? 0;
+        rows = structuredClone(rows);
+        if (this.sealed.has(sessionId)) {
+            throw new Error(`session "${sessionId}" has ended — a sealed session's authorizations cannot be restored (termination is one-way)`);
+        }
+        if ((this.epochs.get(sessionId) ?? 0) !== epochBeforeRead) {
+            throw new Error(`restoreSession("${sessionId}") raced a landing on the same session — refusing the whole restore (this door replaces the session's rows, and a grant that already answered landed must not be erased by a resume)`);
+        }
+        for (const r of rows) {
+            const scope = r?.scope;
+            if (scope?.kind !== "session" || scope.sessionId !== sessionId || !isValidConsentScope(scope)) {
+                throw new Error(`restoreSession("${sessionId}") was handed a row that is not a session row of that session — refusing the whole restore (a foreign-scope row through this door would reach adjudication)`);
+            }
+            if ("reject" in normalizePersistedRule(r)) {
+                throw new Error(`restoreSession("${sessionId}") was handed a row whose text/metadata do not survive the canonical re-projection — refusing the whole restore (a row the engine cannot re-project must not reach adjudication)`);
+            }
+        }
+        const ownDotRule = new Map();
+        for (const held of this.rows.get(sessionId) ?? []) {
+            for (const h of held.adds)
+                ownDotRule.set(`${h.dot.actor}#${h.dot.counter}`, held.rule);
+        }
+        const seenDots = new Map();
+        for (const r of rows) {
+            if (!Array.isArray(r.adds) || r.adds.length === 0 || !r.adds.every(isValidOverlayAdd)) {
+                throw new Error(`restoreSession("${sessionId}") was handed a row with malformed add evidence — refusing the whole restore (an add whose dot/origin cannot be read is not a consent anyone can audit)`);
+            }
+            for (const a of r.adds) {
+                const key = `${a.dot.actor}#${a.dot.counter}`;
+                const holder = seenDots.get(key);
+                if (holder !== undefined && holder !== r.rule) {
+                    throw new Error(`restoreSession("${sessionId}"): dot ${key} vouches for two different rules — refusing the whole restore`);
+                }
+                seenDots.set(key, r.rule);
+                const ownHolder = ownDotRule.get(key);
+                if (ownHolder !== undefined && ownHolder !== r.rule) {
+                    throw new Error(`restoreSession("${sessionId}"): dot ${key} is live in this session under a different rule — a restore may replay a grant, never reassign its dot; refusing the whole restore`);
+                }
+                for (const [heldSession, heldRows] of this.rows) {
+                    if (heldSession === sessionId)
+                        continue;
+                    if (heldRows.some((held) => held.adds.some((h) => h.dot.actor === a.dot.actor && h.dot.counter === a.dot.counter))) {
+                        throw new Error(`restoreSession("${sessionId}"): dot ${key} already vouches for another live session's grant — refusing the whole restore`);
+                    }
+                }
+            }
+        }
+        this.rows.set(sessionId, rows);
+        this.bumpEpoch(sessionId);
+    }
+}

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

@@ -215,7 +215,8 @@ export interface WritablePermissionRuleStore extends PermissionRuleStore {
 }
 /** The writer of a store, or `undefined` when the backend is read-only from the engine's side. */
 export declare function writerOf(store: PermissionRuleStore): PermissionRuleWriter | undefined;
-/** Do two scopes name the same place? */
+/** Do two scopes name the same place? Three members (design/382 §4.1): global, project-by-root,
+ *  session-by-sessionId. */
 export declare function sameScope(a: RuleScope, b: RuleScope): boolean;
 /**
  * Apply tombstones to a raw persisted set: an add survives iff its dot appears in no tombstone for the
@@ -238,6 +239,33 @@ export declare function addDotsOf(rules: readonly PersistedAllowRule[]): RuleDot
  * Every backend calls this before appending a tombstone.
  */
 export declare function assertDeleteDeltaCarriesNoAdd(delta: RuleDeleteDelta): void;
+/**
+ * design/382 §4.3 — the DURABLE-scope gate of the two direct write arms, shared by every backend
+ * (the `assertDeleteDeltaCarriesNoAdd` doctrine: the check is executed, not merely intended, because a
+ * union does not constrain a JavaScript caller's payload).
+ *
+ * A `redemption-add` whose scope — or a `tighten-delete` whose tombstone's scope — is a session scope
+ * refuses LOUDLY with the typed code `unsupported.session_scope_store`: a session authorization's home
+ * is the session's own overlay, and a session TOMBSTONE is equally unspellable here — session rows are
+ * not individually deletable (they die with their session, design/382 §10), so a tombstone naming one
+ * is either a foreign writer's fabrication or a caller wiring fault, and both deserve the loud arm.
+ * The third arm (`sync-join`) is NOT gated here: its session rows are per-row DROPPED AND DISCLOSED by
+ * {@link screenRuleSyncState} (a peer's damage must not veto a whole round the way a local caller's
+ * bug must), and a session-scoped QUARANTINE instruction throws inside {@link applySyncJoin} itself.
+ *
+ * The session member is the LOUD, typed arm; the rest of the face is executed too. A scope that is
+ * neither member in well-formed shape — `{kind:"project", root:""}` above all, which `pathWithinRoot`
+ * turns into base `/` so the row crosses every project boundary — is a caller wiring fault, refused
+ * with the untyped loud arm the sibling {@link assertDeleteDeltaCarriesNoAdd} uses (no closed-set code
+ * names it: it is nobody's supported request). The sync arm already refuses the same shape inbound
+ * ({@link applySyncJoin} runs {@link isValidDurableScope} on every joined row), so this closes the
+ * matching direct-write door rather than inventing a new rule.
+ *
+ * Exported with the backend contract for the same OPEN-SET duty {@link isValidDurableScope} names:
+ * any lane — host-side import doors included — that writes rows into a persisted store carries the
+ * durable two-member face.
+ */
+export declare function assertWriteDeltaScopeDurable(delta: RuleAddDelta | RuleDeleteDelta): void;
 /**
  * The state one sync round exchanges: raw adds (tombstoned dots NOT pre-filtered) plus tombstones.
  * The live view is always DERIVED (`applyTombstones`); the join below never deletes anything.
@@ -291,6 +319,27 @@ export interface RuleSyncLandingReport {
      *  a dropped tombstone may have covered them — they re-arrive once the peer's state is clean). */
     withheldAdds: number;
 }
+/**
+ * design/382 §4.3 — the CONSENT face's scope validity: the union's full three members, their shapes
+ * executed (a project scope with an empty root would admit every cwd, wider than global, through
+ * `pathWithinRoot`'s base construction; an empty sessionId would be a session nobody can name).
+ * Read by the consent protocol's entries (prepare's explicit-scope gate, the record integrity walk),
+ * and exported for the server's consent-projection twin. NEVER by a durable entrance — that face is
+ * {@link isValidDurableScope}, and keeping the two as separate named tables is the design's point:
+ * a session row leaking toward the store must meet an explicit refusal at every door, not a shared
+ * table someone widened for the other face's sake.
+ */
+export declare function isValidConsentScope(scope: RuleScope): boolean;
+/**
+ * design/382 §4.3 — the DURABLE face's scope validity: the two members a persisted row may carry,
+ * `{global, project}`. A session scope is a WELL-FORMED consent scope that is structurally not a
+ * durable one — session authorizations live in the session's own overlay and die with it; letting one
+ * into the store (or the sync wire, or the at-rest bytes) would give it exactly the afterlife the
+ * dimension is defined not to have. Exported for the server's rule-sync validator (same face, same
+ * two members) and for any host-side lane that writes rows into a persisted store — the OPEN-SET
+ * duty (design/382 §10): every such entrance, present or future, carries this face.
+ */
+export declare function isValidDurableScope(scope: RuleScope): boolean;
 /** Is `dot` at or below the frontier? Absent actor ⇒ not below (a frontier never covers what it never saw). */
 export declare function dotAtOrBelowFrontier(dot: RuleDot, frontier: RuleSyncFrontier): boolean;
 /**
@@ -314,7 +363,21 @@ export declare function normalizePersistedRule(r: PersistedAllowRule): {
 } | {
     reject: Extract<RuleSyncDropReason, "invalid_rule_text" | "metadata_mismatch">;
 };
-/** The normalization half exposed for the DISCLOSURE layer: which records a join would refuse, and why. */
+/** The normalization half exposed for the DISCLOSURE layer: which records a join would refuse, and why.
+ *
+ *  design/382 §4.3 — this screen carries the SESSION member of the durable face on every JOIN leg
+ *  (inbound state, local state, both sides of the pure join): a rule or tombstone row carrying a
+ *  session scope is dropped and reported (`session_scope_not_durable`), never landed and never allowed
+ *  to veto the round the way a malformed tombstone does. Dropping a session TOMBSTONE cannot widen:
+ *  tombstones remove adds only under the SAME (rule, scope), and every session-scope add is dropped by
+ *  this same screen — the #176 "its cover is not load-bearing" argument, one scope over.
+ *
+ *  The face's OTHER member — a durable scope that is not well-formed, `{kind:"project", root:""}`
+ *  above all — is executed on the INBOUND legs by {@link applySyncJoin} (its tombstone pre-loop and its
+ *  rule arm both run {@link isValidDurableScope}) and at the direct write arms by
+ *  {@link assertWriteDeltaScopeDurable}, not here. Stated so the boundary is readable: a LOCAL row of
+ *  that shape — reachable only by editing the at-rest bytes, or from a store written before the write
+ *  arm executed that axis — passes this screen and stays live. */
 export declare function screenRuleSyncState(state: RuleSyncState): {
     state: RuleSyncState;
     rejected: RuleSyncDrop[];