@sema-agent/core 6.0.0 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 7.0.0 — 2026-08-30
+
+> Ships as its own major immediately after 6.0.0 (ruled: the three-dimensional rule scope travels alone so downstream adapts to it in isolation). The 6.0.0 artifact is this same tree with the design/382 P1 surface excised whole (type-driven surgery in an isolated worktree, tag v6.0.0); `npm run handoff:diff v6.0.0 v7.0.0` reproduces exactly this surface.
+
+### BREAKING (design/382 P1 — the three-dimensional rule scope)
+- **`RuleScope` grows a third member** `{ kind: "session"; sessionId }` (design/382 §4): exhaustive switches over the two-member set no longer compile; `sameScope`/`scopeKey` answer three members. Org is deliberately NOT a member — an approval card is structurally unable to spell an org-wide grant. Two NAMED validation faces replace any one-table reading: `isValidConsentScope` (three members; the consent protocol and its server projection) vs `isValidDurableScope` (two members; the persisted store and rule-sync — a session row is refused at every durable entrance).
+- **The consent scope default flips** (#490②): `prepareCardApproval` no longer defaults an absent `scope` to global. Explicit scope wins (validated; garbage refuses `config.invalid_argument`); absent scope with `cwd` present derives `{ kind: "project", root: cwd }`; BOTH absent refuses loudly with the new code `config.missing_scope`. Hosts relying on absent-scope-⇒-global must pass `{kind:"global"}` explicitly or thread the adjudicated cwd — the failure direction is toward asking, never a silent widening. Starter batch stays literal global; import scope mapping unchanged.
+- **A session row is refused at every durable entrance** (§4.3, the open-set duty): `redemption-add`/`tighten-delete` deltas throw typed `unsupported.session_scope_store` (new shared backend assert `assertWriteDeltaScopeDurable`); sync-join drops session rules AND tombstones per-row with the new closed-set reason `session_scope_not_durable` (`RULE_SYNC_DROP_CODES` +1; `RuleQuarantineReason` excludes it — the quarantine area is itself durable) without withholding the round; a session-scope quarantine instruction throws; the file backend screens at-rest bytes off every read face including the sync outbound `readRaw`; `removePersistedRule` refuses a session scope — a session rule is not individually deletable, it dies with its session. The `permission.rule_sync_resurrected/dropped` trace events' `scopeKind` widens to include `"session"`.
+
+### Added
+- **The session-rule overlay** (`permission-rule-session.ts`): `SessionRuleOverlay` contract + `InMemorySessionRuleOverlay` reference implementation (apply idempotent by dot; termination seals the lifetime epoch FIRST then clears — a late in-flight write refuses `session_ended`; `snapshotSession`/`restoreSession` carry rows across park/resume, restore fail-closed on scope and on the canonical re-projection). `RuleConsentDeps.sessionRules` lands session-scope redemptions there (the store write leg is never taken; dot-first crash order and re-apply-on-replay preserved); `RunnerDeps.sessionPermissionRules` splices the current session's rows in front of the persisted `list()` at the gate lane (narrowest-first report order; `sessionId` becomes the eligibility context's third axis, fail-closed when unthreaded). Overlay-served rows pass the same `normalizePersistedRule` re-projection screen the sync face runs on store rows, at all three re-entry doors (gate lane, prepare coverage, restore). New exports: `isValidConsentScope`, `isValidDurableScope`, `assertWriteDeltaScopeDurable`, `SessionRuleOverlay`, `SessionRuleOverlayAdd`, `SessionRuleOverlayApplyResult`, `InMemorySessionRuleOverlay`. The rule-sync contract kit grows the durable-two-member-face conformance vector (server twin duty, mechanized).
+
 ## 6.0.0 — 2026-08-30
 
 ### BREAKING

package/dist/core/governance-codes.d.ts

@@ -62,12 +62,21 @@ export declare const RULE_SYNC_DROP_CODES: {
     /** The server refused this local row (its response `dropped` names it); it leaves the live view so
      *  it does not ride — and get refused on — every future round. */
     readonly server_rejected: "local-quarantined";
+    /** design/382 §4.3 — the row carries a SESSION scope, which the durable face (store, sync wire,
+     *  at-rest bytes) structurally never holds: a session authorization lives in its session's overlay
+     *  and dies with it. The row is dropped and disclosed, never landed and never quarantined (the
+     *  quarantine area is itself durable — parking a session row there would persist it). Inbound-
+     *  refused in every reachable case: the direct write arms refuse session scopes LOUDLY
+     *  (`unsupported.session_scope_store`) before one can become local. */
+    readonly session_scope_not_durable: "inbound-refused";
 };
 /** Every reason a sync round may drop or quarantine a record. Closed set; free text is not a member. */
 export type RuleSyncDropReason = keyof typeof RULE_SYNC_DROP_CODES;
 /** The subset that may appear on a LOCAL quarantined row (design/182 §8.1 `quarantine` instruction /
- *  fence arm / local screening). `own_actor_forged` is inbound-only by construction. */
-export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged">;
+ *  fence arm / local screening). `own_actor_forged` is inbound-only by construction;
+ *  `session_scope_not_durable` never quarantines — the quarantine area is durable, and a session row
+ *  parked there would be a session row persisted (design/382 §4.3). */
+export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged" | "session_scope_not_durable">;
 /**
  * WHO a notice code is for. `"user"` = a session-scoped disclosure the end user of that session is
  * entitled to see (safe to project onto that session's event stream); `"operator"` = a

package/dist/core/governance-codes.js

@@ -90,6 +90,7 @@ export const RULE_SYNC_DROP_CODES = {
     dot_identity_conflict: "inbound-refused",
     below_gc_frontier: "local-quarantined",
     server_rejected: "local-quarantined",
+    session_scope_not_durable: "inbound-refused",
 };
 export const ENGINE_NOTICE_CODES = [
     "config.autocompact_window_clamped",

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

@@ -29,6 +29,7 @@
  */
 import { type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner } from "./permission-rule-store.js";
+import type { SessionRuleOverlay } from "./permission-rule-session.js";
 /** One candidate rule inside an approval record: the exact text and where it would apply. */
 export interface RuleCandidate {
     rule: string;
@@ -199,6 +200,15 @@ export interface RuleConsentDeps {
      * happened, and withholding the receipt helps no one.
      */
     cardEdits?: boolean;
+    /**
+     * design/382 §4.3 — the SESSION-RULE OVERLAY: where a `{kind:"session"}` scoped candidate lands at
+     * redemption (the store write leg is never taken for one), and where the prepare-time coverage read
+     * merges a session's standing rows from. Host-provided, session-lifetime, never synced — see
+     * `permission-rule-session.ts` for the contract and the reference implementation. Absent ⇒ a
+     * session-scope candidate's redemption refuses loudly (there is nowhere for it to land), and
+     * coverage reads see no session rows — both fail toward asking.
+     */
+    sessionRules?: SessionRuleOverlay;
 }
 /** In-memory approval records — the test backend and the reference CAS semantics, the stale-row
  *  envelope read included. */
@@ -257,8 +267,27 @@ export declare function prepareCardApproval(opts: {
     /** The ask's call id and argument digest, recorded for reconciliation. */
     toolCallId?: string;
     boundInputHash?: string;
-    /** Where a redeemed rule would apply. Defaults to global. */
+    /**
+     * Where a redeemed rule would apply — any of the three consent dimensions (design/382 §4.1).
+     *
+     * design/382 §4.4 (#490②, BREAKING B2) — the DEFAULT is no longer global:
+     *  · present ⇒ used as given (the explicit channel; all three members legal, garbage refused loudly);
+     *  · absent with `cwd` present ⇒ `{ kind: "project", root: cwd }`. Root = the adjudicated call's
+     *    cwd is a deliberately NARROW default — the engine is a library and repository semantics are
+     *    host business; a host wanting the true project root passes an explicit scope. The narrow cost
+     *    is more asks (a nested-directory rule does not cover siblings), the safe direction;
+     *  · both absent ⇒ a LOUD refusal (`config.missing_scope`): silent-global was the #490② defect,
+     *    silent-project has no root to anchor, and "where does this consent land" is not guessable.
+     */
     scope?: RuleScope;
+    /**
+     * design/382 §4.3 — the SESSION IDENTITY of the adjudicated call, threaded by the caller from the
+     * original call context exactly like `cwd` (never inferred from the process). It is the coverage
+     * read's third eligibility axis: with it, a standing session rule of that session counts as
+     * coverage; without it, no session rule covers anything (fail-closed). Independent of `scope` on
+     * purpose — `scope` names where a NEW consent would land, this names where the CALL is running.
+     */
+    sessionId?: string;
     /**
      * The working directory of the ADJUDICATED CALL — the same task root the gate's lane judged
      * with — threaded by the caller from the original call context. Never inferred from `scope`
@@ -400,7 +429,12 @@ export type EditedRuleTextPrecheck = {
  * so the surface's move is to not offer the edit box at all.
  */
 export declare function precheckEditedRuleText(text: string, command: string): EditedRuleTextPrecheck;
-/** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule. */
+/** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule.
+ *
+ *  `rev` is the DURABLE store's revision. A session-scope redemption (design/382 §4.3) lands in the
+ *  session overlay and does not move it: its `rev` is a best-effort read of the store's current
+ *  revision (0 when the store could not be read — the landing is in the overlay either way, and the
+ *  durable revision is reporting, not the landing's identity). */
 export type RedeemResult = {
     status: "redeemed";
     rule: string;
@@ -508,6 +542,12 @@ export interface ImportPreview {
  * `false` AND `deduped` — the two axes answer different questions and neither implies the other).
  * A refused row always carries its `reason`. `deduped` counts as LANDED: an equivalent rule
  * already standing means the consent is already in effect.
+ *
+ * design/382 §4.3 — on a SESSION-scope member the two landed words mean the same thing about a
+ * different home: landed in / already in the session's OVERLAY (a session rule's home store), never
+ * the persisted store. The words state that the landing happened; DURABILITY is what the member's own
+ * `scope` says, so a consumer never has to guess it off the status (deliberately no fourth status
+ * value — the closed set names landing outcomes, not storage classes).
  */
 export type RedeemedBatchMember = {
     readonly candidateIndex: number;

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>;
+}