@sema-agent/core 5.26.0 → 5.28.0

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

@@ -1,5 +1,5 @@
-import { closeSync, constants as fsConstants, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW } = fsConstants;
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -184,6 +184,119 @@ export function scopeDirName(scope) {
     const hash = createHash("sha256").update(scope, "utf8").digest("hex").slice(0, 6);
     return `${cleaned}-${hash}`;
 }
+const caseFoldByDirIdentity = new Map();
+let caseFoldProbeSeq = 0;
+function lstatOrAbsent(p) {
+    try {
+        return lstatSync(p);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+function probeDirCaseFolds(dir) {
+    const name = `.casefold-probe-${process.pid}-${caseFoldProbeSeq++}`;
+    const writeLeg = (() => {
+        let fd;
+        try {
+            fd = openSync(join(dir, name), O_WRONLY | O_CREAT | O_EXCL, 0o600);
+        }
+        catch {
+            return undefined;
+        }
+        let identity;
+        try {
+            const st = fstatSync(fd);
+            identity = { dev: st.dev, ino: st.ino };
+        }
+        catch {
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            let swapped;
+            let orig;
+            try {
+                swapped = lstatOrAbsent(join(dir, name.toUpperCase()));
+                orig = swapped === undefined ? lstatOrAbsent(join(dir, name)) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+            if (swapped !== undefined) {
+                return identity === undefined || (swapped.dev === identity.dev && swapped.ino === identity.ino) ? true : undefined;
+            }
+            if (orig === undefined || identity === undefined)
+                return undefined;
+            return orig.dev === identity.dev && orig.ino === identity.ino ? false : undefined;
+        }
+        finally {
+            try {
+                rmSync(join(dir, name), { force: true });
+            }
+            catch {
+            }
+        }
+    })();
+    if (writeLeg !== undefined)
+        return writeLeg;
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (!/[A-Za-z]/.test(entry))
+                continue;
+            const swapped = entry.toLowerCase() !== entry ? entry.toLowerCase() : entry.toUpperCase();
+            try {
+                const orig = lstatOrAbsent(join(dir, entry));
+                if (orig === undefined)
+                    continue;
+                const other = lstatOrAbsent(join(dir, swapped));
+                const again = lstatOrAbsent(join(dir, entry));
+                if (again === undefined || again.dev !== orig.dev || again.ino !== orig.ino)
+                    continue;
+                if (other === undefined)
+                    return false;
+                return other.dev === orig.dev && other.ino === orig.ino;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
+export function dirCaseFolds(dir) {
+    let key;
+    try {
+        ensureDirExists(dir);
+        const s = statSync(dir);
+        key = `${s.dev}:${s.ino}`;
+    }
+    catch {
+    }
+    if (key !== undefined) {
+        const cached = caseFoldByDirIdentity.get(key);
+        if (cached !== undefined)
+            return cached;
+    }
+    const folds = probeDirCaseFolds(dir);
+    if (folds === undefined)
+        return undefined;
+    try {
+        const after = statSync(dir);
+        if (key === undefined || key !== `${after.dev}:${after.ino}`)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    caseFoldByDirIdentity.set(key, folds);
+    return folds;
+}
 function readScopesRecord(controlDir) {
     const path = join(controlDir, SCOPES_FILE);
     let raw;
@@ -217,6 +330,11 @@ function readScopesRecord(controlDir) {
         for (const [k, v] of Object.entries(rec.scopes)) {
             if (typeof v !== "string")
                 throw new ControlPlaneCorruptError(`scope registry entry ${JSON.stringify(k)} is not a string: ${path}`);
+            if ((v === "") !== (k === rec.rootScope)) {
+                throw new ControlPlaneCorruptError(v === ""
+                    ? `scope registry maps ${JSON.stringify(k)} to the root home but rootScope is ${rec.rootScope === undefined ? "unclaimed" : JSON.stringify(rec.rootScope)}: ${path}`
+                    : `scope registry maps the root scope ${JSON.stringify(k)} to subdir ${JSON.stringify(v)} instead of the root home: ${path}`);
+            }
         }
         scopes = rec.scopes;
     }
@@ -255,20 +373,26 @@ export function claimRootScope(controlDir, scope) {
         return { next: { rootScope: scope, scopes: { ...rec.scopes, [scope]: "" } }, result: scope };
     });
 }
-export function registerScope(memoryDir, controlDir, scope) {
+export function registerScope(memoryDir, controlDir, scope, opts) {
     return lockedScopesUpdate(controlDir, (rec) => {
-        const dirName = rec.rootScope === scope ? "" : scopeDirName(scope);
+        const dirName = rec.rootScope === scope ? "" : (rec.scopes?.[scope] ?? scopeDirName(scope));
         for (const [other, otherDir] of Object.entries(rec.scopes ?? {})) {
-            if (other !== scope && otherDir !== "" && otherDir === dirName) {
+            if (other === scope || otherDir === "")
+                continue;
+            if (otherDir === dirName) {
                 throw new ControlPlaneCorruptError(`scope directory collision: ${JSON.stringify(scope)} and ${JSON.stringify(other)} both map to ${JSON.stringify(dirName)} — refusing (fail-closed)`);
             }
+            if (dirName !== "" && otherDir.toLowerCase() === dirName.toLowerCase()) {
+                const folds = opts?.caseFoldingFs ?? dirCaseFolds(memoryDir);
+                if (folds !== false) {
+                    throw new ControlPlaneCorruptError(`scope directory collision on a case-folding filesystem: ${JSON.stringify(scope)} → ${JSON.stringify(dirName)} and ${JSON.stringify(other)} → ${JSON.stringify(otherDir)} are one physical directory under ${memoryDir}` +
+                        `${folds === undefined ? " (volume case semantics could not be probed — refusing the fold-equal pair rather than risking a silent cross-scope merge)" : ""} — refusing (fail-closed)`);
+                }
+            }
         }
         if (rec.scopes?.[scope] === undefined) {
             return { next: { ...rec, scopes: { ...rec.scopes, [scope]: dirName } }, result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
         }
-        if (rec.scopes[scope] !== dirName) {
-            return { result: rec.scopes[scope] === "" ? memoryDir : join(memoryDir, rec.scopes[scope]) };
-        }
         return { result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
     });
 }

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

@@ -223,9 +223,17 @@ export interface MemorySessionHandle {
      *  the gate's whole purpose is keeping those bytes out of the prompt, so a refused clear must not
      *  leave the injection path reading them anyway. Absent ⇒ the normal "live file wins" behavior. */
     indexOnDiskUntrusted?: boolean;
+    /** True ⇔ this session materialized through the ADOPTION-RESTRICTED (committed-view) read face:
+     *  the caller declared the session unable to persist (an explicit session-level verdict — never
+     *  inferred down here, and never derived from the plane's shape: a read-only layering
+     *  (`writeScope === null`) keeps its ordinary adopt-on-read semantics and does NOT set this).
+     *  Restricted sessions read committed state only (ledger + control-plane shadow); disk divergence
+     *  with no transaction backing is neither adopted into the committed account nor served, and
+     *  `inject` reads the materialize-time index text instead of the live on-disk file. */
+    adoptionRestricted?: boolean;
 }
 /** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */
-export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "polluted" | "invalid";
+export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "polluted" | "restricted_divergence" | "invalid";
 /** One rejected file: path (relative to the memory dir), stable code, and a model-readable reason. */
 export interface HarvestRejection {
     path: string;

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

@@ -13,7 +13,12 @@
  * MySQL is NOT "can't support vectors" — it is `portable`-capable (JSON column + in-process cosine), just not
  * `native`. A deployment injects an embedder (config-driven); the store then reports the achieved rung.
  */
-/** Lower-cased alphanumeric term set of a string (for the lexical stand-in distance). */
+/** Lower-cased lexical term set: alphanumeric runs PLUS CJK character bigrams (a single-character
+ *  run contributes its unigram). CJK scripts have no `a-z0-9` runs at all, so an alphanumeric-only
+ *  tokenizer made every pure-CJK entry an EMPTY set — never a lexical-rung candidate for any query
+ *  — and a pure-CJK query returned nothing; character bigrams are the standard analyzer unit there
+ *  (word boundaries are not written). Bigrams stay within one run: adjacency across an intervening
+ *  non-CJK character is not real adjacency. */
 export declare function termSet(s: string): Set<string>;
 /** Lexical stand-in distance: `1 - Jaccard(terms)` ∈ [0,1] ⊂ [0,2]; `null` = no overlap (not a candidate). */
 export declare function jaccardDistance(query: Set<string>, text: string): number | null;

package/dist/core/memory-vector.js

@@ -1,8 +1,18 @@
+const CJK_RUN = /[\u3040-\u30FF\u31F0-\u31FF\u3400-\u4DBF\u4E00-\u9FFF\uAC00-\uD7A3\uF900-\uFAFF]+/g;
 export function termSet(s) {
-    return new Set(s
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter(Boolean));
+    const lower = s.toLowerCase();
+    const out = new Set();
+    for (const run of lower.split(/[^a-z0-9]+/))
+        if (run)
+            out.add(run);
+    for (const m of lower.matchAll(CJK_RUN)) {
+        const chars = [...m[0]];
+        for (const c of chars)
+            out.add(c);
+        for (let i = 0; i + 1 < chars.length; i++)
+            out.add(chars[i] + chars[i + 1]);
+    }
+    return out;
 }
 export function jaccardDistance(query, text) {
     const t = termSet(text);

package/dist/core/memory.js

@@ -1,5 +1,6 @@
 import { uuidv7 } from "../internal/harness.js";
 import { parseScopeKey } from "./memory-engine/scope-contract.js";
+import { termSet } from "./memory-vector.js";
 import { sanitizeUntrustedText } from "./untrusted-text.js";
 export function supportsConsolidation(store) {
     return (typeof store.searchScored === "function" &&
@@ -148,12 +149,6 @@ export function guardedMemoryStore(inner, utilityGate) {
 function renderBullet(e) {
     return `- (${e.ts} UTC) ${e.text}`;
 }
-function termSet(s) {
-    return new Set(s
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter(Boolean));
-}
 export class InMemoryMemoryStore {
     byScope = new Map();
     cursorByScope = new Map();

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 RuleScope, type RuleDot } from "./permission-rule-model.js";
+import { 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 {
@@ -52,9 +52,19 @@ export interface RuleApprovalRecord {
     state: "pending" | "approved" | "redeemed";
     candidates: RuleCandidate[];
     createdAt: string;
-    /** The ask this record was drawn from, for reconciliation. Advisory metadata; never adjudication input. */
+    /** 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
+     *  it back, so a record minted without one refuses edits (there is nothing to bind the edit to). */
     toolCallId?: string;
     boundInputHash?: string;
+    /**
+     * The adjudicated command a CARD record was drawn for — the same post-rewrite bytes the ask carried
+     * (the form `boundInputHash` digests). Additive: absent on batch records and on every card a prior
+     * version minted. It is the edit gate's coverage input ("the edited rule must still admit THIS
+     * command"), so a record without one refuses edited candidates rather than guessing; the engine-
+     * candidate paths never read it.
+     */
+    command?: string;
     /** Monotonic revision of THIS record, bumped by every accepted transition. The compare-and-set key:
      *  comparing state alone cannot separate two different writes that both leave the state unchanged. */
     rev: number;
@@ -68,6 +78,20 @@ export interface RuleApprovalRecord {
      * previewed list by construction.
      */
     selectedCandidate?: 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.
+     */
+    edited?: {
+        index: number;
+        text: string;
+        at: string;
+    };
     /** Dots already minted for this record, keyed by candidate index — the replay anchor. */
     redeemedDots?: Record<number, RuleDot>;
 }
@@ -95,6 +119,16 @@ export interface RuleConsentDeps {
     /** Injectable clock/id for deterministic tests; defaults are the real ones. */
     now?: () => Date;
     newId?: () => string;
+    /**
+     * Deployment lever for the card-edit face: whether `confirmRuleApproval` accepts a FRESH
+     * `editedCandidate`. Absent or `false` = OFF (the default — the edit face widens what a fabricated
+     * confirmation could mint, from "one of the engine's bounded candidates" to "any same-head rule
+     * passing the coverage gate", so it is opt-in). Any other non-boolean value is a configuration
+     * mistake and refuses LOUDLY at the read — never silently mapped to a default. Replaying an edit a
+     * record already settled is a pure record read and does not consult this switch: the minting already
+     * happened, and withholding the receipt helps no one.
+     */
+    cardEdits?: boolean;
 }
 /** In-memory approval records — the test backend and the reference CAS semantics. */
 export declare class InMemoryRuleApprovalRecordStore implements RuleApprovalRecordStore {
@@ -157,21 +191,61 @@ 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: 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.
+     * 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`.
      */
     selectedCandidate?: 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
+     * keeps refusing caller candidates). `text` is the rule as authored; `boundInputHash` must echo the
+     * record's own bound-input digest — the submitter's proof of "I am editing the card that showed THIS
+     * 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`.
+     */
+    editedCandidate?: {
+        text: string;
+        boundInputHash: string;
+    };
     deps: RuleConsentDeps;
 }): Promise<ConfirmResult>;
-/** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up). */
-export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict";
-/** The confirmation outcome: landed, or refused with a named reason. */
+/** Why a confirmation did not land. A closed set so a host can branch (re-present, re-fetch, give up).
+ *  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
+ *     (missing echo, a record minted without one, or a different card). Refused BEFORE anything else,
+ *     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";
+/** The confirmation outcome: landed, or refused with a named reason.
+ *
+ *  `mintedCandidate` (additive) is present exactly when an EDITED candidate settled this confirmation —
+ *  fresh mint and idempotent replay alike (a client retrying a lost response gets the same index, the
+ *  same canonical rule text and the same deterministically re-minted ticket, never a push toward a
+ *  second card). `rule` is the CANONICAL spelling, which may differ from the submitted bytes (spelling
+ *  normalization); a surface echoes it back so the person sees the form that will actually persist.
+ *
+ *  `detail` (additive, refusal arm) rides `edit_rejected`: `code` is the shared validator's refusal
+ *  code when the validator is what refused, absent when another gate did; `message` always says why. */
 export type ConfirmResult = {
     ok: true;
+    mintedCandidate?: {
+        index: number;
+        rule: string;
+        ticket: RuleTicket;
+    };
 } | {
     ok: false;
     reason: ConfirmRefusalReason;
+    detail?: {
+        code?: RuleRejectCode;
+        message: string;
+    };
 };
 /** What a redemption produced. `alreadyRedeemed` marks the replay path — the same dot, no second rule. */
 export type RedeemResult = {

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

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { parseAllowRuleText, suggestRulesForCommand } from "./permission-rule-model.js";
+import { parseAllowRuleText, ruleAdmitsCommand, suggestRulesForCommand } from "./permission-rule-model.js";
 import { errText, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
@@ -109,6 +109,7 @@ export async function prepareCardApproval(opts) {
         state: "pending",
         rev: 0,
         candidates,
+        command: opts.command,
         createdAt: nowIso(opts.deps),
         ...(opts.toolCallId !== undefined ? { toolCallId: opts.toolCallId } : {}),
         ...(opts.boundInputHash !== undefined ? { boundInputHash: opts.boundInputHash } : {}),
@@ -120,10 +121,17 @@ const CARD_RULE_TOOL = "Bash";
 export async function confirmRuleApproval(opts) {
     const caller = resolveCallerOwner(opts.principal, opts.owner, "confirmRuleApproval");
     const no = (reason) => ({ ok: false, reason });
+    if (opts.editedCandidate !== undefined && opts.selectedCandidate !== undefined) {
+        const e = new Error("confirmRuleApproval takes selectedCandidate OR editedCandidate, never both — one confirmation carries one choice");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
     const rec = await opts.deps.approvals.get(opts.approvalId);
     const recOwner = rec === undefined ? undefined : ownerOfRecord(rec);
     if (rec === undefined || recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return no("record_not_found");
+    if (opts.editedCandidate !== undefined)
+        return await confirmEditedCandidate(rec, opts.editedCandidate, opts.deps);
     if (rec.kind === "card") {
         const chosen = opts.selectedCandidate;
         if (chosen === undefined)
@@ -145,6 +153,89 @@ export async function confirmRuleApproval(opts) {
     const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
     return won ? { ok: true } : no("conflict");
 }
+function normalizeEditedSpelling(text) {
+    const m = /^([A-Za-z][A-Za-z0-9_]*)\((.+) \*\)$/.exec(text);
+    if (m === null)
+        return text;
+    const head = m[1];
+    const body = m[2];
+    if (head === undefined || body === undefined || body.includes("*"))
+        return text;
+    return `${head}(${body}:*)`;
+}
+async function confirmEditedCandidate(rec, edit, deps) {
+    const no = (reason, detail) => ({
+        ok: false,
+        reason,
+        ...(detail !== undefined ? { detail } : {}),
+    });
+    if (rec.kind !== "card") {
+        return no("edit_rejected", { message: "a batch record takes no edited candidate — its confirmation covers the previewed list whole" });
+    }
+    if (typeof edit.boundInputHash !== "string" || edit.boundInputHash === "")
+        return no("edit_binding_mismatch");
+    if (rec.boundInputHash === undefined) {
+        return no("edit_binding_mismatch");
+    }
+    if (edit.boundInputHash !== rec.boundInputHash)
+        return no("edit_binding_mismatch");
+    if (rec.state === "approved" || rec.state === "redeemed") {
+        if (rec.edited === undefined)
+            return no("selection_mismatch");
+        const canonical = rec.candidates[rec.edited.index]?.rule;
+        if (canonical === undefined)
+            return no("selection_mismatch");
+        let hit = edit.text === rec.edited.text;
+        if (!hit) {
+            const reparsed = parseAllowRuleText(normalizeEditedSpelling(edit.text));
+            hit = "rule" in reparsed && reparsed.rule.rule === canonical;
+        }
+        if (!hit)
+            return no("selection_mismatch");
+        return { ok: true, mintedCandidate: { index: rec.edited.index, rule: canonical, ticket: mintRuleTicket(rec.id, rec.edited.index) } };
+    }
+    if (rec.state !== "pending")
+        return no("not_pending");
+    if (deps.cardEdits !== undefined && typeof deps.cardEdits !== "boolean") {
+        throw new Error(`RuleConsentDeps.cardEdits must be a boolean when present (got ${typeof deps.cardEdits}) — refusing to guess whether the card-edit face is enabled`);
+    }
+    if (deps.cardEdits !== true)
+        return no("edit_disabled");
+    const scope = rec.candidates[0]?.scope;
+    if (scope === undefined || !rec.candidates.every((c) => sameScope(c.scope, scope))) {
+        return no("edit_rejected", { message: "the record's candidates carry no single common scope — an edited candidate inherits the card's scope, and a record without one is malformed" });
+    }
+    if (rec.command === undefined) {
+        return no("edit_rejected", { message: "the record does not carry the adjudicated command (minted before card edits existed) — coverage cannot be verified, so the edit is refused" });
+    }
+    const parsed = parseAllowRuleText(normalizeEditedSpelling(edit.text));
+    if ("reject" in parsed)
+        return no("edit_rejected", { code: parsed.reject.code, message: parsed.reject.message });
+    if (!ruleAdmitsCommand(parsed.rule, rec.command)) {
+        return no("edit_rejected", {
+            message: `the edited rule "${parsed.rule.rule}" does not admit the command that was decided ("${rec.command}") — a card's edit may widen how much the rule covers, never move it to a different grant`,
+        });
+    }
+    const index = rec.candidates.length;
+    const next = {
+        ...rec,
+        rev: rec.rev + 1,
+        state: "approved",
+        candidates: [...rec.candidates, { rule: parsed.rule.rule, scope }],
+        selectedCandidate: index,
+        edited: { index, text: edit.text, at: nowIso(deps) },
+    };
+    const won = await deps.approvals.cas(rec.id, rec.rev, next);
+    if (!won) {
+        const again = await deps.approvals.get(rec.id);
+        if (again === undefined)
+            return no("record_not_found");
+        if (again.state === "pending")
+            return no("conflict");
+        return await confirmEditedCandidate(again, edit, deps);
+    }
+    return { ok: true, mintedCandidate: { index, rule: parsed.rule.rule, ticket: mintRuleTicket(rec.id, index) } };
+}
 export async function redeemRuleTicket(opts) {
     const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleTicket");
     const parsed = parseRuleTicket(opts.ticket);

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

@@ -94,7 +94,7 @@ export interface RuleTombstone {
     deletedBy: RuleDot;
 }
 /** Why a rule text was refused. Codes are stable so an import report can group by them. */
-export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.too_long" | "unsupported.tool" | "unsupported.wildcard";
+export type RuleRejectCode = "invalid.grammar" | "invalid.empty_command" | "invalid.not_simple_command" | "invalid.bare_interpreter_prefix" | "invalid.unbalanced_quotes" | "invalid.control_chars" | "invalid.too_long" | "unsupported.tool" | "unsupported.wildcard";
 export interface RuleReject {
     code: RuleRejectCode;
     message: string;
@@ -120,6 +120,69 @@ export declare const MAX_RULE_TEXT_CHARS = 512;
  * an EXACT rule naming a whole interpreter command line stays legal, since it authorizes one command.
  */
 export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
+/**
+ * design/185 §1 — the reviewed command/subcommand grammar the PREFIX suggestion is generated from
+ * (exactly the "reviewed command/subcommand grammar" the generator's history note names as the one
+ * thing that would let it produce a prefix).
+ *
+ * A flat set of BODIES — word sequences, each at least two words. A prefix candidate exists for a
+ * command iff some body here is a word-boundary prefix of its folded form, and the LONGEST hit wins:
+ * the deeper body is the narrower rule, so listing (or not listing) a deeper body is how this table
+ * sets suggestion granularity per branch. No groups, no denylist, and no fallback arm: a head outside
+ * the table, an unreviewed subcommand, a runtime-defined name (a git alias, a `git-<x>`/`cargo-<x>`
+ * external subcommand, a gh extension, a kubectl plugin), a flag or operand in a body position and a
+ * quoted token all fail the same way — by not being listed. Closure comes from positive enumeration
+ * itself, never from an exclusion list racing names that only exist at runtime.
+ *
+ * Review criteria — every row must pass BOTH axes (the same principle as the interpreter refusal
+ * above: the rule text must not read narrower than what it grants):
+ *  · "runs what it is told to": a body whose use is fetching or naming a program to execute
+ *    (`npm exec`, `docker run`, `kubectl exec`, `gh extension`, `git submodule foreach`, the install
+ *    family) is refused — one click cannot be read as having granted arbitrary execution. Running the
+ *    WORKSPACE'S OWN pinned content (`npm run`, `npm ci`, `cargo run`, `cargo test`) is inside the
+ *    boundary: the scripts and lockfiles those execute are checked into the repository being worked on.
+ *  · "rewrites what others execute": a body whose main use is writing configuration that changes what
+ *    OTHER commands later run (`git config` — hooksPath/pager/alias; `kubectl config` —
+ *    exec-credential; `npm config`/`npm set` — script-shell; `go env` — persisted GOFLAGS/GOBIN) is
+ *    refused — its readable width and its real width differ by a whole composition surface.
+ * Past both axes there is deliberately NO "dangerousness" axis: `git push:*` and `git rebase:*` are
+ * wide but readable, and a person nodding at that text is granting exactly that.
+ *
+ * Residual width, stated rather than hidden (a reviewed trade, not an oversight): a prefix rule
+ * admits ANY arguments after its body, and some listed bodies carry flags that name a program to
+ * execute (`go build`/`go test`/`go vet -toolexec`, `git fetch --upload-pack`, `git rebase -x`,
+ * `git grep -O`, `git push --receive-pack`). The axes judge a body's MAIN use, not every flag —
+ * per-flag grammar is the road this module's history rejected twice, and applied consistently it
+ * would empty the table. Three standing fences hold that residue: the org deny/ask layer runs ahead
+ * of the rule lane and cannot be silenced by it; a mandated ask (egress/irreversibility marks,
+ * shellGate:"always") is not rule-clearable either; and the narrower exact candidate — plus minting
+ * no rule at all — is always on the same card.
+ *
+ * Maintenance: adding a row is a reviewed change — keep the per-group reasoning beside it current.
+ * The integrity pins (every body ≥ 2 words, lowercase word shape, no interpreter heads, no
+ * duplicates) are enforced by this module's test suite. This table and the read-only classifier's
+ * allowlists are DIFFERENT instruments and must never be merged or cross-referenced: that one is a
+ * machine auto-allow face whose criterion is "provably read-only"; this one is a human suggestion
+ * face whose criterion is "width a person can read off the rule text". One guards against a machine
+ * loosening; the other against a person being misled.
+ */
+export declare const SUGGESTION_LEXICON: readonly string[];
+/**
+ * Render a peer- or file-controlled value for a DISCLOSURE line (a warning, a refusal message, an
+ * operator log). Takes `unknown` on purpose: most of these values are typed but arrive off a wire or a
+ * file, so the runtime value can be anything, and a signature that demanded a string would push a bare
+ * `String(x)` to every call site — the exact step that gets forgotten. Rule texts are the motivating case; the same treatment is owed to every untrusted
+ * field a line interpolates (a wire `reason`, an actor id), since the hazard is the character class,
+ * not which field carries it.
+ *
+ * Quoting a refused text verbatim would carry the exact sequence the refusal exists to keep off a
+ * display surface, and would print the two texts a reader has to tell apart — `Bash(echo hi)` and
+ * `Bash(echo<ZWSP>hi)` — identically, so the report could not name WHICH rule it means. Every character
+ * {@link CONTROL_CHARS_RE} covers is therefore printed as its `\uXXXX` escape (`\u{XXXXX}` above the
+ * BMP — the TAG block U+E0020–U+E007F is a `\p{Cf}` family that lives there); everything else passes
+ * through, so an ordinary rule text reads normally. The result is length-bounded.
+ */
+export declare function escapeForDisclosure(value: unknown): string;
 /**
  * Parse one rule text into its canonical shape, or refuse it with a reason.
  *
@@ -184,11 +247,29 @@ export interface RuleSuggestion {
 /**
  * The 1-2 candidates offered on an approval card for `command`.
  *
- * The exact form (this whole command line) is always offered when the command is matchable at all. A
- * prefix form is offered only when it is a shape a person can read as narrow: the upstream multi-word
- * convention (`git status`, `npm run`) is preferred over a bare program name, and no prefix at all is
- * offered for an interpreter head — that candidate would be refused by the validator anyway, and
- * offering a candidate the store will not accept is worse than offering one fewer.
+ * **Array order is a documented CONTRACT, not an implementation accident**: display order = array
+ * order = narrowest first. The EXACT form (this whole command line) is always index 0 whenever
+ * anything is offered at all; a broader reviewed PREFIX form — at most one — follows at index 1.
+ * Selection indices and redemption tickets are index-keyed against this order (a card's
+ * `selectedCandidate` and its `rt.<index>.` tickets), so consumers may rely on it.
+ *
+ * The prefix candidate comes ONLY from {@link SUGGESTION_LEXICON} — the longest reviewed body that is
+ * a word-boundary prefix of the folded command. History, and why there is no heuristic arm: two
+ * rounds of guessing produced two different wrong answers — a bare program name (`rm -f x` →
+ * `Bash(rm:*)`), then an operand mistaken for a subcommand (`rm harmless.txt` →
+ * `Bash(rm harmless.txt:*)`, which admits a second, unnamed target) — and both failed the same way:
+ * nothing in the command TEXT distinguishes a subcommand from an operand without a per-command
+ * grammar. The lexicon IS that grammar, per reviewed row; anything it does not list (a bare verb, an
+ * interpreter head, an unreviewed subcommand, a runtime-defined name) yields no prefix, with no
+ * fallback. Naive spacing note: `folded` keeps quoted whitespace, so splitting on single spaces can
+ * shear a quoted segment — harmless in this direction, because the sheared pieces carry quote
+ * characters and can never equal a bare lexicon word; every suspicious shape lands on "no prefix".
+ *
+ * Every produced candidate must survive the round trip — parse as a rule AND admit the very command
+ * it was minted from. True by construction (a word-boundary lexicon prefix of a folded simple command
+ * is exactly the matcher's two arms); enforced anyway, fail-closed: a candidate that would not
+ * round-trip is silently not offered, since offering an option redemption would refuse is worse than
+ * offering one fewer.
  *
  * Returns an empty array for anything the rule lane cannot speak for (compounds, redirections,
  * substitutions) — the card then simply carries no "don't ask again" option, which is the honest answer.