@sema-agent/core 5.57.0 → 5.58.0

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