@sema-agent/core 7.0.2 → 7.2.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 RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
+import { type EditedRuleBreadthWarning, type UncoveredSegmentDetail, 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. */
@@ -48,10 +48,16 @@ export type RuleApprovalKind = "card" | "import" | "starter";
  *  · `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
+ *    `segments` (each member's source segment, index-aligned with `candidates`),
  *    `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
+ *    prepare-time coverage snapshot) and — since `schema: 3` (design/382 §3.5) — `uncoveredDetail`,
+ *    one reason row per counted segment in segment order: WHY each stayed uncovered is a mint-time
+ *    fact that cannot be re-derived from candidate texts, so it must be stored or a crash/reload
+ *    rebuild would render a card that says less than the first render did (record-is-what-you-see).
+ *    REQUIRED on a card batch, all three: "optional, validated when present" is the
+ *    silent-absence-passes shape this record form already refused once, and it is not re-imported
+ *    for the new seat. On an import/starter record there is no compound command
+ *    and no coverage snapshot, so all three 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.
@@ -67,6 +73,7 @@ export type RuleOffer2 = {
     readonly candidates: readonly number[];
     readonly segments?: readonly string[];
     readonly uncoveredSegments?: number;
+    readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
 /** A durable record of one pending/settled human decision about minting rules.
  *
@@ -81,12 +88,16 @@ export interface RuleApprovalRecord {
     /** 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}.
+     * design/375 §4.5 — the record-form version stamp. A stored row WITHOUT it — or carrying an older
+     * number — 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}. `3` (design/382 §3.5, B8/B7): the card batch's
+     * `uncoveredDetail` seat became REQUIRED and `edited.warnings` became storable — a `schema: 2`
+     * row is read back stale exactly like the pre-stamp rows before it (the short-lived-pending
+     * bargain, unchanged).
      */
-    schema: 2;
+    schema: 3;
     kind: RuleApprovalKind;
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
@@ -137,18 +148,26 @@ export interface RuleApprovalRecord {
      * 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.
+     *
+     * `warnings` (design/382 §3.3-5) — the BREADTH warning codes the text gates raised on this edit,
+     * written in the same CAS that settles it: "the width was named before the yes" becomes a fact the
+     * record itself carries, auditable after any crash or upgrade. Optional; present only when a
+     * warning was raised, and when present it is an array from the closed code set (the read-side
+     * integrity gate refuses anything else). Codes only — the sentences are derivable from the
+     * canonical rule text and are deliberately not stored (no second copy to drift).
      */
     edited?: {
         index: number;
         text: string;
         at: string;
+        warnings?: readonly EditedRuleBreadthWarning["code"][];
     };
     /** 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
+ * CURRENT (`schema: 3`) 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.
@@ -209,6 +228,14 @@ export interface RuleConsentDeps {
      * coverage reads see no session rows — both fail toward asking.
      */
     sessionRules?: SessionRuleOverlay;
+    /**
+     * design/382 §2.4-6 — the deployment's sensitive-read negative control for the directoryRead MINT
+     * floor, same-source with its compiled read-deny judge (`(d) => readDeny.matchPath(d) !== null` is
+     * the canonical wiring). Consulted only when a card would PROPOSE a directory authorization from a
+     * cd segment — never by the explicit-consent doors (hand-written, import), which carry their own
+     * preview and validation. Absent ⇒ the engine's built-in default deny table stands in (refusal-only).
+     */
+    deniesDirectoryRead?: (directory: string) => boolean;
 }
 /** In-memory approval records — the test backend and the reference CAS semantics, the stale-row
  *  envelope read included. */
@@ -297,6 +324,17 @@ export declare function prepareCardApproval(opts: {
      * leans wide — the over-offer direction, which redemption's per-rule validation keeps safe.
      */
     cwd?: string;
+    /**
+     * design/382 §2.4 (adversarial-review r2) — the EXECUTION working directory of the adjudicated
+     * call: the live tracked cwd the shell will resolve a relative `cd ./x` against, threaded by the
+     * caller exactly like `cwd` (the runner's ask-projection seat threads its `handsCwdRef.current`;
+     * a host preparing cards for its own calls threads whatever base those calls execute under).
+     * ONLY the relative-cd resolution reads it; scope eligibility and the derived project scope stay
+     * on `cwd`. Absent ⇒ `cwd` is the base (the single-value deployment, where the two coincide).
+     * Present and DIFFERENT, it is what keeps this durable consent path and the advisory ask-time
+     * projection minting the SAME directory member — two faces reading one world.
+     */
+    execCwd?: string;
     deps: RuleConsentDeps;
 }): Promise<{
     approvalId: string;
@@ -346,7 +384,7 @@ export declare function confirmRuleApproval(opts: {
 /** 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
+ *   - `"record_schema_stale"` — the record predates the current (`schema: 3`) 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
@@ -394,6 +432,16 @@ export type ConfirmResult = {
 export type EditedRuleTextPrecheck = {
     ok: true;
     canonicalRule: string;
+    /**
+     * design/382 §3.3-5 — BREADTH notes about the accepted rule (additive; absent = nothing to
+     * say). A warning is never a refusal: the muscle-memory wide forms are legal (§3.4), and this
+     * seat is what makes accepting one an informed act. Rendering them beside the input line is
+     * the surface's duty (the engine cannot force a display); what the ENGINE guarantees is the
+     * durable half — a confirmation through the edit arm writes the hit codes into the record
+     * (`edited.warnings`), so "the width was named before the yes" is an auditable fact. The
+     * confirmation result deliberately does NOT repeat them (one fact, one loud place).
+     */
+    warnings?: readonly EditedRuleBreadthWarning[];
 } | {
     ok: false;
     code?: RuleRejectCode;
@@ -483,19 +531,20 @@ export interface ImportPreview {
         reason: string;
     }>;
     /**
-     * #490 件4 — the entries whose SPELLING was rewritten on the way in, `from` as the settings file
-     * writes it and `to` as this lane will hold it (`Bash(npm run *)` → `Bash(npm run:*)`).
-     *
-     * Exactly ONE row per candidate the translation produced, in candidate order, carrying that
-     * candidate's `scope`. The scope is load-bearing rather than decoration: the same file line can
-     * appear in two layers and become two candidates in two scopes, and a report keyed on the text alone
-     * would show one row for two consents (independent-review finding — the row count and the candidate
-     * count must be readable against each other).
+     * ALWAYS EMPTY in this version — a compatibility seat, kept on the wire shape so an existing reader
+     * keeps finding the key (removing a wire field would break readers for no gain).
      *
-     * Always present, empty when nothing was translated: a person confirming this batch is being shown
-     * rule texts that are not the ones in their file, and a preview that let that pass silently would be
-     * asking for consent to something it had not shown them. Entries refused AFTER translation are not
-     * here — they are in `skipped`, named as the file writes them.
+     * The seat once carried the entries whose MATCH FORM was rewritten on the way in (the space-star
+     * suggestion form of the other product translated to this lane's colon-star form, one row per
+     * translated candidate with its `scope`). That translation is retired: the space-star wildcard is
+     * now a first-class match form of this lane's own grammar, so an entry's match form imports as the
+     * file states it — `Bash(npm run *)` lands as `Bash(npm run *)`, never as a colon-star — and nothing
+     * is ever pushed here. What `candidates` carries is the grammar's CANONICAL re-projection of each
+     * entry (the parser folds spacing: `Bash(npm<TAB>run *)` lands as `Bash(npm run *)`); that is the
+     * ordinary normalization every rule text in this lane undergoes, the same one the store applies,
+     * and not a translation this seat reports. An entry whose star placement has no rule form is
+     * refused into `skipped` under `unsupported.wildcard`, named as the file writes it. A reader
+     * rendering a "rewritten spellings" column from this seat renders an empty column, correctly.
      */
     translated: Array<{
         from: string;

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

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { escapeForDisclosure, hasUnrenderableCharacters, parseAllowRuleText, ruleAdmitsCommand, segmentCoverageOf, suggestRulesForCommand, translateImportedWildcardRule, } from "./permission-rule-model.js";
+import { escapeForDisclosure, hasUnrenderableCharacters, parseAllowRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, segmentCoverageOf, suggestRulesForCommand, } from "./permission-rule-model.js";
 import { errText, isValidConsentScope, normalizePersistedRule, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
@@ -7,7 +7,7 @@ export class InMemoryRuleApprovalRecordStore {
         const r = this.rows.get(id);
         if (r === undefined)
             return undefined;
-        if (r.schema !== 2) {
+        if (r.schema !== 3) {
             return {
                 staleSchema: true,
                 id: r.id,
@@ -139,8 +139,42 @@ function approvalRecordDamageOf(rec) {
                 if (!Number.isInteger(offer.uncoveredSegments) || offer.uncoveredSegments < 0) {
                     return `card batch offer ${at} must carry a non-negative uncovered-segment count`;
                 }
+                const detail = offer.uncoveredDetail;
+                if (!Array.isArray(detail))
+                    return `card batch offer ${at} must carry its uncovered-segment reason rows`;
+                if (detail.length !== offer.uncoveredSegments) {
+                    return `card batch offer ${at} carries ${detail.length} reason rows for an uncovered-segment count of ${offer.uncoveredSegments} — one fact, two seats, and they must agree`;
+                }
+                for (const [ri, row] of detail.entries()) {
+                    if (typeof row !== "object" ||
+                        row === null ||
+                        typeof row.segment !== "string" ||
+                        (row.reason !== "redirection" && row.reason !== "no_rule_form" && row.reason !== "cap_overflow")) {
+                        return `card batch offer ${at} reason row ${ri} is not a segment/reason row from the closed reason set`;
+                    }
+                }
+                if (detail.length > 0) {
+                    const rows = detail;
+                    const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: CARD_RULE_TOOL, cwd: undefined }) : undefined;
+                    if (table === undefined) {
+                        return `card batch offer ${at} carries reason rows but the record's command cannot back them — a row without a readable source command is a row nobody can audit`;
+                    }
+                    let cursor = 0;
+                    for (const [ri, row] of rows.entries()) {
+                        let found = -1;
+                        for (let j = cursor; j < table.length; j++) {
+                            if (table[j]?.segment === row.segment) {
+                                found = j;
+                                break;
+                            }
+                        }
+                        if (found === -1)
+                            return `card batch offer ${at} reason row ${ri} names a segment the record's command does not carry at or after that position`;
+                        cursor = found + 1;
+                    }
+                }
             }
-            else if (offer.segments !== undefined || offer.uncoveredSegments !== undefined) {
+            else if (offer.segments !== undefined || offer.uncoveredSegments !== undefined || offer.uncoveredDetail !== undefined) {
                 return `${escapeForDisclosure(rec.kind)} batch offer ${at} must not carry segment metadata — there is no compound command behind it`;
             }
         }
@@ -149,6 +183,16 @@ function approvalRecordDamageOf(rec) {
         if (!claimed.has(at))
             return `candidate ${at} belongs to no offer — every candidate row is claimed by exactly one offer`;
     }
+    if (rec.edited !== undefined) {
+        if (typeof rec.edited !== "object" || rec.edited === null)
+            return "the edited seat is not an object";
+        const w = rec.edited.warnings;
+        if (w !== undefined) {
+            if (!Array.isArray(w) || w.length !== 1 || (w[0] !== "broad_prefix" && w[0] !== "compound_prefix")) {
+                return "the edited seat's warnings are not a single-code array from the closed breadth-code set";
+            }
+        }
+    }
     return undefined;
 }
 export function ruleOffersOfRecord(rec) {
@@ -163,21 +207,51 @@ export function ruleOffersOfRecord(rec) {
         return { rule: parsed.rule.rule, match: parsed.rule.match, command: parsed.rule.command };
     };
     return rec.offers.map((offer) => {
-        if (offer.kind === "single")
-            return { kind: "single", ...tripleOf(offer.candidate) };
+        if (offer.kind === "single") {
+            const t = tripleOf(offer.candidate);
+            if (t.match === "subpath") {
+                throw new Error("approval-record single offer references a directory rule — a shape this engine does not mint; refusing to render it");
+            }
+            return { kind: "single", ...t };
+        }
         const segments = offer.segments;
-        if (segments === undefined || offer.uncoveredSegments === undefined) {
+        if (segments === undefined || offer.uncoveredSegments === undefined || offer.uncoveredDetail === undefined) {
             throw new Error("a batch offer without mint-time segment metadata has no card face to project — import/starter batches render as previews, not offer cards");
         }
+        const rawDetail = offer.uncoveredDetail;
+        const count = offer.uncoveredSegments;
+        const detail = [];
+        const detailDamaged = (() => {
+            if (!Array.isArray(rawDetail) || !Number.isInteger(count) || count < 0 || rawDetail.length !== count)
+                return true;
+            for (let i = 0; i < rawDetail.length; i++) {
+                const row = rawDetail[i];
+                if (typeof row !== "object" || row === null)
+                    return true;
+                const segment = row.segment;
+                const reason = row.reason;
+                if (typeof segment !== "string" || (reason !== "redirection" && reason !== "no_rule_form" && reason !== "cap_overflow"))
+                    return true;
+                detail.push({ segment, reason });
+            }
+            return false;
+        })();
+        if (detailDamaged) {
+            throw new Error("a batch offer's uncovered-segment reason rows do not match their count or the closed reason set — refusing to render damaged mint-time facts as a card face");
+        }
         return {
             kind: "batch",
             rules: offer.candidates.map((candidate, i) => {
                 const segment = segments[i];
                 if (segment === undefined)
                     throw new Error(`batch offer member ${i} has no source segment recorded`);
-                return { ...tripleOf(candidate), segment };
+                const t = tripleOf(candidate);
+                return t.match === "subpath"
+                    ? { kind: "directoryRead", rule: t.rule, directory: t.command, segment }
+                    : { kind: "command", rule: t.rule, match: t.match, command: t.command, segment };
             }),
-            uncoveredSegments: offer.uncoveredSegments,
+            uncoveredSegments: count,
+            uncoveredDetail: detail,
         };
     });
 }
@@ -234,12 +308,19 @@ export async function prepareCardApproval(opts) {
             if (sessionRows.length > 0)
                 table = [...sessionRows, ...listed.rules];
         }
-        coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId });
+        coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
     }
     catch {
         coverage = undefined;
     }
-    const suggested = suggestRulesForCommand(opts.command, coverage !== undefined ? { coverage } : undefined);
+    const suggested = suggestRulesForCommand(opts.command, {
+        ...(coverage !== undefined ? { coverage } : {}),
+        scope,
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}),
+        ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+        ...(opts.deps.deniesDirectoryRead !== undefined ? { deniesDirectoryRead: opts.deps.deniesDirectoryRead } : {}),
+    });
     const candidates = [];
     const claimedBy = new Map();
     const claim = (text) => {
@@ -257,13 +338,14 @@ export async function prepareCardApproval(opts) {
             candidates: offer.rules.map((r) => claim(r.rule)),
             segments: offer.rules.map((r) => r.segment),
             uncoveredSegments: offer.uncoveredSegments,
+            uncoveredDetail: offer.uncoveredDetail ?? [],
         });
     if (candidates.length === 0)
         return undefined;
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 2,
+        schema: 3,
         kind: "card",
         state: "pending",
         rev: 0,
@@ -366,7 +448,8 @@ function checkEditedRuleText(text, command) {
             message: `the edited rule "${parsed.rule.rule}" does not admit the command that was decided ("${escapeForDisclosure(command)}") — a card's edit may widen how much the rule covers, never move it to a different grant`,
         };
     }
-    return { ok: true, canonicalRule: parsed.rule.rule };
+    const warnings = ruleBreadthWarningsOf(parsed.rule);
+    return { ok: true, canonicalRule: parsed.rule.rule, ...(warnings.length > 0 ? { warnings } : {}) };
 }
 export function precheckEditedRuleText(text, command) {
     if (typeof text !== "string") {
@@ -443,7 +526,7 @@ async function confirmEditedCandidate(rec, edit, deps) {
         candidates: [...rec.candidates, { rule: checked.canonicalRule, scope }],
         offers: [...rec.offers, { kind: "single", candidate: index }],
         selectedOffer: rec.offers.length,
-        edited: { index, text: edit.text, at: nowIso(deps) },
+        edited: { index, text: edit.text, at: nowIso(deps), ...(checked.warnings !== undefined ? { warnings: checked.warnings.map((w) => w.code) } : {}) },
     };
     const won = await deps.approvals.cas(rec.id, rec.rev, next);
     if (!won) {
@@ -675,30 +758,36 @@ export async function prepareCcImport(opts) {
                 skipped.push({ rule: String(entry), reason: "settings entry is not a string" });
                 continue;
             }
+            if (entry.startsWith("Read(")) {
+                const parsed = parseAllowRuleText(entry);
+                if ("reject" in parsed) {
+                    skipped.push({
+                        rule: entry,
+                        reason: "unsupported.form: only the Read(//abs-dir/**) directory form imports in v1 — this entry stays in the settings file, unimported",
+                    });
+                    continue;
+                }
+                if (!candidates.some((c) => c.rule === parsed.rule.rule && sameScope(c.scope, scope))) {
+                    candidates.push({ rule: parsed.rule.rule, scope });
+                }
+                continue;
+            }
             if (!entry.startsWith("Bash(")) {
                 const reason = /^[A-Za-z][A-Za-z0-9_]*\(.*\)$/.test(entry)
-                    ? "unsupported.tool: only Bash(...) command rules import in v1 — this entry stays in the settings file, unimported"
+                    ? "unsupported.tool: only Bash(...) command rules and Read(//abs-dir/**) directory rules import in v1 — this entry stays in the settings file, unimported"
                     : /^[A-Za-z][A-Za-z0-9_-]*$/.test(entry)
                         ? "unsupported.form: a bare tool-name entry is a name-set item, not a command rule — it stays in the settings file, unimported"
-                        : "unsupported.form: not a Bash(...) command rule — it stays in the settings file, unimported";
+                        : "unsupported.form: not a command rule spelling this version imports — it stays in the settings file, unimported";
                 skipped.push({ rule: entry, reason });
                 continue;
             }
-            const wildcard = translateImportedWildcardRule(entry);
-            if (wildcard !== undefined && "skip" in wildcard) {
-                skipped.push({ rule: entry, reason: wildcard.skip });
-                continue;
-            }
-            const text = wildcard?.rule ?? entry;
-            const parsed = parseAllowRuleText(text);
+            const parsed = parseAllowRuleText(entry);
             if ("reject" in parsed) {
                 skipped.push({ rule: entry, reason: `${parsed.reject.code}: ${parsed.reject.message}` });
                 continue;
             }
             if (candidates.some((c) => c.rule === parsed.rule.rule && sameScope(c.scope, scope)))
                 continue;
-            if (wildcard !== undefined)
-                translated.push({ from: entry, to: parsed.rule.rule, scope });
             candidates.push({ rule: parsed.rule.rule, scope });
         }
     }
@@ -708,7 +797,7 @@ export async function prepareCcImport(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 2,
+        schema: 3,
         kind: "import",
         state: "pending",
         rev: 0,
@@ -742,7 +831,7 @@ export async function prepareStarterBatch(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
-        schema: 2,
+        schema: 3,
         kind: "starter",
         state: "pending",
         rev: 0,