@sema-agent/core 5.56.0 → 5.58.0

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

@@ -1,11 +1,21 @@
 import { randomBytes } from "node:crypto";
-import { parseAllowRuleText, ruleAdmitsCommand, suggestRulesForCommand } from "./permission-rule-model.js";
+import { hasUnrenderableCharacters, parseAllowRuleText, ruleAdmitsCommand, segmentCoverageOf, suggestRulesForCommand, } from "./permission-rule-model.js";
 import { errText, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
     async get(id) {
         const r = this.rows.get(id);
-        return r === undefined ? undefined : structuredClone(r);
+        if (r === undefined)
+            return undefined;
+        if (r.schema !== 2) {
+            return {
+                staleSchema: true,
+                id: r.id,
+                ...(typeof r.principal === "string" ? { principal: r.principal } : {}),
+                ...(r.owner !== undefined ? { owner: structuredClone(r.owner) } : {}),
+            };
+        }
+        return structuredClone(r);
     }
     async create(record) {
         if (this.rows.has(record.id))
@@ -80,6 +90,90 @@ function storeForOwner(provider, owner) {
     }
     return store;
 }
+function isStale(rec) {
+    return rec.staleSchema === true;
+}
+const STALE_RECORD_MESSAGE = "this approval record predates the current record form, and the decision it carried is void — re-trigger the command to draw a fresh card";
+function offerMembersOf(offer) {
+    return offer.kind === "single" ? [offer.candidate] : offer.candidates;
+}
+function approvalRecordDamageOf(rec) {
+    if (!Array.isArray(rec.candidates))
+        return "the record carries no candidate list";
+    if (!Array.isArray(rec.offers) || rec.offers.length === 0)
+        return "the record carries no offers";
+    const claimed = new Set();
+    for (const [at, offer] of rec.offers.entries()) {
+        if (typeof offer !== "object" || offer === null)
+            return `offer ${at} is not an offer object`;
+        if (offer.kind !== "single" && offer.kind !== "batch")
+            return `offer ${at} has an unknown kind`;
+        if (offer.kind === "batch" && (!Array.isArray(offer.candidates) || offer.candidates.length === 0)) {
+            return `batch offer ${at} has no members`;
+        }
+        const members = offerMembersOf(offer);
+        const seen = new Set();
+        for (const member of members) {
+            if (!Number.isInteger(member) || member < 0 || rec.candidates[member] === undefined) {
+                return `offer ${at} references candidate ${member}, which the record does not carry`;
+            }
+            const cand = rec.candidates[member];
+            if (typeof cand !== "object" || cand === null || typeof cand.rule !== "string") {
+                return `offer ${at} references candidate ${member}, which is not a candidate row`;
+            }
+            if (seen.has(member))
+                return `batch offer ${at} references candidate ${member} twice`;
+            seen.add(member);
+            if (claimed.has(member))
+                return `candidate ${member} belongs to more than one offer`;
+            claimed.add(member);
+        }
+        if (offer.kind === "batch") {
+            if (rec.kind === "card") {
+                if (!Array.isArray(offer.segments) || offer.segments.length !== offer.candidates.length || !offer.segments.every((s) => typeof s === "string")) {
+                    return `card batch offer ${at} must carry exactly one source segment per member`;
+                }
+                if (!Number.isInteger(offer.uncoveredSegments) || offer.uncoveredSegments < 0) {
+                    return `card batch offer ${at} must carry a non-negative uncovered-segment count`;
+                }
+            }
+            else if (offer.segments !== undefined || offer.uncoveredSegments !== undefined) {
+                return `${rec.kind} batch offer ${at} must not carry segment metadata — there is no compound command behind it`;
+            }
+        }
+    }
+    return undefined;
+}
+export function ruleOffersOfRecord(rec) {
+    const tripleOf = (index) => {
+        const text = rec.candidates[index]?.rule;
+        if (text === undefined)
+            throw new Error(`approval-record offer references candidate ${index}, which the record does not carry`);
+        const parsed = parseAllowRuleText(text);
+        if ("reject" in parsed) {
+            throw new Error(`approval-record candidate ${index} does not parse as a rule (${parsed.reject.code}) — refusing to render it as one`);
+        }
+        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) };
+        const segments = offer.segments;
+        if (segments === undefined || offer.uncoveredSegments === 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");
+        }
+        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 };
+            }),
+            uncoveredSegments: offer.uncoveredSegments,
+        };
+    });
+}
 export function mintRuleTicket(recordId, candidateIndex) {
     return `rt.${candidateIndex}.${recordId}`;
 }
@@ -99,30 +193,72 @@ export async function prepareCardApproval(opts) {
     if (opts.toolName !== CARD_RULE_TOOL)
         return undefined;
     const scope = opts.scope ?? { kind: "global" };
-    const candidates = suggestRulesForCommand(opts.command).map((s) => ({ rule: s.rule, scope }));
+    let coverage;
+    try {
+        const listed = await storeForOwner(opts.deps.provider, owner).list();
+        coverage = segmentCoverageOf(opts.command, { persisted: listed.rules }, { tool: CARD_RULE_TOOL, cwd: opts.cwd });
+    }
+    catch {
+        coverage = undefined;
+    }
+    const suggested = suggestRulesForCommand(opts.command, coverage !== undefined ? { coverage } : undefined);
+    const candidates = [];
+    const claimedBy = new Map();
+    const claim = (text) => {
+        if (claimedBy.has(text))
+            throw new Error(`engine defect: rule "${text}" was minted into two offers on one card`);
+        const index = candidates.length;
+        candidates.push({ rule: text, scope });
+        claimedBy.set(text, index);
+        return index;
+    };
+    const offers = suggested.map((offer) => offer.kind === "single"
+        ? { kind: "single", candidate: claim(offer.rule) }
+        : {
+            kind: "batch",
+            candidates: offer.rules.map((r) => claim(r.rule)),
+            segments: offer.rules.map((r) => r.segment),
+            uncoveredSegments: offer.uncoveredSegments,
+        });
     if (candidates.length === 0)
         return undefined;
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
+        schema: 2,
         kind: "card",
         state: "pending",
         rev: 0,
         candidates,
+        offers,
         command: opts.command,
         createdAt: nowIso(opts.deps),
         ...(opts.toolCallId !== undefined ? { toolCallId: opts.toolCallId } : {}),
         ...(opts.boundInputHash !== undefined ? { boundInputHash: opts.boundInputHash } : {}),
     };
     await opts.deps.approvals.create(record);
-    return { approvalId: record.id, tickets: candidates.map((_, i) => mintRuleTicket(record.id, i)), candidates };
+    return {
+        approvalId: record.id,
+        offers: ruleOffersOfRecord(record),
+        tickets: candidates.map((_, i) => mintRuleTicket(record.id, i)),
+        candidates,
+    };
 }
 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");
+    const no = (reason, detail) => ({
+        ok: false,
+        reason,
+        ...(detail !== undefined ? { detail } : {}),
+    });
+    if (opts.editedCandidate !== undefined && opts.selectedOffer !== undefined) {
+        const e = new Error("confirmRuleApproval takes selectedOffer OR editedCandidate, never both — one confirmation carries one choice");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
+    if ("selectedCandidate" in opts) {
+        const e = new Error("confirmRuleApproval no longer takes selectedCandidate — selection is by OFFER index (selectedOffer) against the prepared record's offers; re-fetch the card and choose an offer");
         e.code = "config.invalid_argument";
         throw e;
     }
@@ -130,28 +266,44 @@ export async function confirmRuleApproval(opts) {
     const recOwner = rec === undefined ? undefined : ownerOfRecord(rec);
     if (rec === undefined || recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return no("record_not_found");
+    if (isStale(rec))
+        return no("record_schema_stale", { message: STALE_RECORD_MESSAGE });
+    const damage = approvalRecordDamageOf(rec);
+    if (damage !== undefined)
+        return no("record_malformed", { message: damage });
     if (opts.editedCandidate !== undefined)
         return await confirmEditedCandidate(rec, opts.editedCandidate, opts.deps);
-    if (rec.kind === "card") {
-        const chosen = opts.selectedCandidate;
-        if (chosen === undefined)
-            return no("selection_missing");
-        if (!Number.isInteger(chosen) || rec.candidates[chosen] === undefined)
-            return no("selection_invalid");
-        if (rec.state === "approved" || rec.state === "redeemed") {
-            return rec.selectedCandidate === chosen ? { ok: true } : no("selection_mismatch");
+    const chosen = opts.selectedOffer === undefined ? (rec.offers.length === 1 ? 0 : undefined) : opts.selectedOffer;
+    if (chosen === undefined)
+        return no("selection_missing");
+    if (!Number.isInteger(chosen) || rec.offers[chosen] === undefined)
+        return no("selection_invalid");
+    if (rec.state === "approved" || rec.state === "redeemed") {
+        const stored = rec.selectedOffer;
+        if (stored === undefined || !Number.isInteger(stored) || rec.offers[stored] === undefined) {
+            return no("record_malformed", { message: "the settled record does not name a valid chosen offer" });
         }
-        const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedCandidate: chosen });
-        return won ? { ok: true } : no("conflict");
+        return stored === chosen ? { ok: true } : no("selection_mismatch");
     }
-    if (opts.selectedCandidate !== undefined)
-        return no("batch_takes_no_selection");
-    if (rec.state === "approved")
-        return { ok: true };
     if (rec.state !== "pending")
         return no("not_pending");
-    const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
-    return won ? { ok: true } : no("conflict");
+    if (rec.selectedOffer !== undefined)
+        return no("record_malformed", { message: "a pending record must not already carry a chosen offer" });
+    const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedOffer: chosen });
+    if (won)
+        return { ok: true };
+    const again = await opts.deps.approvals.get(rec.id);
+    if (again === undefined)
+        return no("record_not_found");
+    if (isStale(again))
+        return no("record_schema_stale", { message: STALE_RECORD_MESSAGE });
+    if (again.state === "pending")
+        return no("conflict");
+    const settled = again.selectedOffer;
+    if (settled === undefined || !Number.isInteger(settled) || again.offers[settled] === undefined) {
+        return no("record_malformed", { message: "the settled record does not name a valid chosen offer" });
+    }
+    return settled === chosen ? { ok: true } : no("selection_mismatch");
 }
 function normalizeEditedSpelling(text) {
     const m = /^([A-Za-z][A-Za-z0-9_]*)\((.+) \*\)$/.exec(text);
@@ -163,6 +315,39 @@ function normalizeEditedSpelling(text) {
         return text;
     return `${head}(${body}:*)`;
 }
+function parseSubmittedSpelling(text) {
+    return parseAllowRuleText(normalizeEditedSpelling(text));
+}
+function checkEditedRuleText(text, command) {
+    const parsed = parseSubmittedSpelling(text);
+    if ("reject" in parsed)
+        return { ok: false, code: parsed.reject.code, message: parsed.reject.message };
+    if (!ruleAdmitsCommand(parsed.rule, command)) {
+        return {
+            ok: false,
+            message: `the edited rule "${parsed.rule.rule}" does not admit the command that was decided ("${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 };
+}
+export function precheckEditedRuleText(text, command) {
+    if (typeof text !== "string") {
+        const e = new Error(`precheckEditedRuleText takes the edited rule text as a string (got ${typeof text}) — a non-string is a caller bug, not a rule a person could have typed`);
+        e.code = "config.invalid_argument";
+        throw e;
+    }
+    if (typeof command !== "string" || command === "") {
+        const e = new Error("precheckEditedRuleText takes the adjudicated command the card was drawn for — coverage cannot be judged without it, and reporting the absence as a rejected rule would blame the person's text");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
+    if (hasUnrenderableCharacters(command)) {
+        const e = new Error("precheckEditedRuleText takes a command this lane can read — one carrying control or format characters is not a command any card was drawn for, and the refusal line naming it would carry those bytes onto a display surface");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
+    return checkEditedRuleText(text, command);
+}
 async function confirmEditedCandidate(rec, edit, deps) {
     const no = (reason, detail) => ({
         ok: false,
@@ -187,7 +372,7 @@ async function confirmEditedCandidate(rec, edit, deps) {
             return no("selection_mismatch");
         let hit = edit.text === rec.edited.text;
         if (!hit) {
-            const reparsed = parseAllowRuleText(normalizeEditedSpelling(edit.text));
+            const reparsed = parseSubmittedSpelling(edit.text);
             hit = "rule" in reparsed && reparsed.rule.rule === canonical;
         }
         if (!hit)
@@ -208,33 +393,30 @@ async function confirmEditedCandidate(rec, edit, deps) {
     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 checked = checkEditedRuleText(edit.text, rec.command);
+    if (!checked.ok) {
+        return no("edit_rejected", { ...(checked.code !== undefined ? { code: checked.code } : {}), message: checked.message });
     }
     const index = rec.candidates.length;
     const next = {
         ...rec,
         rev: rec.rev + 1,
         state: "approved",
-        candidates: [...rec.candidates, { rule: parsed.rule.rule, scope }],
-        selectedCandidate: index,
+        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) },
     };
     const won = await deps.approvals.cas(rec.id, rec.rev, next);
     if (!won) {
         const again = await deps.approvals.get(rec.id);
-        if (again === undefined)
+        if (again === undefined || isStale(again))
             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) } };
+    return { ok: true, mintedCandidate: { index, rule: checked.canonicalRule, ticket: mintRuleTicket(rec.id, index) } };
 }
 export async function redeemRuleTicket(opts) {
     const caller = resolveCallerOwner(opts.principal, opts.owner, "redeemRuleTicket");
@@ -247,12 +429,22 @@ export async function redeemRuleTicket(opts) {
     const recOwner = ownerOfRecord(rec);
     if (recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return { status: "refused", reason: "the ticket belongs to a different principal" };
+    if (isStale(rec))
+        return { status: "refused", reason: `record_schema_stale: ${STALE_RECORD_MESSAGE}` };
     if (rec.state === "pending")
         return { status: "refused", reason: "the approval record has not been confirmed" };
+    const damage = approvalRecordDamageOf(rec);
+    if (damage !== undefined)
+        return { status: "refused", reason: `the approval record is malformed: ${damage}` };
     const candidate = rec.candidates[parsed.index];
     if (candidate === undefined)
         return { status: "refused", reason: "the ticket names no candidate on this record" };
-    if (rec.kind === "card" && rec.selectedCandidate !== parsed.index) {
+    const chosen = rec.selectedOffer;
+    const chosenOffer = chosen !== undefined && Number.isInteger(chosen) ? rec.offers[chosen] : undefined;
+    if (chosenOffer === undefined) {
+        return { status: "refused", reason: "the approval record is malformed: it is settled but names no valid chosen offer" };
+    }
+    if (!offerMembersOf(chosenOffer).includes(parsed.index)) {
         return { status: "refused", reason: "the ticket names an option the person did not choose" };
     }
     const parsedRule = parseAllowRuleText(candidate.rule);
@@ -280,7 +472,7 @@ export async function redeemRuleTicket(opts) {
         const ok = await opts.deps.approvals.cas(rec.id, rec.rev, next);
         if (!ok) {
             const again = await opts.deps.approvals.get(rec.id);
-            const theirs = again?.redeemedDots?.[parsed.index];
+            const theirs = again === undefined || isStale(again) ? undefined : again.redeemedDots?.[parsed.index];
             if (theirs === undefined)
                 return { status: "refused", reason: "the approval record changed state concurrently" };
             return await applyRedemption({ deps: opts.deps, owner: caller, candidate, parsedRule: parsedRule.rule, dot: theirs, recordId: rec.id, kind: rec.kind, replay: true });
@@ -428,17 +620,22 @@ export async function prepareCcImport(opts) {
             candidates.push({ rule: parsed.rule.rule, scope });
         }
     }
+    const preview = { candidates, skipped, layers, uncovered: { ...IMPORT_UNCOVERED_LAYERS, denyAskBuckets } };
+    if (candidates.length === 0)
+        return { preview };
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
+        schema: 2,
         kind: "import",
         state: "pending",
         rev: 0,
         candidates,
+        offers: [{ kind: "batch", candidates: candidates.map((_, i) => i) }],
         createdAt: nowIso(opts.deps),
     };
     await opts.deps.approvals.create(record);
-    return { preview: { candidates, skipped, layers, uncovered: { ...IMPORT_UNCOVERED_LAYERS, denyAskBuckets } }, approvalId: record.id };
+    return { preview, approvalId: record.id };
 }
 export const STARTER_RULES = [
     "Bash(ls)",
@@ -463,10 +660,12 @@ export async function prepareStarterBatch(opts) {
     const record = {
         id: mintId(opts.deps, "rar"),
         ...recordIdentityOf(owner),
+        schema: 2,
         kind: "starter",
         state: "pending",
         rev: 0,
         candidates,
+        offers: [{ kind: "batch", candidates: candidates.map((_, i) => i) }],
         createdAt: nowIso(opts.deps),
     };
     await opts.deps.approvals.create(record);
@@ -480,14 +679,18 @@ export async function redeemRuleBatch(opts) {
     const recOwner = ownerOfRecord(rec);
     if (recOwner === undefined || !sameRuleOwner(recOwner, caller))
         return { status: "refused", reason: "the record belongs to a different principal" };
-    if (rec.kind === "card")
-        return { status: "refused", reason: "a card record is redeemed by its chosen ticket, not as a batch" };
+    if (isStale(rec))
+        return { status: "refused", reason: `record_schema_stale: ${STALE_RECORD_MESSAGE}` };
     if (rec.state === "pending")
         return { status: "refused", reason: "the approval record has not been confirmed" };
-    const persisted = [];
-    const deduped = [];
-    const skippedAtRedeem = [];
-    let rev = 0;
+    const damage = approvalRecordDamageOf(rec);
+    if (damage !== undefined)
+        return { status: "refused", reason: `the approval record is malformed: ${damage}` };
+    const chosen = rec.selectedOffer;
+    const chosenOffer = chosen !== undefined && Number.isInteger(chosen) ? rec.offers[chosen] : undefined;
+    if (chosenOffer === undefined) {
+        return { status: "refused", reason: "the approval record is malformed: it is settled but names no valid chosen offer" };
+    }
     let store;
     try {
         store = storeForOwner(opts.deps.provider, caller);
@@ -495,8 +698,11 @@ export async function redeemRuleBatch(opts) {
     catch (err) {
         return { status: "refused", reason: errText(err) };
     }
-    for (let i = 0; i < rec.candidates.length; i++) {
-        const candidate = rec.candidates[i];
+    const members = [];
+    let rev = 0;
+    for (const candidateIndex of offerMembersOf(chosenOffer)) {
+        const candidate = rec.candidates[candidateIndex];
+        const row = { candidateIndex, rule: candidate.rule, scope: candidate.scope };
         let alreadyThere = false;
         try {
             const snap = await store.list();
@@ -504,22 +710,20 @@ export async function redeemRuleBatch(opts) {
             alreadyThere = snap.rules.some((r) => r.rule === candidate.rule && sameScope(r.scope, candidate.scope));
         }
         catch (err) {
-            return { status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` };
+            members.push({ ...row, status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` });
+            continue;
         }
         const res = await redeemRuleTicket({
-            ticket: mintRuleTicket(rec.id, i),
+            ticket: mintRuleTicket(rec.id, candidateIndex),
             ...(caller.kind === "principal" ? { principal: caller.principal } : { owner: caller }),
             deps: opts.deps,
         });
         if (res.status === "refused") {
-            skippedAtRedeem.push({ rule: candidate.rule, reason: res.reason });
+            members.push({ ...row, status: "refused", reason: res.reason });
             continue;
         }
         rev = res.rev;
-        if (alreadyThere)
-            deduped.push(candidate);
-        else
-            persisted.push(candidate);
+        members.push({ ...row, status: alreadyThere ? "deduped" : "persisted", alreadyRedeemed: res.alreadyRedeemed, dot: res.dot });
     }
-    return { persisted, deduped, skippedAtRedeem, rev };
+    return { members, rev };
 }