@sema-agent/core 6.0.0 → 7.0.0

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[];

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

@@ -10,7 +10,11 @@ export function writerOf(store) {
     return w !== undefined && typeof w.apply === "function" && typeof w.nextDot === "function" ? w : undefined;
 }
 export function sameScope(a, b) {
-    return a.kind === "global" ? b.kind === "global" : b.kind === "project" && a.root === b.root;
+    if (a.kind === "global")
+        return b.kind === "global";
+    if (a.kind === "session")
+        return b.kind === "session" && a.sessionId === b.sessionId;
+    return b.kind === "project" && a.root === b.root;
 }
 function sameDot(a, b) {
     return a.actor === b.actor && a.counter === b.counter;
@@ -47,7 +51,29 @@ export function assertDeleteDeltaCarriesNoAdd(delta) {
         throw new Error("a tighten-delete must carry a tombstone naming at least one observed add dot");
     }
 }
-function isValidScope(scope) {
+export function assertWriteDeltaScopeDurable(delta) {
+    const scope = delta.kind === "redemption-add" ? delta.scope : delta.tombstone?.scope;
+    if (scope?.kind === "session") {
+        const e = new Error(delta.kind === "redemption-add"
+            ? "a session-scope rule cannot enter the persisted store — its home is the session's own overlay (design/382 §4.3); refusing the redemption-add"
+            : "a session-scope tombstone cannot enter the persisted store — session rows are not individually deletable and die with their session (design/382 §4.3/§10); refusing the tighten-delete");
+        e.code = "unsupported.session_scope_store";
+        throw e;
+    }
+    if (!isValidDurableScope(scope)) {
+        throw new Error(delta.kind === "redemption-add"
+            ? "a redemption-add whose scope is not a well-formed durable scope cannot enter the persisted store (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write"
+            :
+                "a tighten-delete must carry a tombstone whose scope is a well-formed durable scope (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write");
+    }
+}
+export function isValidConsentScope(scope) {
+    const sc = scope;
+    return (sc?.kind === "global" ||
+        (sc?.kind === "project" && typeof sc.root === "string" && sc.root !== "") ||
+        (sc?.kind === "session" && typeof sc.sessionId === "string" && sc.sessionId !== ""));
+}
+export function isValidDurableScope(scope) {
     const sc = scope;
     return sc?.kind === "global" || (sc?.kind === "project" && typeof sc.root === "string" && sc.root !== "");
 }
@@ -56,7 +82,7 @@ function isValidDot(dot) {
     return typeof d?.actor === "string" && d.actor !== "" && typeof d.counter === "number" && Number.isFinite(d.counter);
 }
 function scopeKey(scope) {
-    return JSON.stringify(scope.kind === "global" ? ["g"] : ["p", scope.root]);
+    return JSON.stringify(scope.kind === "global" ? ["g"] : scope.kind === "session" ? ["s", scope.sessionId] : ["p", scope.root]);
 }
 function dotKey(dot) {
     return JSON.stringify([dot.actor, dot.counter]);
@@ -114,6 +140,11 @@ export function screenRuleSyncState(state) {
     for (const r of state.rules) {
         if (!Array.isArray(r.adds) || r.adds.length === 0)
             continue;
+        if (r.scope?.kind === "session") {
+            for (const a of r.adds)
+                rejected.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "session_scope_not_durable" });
+            continue;
+        }
         const n = normalizePersistedRule(r);
         if ("reject" in n) {
             for (const a of r.adds)
@@ -122,7 +153,15 @@ export function screenRuleSyncState(state) {
         }
         rules.push(r);
     }
-    return { state: { rules, tombstones: state.tombstones }, rejected };
+    const tombstones = [];
+    for (const t of state.tombstones) {
+        if (t?.scope?.kind === "session") {
+            rejected.push({ rule: t.rule, scope: t.scope, dot: t.deletedBy, reason: "session_scope_not_durable" });
+            continue;
+        }
+        tombstones.push(t);
+    }
+    return { state: { rules, tombstones }, rejected };
 }
 export function joinRuleStates(a, b) {
     const sa = screenRuleSyncState(a).state;
@@ -183,10 +222,12 @@ export function applySyncJoin(cur, delta, nowMs) {
         throw new Error("a sync-join delta must carry an inbound state with rules and tombstones arrays");
     }
     for (const t of delta.inbound.tombstones) {
+        if (t?.scope?.kind === "session")
+            continue;
         if (!Array.isArray(t?.removedDots) || t.removedDots.length === 0) {
             throw new Error("an inbound tombstone must name at least one observed add dot — refusing the whole sync-join (the client's partitioning must withhold the round's adds alongside a malformed tombstone)");
         }
-        if (!isValidScope(t.scope) || !isValidDot(t.deletedBy) || !t.removedDots.every(isValidDot)) {
+        if (!isValidDurableScope(t.scope) || !isValidDot(t.deletedBy) || !t.removedDots.every(isValidDot)) {
             throw new Error("an inbound tombstone carries a malformed scope or dot — refusing the whole sync-join (a tombstone that cannot identity-match what it deletes would land its covered adds live)");
         }
         const canonicalTomb = parseAllowRuleText(t.rule);
@@ -229,7 +270,7 @@ export function applySyncJoin(cur, delta, nowMs) {
             withheldAdds += r.adds.length;
             continue;
         }
-        if (!isValidScope(r.scope)) {
+        if (!isValidDurableScope(r.scope)) {
             for (const a of r.adds)
                 droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
             continue;
@@ -288,6 +329,11 @@ export function applySyncJoin(cur, delta, nowMs) {
         }
     }
     for (const q of delta.quarantine ?? []) {
+        if (q.scope?.kind === "session") {
+            const e = new Error("a quarantine instruction names a session scope — the persisted store never holds a session row (design/382 §4.3); refusing the instruction");
+            e.code = "unsupported.session_scope_store";
+            throw e;
+        }
         for (const dot of q.dots) {
             if (joined.tombstones.some((t) => sameDot(t.deletedBy, dot))) {
                 throw new Error("a quarantine instruction may not touch a tombstone — it moves adds only");
@@ -332,6 +378,12 @@ export async function removePersistedRule(opts) {
     const target = opts.principal;
     const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
     const provider = opts.provider;
+    if (scope?.kind === "session") {
+        return {
+            status: "failed",
+            error: "unsupported.session_scope_store: a session-scope rule cannot be removed through the persisted-store entry — session authorizations live in the session's own overlay and end with the session (design/382 §4.3)",
+        };
+    }
     if (owner.kind === "local-owner" && 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" };
     }
@@ -435,10 +487,12 @@ export class InMemoryPermissionRuleStore {
             if (opts.expectedRev !== this.rev)
                 return { conflict: true, rev: this.rev };
             if (delta.kind === "redemption-add") {
+                assertWriteDeltaScopeDurable(delta);
                 assertRedemptionNotQuarantined(this.quarantinedRows, delta);
                 this.rules = foldDelta(this.rules, delta);
             }
             else if (delta.kind === "tighten-delete") {
+                assertWriteDeltaScopeDurable(delta);
                 assertDeleteDeltaCarriesNoAdd(delta);
                 this.tombstones = [...this.tombstones, delta.tombstone];
             }

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

@@ -134,6 +134,15 @@ interface ParsedRuleSyncResponse {
         dot: RuleDot;
         code: RuleRejectCode;
     }>;
+    /** design/382 §4.3 — SESSION-scope tombstones, dropped at the parse as per-row refusals (never
+     *  `undefined`-malformed): a session row can never land regardless of its dots, so classifying a
+     *  DAMAGED one as generic-malformed would withhold every valid inbound add on every round — one
+     *  peer row poisoning sync forever, the exact shape the per-row drop arm exists to avoid. */
+    sessionScopeTombstones: Array<{
+        rule: string;
+        scope: RuleScope;
+        dot: RuleDot;
+    }>;
     warnings: string[];
 }
 /**

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

@@ -91,6 +91,9 @@ export async function syncPermissionRules(opts) {
     for (const t of response.textRefusedTombstones) {
         dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "invalid_rule_text" });
     }
+    for (const t of response.sessionScopeTombstones) {
+        dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "session_scope_not_durable" });
+    }
     if (response.textRefusedTombstones.length > 0) {
         const named = response.textRefusedTombstones
             .slice(0, DISCLOSED_REFUSED_TOMBSTONES)
@@ -131,6 +134,10 @@ export async function syncPermissionRules(opts) {
     }
     const localDots = new Set(raw.rules.flatMap((r) => r.adds.map((a) => JSON.stringify([a.dot.actor, a.dot.counter]))));
     for (const d of response.dropped) {
+        if (d.scope.kind === "session") {
+            warnings.push(`the server's dropped list names a session-scope row (${escapeForDisclosure(d.rule)}) — the durable store never holds one, so there is no local row it could mean; ignored`);
+            continue;
+        }
         if (localDots.has(JSON.stringify([d.dot.actor, d.dot.counter]))) {
             const reason = d.reason === "below_gc_frontier" ? "below_gc_frontier" : "server_rejected";
             quarantine.push({ rule: d.rule, scope: d.scope, dots: [d.dot], reason });
@@ -190,7 +197,7 @@ export async function syncPermissionRules(opts) {
         const dotKeyOf = (d) => JSON.stringify([d.actor, d.counter]);
         const preDots = new Set(current.rules.flatMap((r) => r.adds.map((a) => dotKeyOf(a.dot))));
         const newAdds = landedRaw.rules.flatMap((r) => r.adds).filter((a) => !preDots.has(dotKeyOf(a.dot))).length;
-        const tombKeyOf = (t) => JSON.stringify([t.rule, t.scope.kind === "global" ? null : t.scope.root, dotKeyOf(t.deletedBy)]);
+        const tombKeyOf = (t) => JSON.stringify([t.rule, t.scope.kind, t.scope.kind === "project" ? t.scope.root : t.scope.kind === "session" ? t.scope.sessionId : null, dotKeyOf(t.deletedBy)]);
         const preTombs = new Set(current.tombstones.map(tombKeyOf));
         const newTombstones = landedRaw.tombstones.filter((t) => !preTombs.has(tombKeyOf(t))).length;
         const landedReport = res.sync;
@@ -228,13 +235,23 @@ function pickDot(v) {
     const counter = d?.counter;
     return typeof actor === "string" && actor !== "" && typeof counter === "number" && Number.isFinite(counter) ? { actor, counter } : undefined;
 }
-function pickScope(v) {
+function pickScopeCaptured(v) {
     const s = v;
-    if (s?.kind === "global")
-        return { kind: "global" };
-    if (s?.kind === "project" && typeof s.root === "string" && s.root !== "")
-        return { kind: "project", root: s.root };
-    return undefined;
+    const kind = s?.kind;
+    if (kind === "global")
+        return { kind, scope: { kind: "global" } };
+    if (kind === "project") {
+        const root = s?.root;
+        return { kind, scope: typeof root === "string" && root !== "" ? { kind: "project", root } : undefined };
+    }
+    if (kind === "session") {
+        const sessionId = s?.sessionId;
+        return { kind, scope: typeof sessionId === "string" && sessionId !== "" ? { kind: "session", sessionId } : undefined };
+    }
+    return { kind, scope: undefined };
+}
+function pickScope(v) {
+    return pickScopeCaptured(v).scope;
 }
 function pickAdd(v) {
     const a = v;
@@ -325,9 +342,11 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
     }
     const tombstones = [];
     const textRefusedTombstones = [];
+    const sessionScopeTombstones = [];
     for (const entry of mergedTombstones) {
         const t = entry;
-        const scope = pickScope(t?.scope);
+        const pickedScope = pickScopeCaptured(t?.scope);
+        const scope = pickedScope.scope;
         const ruleText = t?.rule;
         const deletedBy = pickDot(t?.deletedBy);
         const removedRaw = t?.removedDots;
@@ -342,6 +361,15 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
                 removedDots.push(dot);
             }
         }
+        if (pickedScope.kind === "session") {
+            if (typeof ruleText === "string" && deletedBy !== undefined && scope !== undefined) {
+                sessionScopeTombstones.push({ rule: ruleText, scope, dot: deletedBy });
+            }
+            else {
+                warnings.push("the response carried a session-scope tombstone whose identity could not be read — dropped per-row (a session row never lands here, and nothing is withheld for it)");
+            }
+            continue;
+        }
         if (typeof ruleText !== "string" || scope === undefined || deletedBy === undefined || removedDots.length === 0) {
             tombstones.push(undefined);
             continue;
@@ -384,6 +412,7 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
         ...(gcFrontier !== undefined ? { gcFrontier } : {}),
         dropped,
         textRefusedTombstones,
+        sessionScopeTombstones,
         warnings,
     };
 }

package/dist/core/runner/prepare-task.js

@@ -24,6 +24,7 @@ import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import { askApproverIdentity, carriesBidiControls, checkToolPolicyProjection, combinePolicies, constraintChainDigest, constraintChainEntryOfLayer, isApprovalSettledBy, isAskDenyResolution, screenApproverAttribution, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, describeThrown, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, tryCloneArgs } from "../tool-policy.js";
 const PERSISTED_RULE_TOOL = "Bash";
 import { findAdmittingRule, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { normalizePersistedRule } from "../permission-rule-store.js";
 import { ActiveSkillScope, createActiveSkillScopePolicy } from "./active-skill-scope.js";
 import { CHANGED_FILES_MTIME_EPS_MS, fenceMcpServerInstructions, renderAgentListingDelta } from "./turn-attachments.js";
 import { inlineUntrusted } from "../untrusted-text.js";
@@ -893,6 +894,37 @@ function explicitlyDeferredMemoryTrio(mounted, roster, deferNames) {
 function memoryGroupRetractionSet(builtinDeferPairNames, engineTrioInPlay) {
     return new Set([...builtinDeferPairNames, ...(engineTrioInPlay ? MEMORY_ENGINE_TOOL_NAMES : [])]);
 }
+async function spliceSessionOverlayRows(overlay, sessionId, persisted, tracer, hostTaskId) {
+    if (overlay === undefined)
+        return persisted;
+    try {
+        const served = structuredClone(await overlay.read(sessionId));
+        const sessionRows = served.filter((r) => {
+            const scope = r?.scope;
+            return scope?.kind === "session" && scope.sessionId === sessionId && !("reject" in normalizePersistedRule(r));
+        });
+        if (sessionRows.length < served.length) {
+            emitTrace(tracer, () => ({
+                kind: "permission.rule_store_unreadable",
+                version: 1,
+                taskId: hostTaskId,
+                message: `session-rule overlay served ${served.length - sessionRows.length} row(s) that are not canonical session rows of this session — dropped, not adjudicated`,
+                ts: Date.now(),
+            }));
+        }
+        return sessionRows.length > 0 ? [...sessionRows, ...persisted] : persisted;
+    }
+    catch (err) {
+        emitTrace(tracer, () => ({
+            kind: "permission.rule_store_unreadable",
+            version: 1,
+            taskId: hostTaskId,
+            message: `session-rule overlay: ${err instanceof Error ? err.message : String(err)}`,
+            ts: Date.now(),
+        }));
+        return persisted;
+    }
+}
 function refuseRequireExistingWithoutSession(spec) {
     if (spec.requireExistingSession && !spec.sessionId) {
         const e = new Error(`requireExistingSession requires a sessionId — cannot require an existing session without one (design/114 Phase3)`);
@@ -3600,10 +3632,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         }));
                         return { unreadable: true };
                     }
-                    const admitting = findAdmittingRule(listed.rules, { tool: req.toolName, command, cwd: root });
+                    const table = await spliceSessionOverlayRows(deps.sessionPermissionRules, sessionId, listed.rules, deps.tracer, hostTaskId);
+                    const admitting = findAdmittingRule(table, { tool: req.toolName, command, cwd: root, sessionId });
                     if (admitting !== undefined)
                         return persistedRuleHitOf(admitting);
-                    const coverage = segmentCoverageOf(command, { persisted: listed.rules }, { tool: req.toolName, cwd: root });
+                    const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: root, sessionId });
                     return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
                 },
             };

package/dist/core/store-contracts/permission-rule-sync-contract.js

@@ -34,7 +34,11 @@ function liveDots(s) {
     return out;
 }
 function sameScope(a, b) {
-    return a.kind === "global" ? b.kind === "global" : b.kind === "project" && a.root === b.root;
+    if (a.kind === "global")
+        return b.kind === "global";
+    if (a.kind === "session")
+        return b.kind === "session" && a.sessionId === b.sessionId;
+    return b.kind === "project" && a.root === b.root;
 }
 function allDots(s) {
     return new Set(s.rules.flatMap((r) => r.adds.map((a) => `${r.rule}|${a.dot.actor}#${a.dot.counter}`)));
@@ -150,6 +154,16 @@ export async function permissionRuleSyncContract(hooks = {}) {
         const merged = join(state([rule("Bash(node:*)", [add("z", 1)])]), state());
         assert.strictEqual(allDots(merged).size, 0, "Bash(node:*) must be refused by the shared validator inside the join");
     });
+    run("durable two-member face (design/382 §4.3): a session-scope row or tombstone never survives a join, and never poisons the round", async () => {
+        const sessionScope = { kind: "session", sessionId: "sess-1" };
+        const dirty = state([rule("Bash(ls)", [add("z", 1)], sessionScope), rule("Bash(git status)", [add("a", 1)])], [tomb("Bash(pwd)", [["z", 2]], ["z", 3], sessionScope)]);
+        const ab = join(dirty, state());
+        const ba = join(state(), dirty);
+        assert.ok(!allDots(ab).has("Bash(ls)|z#1"), "a session-scope add must not survive the join — the durable face holds two members");
+        assert.strictEqual(ab.tombstones.length, 0, "a session-scope tombstone must not survive the join");
+        assert.ok(allDots(ab).has("Bash(git status)|a#1"), "dropping the session row must not withhold or disturb the durable rest — per-row, never round-poisoning");
+        assert.deepStrictEqual(ab, ba, "the session-scope drop must preserve commutativity");
+    });
     run("identity keys are collision-free: roots and actors containing spaces keep DISTINCT tombstone identities, and the covered add stays dead through an identity join", async () => {
         const scopeA = { kind: "project", root: "/x" };
         const scopeB = { kind: "project", root: "/x a" };

package/dist/core/trace.d.ts

@@ -449,7 +449,10 @@ export type TraceEvent = {
     /** The bucket this round synced. A local-owner bucket cannot sync, so this is always a principal. */
     principal: string;
     rule: string;
-    scopeKind: "global" | "project";
+    /** `"session"` is unreachable here in a healthy fleet (design/382 §4.3: a session row never
+     *  lands, so it can never resurrect) — declared because the sibling drop event names it and a
+     *  lockstep union is what keeps the two from drifting. */
+    scopeKind: "global" | "project" | "session";
     ts: number;
 } | {
     /**
@@ -462,7 +465,9 @@ export type TraceEvent = {
     version: 1;
     principal: string;
     rule: string;
-    scopeKind: "global" | "project";
+    /** `"session"` names the design/382 §4.3 durable-face drop: a peer sent a session-scope row,
+     *  refused per-row with `session_scope_not_durable`. */
+    scopeKind: "global" | "project" | "session";
     /** Closed reason code ({@link import("./governance-codes.js").RuleSyncDropReason}). */
     reason: string;
     ts: number;

package/dist/core/types.d.ts

@@ -6436,6 +6436,17 @@ export interface RunnerDeps {
      * adopted principal's bucket forever.
      */
     localOwnerRules?: boolean;
+    /**
+     * design/382 §4.3 — the SESSION-RULE OVERLAY: where `{kind:"session"}` scoped allow rules live
+     * (the session's own state, never the persisted store). Wired, the gate's persisted-rule lane
+     * splices the CURRENT session's overlay rows in front of the store's `list()` on every
+     * adjudication — session > project > global, the narrowest-first reporting order — and threads the
+     * session's identity as the eligibility context's third axis; a host lands rows into it through
+     * the consent protocol (`RuleConsentDeps.sessionRules`, a session-scope candidate's redemption).
+     * Omitted ⇒ the session dimension does not exist at this gate and the lane is byte-identical.
+     * See `permission-rule-session.ts` for the contract and the reference implementation.
+     */
+    sessionPermissionRules?: import("./permission-rule-session.js").SessionRuleOverlay;
     /**
      * design/182 §7 — the ORG rule overlay for an org-GOVERNED deployment. Constructed with
      * `createOrgRuleOverlay` (that constructor is the boot gate: a governed declaration with no snapshot

package/dist/index.d.ts

@@ -167,8 +167,9 @@ export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRul
  * allowed and widening is not.
  */
 export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, renderUntrustedCommandText, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, type PersistedAllowRule, type RuleTombstone, type RuleScope, type RuleDot, type RuleAdd, type RuleAddOrigin, type RuleOffer, type SegmentRuleSuggestion, type SegmentCoverage, type RuleReject, type RuleRejectCode, type ParsedAllowRule, type PersistedRuleTool, type PersistedRuleMatch, } from "./core/permission-rule-model.js";
-export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, type PermissionRuleStore, type PermissionRuleStoreProvider, type StoredAllowRules, type RemoveResult, type PutResult, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, type RuleSyncState, type RuleSyncFrontier, type RuleSyncDrop, type RuleSyncLandingReport, type RuleOwner, type QuarantinedRuleAdd, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, type PermissionRuleWriter, type WritablePermissionRuleStore, type RuleWriteDelta, type RuleAddDelta, type RuleDeleteDelta, type RuleSyncJoinDelta, type RawRuleSyncState, type RedemptionAuthorization, } from "./core/permission-rule-store.js";
+export { removePersistedRule, applyTombstones, sameScope, isValidConsentScope, isValidDurableScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, type PermissionRuleStore, type PermissionRuleStoreProvider, type StoredAllowRules, type RemoveResult, type PutResult, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, type RuleSyncState, type RuleSyncFrontier, type RuleSyncDrop, type RuleSyncLandingReport, type RuleOwner, type QuarantinedRuleAdd, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, type PermissionRuleWriter, type WritablePermissionRuleStore, type RuleWriteDelta, type RuleAddDelta, type RuleDeleteDelta, type RuleSyncJoinDelta, type RawRuleSyncState, type RedemptionAuthorization, } from "./core/permission-rule-store.js";
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, type PermissionRuleSyncTransport, type PermissionRuleSyncResult, type RuleSyncRequestBody, type RuleSyncResponseBody, } from "./core/permission-rule-sync.js";
+export { InMemorySessionRuleOverlay, type SessionRuleOverlay, type SessionRuleOverlayAdd, type SessionRuleOverlayApplyResult, } from "./core/permission-rule-session.js";
 export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, type OrgPermissionRule, type OrgRuleSnapshot, type OrgRuleSnapshotProvider, type OrgRuleStatePersistence, type PersistedOrgRuleState, type OrgRuleOverlay, type OrgOverlayResolution, type OrgOverlayStatus, type EffectivePermissionRule, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES, type RuleSyncDropReason, type RuleQuarantineReason } from "./core/governance-codes.js";
 export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, precheckEditedRuleText, type EditedRuleTextPrecheck, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, ruleOffersOfRecord, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleOffer2, type StaleRuleApprovalRecord, type RuleConsentDeps, type RedeemResult, type RedeemedBatchMember, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, } from "./core/permission-rule-consent.js";

package/dist/index.js

@@ -127,8 +127,9 @@ export { AUTO_MODE_ARMING_RECIPE_VERSION, autoModeArmingRecipeOf, sanitizeAutoMo
 export { rebuildAutoModeDecider, } from "./core/auto-mode-rebuild.js";
 export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRule, wildcardMatch, isNamespacedCoveringRuleName, namespacedRuleNameCovers, } from "./core/permission-rules.js";
 export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, renderUntrustedCommandText, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, } from "./core/permission-rule-model.js";
-export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, } from "./core/permission-rule-store.js";
+export { removePersistedRule, applyTombstones, sameScope, isValidConsentScope, isValidDurableScope, InMemoryPermissionRuleStore, EMPTY_RULE_STORE, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, } from "./core/permission-rule-store.js";
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, } from "./core/permission-rule-sync.js";
+export { InMemorySessionRuleOverlay, } from "./core/permission-rule-session.js";
 export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES } from "./core/governance-codes.js";
 export { prepareCardApproval, confirmRuleApproval, precheckEditedRuleText, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, ruleOffersOfRecord, } from "./core/permission-rule-consent.js";