@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/roles.js

@@ -1,16 +1,21 @@
 import { selectModel } from "./select-model.js";
+import { namesRoleBase } from "../prompt-assembly/role-base.js";
+import { readPromptRole } from "../prompt-assembly/select.js";
 import { MODEL_ROLES } from "./types.js";
 export { MODEL_ROLES } from "./types.js";
 function catalogModel(ref, models) {
     const m = models != null && (typeof models === "object" || typeof models === "function") && Object.hasOwn(models, ref) ? models[ref] : undefined;
     return m || undefined;
 }
-function modelBindingRefusal(seat, reason, message) {
+function modelBindingRefusal(field, reason, message) {
     const e = new Error(message);
     e.code = "config.unknown_role";
-    e.detail = { field: seat, reason };
+    e.detail = { field, reason };
     return e;
 }
+function isBindingObject(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function";
+}
 function bindingShown(value) {
     if (typeof value === "string")
         return JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}…` : value);
@@ -19,15 +24,27 @@ function bindingShown(value) {
 function unknownModelRefRefusal(ref, seat) {
     return modelBindingRefusal(seat, "unknown_model_ref", `Unknown model ref ${bindingShown(ref)} in ${seat}. Provide it in RunnerDeps.models or pass a Model object.`);
 }
-export function resolveModel(ref, models) {
-    if (typeof ref !== "string") {
-        return ref;
+function modelOfBinding(value, models, seat, binds) {
+    assertModelBindingShape(value, seat, binds);
+    if (typeof value === "string") {
+        const held = catalogModel(value, models);
+        if (held === undefined)
+            throw unknownModelRefRefusal(value, seat);
+        return held;
     }
-    const m = catalogModel(ref, models);
-    if (!m) {
-        throw new Error(`Unknown model ref "${ref}". Provide it in RunnerDeps.models or pass a Model object.`);
+    return value;
+}
+function assertModelBindingShape(value, seat, binds) {
+    if (typeof value === "string")
+        return;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(value)}, not a model reference — ${binds}.`);
     }
-    return m;
+}
+const ROLE_BINDS = "a role binds a catalog model name or a Model object";
+const roleModelSeat = (named, seat) => (typeof named === "string" ? seat : `${seat}.model`);
+export function resolveModel(ref, models, seat = "model") {
+    return modelOfBinding(ref, models, seat, "a model is named by a catalog model name or a Model object");
 }
 export const DEFAULT_TIER_ORDER = ["ultra", "max", "pro", "flash", "lite"];
 export const CC_MODEL_TIER_ALIASES = {
@@ -53,17 +70,7 @@ export function expandTiers(models, tiers) {
         const b = Object.hasOwn(tiers, name) ? tiers[name] : undefined;
         if (b === undefined)
             return undefined;
-        const seat = `tiers.${name}`;
-        if (typeof b === "string") {
-            const held = catalogModel(b, models);
-            if (held === undefined)
-                throw unknownModelRefRefusal(b, seat);
-            return held;
-        }
-        if (typeof b !== "object" || b === null || Array.isArray(b)) {
-            throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(b)}, not a model reference — a tier binds a catalog model name or a Model object.`);
-        }
-        return b;
+        return modelOfBinding(b, models, `tiers.${name}`, "a tier binds a catalog model name or a Model object");
     };
     const ownKey = (k) => models !== undefined && Object.hasOwn(models, k) && Boolean(models[k]);
     const landing = (t, self) => {
@@ -162,27 +169,27 @@ const FALLBACK = {
     consolidate: ["summarize"],
 };
 function specParts(s, seat = "a role seat") {
-    if (s == null) {
+    if (s === undefined) {
         return {};
     }
     if (typeof s === "string") {
         return { model: s };
     }
-    if (typeof s !== "object" && typeof s !== "function") {
+    if (!isBindingObject(s)) {
         throw modelBindingRefusal(seat, "not_a_model_ref", `${seat} is ${bindingShown(s)}, not a model reference — a role binds a catalog model name, a Model object or a { model, select, thinking, systemPrompt } record.`);
     }
     if ("id" in s && "api" in s) {
         return { model: s };
     }
     const cfg = s;
-    return { model: cfg.model, select: cfg.select, thinking: cfg.thinking, systemPrompt: cfg.systemPrompt };
+    return { model: cfg.model, select: cfg.select, thinking: cfg.thinking, promptRole: readPromptRole(`${seat}.promptRole`, cfg.promptRole), systemPrompt: cfg.systemPrompt };
 }
 export function roleSpecNamesModel(spec) {
     const parts = specParts(spec);
     return parts.model !== undefined || parts.select !== undefined;
 }
 function toConfig(s) {
-    if (s == null) {
+    if (s === undefined) {
         return undefined;
     }
     if (typeof s === "string" || ("id" in s && "api" in s)) {
@@ -198,26 +205,34 @@ function mergeRoleSpec(base, over) {
     if (!b)
         return over;
     const overHasSource = o.model !== undefined || o.select !== undefined;
+    const roleBase = namesRoleBase(o) ? o : b;
     return {
         model: overHasSource ? o.model : b.model,
         select: overHasSource ? o.select : b.select,
         thinking: o.thinking ?? b.thinking,
-        systemPrompt: o.systemPrompt ?? b.systemPrompt,
+        promptRole: roleBase.promptRole,
+        systemPrompt: roleBase.systemPrompt,
     };
 }
-function assertKnownRole(word, seat) {
+function assertKnownRole(word, field, ofKey = false) {
     if (typeof word === "string" && MODEL_ROLES.includes(word))
         return;
     const shown = typeof word === "string" ? JSON.stringify(word).slice(0, 80) : `<${word === null ? "null" : typeof word}>`;
-    const e = new Error(`${seat} names the model role ${shown}, which is not one of ${MODEL_ROLES.join(" / ")} — a word outside the vocabulary binds nothing and resolves nothing; bind the model on one of these roles, or name it on TaskSpec.model`);
-    e.code = "config.unknown_role";
-    throw e;
+    throw modelBindingRefusal(field, "unknown_role_word", `${ofKey ? `${field} key` : field} names the model role ${shown}, which is not one of ${MODEL_ROLES.join(" / ")} — a word outside the vocabulary binds nothing and resolves nothing; bind the model on one of these roles, or name it on TaskSpec.model`);
+}
+export function screenRoleMap(roles, field) {
+    for (const key of Object.keys(roles ?? {}))
+        assertKnownRole(key, field, true);
+    for (const [key, value] of Object.entries(roles ?? {})) {
+        const seat = `roles.${key}`;
+        const named = specParts(value, seat).model;
+        if (named !== undefined)
+            assertModelBindingShape(named, roleModelSeat(named, seat), ROLE_BINDS);
+    }
 }
 function mergeRoles(base, over) {
-    for (const key of Object.keys(base ?? {}))
-        assertKnownRole(key, "RunnerDeps.roles key");
-    for (const key of Object.keys(over ?? {}))
-        assertKnownRole(key, "TaskSpec.roles key");
+    screenRoleMap(base, "RunnerDeps.roles");
+    screenRoleMap(over, "TaskSpec.roles");
     const out = { ...base };
     for (const role of Object.keys(over ?? {})) {
         out[role] = mergeRoleSpec(base?.[role], over?.[role]);
@@ -225,8 +240,8 @@ function mergeRoles(base, over) {
     return out;
 }
 function partsModel(parts, models, seat = "a role seat") {
-    if (parts.model) {
-        return resolveModel(parts.model, models);
+    if (parts.model !== undefined) {
+        return modelOfBinding(parts.model, models, roleModelSeat(parts.model, seat), ROLE_BINDS);
     }
     if (parts.select) {
         const needs = parts.select.needs;
@@ -238,27 +253,35 @@ function partsModel(parts, models, seat = "a role seat") {
     }
     return undefined;
 }
-export function resolveTaskModel(spec, deps) {
-    const start = spec.modelRole ?? "default";
+function chainHead(spec, deps) {
+    const start = spec.modelRole === undefined ? "default" : spec.modelRole;
     assertKnownRole(start, "modelRole");
-    if (spec.model) {
-        const startParts = specParts(mergeRoles(deps.roles, spec.roles)[start], `roles.${start}`);
+    const merged = mergeRoles(deps.roles, spec.roles);
+    return { start, merged, startParts: specParts(merged[start], `roles.${start}`) };
+}
+export function presetRoleBaseOf(spec, deps) {
+    const { promptRole, systemPrompt } = chainHead(spec, deps).startParts;
+    return namesRoleBase({ promptRole, systemPrompt }) ? { ...(promptRole !== undefined ? { promptRole } : {}), ...(systemPrompt !== undefined ? { systemPrompt } : {}) } : undefined;
+}
+export function resolveTaskModel(spec, deps) {
+    const { start, merged, startParts } = chainHead(spec, deps);
+    if (spec.model !== undefined) {
         return {
-            model: resolveModel(spec.model, deps.models),
+            model: resolveModel(spec.model, deps.models, "TaskSpec.model"),
             modelRef: spec.model,
             thinking: spec.thinking ?? startParts.thinking,
+            promptRole: startParts.promptRole,
             systemPrompt: startParts.systemPrompt,
         };
     }
-    const merged = mergeRoles(deps.roles, spec.roles);
-    const startSystemPrompt = specParts(merged[start], `roles.${start}`).systemPrompt;
+    const { promptRole: startPromptRole, systemPrompt: startSystemPrompt } = startParts;
     for (const role of [start, ...FALLBACK[start]]) {
         const parts = specParts(merged[role], `roles.${role}`);
         const fromParts = partsModel(parts, deps.models, `roles.${role}`);
         const model = fromParts ?? roleTierModel(role, deps.models);
         if (model) {
             const modelRef = fromParts !== undefined ? (parts.model ?? model) : (ROLE_TIER_DEFAULTS[role] ?? model);
-            return { model, modelRef, thinking: spec.thinking ?? parts.thinking, systemPrompt: startSystemPrompt };
+            return { model, modelRef, thinking: spec.thinking ?? parts.thinking, promptRole: startPromptRole, systemPrompt: startSystemPrompt };
         }
     }
     throw new Error(`No model for role "${start}": set TaskSpec.model, or configure RunnerDeps.roles / TaskSpec.roles["${start}"] (or a "default" role). A "select" RoleSpec also fails here if no catalog model matches.`);
@@ -267,15 +290,5 @@ export function roleModelIfSet(role, spec, deps) {
     const merged = mergeRoles(deps.roles, spec.roles);
     const seat = `roles.${role}`;
     const parts = specParts(merged[role], seat);
-    const named = parts.model;
-    if (named) {
-        if (typeof named === "string") {
-            if (catalogModel(named, deps.models) === undefined)
-                throw unknownModelRefRefusal(named, seat);
-        }
-        else if (typeof named !== "object" || Array.isArray(named)) {
-            throw modelBindingRefusal(seat, "not_a_model_ref", `${seat}.model is ${bindingShown(named)}, not a model reference — a role binds a catalog model name or a Model object.`);
-        }
-    }
     return partsModel(parts, deps.models, seat) ?? roleTierModel(role, deps.models);
 }

package/dist/core/rule-lane-reads.d.ts

@@ -34,16 +34,20 @@ export declare function normalizeOrgGateVerdict(answer: unknown, unreadable: str
 /**
  * Normalize the accepted {@link ToolGateInput.persistedRules} answers into one reading.
  *
- * `{}` = a clean negative (no rule admits this call). `{ unreadable: true }` = the lane could not read
- * its source. `{ hit }` = a match, whose `rules` is the non-empty coverage set (design/375). An answer
- * outside every accepted shape — a number, `null`, an object with neither `rules` nor `unreadable`, an
- * EMPTY `rules` array, the retired pre-375 `{ rule, dots? }` single-rule object — is read as a clean
- * negative rather than a match: this is a LOOSENING seam, so an answer nobody can name degrades toward
- * asking, never toward an allow built on it. All-or-nothing across the set's TEXTS for the same
- * reason: a set with one unreadable member is a different (smaller) claim than the lane made, and a
- * decision must not stand on a claim nobody made — one bad member drops the whole answer to the clean
- * negative. Per-member DOTS stay individually optional (identity lost ⇒ `"not_reported"`, exactly the
- * single-rule contract).
+ * Four readings, and the lane's own words pick them. `{}` = the lane SAID no rule speaks: the `undefined` answer
+ * (the store was read and holds nothing for this call) or a coverage answer (design/375 §5.2②, whose decision
+ * meaning is "no rule"). `{ hit }` = a match: a `behavior` of the closed set and a NON-EMPTY `rules` whose members each
+ * carry a text (design/375). `{ unreadable: true }` = the lane said it could not read its source (the store form).
+ * `{ unreadable: true, reason }` = the lane could not read the call against its rows (its own call form), OR the lane
+ * answered something this seam cannot read — `null`, a string or number, an object that is none of the shapes above, a
+ * `behavior` outside the closed set or absent, `rules` absent / not an array / empty, a member that is not a record or
+ * whose `rule` is not a string, a carrier that is not a plain object. The last arm is the one that matters: an answer the
+ * lane gave and nobody can read may be a DENY or an ASK row that did not survive the seam, and reading it as "no rule"
+ * would let the person's standing "never run this" fail silently — so it is read as the unreadable word (a
+ * real-approval ask no mode releases; headless, a refusal), the same word the org lane's unreadable answer takes.
+ * All-or-nothing across the set for the same reason: a set with one unreadable member is a different (smaller) claim than
+ * the lane made, and a decision must not stand on a claim nobody made. Per-member DOTS stay individually optional
+ * (identity lost ⇒ `"not_reported"`, exactly the single-rule contract).
  *
  * The hit's dots are COPIED, not aliased. The array travels onto an ask that may sit in front of a
  * person for a long time; a lane that retains and mutates its own array would otherwise change what the
@@ -68,11 +72,12 @@ export declare function readOrgRuleLane(org: {
 }, req: ToolCallRequest, signal: AbortSignal | undefined, timeoutMs?: number): Promise<OrgGateVerdict>;
 /**
  * The persisted-rule lane's one read for one call — every consumer's (the live gate, the synthetic-Read
- * judge), normalized once. A lane that throws, hangs past the dependency timeout, or answers something
- * unreadable is a lane that could not answer: a row nobody could read may forbid the call, so for the DECISION it
- * fails closed (`applyPersistedTightening` reads `{ unreadable }` without a reason as the store form: a real-approval
- * ask), and for the RECORD it is `"unavailable"`. A call the lane could not read against the rows (`reason`) fails
- * closed in the arms the same way, as the call form. Absent lane ⇒ the clean negative.
+ * judge), normalized once. A lane that throws or hangs past the dependency timeout is a lane that could not answer: a row
+ * nobody could read may forbid the call, so for the DECISION it fails closed (`applyPersistedTightening` reads `{ unreadable }`
+ * without a reason as the store form: a real-approval ask), and for the RECORD it is `"unavailable"`. A lane that ANSWERS
+ * something this seam cannot read, and a call the lane could not read against the rows, are `unreadable` with a `reason`
+ * (the normalizer's words, naming the field): they fail closed in the arms the same way, as the call form. Absent lane,
+ * or the lane's own `undefined` ⇒ the clean negative.
  */
 export declare function readPersistedRuleLane(lane: {
     adjudicate: (req: ToolCallRequest) => PersistedRuleAnswer | Promise<PersistedRuleAnswer>;

package/dist/core/rule-lane-reads.js

@@ -1,6 +1,6 @@
 import { describeThrown } from "./tool-policy.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, settleOrgVerdictWithin } from "./permission-rule-org.js";
-import { isRuleBehavior } from "./permission-rule-model.js";
+import { isRuleBehavior, RULE_BEHAVIORS } from "./permission-rule-model.js";
 function isPlainOwnRecord(x) {
     try {
         if (x === null || typeof x !== "object" || Array.isArray(x))
@@ -21,6 +21,15 @@ function ownDataValue(obj, key) {
         return undefined;
     }
 }
+function bearsOwn(obj, key) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(obj, key);
+        return d !== undefined && (!("value" in d) || d.value !== undefined);
+    }
+    catch {
+        return true;
+    }
+}
 export function normalizeOrgGateVerdict(answer, unreadable) {
     const clean = (v) => Object.assign(Object.create(null), v);
     const readable = (x) => {
@@ -94,16 +103,24 @@ function copiedUsableDots(dots) {
     const usable = copied?.every((d) => typeof d.actor === "string" && typeof d.counter === "number" && Number.isFinite(d.counter)) === true && copied.length > 0;
     return usable ? { dots: copied } : {};
 }
+function unreadableAnswer(where) {
+    return { unreadable: true, reason: `the host's persisted-rule lane, persistedRules.adjudicate, answered what this gate cannot read: ${where}` };
+}
 export function normalizePersistedRuleHit(hit) {
-    if (!isPlainOwnRecord(hit))
+    if (hit === undefined)
         return {};
+    if (!isPlainOwnRecord(hit))
+        return unreadableAnswer(hit === null ? "the answer is `null` — a lane with no rule for the call answers `undefined`" : "the answer is not a plain object");
     if (ownDataValue(hit, "unreadable") === true) {
         const reason = ownDataValue(hit, "reason");
         return typeof reason === "string" ? { unreadable: true, reason } : { unreadable: true };
     }
     const rulesRaw = ownDataValue(hit, "rules");
-    if (rulesRaw === undefined) {
+    const behavior = ownDataValue(hit, "behavior");
+    if (!bearsOwn(hit, "rules") && !bearsOwn(hit, "behavior") && !bearsOwn(hit, "unreadable")) {
         const coverageRaw = ownDataValue(hit, "segmentCoverage");
+        if (coverageRaw === undefined)
+            return unreadableAnswer("it names no `behavior`, no `rules`, no `unreadable` report and no `segmentCoverage` table");
         let rows;
         try {
             if (Array.isArray(coverageRaw)) {
@@ -120,27 +137,38 @@ export function normalizePersistedRuleHit(hit) {
         }
         return rows !== undefined && rows.length > 0 ? { coverage: rows.map((r) => ({ segment: r.segment, covered: r.covered })) } : {};
     }
-    let members;
+    if (!isRuleBehavior(behavior))
+        return unreadableAnswer(`\`behavior\` is not one of ${RULE_BEHAVIORS.join(" / ")}`);
+    const members = [];
+    let problem;
     try {
-        if (Array.isArray(rulesRaw)) {
-            const walked = [];
-            for (let i = 0; i < rulesRaw.length; i++) {
+        const count = Array.isArray(rulesRaw) ? rulesRaw.length : undefined;
+        if (!Array.isArray(rulesRaw))
+            problem = rulesRaw === undefined ? "`rules` is absent or not an own data property" : "`rules` is not an array";
+        else if (count === 0)
+            problem = "`rules` is empty — a hit names at least one rule";
+        else if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
+            problem = "`rules` has no readable length";
+        else {
+            for (let i = 0; i < count && problem === undefined; i++) {
                 const m = rulesRaw[i];
-                walked.push(isPlainOwnRecord(m) ? { rule: ownDataValue(m, "rule"), dots: ownDataValue(m, "dots") } : { rule: undefined, dots: undefined });
+                if (!isPlainOwnRecord(m))
+                    problem = `\`rules[${i}]\` is not a plain object`;
+                else {
+                    const rule = ownDataValue(m, "rule");
+                    if (typeof rule !== "string")
+                        problem = `\`rules[${i}].rule\` is not a string`;
+                    else
+                        members.push({ rule, dots: ownDataValue(m, "dots") });
+                }
             }
-            members = walked;
         }
     }
     catch {
-        members = undefined;
+        problem = "`rules` could not be read (a throwing element or a revoked proxy)";
     }
-    if (members === undefined || members.length === 0)
-        return {};
-    if (!members.every((m) => typeof m.rule === "string"))
-        return {};
-    const behavior = ownDataValue(hit, "behavior");
-    if (!isRuleBehavior(behavior))
-        return {};
+    if (problem !== undefined)
+        return unreadableAnswer(problem);
     const denial = behavior === "deny" ? copiedDenial(ownDataValue(hit, "denial"), members.map((m) => m.rule)) : undefined;
     return { hit: { behavior, rules: members.map((m) => ({ rule: m.rule, ...copiedUsableDots(m.dots) })), ...(denial !== undefined ? { denial } : {}) } };
 }

package/dist/core/rule-offer-read.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The read-back judge of a stored rule-offer list: the {@link RuleOffer} array core mints beside an approval
+ * (`AskRequest.ruleOffers`, a parked row's `pendingAction.ruleOffers`). Core mints the shape, so its reading lives
+ * here; a backend or a surface that reads the list back calls {@link readRuleOffers} instead of keeping a schema of
+ * its own. Display caps (how many offers, members or detail rows a surface shows) stay with the surface.
+ */
+import { type RuleOffer } from "./permission-rule-model.js";
+/**
+ * Why a stored rule-offer value, or one element of it, is not read:
+ *  · `not_an_array` — the value itself (present, and not a list): no element is read;
+ *  · `unknown_word` — a closed-set member holds a word this engine does not know: the offer `kind`, a batch member's
+ *    `kind`, a `match` (a newer minter, or another writer);
+ *  · `malformed` — not an object, a member missing or of the wrong type, a batch with no members, an uncovered count
+ *    that is not a non-negative safe integer.
+ * The first defect in reading order names the element's problem.
+ */
+export declare const RULE_OFFER_SHAPE_PROBLEMS: readonly ["not_an_array", "unknown_word", "malformed"];
+export type RuleOfferShapeProblem = (typeof RULE_OFFER_SHAPE_PROBLEMS)[number];
+/** One element read. `index` is its position in the stored list — the selection key a card and its redemption keep. */
+export interface RuleOfferRead {
+    readonly index: number;
+    /** A fresh object holding only the members the type declares (additive members the minter wrote are not copied). */
+    readonly offer: RuleOffer;
+    /** Present when the batch's `uncoveredDetail` seat was not one well-formed row per counted segment and was left out
+     *  (the count is the truth source and an absent seat claims nothing); the caller owes that loss a disclosure. */
+    readonly uncoveredDetailDropped?: true;
+    /** Present when at least one batch member was read through the kind-less stored form (no `kind`, the four command
+     *  text members). A backend counts these to know whether its rows still carry the form that retirement line
+     *  RL-2164-kindless-batch-member waits on. */
+    readonly kindlessForm?: true;
+}
+/** One element not read, and why. The rest of the list is read regardless. */
+export interface RuleOfferDropped {
+    readonly index: number;
+    readonly problem: Exclude<RuleOfferShapeProblem, "not_an_array">;
+}
+/** {@link readRuleOffers}' answer. */
+export type RuleOffersReading = {
+    readonly offers: readonly RuleOfferRead[];
+    readonly dropped: readonly RuleOfferDropped[];
+} | {
+    readonly problem: "not_an_array";
+};
+/**
+ * Read a stored rule-offer list. `undefined` (the member absent) reads as no offers; any other non-list is
+ * `not_an_array`. Each element is judged alone and keeps its original index: an element that is not an offer this
+ * engine reads is dropped WHOLE (a batch with one unreadable member is dropped, never shortened — a conjunction one
+ * member short would render "yes to N" as "yes to N−1") and its siblings stand. Every member is read once.
+ * The input domain is a decoded JSON value or a list core minted: a value carrying accessors or a Proxy is outside it,
+ * and such a value may be refused as malformed or may throw while it is read. A record is a plain one
+ * ({@link isPlainRecord}, the reading the risk-descriptor axes take too).
+ */
+export declare function readRuleOffers(raw: unknown): RuleOffersReading;

package/dist/core/rule-offer-read.js

@@ -0,0 +1,146 @@
+import { PERSISTED_RULE_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, } from "./permission-rule-model.js";
+import { isPlainRecord } from "./checkpoint-store.js";
+export const RULE_OFFER_SHAPE_PROBLEMS = Object.freeze(["not_an_array", "unknown_word", "malformed"]);
+const MALFORMED = Object.freeze({ problem: "malformed" });
+const UNKNOWN_WORD = Object.freeze({ problem: "unknown_word" });
+export function readRuleOffers(raw) {
+    if (raw === undefined)
+        return { offers: [], dropped: [] };
+    if (!Array.isArray(raw))
+        return { problem: "not_an_array" };
+    const offers = [];
+    const dropped = [];
+    const length = raw.length;
+    for (let index = 0; index < length; index++) {
+        const verdict = readOfferElement(raw[index]);
+        if ("problem" in verdict)
+            dropped.push({ index, problem: verdict.problem });
+        else
+            offers.push({ index, ...verdict });
+    }
+    return { offers, dropped };
+}
+function wordOf(value, words) {
+    if (typeof value !== "string")
+        return MALFORMED;
+    return words.some((w) => w === value) ? value : UNKNOWN_WORD;
+}
+function readOfferElement(value) {
+    if (!isPlainRecord(value))
+        return MALFORMED;
+    const kind = wordOf(value.kind, RULE_OFFER_KINDS);
+    if (typeof kind !== "string")
+        return kind;
+    switch (kind) {
+        case "single": {
+            const rule = value.rule;
+            const match = wordOf(value.match, PERSISTED_RULE_MATCHES);
+            const command = value.command;
+            if (typeof rule !== "string")
+                return MALFORMED;
+            if (typeof match !== "string")
+                return match;
+            if (typeof command !== "string")
+                return MALFORMED;
+            return { offer: { kind: "single", rule, match, command } };
+        }
+        case "batch":
+            return readBatch(value);
+        default: {
+            const unhandled = kind;
+            return unhandled;
+        }
+    }
+}
+function readBatch(value) {
+    const rules = value.rules;
+    const count = value.uncoveredSegments;
+    const detail = value.uncoveredDetail;
+    if (!Array.isArray(rules))
+        return MALFORMED;
+    const length = rules.length;
+    if (length === 0)
+        return MALFORMED;
+    const members = [];
+    let kindless = false;
+    for (let i = 0; i < length; i++) {
+        const verdict = readBatchMember(rules[i]);
+        if ("problem" in verdict)
+            return verdict;
+        members.push(verdict.member);
+        if (verdict.kindlessForm === true)
+            kindless = true;
+    }
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
+        return MALFORMED;
+    const offer = { kind: "batch", rules: members, uncoveredSegments: count };
+    const marks = kindless ? { kindlessForm: true } : {};
+    if (detail === undefined)
+        return { offer, ...marks };
+    const rows = detailRowsOf(detail, count);
+    return rows !== undefined ? { offer: { ...offer, uncoveredDetail: rows }, ...marks } : { offer, uncoveredDetailDropped: true, ...marks };
+}
+function readBatchMember(value) {
+    if (!isPlainRecord(value))
+        return MALFORMED;
+    if (!("kind" in value))
+        return readKindlessBatchMember(value);
+    const kind = wordOf(value.kind, RULE_OFFER_BATCH_MEMBER_KINDS);
+    if (typeof kind !== "string")
+        return kind;
+    switch (kind) {
+        case "command":
+            return commandMember(value.rule, value.match, value.command, value.segment);
+        case "directoryRead": {
+            const rule = value.rule;
+            const directory = value.directory;
+            const segment = value.segment;
+            if (typeof rule !== "string" || typeof directory !== "string" || typeof segment !== "string")
+                return MALFORMED;
+            return { member: { kind: "directoryRead", rule, directory, segment } };
+        }
+        default: {
+            const unhandled = kind;
+            return unhandled;
+        }
+    }
+}
+function readKindlessBatchMember(value) {
+    const rule = value.rule;
+    const match = value.match;
+    const command = value.command;
+    const segment = value.segment;
+    if (typeof rule !== "string" || typeof match !== "string" || typeof command !== "string" || typeof segment !== "string")
+        return MALFORMED;
+    const verdict = commandMember(rule, match, command, segment);
+    return "problem" in verdict ? verdict : { ...verdict, kindlessForm: true };
+}
+function commandMember(rule, rawMatch, command, segment) {
+    if (typeof rule !== "string")
+        return MALFORMED;
+    const match = wordOf(rawMatch, PERSISTED_RULE_MATCHES);
+    if (typeof match !== "string")
+        return match;
+    if (typeof command !== "string" || typeof segment !== "string")
+        return MALFORMED;
+    return { member: { kind: "command", rule, match, command, segment } };
+}
+function detailRowsOf(detail, count) {
+    if (!Array.isArray(detail))
+        return undefined;
+    const length = detail.length;
+    if (length !== count)
+        return undefined;
+    const rows = [];
+    for (let i = 0; i < length; i++) {
+        const row = detail[i];
+        if (!isPlainRecord(row))
+            return undefined;
+        const segment = row.segment;
+        const reason = wordOf(row.reason, UNCOVERED_SEGMENT_REASONS);
+        if (typeof segment !== "string" || typeof reason !== "string")
+            return undefined;
+        rows.push({ segment, reason });
+    }
+    return rows;
+}

package/dist/core/rule-owner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Who a permission-rule bucket belongs to: the owner type, its discriminant words, the one reading of an owner from a
+ * value the engine did not just build, and the one equality between two owners.
+ *
+ * The faces that read an owner out of data — the two adoption markers read back from disk, the two adoption entries'
+ * source, a stored approval record's identity and the consent entries' `owner` option — read it through
+ * {@link readRuleOwner}, so the source an adoption entry writes into its marker is one that marker's reader reads back.
+ * Its run-time imports are the two import-free judges — the record judge and the principal-name judge — because the root
+ * adoption marker reader, which every file store loads, depends on this module and is kept free of the rule store's own imports.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/**
+ * Who a rule bucket belongs to, as a STRUCTURAL position.
+ *
+ * Identity absence is spelled as a distinct union member, never as a sentinel string flowing through
+ * `forPrincipal` — every consumer of a principal string is an identity surface, and a made-up name on an
+ * identity surface is indistinguishable from a real one downstream. Cloud sync and cloud tickets accept
+ * ONLY the `principal` kind: syncing is an authenticated act, and a local-owner bucket has no cloud home
+ * until it is adopted (`adoptFilePermissionRuleStore`).
+ */
+export type RuleOwner = {
+    kind: "principal";
+    principal: string;
+} | {
+    kind: "local-owner";
+};
+/** The owner discriminants as a value: the `kind` words of {@link RuleOwner}, both directions fenced at compile time
+ *  ({@link RuleOwnerKindsCoverEveryArm} / {@link RuleOwnerArmsCoverEveryKind}). */
+export declare const RULE_OWNER_KINDS: readonly ["principal", "local-owner"];
+/** Compile fence: an arm whose `kind` is not in {@link RULE_OWNER_KINDS} turns the argument into that word. */
+export type RuleOwnerKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOwner["kind"], (typeof RULE_OWNER_KINDS)[number]>>;
+/** Compile fence, the other direction: a word in {@link RULE_OWNER_KINDS} that no arm carries. */
+export type RuleOwnerArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OWNER_KINDS)[number], RuleOwner["kind"]>>;
+/** Do two owners name the same bucket? */
+export declare function sameRuleOwner(a: RuleOwner, b: RuleOwner): boolean;
+/**
+ * Read an owner from a value the engine did not just build, or `undefined` when it is not one: not a plain record (an
+ * object whose prototype is `Object.prototype` or none, so no member comes from a prototype it was given), a `kind`
+ * outside {@link RULE_OWNER_KINDS}, or a `principal` arm whose name is not a principal name ({@link principalNameOf}: an
+ * identity-less bucket is the `local-owner` kind, never a blank name). Fail-closed: a caller treats `undefined` as
+ * "owns nothing" or refuses — never as either arm. The answer is a fresh object holding only the members the type
+ * declares; `kind` and `principal` are each read once.
+ */
+export declare function readRuleOwner(raw: unknown): RuleOwner | undefined;
+/** An owner as an operator's sentence names it: `principal "<name>"`, or `the local owner`. */
+export declare function ruleOwnerText(owner: RuleOwner): string;