@sema-agent/core 7.54.1 → 7.56.0

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

@@ -27,8 +27,10 @@
  * 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 EditedRuleBreadthWarning, type UncoveredSegmentDetail, type RuleBehavior, type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
-import type { RuleOwner } from "./permission-rule-store.js";
+import { RULE_OFFER_KINDS, type EditedRuleBreadthWarning, type UncoveredSegmentDetail, type RuleBehavior, type RuleOffer, type RuleRejectCode, type RuleScope, type RuleDot } from "./permission-rule-model.js";
+import { type RuleOwner } from "./rule-owner.js";
+import type { RuleOfferShapeProblem } from "./rule-offer-read.js";
+import type { AssertAllKeysHandled } from "./ask-origin.js";
 import { type PermissionRuleStoreProvider } from "./permission-rule-provider.js";
 /** One candidate rule inside an approval record: what it says (`behavior`), the exact text and where it
  *  would apply. A card mints `allow` candidates only (a card is one person's yes); the settings import
@@ -85,6 +87,28 @@ export type RuleOffer2 = {
     readonly uncoveredSegments?: number;
     readonly uncoveredDetail?: readonly UncoveredSegmentDetail[];
 };
+/** {@link import("./permission-rule-model.js").RuleOfferKindsCoverEveryArm}'s twin over the record's option form. */
+export type RuleOffer2KindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOffer2["kind"], (typeof RULE_OFFER_KINDS)[number]>>;
+/** {@link import("./permission-rule-model.js").RuleOfferArmsCoverEveryKind}'s twin over the record's option form. */
+export type RuleOffer2ArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OFFER_KINDS)[number], RuleOffer2["kind"]>>;
+/** {@link readRuleOffer2}'s answer: the option as read, or why it is not one (the offer read-back judge's two element words). */
+export type RuleOffer2Reading = {
+    readonly offer: RuleOffer2;
+} | {
+    readonly problem: Exclude<RuleOfferShapeProblem, "not_an_array">;
+};
+/**
+ * The one SHAPE reading of a stored record option ({@link RuleOffer2}), for every reader of an approval record the engine did not
+ * just build — the consent entries' record check, and a durable backend reading its rows back. Not a plain record, a member the form
+ * does not declare, a candidate index that is not a non-negative safe integer, a batch with no members, a `segments` that is not a
+ * list of strings, an uncovered count that is not a non-negative safe integer, a reason row that is not exactly a segment and a reason
+ * ⇒ `malformed`; a `kind` or a reason that is a string outside its closed set ⇒ `unknown_word`. A member the form does not declare is
+ * refused, not dropped: the record's `schema` stamp is the version gate, so a same-stamp row carrying one was written by another writer.
+ * Which batch seats a record of which kind must carry, and whether the indices name its candidates, are the record's own facts —
+ * judged by the record check, not here. The answer is a fresh object holding the members it judged; each member is read once, a list
+ * by position with its length read once.
+ */
+export declare function readRuleOffer2(raw: unknown): RuleOffer2Reading;
 /** The CURRENT record-form version stamp ({@link RuleApprovalRecord.schema}), spelled once: every mint writes it and
  *  every readback compares against it by equality (an older or absent stamp is a stale row, never a floor). A
  *  durable backend's stale gate reads this value rather than its own number. */
@@ -293,10 +317,11 @@ export declare function prepareCardApproval(opts: {
     principal?: string;
     /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
     owner?: RuleOwner;
-    /** The tool whose ask this card belongs to. Only the shell tool the rule lane speaks for and the name tools (the skill-activation
-     *  card) are accepted. */
+    /** The tool whose ask this card belongs to. Only the shell tool the rule lane speaks for, the name tools (the skill-activation
+     *  card) and the host tools (the fetch card) are accepted. */
     toolName: string;
-    /** The command as adjudicated — the same bytes the ask carried; for a name tool (`Skill`), the name its call carried (`args.skill`). */
+    /** The command as adjudicated — the same bytes the ask carried; for a name tool (`Skill`), the name its call carried (`args.skill`);
+     *  for a host tool (`WebFetch`), the host its call reaches (the offer's `command`). */
     command: string;
     /** The ask's call id and argument digest, recorded for reconciliation. */
     toolCallId?: string;

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

@@ -1,10 +1,111 @@
 import { randomBytes } from "node:crypto";
-import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
+import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
+import { readRuleOwner, sameRuleOwner } from "./rule-owner.js";
+import { principalNameOf, readPrincipal } from "./principal-name.js";
+import { isPlainRecord } from "./mods/kernel/receive.js";
 import { effectiveOrThrow } from "./permission-rule-provider.js";
-import { errText, isValidConsentScope, landRuleAdd, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
+import { errText, isValidConsentScope, landRuleAdd, sameScope, writerOf } from "./permission-rule-store.js";
 const isUncoveredSegmentReason = (v) => UNCOVERED_SEGMENT_REASONS.some((word) => v === word);
 export const RULE_APPROVAL_KINDS = Object.freeze(["card", "import", "starter"]);
 export const RULE_APPROVAL_STATES = Object.freeze(["pending", "approved", "redeemed"]);
+const RECORD_OPTION_MEMBERS = { single: ["kind", "candidate"], batch: ["kind", "candidates", "segments", "uncoveredSegments", "uncoveredDetail"] };
+export function readRuleOffer2(raw) {
+    if (!isPlainRecord(raw))
+        return { problem: "malformed" };
+    const kind = raw.kind;
+    if (typeof kind !== "string")
+        return { problem: "malformed" };
+    const word = RULE_OFFER_KINDS.find((k) => k === kind);
+    if (word === undefined)
+        return { problem: "unknown_word" };
+    const declared = RECORD_OPTION_MEMBERS[word];
+    if (Object.keys(raw).some((name) => !declared.includes(name)))
+        return { problem: "malformed" };
+    switch (word) {
+        case "single": {
+            const candidate = raw.candidate;
+            return isCandidateIndex(candidate) ? { offer: { kind: "single", candidate } } : { problem: "malformed" };
+        }
+        case "batch": {
+            const candidates = indexListOf(raw.candidates);
+            if (candidates === undefined || candidates.length === 0)
+                return { problem: "malformed" };
+            const segments = raw.segments;
+            const uncoveredSegments = raw.uncoveredSegments;
+            const detail = raw.uncoveredDetail;
+            const segmentList = segments === undefined ? undefined : stringListOf(segments);
+            if (segments !== undefined && segmentList === undefined)
+                return { problem: "malformed" };
+            if (uncoveredSegments !== undefined && !isCandidateIndex(uncoveredSegments))
+                return { problem: "malformed" };
+            const rows = detail === undefined ? undefined : reasonRowsOf(detail);
+            if (rows !== undefined && "problem" in rows)
+                return rows;
+            return {
+                offer: {
+                    kind: "batch",
+                    candidates,
+                    ...(segmentList !== undefined ? { segments: segmentList } : {}),
+                    ...(uncoveredSegments !== undefined ? { uncoveredSegments } : {}),
+                    ...(rows !== undefined ? { uncoveredDetail: rows.rows } : {}),
+                },
+            };
+        }
+        default: {
+            const unhandled = word;
+            return unhandled;
+        }
+    }
+}
+function isCandidateIndex(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function indexListOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const length = value.length;
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const item = value[i];
+        if (!isCandidateIndex(item))
+            return undefined;
+        out.push(item);
+    }
+    return out;
+}
+function stringListOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const length = value.length;
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const item = value[i];
+        if (typeof item !== "string")
+            return undefined;
+        out.push(item);
+    }
+    return out;
+}
+function reasonRowsOf(value) {
+    if (!Array.isArray(value))
+        return { problem: "malformed" };
+    const length = value.length;
+    const rows = [];
+    for (let i = 0; i < length; i++) {
+        const row = value[i];
+        if (!isPlainRecord(row) || Object.keys(row).some((name) => name !== "segment" && name !== "reason"))
+            return { problem: "malformed" };
+        const segment = row.segment;
+        const reason = row.reason;
+        if (typeof segment !== "string" || typeof reason !== "string")
+            return { problem: "malformed" };
+        const word = UNCOVERED_SEGMENT_REASONS.find((r) => r === reason);
+        if (word === undefined)
+            return { problem: "unknown_word" };
+        rows.push({ segment, reason: word });
+    }
+    return { rows };
+}
 export const RULE_APPROVAL_RECORD_SCHEMA = 4;
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
@@ -47,41 +148,46 @@ function mintId(deps, prefix) {
     return `${prefix}_${Date.now().toString(36)}_${randomBytes(9).toString("base64url")}`;
 }
 function requirePrincipal(principal, entry) {
-    if (typeof principal !== "string" || principal === "") {
+    const name = principalNameOf(principal);
+    if (name === undefined) {
         throw new Error(`${entry} requires a verified principal — refusing to create an approval record without one`);
     }
-    return principal;
+    return name;
 }
 function resolveCallerOwner(principal, owner, entry) {
     if (owner !== undefined) {
-        if (owner.kind === "principal") {
-            const p = requirePrincipal(owner.principal, entry);
-            if (typeof principal === "string" && principal !== "" && principal !== p) {
-                throw new Error(`${entry}: contradictory identity — principal "${principal}" and owner principal "${p}" disagree`);
+        const given = readRuleOwner(owner);
+        if (given === undefined) {
+            throw new Error(`${entry} requires a verified principal or the local owner — the owner given is neither (a principal owner names a principal name)`);
+        }
+        if (given.kind === "principal") {
+            if (readPrincipal(principal).kind !== "absent" && principal !== given.principal) {
+                throw new Error(`${entry}: contradictory identity — principal "${principal}" and owner principal "${given.principal}" disagree`);
             }
-            return { kind: "principal", principal: p };
+            return given;
         }
-        if (typeof principal === "string" && principal !== "") {
+        if (readPrincipal(principal).kind !== "absent") {
             throw new Error(`${entry}: contradictory identity — a principal and a local-owner were both given; a bucket has one owner`);
         }
-        return { kind: "local-owner" };
+        return given;
     }
     return { kind: "principal", principal: requirePrincipal(principal, entry) };
 }
 function ownerOfRecord(rec) {
-    if (rec.owner !== undefined) {
-        if (rec.owner.kind === "principal") {
-            if (typeof rec.owner.principal !== "string" || rec.owner.principal === "")
-                return undefined;
-            if (typeof rec.principal === "string" && rec.principal !== "" && rec.principal !== rec.owner.principal)
-                return undefined;
-            return rec.owner;
-        }
-        if (typeof rec.principal === "string" && rec.principal !== "")
-            return undefined;
-        return { kind: "local-owner" };
-    }
-    return typeof rec.principal === "string" && rec.principal !== "" ? { kind: "principal", principal: rec.principal } : undefined;
+    const stated = rec.owner;
+    const owner = stated === undefined ? undefined : readRuleOwner(stated);
+    if (stated !== undefined && owner === undefined)
+        return undefined;
+    const principal = rec.principal;
+    const given = typeof principal === "string" && principal !== "";
+    const named = given ? readRuleOwner({ kind: "principal", principal }) : undefined;
+    if (given && named === undefined)
+        return undefined;
+    if (owner === undefined)
+        return named;
+    if (named !== undefined && !sameRuleOwner(owner, named))
+        return undefined;
+    return owner;
 }
 function recordIdentityOf(owner) {
     return owner.kind === "principal" ? { principal: owner.principal } : { owner: { kind: "local-owner" } };
@@ -108,19 +214,17 @@ function approvalRecordDamageOf(rec) {
     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`;
+    for (const [at, stored] of rec.offers.entries()) {
+        const read = readRuleOffer2(stored);
+        if ("problem" in read) {
+            return `offer ${at} is not a record option this engine reads (${read.problem}): an option is an object whose kind is ${RULE_OFFER_KINDS.join(" or ")}, whose candidate indices are non-negative integers (a batch with no members is not one), whose reason rows are segment/reason rows from the closed reason set, and which carries no other member`;
         }
+        const offer = read.offer;
         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 ${escapeForDisclosure(member)}, which the record does not carry`;
+            if (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") {
@@ -144,26 +248,18 @@ function approvalRecordDamageOf(rec) {
         }
         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")) {
+                if (offer.segments === undefined || offer.segments.length !== offer.candidates.length) {
                     return `card batch offer ${at} must carry exactly one source segment per member`;
                 }
-                if (!Number.isInteger(offer.uncoveredSegments) || offer.uncoveredSegments < 0) {
+                if (offer.uncoveredSegments === undefined) {
                     return `card batch offer ${at} must carry a non-negative uncovered-segment count`;
                 }
                 const detail = offer.uncoveredDetail;
-                if (!Array.isArray(detail))
+                if (detail === undefined)
                     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" ||
-                        !UNCOVERED_SEGMENT_REASONS.some((word) => row.reason === word)) {
-                        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;
@@ -283,8 +379,9 @@ export async function prepareCardApproval(opts) {
         e.code = "config.invalid_argument";
         throw e;
     }
-    const nameCard = ruleToolGrammarOf(opts.toolName) === "name";
-    if (opts.toolName !== CARD_RULE_TOOL && !nameCard)
+    const grammar = ruleToolGrammarOf(opts.toolName);
+    const oneRuleCard = grammar === "name" || grammar === "domain" ? grammar : undefined;
+    if (opts.toolName !== CARD_RULE_TOOL && oneRuleCard === undefined)
         return undefined;
     const scope = (() => {
         if (opts.scope !== undefined) {
@@ -308,7 +405,7 @@ export async function prepareCardApproval(opts) {
         throw e;
     })();
     let coverage;
-    if (!nameCard) {
+    if (oneRuleCard === undefined) {
         try {
             const view = await effectiveOrThrow(storeForOwner(opts.deps.provider, owner), opts.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
             const table = view.rules;
@@ -318,8 +415,8 @@ export async function prepareCardApproval(opts) {
             coverage = undefined;
         }
     }
-    const suggested = nameCard
-        ? [suggestRuleForName(opts.toolName, opts.command)].filter((o) => o !== undefined)
+    const suggested = oneRuleCard !== undefined
+        ? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : suggestRuleForHost(opts.toolName, opts.command)].filter((o) => o !== undefined)
         : suggestRulesForCommand(opts.command, {
             ...(coverage !== undefined ? { coverage } : {}),
             scope,
@@ -358,7 +455,7 @@ export async function prepareCardApproval(opts) {
         rev: 0,
         candidates,
         offers,
-        ...(nameCard ? {} : { command: opts.command }),
+        ...(oneRuleCard !== undefined ? {} : { command: opts.command }),
         createdAt: nowIso(opts.deps),
         ...(opts.toolCallId !== undefined ? { toolCallId: opts.toolCallId } : {}),
         ...(opts.boundInputHash !== undefined ? { boundInputHash: opts.boundInputHash } : {}),