@sema-agent/core 5.57.0 → 5.59.0

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

@@ -303,21 +303,35 @@ export function dirCaseFolds(dir) {
 }
 function readScopesRecord(controlDir) {
     const path = join(controlDir, SCOPES_FILE);
+    const journalPath = `${path}.journal`;
     let raw;
+    let sourcePath = journalPath;
     try {
-        raw = readFileSync(path, "utf8");
+        raw = readFileSync(journalPath, "utf8");
     }
     catch (err) {
-        if (err.code === "ENOENT")
-            return {};
-        throw new ControlPlaneCorruptError(`scope registry unreadable (${err.code ?? "io error"}): ${path}`, { cause: err });
+        if (err.code !== "ENOENT") {
+            throw new ControlPlaneCorruptError(`scope registry journal unreadable (${err.code ?? "io error"}) — a committed next state may exist that cannot be proven: ${journalPath}`, { cause: err });
+        }
+        raw = undefined;
+    }
+    if (raw === undefined) {
+        sourcePath = path;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return {};
+            throw new ControlPlaneCorruptError(`scope registry unreadable (${err.code ?? "io error"}): ${path}`, { cause: err });
+        }
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new ControlPlaneCorruptError(`scope registry is unparseable: ${path}`);
+        throw new ControlPlaneCorruptError(`scope registry is unparseable: ${sourcePath}`);
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new ControlPlaneCorruptError(`scope registry has the wrong shape: ${path}`);
@@ -351,7 +365,7 @@ function lockedScopesUpdate(controlDir, fn) {
     const lock = `${file}.lock`;
     const token = acquireSidecarLock(lock, { onDeadline: "throw" });
     try {
-        rollForwardSidecar(file, journal);
+        rollForwardStrictSidecar(file, journal);
         const rec = readScopesRecord(controlDir);
         const { next, result } = fn(rec);
         if (next !== undefined) {

package/dist/core/memory-engine/origin-clearance.d.ts

@@ -63,7 +63,7 @@ export declare function markOriginClearanceTombstoned(controlDir: string, input:
 /**
  * Terminal event append + status flip. Unknown clearanceId is a corrupt-caller refusal.
  *
- * SINGLE-WINNER terminal (codex r1): a row already terminal ignores a late contradictory
+ * SINGLE-WINNER terminal: a row already terminal ignores a late contradictory
  * settlement — two concurrent resumers race the store legs (the store's own CAS decides those),
  * and the loser's stale verdict must not overwrite the winner's audit state (a successfully
  * cleared entry reading `failed` with contradictory events). The loser's own thrown refusal is

package/dist/core/memory-engine/scope-contract.d.ts

@@ -10,7 +10,7 @@ export declare const SCOPE_SEGMENT_MAX_ENCODED = 64;
  */
 export declare function encodeScopeSegment(raw: string): string;
 /**
- * Inverse of {@link encodeScopeSegment}, CANONICAL-FORM ONLY (codex 复审 B6): the input must be
+ * Inverse of {@link encodeScopeSegment}, CANONICAL-FORM ONLY: the input must be
  * exactly what the encoder produces — safe chars stay bare (so `%41` for `A` is refused: two
  * spellings of one identity must not mint two keys), `%XX` sequences must decode as valid UTF-8
  * (fatal decoder — no U+FFFD smoothing), and the 64-char cap holds here too (parse side enforces
@@ -52,7 +52,7 @@ export declare function parseScopeKey(key: string): ParsedScopeKey;
 export declare function isPersonalScope(parsed: ParsedScopeKey): boolean;
 /** True when the key's AUTHORITY is central (design/142 §2 表: user/userproj/org rows) — these keys
  *  must never project into an in-repo memory dir (they would leak to every collaborator AND enter
- *  commit history; codex 复审 B1 extended the F9 gate from personal to org). `proj:`/legacy stay
+ *  commit history; extended the F9 gate from personal to org). `proj:`/legacy stay
  *  repo-planed. */
 export declare function isCentralAuthorityScope(parsed: ParsedScopeKey): boolean;
 /**
@@ -71,14 +71,14 @@ export declare function assertScopeContractPlacement(args: {
 /** Repo-root marker file: minted once (by scaffold/deployment, NEVER by the engine), committed, and
  *  from then on the project's identity survives clone/copy/rename/machine/cloud-sandbox. */
 export declare const PROJECT_MARKER_PATH = ".sema/project";
-/** projectId 格式单源([637]① 承诺):generic UUID,version nibble 不收紧——宽读严写(读面认外部/
+/** projectId 格式单源:generic UUID,version nibble 不收紧——宽读严写(读面认外部/
  *  历史 v4;铸造面 formatProjectMarker / center mint 统一产 uuidv7)。center 侧自持镜像+dev-only
  *  drift 锁对着这条(registry-core coreTypes 先例)。 */
 export declare const PROJECT_ID_REGEX: RegExp;
 /** Serialize a marker file body (scaffold-side helper; the engine itself never writes one). */
 export declare function formatProjectMarker(projectId: string): string;
 /** Parse a marker body: TOML-subset `key = value` lines, `#` comments and blank lines ignored,
- *  optional quotes around the value. Unknown keys are ignored (forward-compatible). codex 复审 H7:
+ *  optional quotes around the value. Unknown keys are ignored (forward-compatible).
  *  ANY line that starts a `projectId` assignment but is not one canonical UUID assignment is a
  *  CORRUPT marker (fail-loud, `config.memory_project_marker`) — an empty value, an unclosed quote,
  *  a non-UUID, or a DUPLICATE projectId line must never degrade to "no marker" (that would be a

package/dist/core/memory-engine/sync-client.d.ts

@@ -5,7 +5,7 @@ import { type MemoryBackend, type MemoryEntry, type PatchReport } from "./types.
  *  DECODED JSON body of a 2xx response; any non-2xx / network failure should THROW (the round then
  *  aborts with zero local side effects — the transport runs before any local write). */
 export type MemorySyncTransport = (path: string, body: unknown) => Promise<unknown>;
-/** The wire REQUEST of one round (the server's `parseMemorySyncRequest` twin — [671]①): the push
+/** The wire REQUEST of one round (the server's `parseMemorySyncRequest` twin): the push
  *  half as computed against the client's own cursor. `deletes` ⊆ `Object.keys(baseRevs)` by
  *  construction (a delete is CAS'd on its baseline; an id never synced cannot be delete-propagated). */
 export interface MemorySyncRequestBody {
@@ -14,20 +14,20 @@ export interface MemorySyncRequestBody {
     baseRevs: Record<string, string>;
     /** Full state of every entry new/changed here since the baseline. When
      *  {@link SyncMemoryScopeOptions.maxPushEntries} is set this is the id-ascending PREFIX of the
-     *  full push set ([767]③ batching — the remainder rides later rounds). */
+     *  full push set (batching — the remainder rides later rounds). */
     entries: MemoryEntry[];
     /** Ids deleted here since the baseline (tombstoned or gone from the local plane). Deletes are
-     *  NEVER batched/split — they are id+baseRev pairs, weightless next to entry bodies ([767]③). */
+     *  NEVER batched/split — they are id+baseRev pairs, weightless next to entry bodies. */
     deletes: string[];
-    /** [767]③ pull-half batching (wire contract; server implements the response side): ask the
-     *  server to cap this round's pull half at `limit` items. Absent ⇔ unbatched (the pre-[767]③
+    /** pull-half batching (wire contract; server implements the response side): ask the
+     *  server to cap this round's pull half at `limit` items. Absent ⇔ unbatched (the prior
      *  wire shape byte-for-byte — old servers never see the key). */
     pull?: {
         limit?: number;
     };
 }
-/** The wire RESPONSE of one round (server `MemorySyncResponse` twin — [671]①: one RTT, both
- *  directions; `serverDeletes` is the delete-propagation leg [codex B4 — without it a central
+/** The wire RESPONSE of one round (server `MemorySyncResponse` twin: one RTT, both
+ *  directions; `serverDeletes` is the delete-propagation leg [without it a central
  *  removal never crosses = livelock]; `cursor` is the server-computed next baseline with the
  *  retention discipline ALREADY applied to the pull half). */
 export interface MemorySyncResponseBody {
@@ -57,7 +57,7 @@ export interface MemorySyncResponseBody {
         baseRevs: Record<string, string>;
         updatedAtMs: number;
     };
-    /** [767]③ pull-half batching (wire contract; server sets it): true ⇔ the server withheld part
+    /** pull-half batching (wire contract; server sets it): true ⇔ the server withheld part
      *  of the pull half under the requested `pull.limit` — the caller should run another round.
      *  The server MUST retain every withheld id at the OLD baseline inside `cursor` (the client
      *  refuses prefilled undelivered revs — see ⑤ defense — so violating this only costs the
@@ -87,22 +87,22 @@ export interface SyncMemoryScopeOptions {
     peer?: string;
     /** Caller-injected clock (engine precedent) — stamps the returned cursor's updatedAtMs. */
     now?: () => number;
-    /** [767]③ push-half batching: cap the number of push-half ENTRIES sent this round. The full
+    /** push-half batching: cap the number of push-half ENTRIES sent this round. The full
      *  push set is put in STABLE order (id ascending — deterministic across rounds/replicas) and the
      *  first `maxPushEntries` ride the wire; a cut round reports `pushTruncated: true`. Deletes are
      *  never split (id+baseRev pairs are weightless next to bodies). CALLER CONTRACT: on
      *  `pushTruncated`/`pullTruncated`, persist the returned cursor and run ANOTHER round until both
      *  flags clear — core deliberately never loops internally (the runner loop is the deployment's,
-     *  server-side semantics per [767]③); bound your loop (e.g. a fixed max-rounds cap ≥
+     *  server-side semantics apply); bound your loop (e.g. a fixed max-rounds cap ≥
      *  ⌈expected entries / limit⌉ + slack) so a misbehaving peer cannot spin it forever. Must be a
      *  POSITIVE integer (≥ 1 — C5: a 0 cap would flag pushTruncated forever and livelock the caller
-     *  loop); absent ⇔ unbatched (pre-[767]③ behavior byte-for-byte). */
+     *  loop); absent ⇔ unbatched (prior behavior byte-for-byte). */
     maxPushEntries?: number;
-    /** [767]③ pull-half batching: forwarded verbatim as the wire request's `pull.limit`; a server
+    /** pull-half batching: forwarded verbatim as the wire request's `pull.limit`; a server
      *  that withholds part of its pull half answers `pullTruncated`, passed through on the result.
      *  Same caller contract as {@link maxPushEntries}: continue rounds (bounded) until it clears.
      *  Must be a POSITIVE integer (≥ 1 — C5, same livelock gate); absent ⇔ the request carries NO
-     *  `pull` key (old-server compatible, pre-[767]③ wire bytes). */
+     *  `pull` key (old-server compatible, pre- wire bytes). */
     maxPullEntries?: number;
     /** design/178 §3 — per-entry byte bound for the PUSH gate, matched against the entry's serialized
      *  file form (the same domain the harvest gate measures). Defaults to {@link MAX_MEMORY_BYTES},
@@ -130,11 +130,11 @@ export interface MemorySyncClientResult {
     /** The cursor the caller should now persist: advanced on full success, otherwise the INPUT
      *  cursor unchanged (undefined on a failed first round) — the retention discipline. */
     cursor: MemorySyncCursor | undefined;
-    /** [767]③: present (true) ⇔ `maxPushEntries` cut this round's push set — run another round off
+    /** present (true) ⇔ `maxPushEntries` cut this round's push set — run another round off
      *  the persisted cursor until it clears (see the {@link SyncMemoryScopeOptions.maxPushEntries}
      *  caller contract). Never present on an uncut round (additive: old callers see no new key). */
     pushTruncated?: true;
-    /** [767]③: present (true) ⇔ the server reported its pull half was cut under `pull.limit` —
+    /** present (true) ⇔ the server reported its pull half was cut under `pull.limit` —
      *  same continue-until-clear caller contract. */
     pullTruncated?: true;
     /** Honest-disclosure channel for tolerated protocol violations (present only when non-empty).
@@ -146,7 +146,7 @@ export interface MemorySyncClientResult {
     warnings?: string[];
 }
 /**
- * One full CLIENT sync round for one (scope, peer) against the [671]① central sync API — see the
+ * One full CLIENT sync round for one (scope, peer) against the central sync API — see the
  * module header for the ①-⑤ flow and the cursor retention discipline. Pure orchestration: all I/O
  * rides the injected backend/transport; the caller persists the returned cursor.
  */

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

@@ -3,7 +3,7 @@ import type { MemoryEntry, ScoredMemoryEntry } from "./types.js";
  * design/142 §3 — the per-replica per-scope sync cursor: the COMMON BASELINE a reconciliation run
  * judges divergence against (`id → rev` as of the last completed sync round). This is a NEW
  * persistence face — deliberately NOT revs.json (that is the local disk-vs-committed ledger): File
- * plane = a control-plane sidecar, DB plane = a service-owned table (PG+TiDB, [628] dual-dialect).
+ * plane = a control-plane sidecar, DB plane = a service-owned table (PG+TiDB dual-dialect).
  * Serializable by construction.
  */
 export interface MemorySyncCursor {
@@ -31,7 +31,7 @@ export interface MemorySyncPlan {
     /** Entries the LOCAL side should adopt from the peer (new there or changed-there-only). Same CAS
      *  discipline as {@link push}, mirrored: local conditional write with `baseRevs[id]`. */
     pull: MemoryEntry[];
-    /** codex 复审 B4 — DELETE propagation (without these the removal never crosses and every round
+    /** DELETE propagation (without these the removal never crosses and every round
      *  re-plans the same state = livelock): the peer removed an entry the local side left UNCHANGED
      *  since baseline ⇒ delete locally (CAS on baseRev — a local edit racing in makes the delete a
      *  conflict on the next round instead of silent loss). */
@@ -61,7 +61,7 @@ export interface MemorySyncPlan {
  *  - changed on exactly ONE side → push/pull;
  *  - changed on BOTH sides, or delete-on-one × edit-on-the-other → conflict (caller's ladder);
  *  - deleted on one side × UNCHANGED on the other → the delete propagates (deleteLocal/deleteRemote,
- *    CAS on baseRev — codex B4: without this leg removals never cross and the plan livelocks);
+ *    CAS on baseRev: without this leg removals never cross and the plan livelocks);
  *  - present only on one side with NO baseline → new entry → propagate;
  *  - absent on both but present in baseline → cleared (cursor cleanup).
  */
@@ -81,7 +81,7 @@ export declare function nextSyncBaseline(local: readonly MemoryEntry[], remote:
  * because the seat is advisory: the authoritative body is re-read from the real backend by id/slug
  * when a hit is followed. Mount point: a deployment composes its RecallSource(s) inside its recall
  * select hook (the design/65 selective-recall trust seat) or pre-queries before prepare; core adds
- * no RunnerDeps seat until a real integration signals the need (YAGNI, [622]③ two-lane ruling).
+ * no RunnerDeps seat until a real integration signals the need (YAGNI two-lane ruling).
  */
 export interface RecallSource {
     /** Stable adapter name (diagnostics/attribution: hits are labeled, never silently mixed). */

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

@@ -246,6 +246,23 @@ export interface NotePatch {
      *  Ignored on `update`/`delete`. */
     guard?: "absent";
 }
+/**
+ * design/376 slice ③ (#437③) — a backend's scope-enumeration answer, DISCRIMINATED on purpose:
+ * "this backend cannot enumerate" and "this store hosts no scopes" must never share a spelling
+ * (an unsupported backend read as `[]` would make every audit sweep over it silently claim a
+ * clean store). The capability itself is an OPTIONAL backend face (`listScopes`, probed like the
+ * File class's audit faces): a backend without it is answered `supported: false` by
+ * `MemoryEngine.listMemoryScopes`, never an empty array. The File leg derives from the store
+ * root's durable scope registry; the SQL twins' leg is a store-contracts extension (separate
+ * ticket) — until it lands they simply do not implement the face.
+ */
+export type MemoryScopeEnumeration = {
+    supported: true;
+    scopes: string[];
+} | {
+    supported: false;
+    reason: string;
+};
 /** Result of {@link MemoryBackend.applyPatches} — applied ops + per-id CAS conflicts (reported, not thrown). */
 export interface PatchReport {
     applied: Array<{

package/dist/core/memory-recall.d.ts

@@ -164,7 +164,7 @@ export declare function composeSelectiveBody(manifestText: string, selected: Mem
  *  both. Core owns the FORMAT so a caller can't drift the wire format (decision 7) — the encoding is OPAQUE
  *  and length-prefixes the scope so a scope/id containing the separator cannot self-declare a collision.
  *
- *  ONE-WAY by design (codex MINOR (d)): the key is only ever PRODUCED here (`surfacedKeys`) and compared by
+ *  ONE-WAY by design ((d)): the key is only ever PRODUCED here (`surfacedKeys`) and compared by
  *  STRING EQUALITY against the caller's persisted set ({@link LayeredRecallOptions.priorSurfacedKeys}, applied
  *  at memory-recall.ts via `priorSurfacedKeys.has(encodeSurfacedKey(h.scope, h.id))`). Nothing ever needs the
  *  `(scope, id)` BACK out of a key, so there is intentionally NO `decodeSurfacedKey` — adding a decode would

package/dist/core/memory.d.ts

@@ -282,7 +282,7 @@ export declare class MemoryGateError extends Error {
  * prose that merely mentions tokens/keys/passwords passes through untouched (false-positives are the head
  * risk — a wrongly-rejected normal note silently breaks legitimate memory).
  *
- * 🔴 RB-445 (blackboard [2230]): this is a BEST-EFFORT tripwire for a handful of high-signal token
+ * 🔴 RB-445: this is a BEST-EFFORT tripwire for a handful of high-signal token
  * formats, NOT a data-loss-prevention boundary — "the write gate passed" never means "the text contains
  * no credential". Known-through shapes (deliberate, per the false-positive stance above): connection
  * strings carrying passwords, `password=`/`Authorization:` header values, bare high-entropy bodies
@@ -530,7 +530,7 @@ export type MemorySpecInput = {
  *  - `writeScope` defaults to the LAST scope (the highest-priority layer); an EXPLICIT `null` means read-only
  *    (no `remember` tool, no consolidation); an explicit non-null string is taken as-is (it need NOT be one
  *    of `scopes` — a deployment may write a layer it does not inject, though normally it is the last scope).
- *    ⚠️ Layered READ seeding (service [646]①, 142-S4): when `scopes` comes from a registry's defaultScopes
+ *    ⚠️ Layered READ seeding (142-S4): when `scopes` comes from a registry's defaultScopes
  *    (shared read layers), ALWAYS pin `writeScope` explicitly — the last-scope default would land every
  *    harvest in whichever shared layer happens to be listed last (a cross-tenant write surface).
  *  - returns `undefined` when there are no usable scopes (the caller treats it like "no memory configured").

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

@@ -27,7 +27,7 @@
  * this by editing a file backend's file. That is the settings-file trust model, stated rather than
  * defended against: for a file backend, host = user, no more and no less.
  */
-import { type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
+import { type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider, RuleOwner } from "./permission-rule-store.js";
 /** One candidate rule inside an approval record: the exact text and where it would apply. */
 export interface RuleCandidate {
@@ -36,6 +36,37 @@ export interface RuleCandidate {
 }
 /** What the approval record is for — it decides the provenance the minted adds carry. */
 export type RuleApprovalKind = "card" | "import" | "starter";
+/**
+ * design/375 §4.1 — one "don't ask again" OPTION as the record stores it: references into the
+ * record's `candidates` by index, never rule text of its own. The display triple (rule, match,
+ * command) is deliberately NOT here — it is derived at projection time from the referenced
+ * candidate's text ({@link ruleOffersOfRecord}), so there is no stored copy to drift from the rule
+ * that would actually persist.
+ *
+ *  · `kind: "single"` — one candidate covering the whole command.
+ *  · `kind: "batch"` — a CONJUNCTION batch: confirming it is one yes to ALL of `candidates` at
+ *    once, with no per-member sub-selection. On a CARD record the batch carries two MINT-TIME
+ *    facts that cannot be re-derived from candidate texts and therefore must be stored:
+ *    `segments` (each member's source segment, index-aligned with `candidates`) and
+ *    `uncoveredSegments` (the honest surplus count the wire offer disclosed, judged on the
+ *    prepare-time coverage snapshot). On an import/starter record there is no compound command
+ *    and no coverage snapshot, so both fields must be ABSENT — honest absence, never an
+ *    empty-string stand-in. The read-side integrity checks refuse either direction's violation.
+ *
+ * Cardinality: a batch references 1..N candidates where N is the record's own candidate count.
+ * The wire offer's 1..5 is the CARD-lane minting cap — a card record inherits it by being minted
+ * there — while an import batch of twenty is a legal record; the two contracts are deliberately
+ * separate and neither speaks in the other's name.
+ */
+export type RuleOffer2 = {
+    readonly kind: "single";
+    readonly candidate: number;
+} | {
+    readonly kind: "batch";
+    readonly candidates: readonly number[];
+    readonly segments?: readonly string[];
+    readonly uncoveredSegments?: number;
+};
 /** A durable record of one pending/settled human decision about minting rules.
  *
  * Identity (design/182 §4.5, additive): a v1 record carries `principal` and nothing else — it stays
@@ -48,9 +79,26 @@ export interface RuleApprovalRecord {
     principal?: string;
     /** Structural owner (additive). Absent on every record a v1 tree minted. */
     owner?: RuleOwner;
+    /**
+     * design/375 §4.5 — the record-form version stamp. A stored row WITHOUT it predates this form;
+     * such a row confirms and redeems nothing (refused loudly, `record_schema_stale`) and is never
+     * read through a compatibility shim: pending approvals are short-lived, and re-triggering the
+     * command draws a fresh card. Stores hand pre-form rows back as {@link StaleRuleApprovalRecord}.
+     */
+    schema: 2;
     kind: RuleApprovalKind;
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
+    /**
+     * The card's OPTION structure over `candidates` (design/375 §4.1). The flat candidate list stays
+     * the redemption/replay anchor — tickets, `redeemedDots` and the store writes all key on
+     * candidate indices, unchanged — while confirmation keys on OFFER indices into this array.
+     * Import/starter records are the whole-list normalization: one batch offer over every candidate,
+     * so all three entries speak one protocol. Offers are pairwise DISJOINT in membership (an
+     * unchosen offer's members must stay unredeemable, which overlapping offers could not
+     * guarantee); the mint sites satisfy that by construction and the read side refuses violations.
+     */
+    offers: RuleOffer2[];
     createdAt: string;
     /** The ask this record was drawn from, for reconciliation. Advisory metadata; never adjudication input.
      *  `boundInputHash` is ALSO the card-edit binding anchor: an edited-candidate confirmation must echo
@@ -69,23 +117,25 @@ export interface RuleApprovalRecord {
      *  comparing state alone cannot separate two different writes that both leave the state unchanged. */
     rev: number;
     /**
-     * Which candidate the person actually chose, recorded by the confirmation transfer.
+     * Which OFFER the person actually chose, recorded by the confirmation transfer (design/375 §4.3;
+     * takes the seat the per-candidate selection held before offers existed).
      *
-     * A card offers alternatives — the exact command and, sometimes, a broader prefix — and a human picks
-     * ONE. Without this, confirming the card would authorize every option on it: a host could redeem the
-     * exact ticket, then later redeem the wider prefix ticket, and the second rule would exist without
-     * anyone ever having agreed to it. Absent on batch records, where the confirmation is over the whole
-     * previewed list by construction.
+     * A card offers alternatives of different breadth and a human picks ONE. Without this, confirming
+     * the card would authorize every option on it: a host could redeem the narrow ticket, then later
+     * the wider one, and the second rule would exist without anyone ever having agreed to it.
+     * Choosing a BATCH offer is a conjunction — one yes to ALL of its member candidates at once —
+     * so every member becomes redeemable and every non-member stays unredeemable forever. Absent
+     * exactly while the record is pending.
      */
-    selectedCandidate?: number;
+    selectedOffer?: number;
     /**
      * The person-EDITED candidate this record carries, if any — full provenance for the one candidate
      * whose text was authored at the card rather than derived by the engine. `index` names the appended
      * row in `candidates` (whose `rule` holds the CANONICAL spelling); `text` keeps the raw input bytes
      * exactly as submitted (the idempotency primary key — a client retrying a lost response resends the
-     * same bytes); `at` is when the edit landed. Present ⇒ `selectedCandidate === index` (the edit and
-     * the choice are one CAS write). Absent on every record a prior version minted and on every card
-     * settled through an engine candidate.
+     * same bytes); `at` is when the edit landed. Present ⇒ the record's chosen offer is the single
+     * offer minted over this candidate (the append, the offer and the choice are one CAS write).
+     * Absent on every card settled through an engine candidate.
      */
     edited?: {
         index: number;
@@ -95,12 +145,32 @@ export interface RuleApprovalRecord {
     /** Dots already minted for this record, keyed by candidate index — the replay anchor. */
     redeemedDots?: Record<number, RuleDot>;
 }
+/**
+ * design/375 §4.5 — the minimal ENVELOPE a store hands back for a durable row that predates the
+ * `schema: 2` record form. A typed read cannot honestly return such a row as a
+ * {@link RuleApprovalRecord}, and dropping it at the store layer would misreport "stale" as
+ * corruption — so the store contract is this variant instead: `staleSchema: true` plus the
+ * IDENTITY fields, which are spelled the same way in every version and therefore safe to read.
+ * The identity fields exist so the owner gate can still run, and it runs FIRST: a non-owner
+ * asking about a stale row is answered exactly like a non-owner asking about any row (existence
+ * is never confirmed); the stale disclosure is for the record's own owner only. Nothing else
+ * about the row is surfaced.
+ */
+export interface StaleRuleApprovalRecord {
+    readonly staleSchema: true;
+    readonly id: string;
+    readonly principal?: string;
+    readonly owner?: RuleOwner;
+}
 /**
  * The durable home of approval records. A separate record type on purpose: it is not a checkpoint row and
  * must not evolve with one.
  */
 export interface RuleApprovalRecordStore {
-    get(id: string): Promise<RuleApprovalRecord | undefined>;
+    /** A row whose `schema` is missing or unknown MUST come back as {@link StaleRuleApprovalRecord}
+     *  (identity fields only) — never thrown away as a parse failure, never widened into a full
+     *  record the current form cannot vouch for. */
+    get(id: string): Promise<RuleApprovalRecord | StaleRuleApprovalRecord | undefined>;
     /**
      * Compare-and-set on the record's REVISION, not on its state.
      *
@@ -130,15 +200,32 @@ export interface RuleConsentDeps {
      */
     cardEdits?: boolean;
 }
-/** In-memory approval records — the test backend and the reference CAS semantics. */
+/** In-memory approval records — the test backend and the reference CAS semantics, the stale-row
+ *  envelope read included. */
 export declare class InMemoryRuleApprovalRecordStore implements RuleApprovalRecordStore {
     private readonly rows;
-    get(id: string): Promise<RuleApprovalRecord | undefined>;
+    get(id: string): Promise<RuleApprovalRecord | StaleRuleApprovalRecord | undefined>;
     create(record: RuleApprovalRecord): Promise<void>;
     cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
     /** Test/inspection helper — how many records exist. The principal negative pins read this. */
     size(): number;
 }
+/**
+ * design/375 §4.1 — project a record's stored offers into the wire {@link RuleOffer} shape: the
+ * AUTHORITATIVE card render source (record-is-what-you-see; the ask-time projection is advisory
+ * and may be coverage-narrower). The display triple (rule, match, command) is derived HERE, at
+ * projection time, by parsing each referenced candidate's stored text — never stored beside it,
+ * never accepted from a caller — so what a card shows is definitionally the rule that would
+ * persist; there is no second copy to corrupt. A batch offer's `segment`s and
+ * `uncoveredSegments` come from the mint-time facts the record carries.
+ *
+ * Card records only, in effect: an import/starter record's whole-list batch carries no segment
+ * metadata (its person-facing form is the import/starter PREVIEW, not an offer card), and asking
+ * for its card projection throws. A candidate text that no longer parses throws too — that is
+ * store damage on a row the validator once accepted, and rendering a wrong rule under a "don't
+ * ask again" label is the one failure a refusal always beats.
+ */
+export declare function ruleOffersOfRecord(rec: Pick<RuleApprovalRecord, "candidates" | "offers">): readonly RuleOffer[];
 /** An opaque, single-purpose redemption ticket. Its only content is which record and which candidate. */
 export type RuleTicket = string;
 export declare function mintRuleTicket(recordId: string, candidateIndex: number): RuleTicket;
@@ -172,9 +259,19 @@ export declare function prepareCardApproval(opts: {
     boundInputHash?: string;
     /** Where a redeemed rule would apply. Defaults to global. */
     scope?: RuleScope;
+    /**
+     * 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`
+     * (a rule's landing scope is not where the call ran; nested project roots make the two
+     * coverage answers diverge) and never from the process. Absent, a project-scope rule covers
+     * nothing (the shared predicate's fail-closed arm), so segments lean UNCOVERED and the batch
+     * leans wide — the over-offer direction, which redemption's per-rule validation keeps safe.
+     */
+    cwd?: string;
     deps: RuleConsentDeps;
 }): Promise<{
     approvalId: string;
+    offers: readonly RuleOffer[];
     tickets: RuleTicket[];
     candidates: RuleCandidate[];
 } | undefined>;
@@ -191,12 +288,16 @@ export declare function confirmRuleApproval(opts: {
     /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
     owner?: RuleOwner;
     /**
-     * REQUIRED for a card record settled through an ENGINE candidate: the index of the option the person
-     * chose. A card presents alternatives of different breadth, so "they said yes" is not an answer on
-     * its own — "they said yes to THIS one" is. Rejected on a batch record, whose confirmation covers
-     * the previewed list by construction. Mutually exclusive with `editedCandidate`.
+     * The index of the OFFER the person chose — into the record's `offers`, the same order
+     * `prepareCardApproval` returned them (design/375 §4.3). A card presents alternatives of
+     * different breadth, so "they said yes" is not an answer on its own — "they said yes to THIS
+     * one" is. A single offer authorizes its one candidate; a BATCH offer is a conjunction, one yes
+     * to ALL of its member candidates at once, with no per-member sub-selection. May be omitted
+     * exactly when the record carries ONE offer (a single-element choice space has no ambiguity —
+     * the import/starter whole-list batch lands here); a multi-offer record with no selection
+     * refuses `selection_missing`. Mutually exclusive with `editedCandidate`.
      */
-    selectedCandidate?: number;
+    selectedOffer?: number;
     /**
      * The person-EDITED rule text for this card, travelling on the SAME authenticated confirmation
      * channel as a choice among the engine's candidates (never the un-authenticated prepare entry, which
@@ -205,7 +306,7 @@ export declare function confirmRuleApproval(opts: {
      * command", an in-process mis-binding fence (a caller holding only a leaked approvalId cannot spell
      * it), not a cryptographic one. The engine validates the text through the one shared validator,
      * requires it to still ADMIT the adjudicated command, appends it as a new candidate and binds the
-     * selection to it, returning the minted ticket. Mutually exclusive with `selectedCandidate`.
+     * selection to it, returning the minted ticket. Mutually exclusive with `selectedOffer`.
      */
     editedCandidate?: {
         text: string;
@@ -214,6 +315,13 @@ export declare function confirmRuleApproval(opts: {
     deps: RuleConsentDeps;
 }): Promise<ConfirmResult>;
 /** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up).
+ *  The two `record_*` members past `record_not_found` are the durable-row gates (design/375 §4.5/§4.7),
+ *  disclosed to the record's own owner only — a non-owner gets `record_not_found` for every row:
+ *   - `"record_schema_stale"` — the record predates the `schema: 2` form; the decision it carried
+ *     is void, and the recovery path is re-triggering the command for a fresh card (no
+ *     compatibility read, no migration — `detail.message` says so);
+ *   - `"record_malformed"` — the record's offer structure failed the read-side integrity checks
+ *     (store damage); `detail.message` names the breakage.
  *  The three `edit_*` members are the card-edit face's own refusals:
  *   - `"edit_disabled"` — the deployment has not opted into card edits (`RuleConsentDeps.cardEdits`);
  *   - `"edit_binding_mismatch"` — the confirmation does not echo the record's bound-input digest
@@ -221,7 +329,7 @@ export declare function confirmRuleApproval(opts: {
  *     settled replays included, and never returns a minted ticket;
  *   - `"edit_rejected"` — the edited text failed a gate (validator refusal, coverage, record shape);
  *     `detail` carries the specifics. */
-export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict" | "edit_disabled" | "edit_binding_mismatch" | "edit_rejected";
+export type ConfirmRefusalReason = "record_not_found" | "record_schema_stale" | "record_malformed" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "not_pending" | "conflict" | "edit_disabled" | "edit_binding_mismatch" | "edit_rejected";
 /** The confirmation outcome: landed, or refused with a named reason.
  *
  *  `mintedCandidate` (additive) is present exactly when an EDITED candidate settled this confirmation —
@@ -370,20 +478,36 @@ export interface ImportPreview {
         };
     };
 }
-/** What the import ACTUALLY did — a different moment and a different contract from the preview, because
- *  dedup, concurrency and redemption-time validation can all move an entry between the two. */
-export interface ImportResult {
-    persisted: RuleCandidate[];
-    deduped: RuleCandidate[];
-    skippedAtRedeem: Array<{
-        rule: string;
-        reason: string;
-    }>;
-    rev: number;
-}
+/**
+ * One member row of a batch redemption's FULL table (design/375 §4.6) — what actually happened to
+ * each candidate of the chosen offer, keyed by its ORIGINAL candidate index. `candidateIndex` is
+ * the member's identity: the same rule text can be two candidates in two scopes with two different
+ * outcomes, so the bare text is not a key. A successful row always carries its `dot` and the
+ * independent `alreadyRedeemed` axis (the single-leg replay marker: a dot-recorded-but-unlanded
+ * retry is `alreadyRedeemed: true` AND `persisted`; a rule that pre-existed in the store is
+ * `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.
+ */
+export type RedeemedBatchMember = {
+    readonly candidateIndex: number;
+    readonly rule: string;
+    readonly scope: RuleScope;
+    readonly status: "persisted" | "deduped";
+    readonly alreadyRedeemed: boolean;
+    readonly dot: RuleDot;
+} | {
+    readonly candidateIndex: number;
+    readonly rule: string;
+    readonly scope: RuleScope;
+    readonly status: "refused";
+    readonly reason: string;
+};
 /**
  * Read the allow buckets of the user-editable settings layers and produce a preview plus a PENDING
  * approval record. Nothing is stored until someone confirms that record and the batch is redeemed.
+ * A preview with zero importable candidates returns NO `approvalId` — there is nothing to confirm,
+ * and the absence says so (design/375 §4.1).
  *
  * Only the allow bucket is IMPORTED. The deny/ask buckets are the tightening direction and have their own
  * channel; importing them through a loosening lane would be the wrong door. They are still COUNTED and
@@ -398,7 +522,7 @@ export declare function prepareCcImport(opts: {
     deps: RuleConsentDeps;
 }): Promise<{
     preview: ImportPreview;
-    approvalId: string;
+    approvalId?: string;
 }>;
 /**
  * The factory-reviewed starter set, offered when there is nothing to import.
@@ -420,15 +544,40 @@ export declare function prepareStarterBatch(opts: {
     approvalId: string;
 }>;
 /**
- * Redeem an approved BATCH record (import or starter) — every candidate, one dot each, reporting what
- * actually landed rather than what was previewed.
+ * Redeem the CHOSEN offer of a confirmed record, member by member — reporting what actually landed
+ * rather than what was previewed (dedup, concurrency and redemption-time validation can all move a
+ * member between the two moments).
+ *
+ * design/375 §4.1/§4.6 — this is the one-yes walk for every record kind: an import/starter record's
+ * whole-list batch, a card's chosen batch (each per-segment rule lands as its own candidate), or a
+ * card's chosen single (a one-member walk). Members OUTSIDE the chosen offer are simply not walked
+ * — and stay individually unredeemable through the ticket entry, same guarantee, one predicate.
+ *
+ * The walk contract, spelled out because each clause is load-bearing:
+ *  · every member goes through the SAME single-ticket redemption leg — dot CAS'd into the record
+ *    BEFORE the store write (a crash in between leaves a replayable intent), concurrent-loser
+ *    dot reuse included; the walk adds no concurrency primitive of its own;
+ *  · a refused member does NOT fold the batch: "all or nothing" is the CONFIRMATION's semantics
+ *    (one yes covered the whole offer), not the landing's transaction shape — the walk continues
+ *    and the member's row says refused, with the reason;
+ *  · resuming a partial walk IS re-walking: already-landed members answer `alreadyRedeemed: true`
+ *    and reuse their recorded dots (two concurrent walkers converge on one dot set, zero double
+ *    mints), unlanded members mint on;
+ *  · the returned table is COMPLETE — exactly one row per member of the chosen offer, in the
+ *    offer's member order, no extras — so a caller's aggregate is an honest projection: all rows
+ *    landed (`persisted` or `deduped`, both count as the consent being in effect) is full
+ *    success, and ANY refused row must project to a non-success aggregate, never to a silent
+ *    partial one.
  */
 export declare function redeemRuleBatch(opts: {
     approvalId: string;
     principal?: string;
     owner?: RuleOwner;
     deps: RuleConsentDeps;
-}): Promise<ImportResult | {
+}): Promise<{
+    members: readonly RedeemedBatchMember[];
+    rev: number;
+} | {
     status: "refused";
     reason: string;
 }>;