@sema-agent/core 7.52.0 → 7.53.0

package/dist/core/own-property-receipt.js

@@ -1,5 +1,6 @@
 import { types } from "node:util";
 import { describeFault, isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { MODS_VALUE_DEPTH } from "./mods/kernel/site-rules.js";
 export function receiptRefusal(message) {
     const e = new Error(message);
     e.code = "config.invalid_argument";
@@ -9,7 +10,8 @@ export function refuseProxy(given, words) {
     if (types.isProxy(given))
         throw receiptRefusal(`${words.subject} must be a plain object, not a Proxy: its ${words.unit}s are read once off its own descriptors, and a Proxy would run its traps in that read — refused rather than wired through it`);
 }
-const CONFIG_RECEIPT_MODE = Object.freeze({ accessors: "call-once", depth: 1, others: "as-is", isProxy: (v) => types.isProxy(v) });
+export const CONFIG_RECEIPT_MODE = Object.freeze({ accessors: "call-once", depth: 1, others: "as-is", isProxy: (v) => types.isProxy(v) });
+export const DECLARATION_RECEIPT_MODE = Object.freeze({ accessors: "call-once", depth: MODS_VALUE_DEPTH + 1, others: "refuse", freeze: true, isProxy: (v) => types.isProxy(v) });
 export function receiveOwnProperties(given, words) {
     refuseProxy(given, words);
     if (!isPlainRecord(given)) {

package/dist/core/parent-spec-seat.d.ts

@@ -52,8 +52,8 @@ export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "cli
  *  · `promptForm` — the host form of the system prompt (`"minimal"`, its only word: the core-behavior band is out). A
  *    host's product choice for the whole delegation tree, so every engine-built child (both delegation lanes and the
  *    observer sidecar) composes the same set of sections. An ORDINARY member (fill law).
- *  · `promptBinding` — the center binding (a deployment's scenario name). A child composes its parent's center
- *    artifact, so it selects that artifact's scoped overlays by the same binding. An ORDINARY member (fill law).
+ *  · `promptBinding` — the binding (a deployment's scenario name), a prompt selector value. A child composes its
+ *    parent's center artifact, so its overlays' `when.binding` reads the same binding. An ORDINARY member (fill law).
  */
 export interface ParentSpecSeat {
     readonly principal?: string;

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

@@ -161,15 +161,43 @@ export declare function callPathFaceOf(call: ToolCallLike): DenyFace | undefined
  *  it, whatever the call's tool is called (a caller's tool declaring a read path target is on the read face too)? */
 export declare function faceRowsSpeakFor(face: DenyFace | undefined): boolean;
 /**
- * The tools whose rule content NAMES THE VALUE of one parameter instead of a command or a path — the reference's `Skill(<name>)`
- * form, one row per tool: `param` is the argument the rule's content is read against, `params` every scalar argument the tool
- * carries (the parameter spelling `Tool(<param>:<pattern>)` those names used to reach is retired for such a tool, see
- * {@link parseNameRuleContent}). The tool's real schema keys are pinned equal to `params` (test/backlog1318).
+ * The tools whose rule content NAMES THE VALUE of one parameter instead of a command or a path — ONE grammar (the name grammar,
+ * match `name`), one row per tool, the row declaring the tool's SPELLING of it:
+ *  · BARE — the reference's `Skill(<name>)` / `Skill(<prefix>:*)`: `param` is the argument the rule's content is read against,
+ *    `params` every scalar argument the tool carries (the parameter spelling `Tool(<param>:<pattern>)` those names used to reach
+ *    is retired for such a tool, see {@link parseNameRuleContent}). The Skill tool's real schema keys are pinned equal to
+ *    `params` (test/backlog1318).
+ *  · KEYED — `words` present: the reference's `Artifact(action:<word>)`, the content carrying the argument's own key. `params`
+ *    is that one key; `words` is the closed set of values the tool itself declares for it (the row points at the tool's own
+ *    set, never a copy), and a rule names exactly one of them — no prefix form, no `*`.
+ * Whatever the spelling, a rule of this grammar says "the call's value of `param` is this value", read by the one subject
+ * reader ({@link nameRuleSubjectOf}), the one predicate ({@link nameRuleAdmits}), the one precedence walk
+ * ({@link adjudicatePersistedNameRules}) and the one offer ({@link suggestRuleForName}).
  */
 export declare const NAME_RULE_FACES: Readonly<Record<string, {
     readonly param: string;
     readonly params: readonly string[];
+    readonly words?: readonly string[];
 }>>;
+/**
+ * Why a call of a KEYED value tool that names no value for the key cannot be read against that key's deny / ask rules, or
+ * undefined (a bare-spelling tool, or no value tool). Every judge reads a call's arguments as the tool reads them
+ * (`argsAsTheToolReads`: its argument preparation, then the schema's coercions); a call that STILL names no value for the key
+ * runs a value no argument shows — a default filled in inside the tool's execution (a caller's tool mounted under the keyed
+ * name, or answering to it, with no argument preparation of its own). Whether a rule by the key reaches such a call is
+ * unknown, so every reader REFUSES it on the key's deny or ask rule — a refusal, never an ask a person could approve past a
+ * deny, and no allow by the key reaches it. A tool whose reading always names the key (the built-in `Artifact`: an absent
+ * action reads as `publish`) never meets this. A bare-spelling tool's call that names nothing is reached by nothing: no
+ * default stands behind it.
+ */
+export declare function keyedValueAbsentReason(tool: string): string | undefined;
+/**
+ * Does the name grammar read this content of this tool? Every content of a bare-spelling tool; on a keyed tool only content
+ * keyed by its own parameter (`action:…` on `Artifact`) — another key (`Artifact(url:…)`) is a rule on another argument,
+ * which the persisted grammar has no form for and the caller policy reads with its generic parameter lane. Undefined grammar
+ * ⇒ false.
+ */
+export declare function nameGrammarReads(tool: string, content: string): boolean;
 /**
  * The tools whose rule content names the HOST of the URL one parameter carries — the reference's `WebFetch(domain:<host>)`
  * form, one row per tool: `param` is the URL argument the host is read from ({@link domainRuleSubjectOf}). Read by
@@ -182,8 +210,9 @@ export declare const DOMAIN_RULE_FACES: Readonly<Record<string, {
  * Which tools a rule may name — the model's tool set is DERIVED, never a hand-kept list: the command rule word
  * ({@link COMMAND_RULE_TOOL}) takes the COMMAND grammar — the other shell-face tools take none of their own, their command is
  * judged by the `Bash(…)` rules ({@link laneToolNamesOf}); every tool the catalog declares a path target for (Read / Edit / Write /
- * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar; the tools of {@link NAME_RULE_FACES} take the NAME grammar;
- * the tools of {@link DOMAIN_RULE_FACES} the DOMAIN grammar.
+ * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar; the tools of {@link NAME_RULE_FACES} take the NAME grammar
+ * (each in its row's spelling: bare `Skill(<name>)`, keyed `Artifact(action:<word>)`); the tools of {@link DOMAIN_RULE_FACES} the
+ * DOMAIN grammar.
  * A rule on any other tool has no content this model can judge and is refused (`unsupported.tool`). The tool set therefore
  * moves with the catalog's declarations, exactly as the protective fences' covered set does.
  */
@@ -355,6 +384,21 @@ export interface ParsedRule {
 /** Upper bound on a rule text. Rules are human-authored one-liners; anything longer is a mistake or an
  *  attempt to make the store unreadable. */
 export declare const MAX_RULE_TEXT_CHARS = 512;
+/**
+ * The most code points of a rule's ORIGINAL text a notice's machine-read slot carries: twice the grammar's own bound. A text past
+ * {@link MAX_RULE_TEXT_CHARS} reads as no rule whatever follows its first characters, so the slot keeps room to show it as far as a person
+ * needs to recognise it and no further; every text a rule can be is carried whole. Not exported from the package root: a consumer reads
+ * the slot and never judges its length (it is not a relay that must refuse what the engine did not mint).
+ */
+export declare const NOTICE_RULE_TEXT_MAX: number;
+/**
+ * A rule's (or allow-list entry's) text as a notice's machine-read slot carries it: the original string, untouched, when it is at most
+ * {@link NOTICE_RULE_TEXT_MAX} code points; a longer one is cut to that many and ends in the engine's one truncation mark
+ * ({@link INLINE_TRUNCATION_MARK}), so the longest slot is `NOTICE_RULE_TEXT_MAX + INLINE_TRUNCATION_MARK_CODEPOINTS` (1 025) code points.
+ * The ONE reading both `permission.allowed_tool_not_granted` (`detail.entries[].entry`) and `permission.rule_row_dropped`
+ * (`detail.rows[].rule`) hand their rule text over through — what spells it for a person is the sentence, never this slot.
+ */
+export declare function noticeRuleText(text: string): string;
 /**
  * Interpreter names whose PREFIX form is refused everywhere a rule can enter the store (minting,
  * import, file reload, every backend). `Bash(node:*)` reads as one narrow-looking rule and means "run
@@ -956,7 +1000,9 @@ export declare function commandCoverageOf(rules: readonly PersistedRule[], call:
 };
 /** The answer of {@link adjudicatePersistedRules}: which behavior decided, and the rule(s) it stands
  *  on — a one-element set for a deny/ask (the first table-order rule of the deciding behavior that
- *  reaches the call) and the allow direction's coverage SET ({@link findAdmittingRule}). */
+ *  reaches the call; for a keyed tool's call naming no value for its key, a DENY standing on the first deny — else ask —
+ *  row of that key, which the call cannot be read against: {@link adjudicatePersistedNameRules}) and the allow
+ *  direction's coverage SET ({@link findAdmittingRule}). */
 export interface PersistedRuleVerdict {
     readonly behavior: RuleBehavior;
     readonly rules: readonly PersistedRule[];
@@ -1032,8 +1078,11 @@ export declare function adjudicatePersistedPathRules(rules: readonly PersistedRu
  * ({@link NAME_RULE_FACES}), judged on the one string the call names (`nameRuleSubjectOf`). A rule of the tool speaks for the call
  * when it is live, of this behavior, in scope ({@link eligiblePersisted}, the one predicate) and {@link nameRuleAdmits} the name; the
  * first behavior in {@link RULE_BEHAVIORS_BY_PRECEDENCE} whose rules speak decides, the first table-order rule of it is the answer.
- * Every behavior is judged with the one predicate — a name has no "program run" the tightening direction could read wider — and
- * there is nothing unreadable: a name is a string.
+ * Every behavior is judged with the one predicate — a name has no "program run" the tightening direction could read wider.
+ * A call that names nothing (read as the tool reads it): on a bare-spelling tool it is reached by no rule; on a KEYED tool it
+ * cannot be read against the key's rules ({@link keyedValueAbsentReason}) and is REFUSED — a deny verdict standing on the
+ * first eligible deny row of the key, else its first ask row (an ask a person could approve would let a deny be approved
+ * past) — and no allow row reaches it.
  */
 export declare function adjudicatePersistedNameRules(rules: readonly PersistedRule[], call: {
     tool: string;

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

@@ -3,13 +3,15 @@ import { shellWordsOf } from "../shell/shell-words.js";
 import { parsePermissionRule } from "./permission-rule-syntax.js";
 import { compileReadDeny } from "../tools/fs/read-deny.js";
 import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
-import { inlineUntrusted } from "./untrusted-text.js";
+import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
 import { isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
 import { heldValues } from "./tool-name-readings.js";
 import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
 import { bindPathRules, judgeRuleRows, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { readShellCommand } from "./shell-lexer.js";
 import { lineDescriptorsOfText, readOnlyLineObjection, readOnlyShellVerdict } from "./read-only-shell.js";
+import { ARTIFACT_ACTIONS } from "./artifact-host.js";
+import { ARTIFACT_TOOL_NAME } from "./tool-catalog-entries.js";
 export const RULE_BEHAVIORS = Object.freeze(["deny", "ask", "allow"]);
 const RULE_BEHAVIOR_SET = new Set(RULE_BEHAVIORS);
 export function isRuleBehavior(v) {
@@ -43,7 +45,25 @@ export function faceRowsSpeakFor(face) {
 }
 export const NAME_RULE_FACES = Object.freeze({
     Skill: Object.freeze({ param: "skill", params: Object.freeze(["skill", "args"]) }),
+    [ARTIFACT_TOOL_NAME]: Object.freeze({ param: "action", params: Object.freeze(["action"]), words: ARTIFACT_ACTIONS }),
 });
+function keyedValueParamOf(tool) {
+    const face = Object.hasOwn(NAME_RULE_FACES, tool) ? NAME_RULE_FACES[tool] : undefined;
+    return face?.words !== undefined ? face.param : undefined;
+}
+export function keyedValueAbsentReason(tool) {
+    const key = keyedValueParamOf(tool);
+    return key === undefined ? undefined : `the ${tool} call names no ${key} as the tool reads it, so the ${key} it runs is not one its arguments show — a rule by ${key} cannot be read against it`;
+}
+export function nameGrammarReads(tool, content) {
+    if (ruleToolGrammarOf(tool) !== "name")
+        return false;
+    const key = keyedValueParamOf(tool);
+    if (key === undefined)
+        return true;
+    const colon = content.indexOf(":");
+    return colon > 0 && content.slice(0, colon).trim() === key;
+}
 export const DOMAIN_RULE_FACES = Object.freeze({
     WebFetch: Object.freeze({ param: "url" }),
 });
@@ -95,6 +115,20 @@ function isCommandMatch(match) {
     return match === "exact" || match === "prefix" || match === "wildcard";
 }
 export const MAX_RULE_TEXT_CHARS = 512;
+export const NOTICE_RULE_TEXT_MAX = 2 * MAX_RULE_TEXT_CHARS;
+export function noticeRuleText(text) {
+    if (text.length <= NOTICE_RULE_TEXT_MAX)
+        return text;
+    let kept = 0;
+    let end = 0;
+    for (const ch of text) {
+        if (kept === NOTICE_RULE_TEXT_MAX)
+            return `${text.slice(0, end)}${INLINE_TRUNCATION_MARK}`;
+        end += ch.length;
+        kept += 1;
+    }
+    return text;
+}
 export const BARE_INTERPRETER_NAMES = new Set([
     "node", "deno", "bun", "python", "python2", "python3", "perl", "ruby", "php", "osascript",
     "java", "dotnet", "mono", "lua", "luajit", "julia", "Rscript", "tclsh", "groovy", "scala",
@@ -243,6 +277,13 @@ function ruleLaneShapeOf(command, reading) {
 }
 const CONTROL_CHARS_RE = /[\u0000-\u0008\u000A-\u001F\u007F-\u009F\p{Cf}\u2028\u2029]/u;
 const CONTROL_CHARS_GLOBAL_RE = new RegExp(CONTROL_CHARS_RE.source, "gu");
+const RULE_SPELLING_REJECT_BYTES = "<>";
+const RULE_SPELLING_REJECT_RE = new RegExp(`[${RULE_SPELLING_REJECT_BYTES}]`);
+function valueRuleFormsSentence() {
+    return Object.entries(NAME_RULE_FACES)
+        .map(([tool, face]) => (face.words !== undefined ? `${tool}(${face.param}:<${face.param}>) rules` : `${tool}(<${face.param}>) rules`))
+        .join(", ");
+}
 const DISCLOSED_RULE_TEXT_MAX_CHARS = 120;
 export function escapeForDisclosure(value) {
     let text;
@@ -293,13 +334,16 @@ export function parseRuleText(text, behavior) {
     }
     if (parsed.toolName !== COMMAND_RULE_TOOL) {
         const grammar = ruleToolGrammarOf(parsed.toolName);
+        if (grammar === undefined) {
+            return reject("unsupported.tool", `only Bash command rules, rules on path-targeting tools (Read, Edit, Write, …), ${valueRuleFormsSentence()} and WebFetch domain rules have a rule form in this version (got "${parsed.toolName}")`);
+        }
+        if (!tighten && RULE_SPELLING_REJECT_RE.test(parsed.ruleContent)) {
+            return reject("invalid.grammar", `"${text}" carries a shell redirection byte (${[...RULE_SPELLING_REJECT_BYTES].map((b) => `\`${b}\``).join(" or ")}) — no path, name or host allow spells one, and the grant would not read as what it looks like`);
+        }
         if (grammar === "name")
             return parseNameRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
         if (grammar === "domain")
             return parseDomainRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
-        if (grammar !== "path") {
-            return reject("unsupported.tool", `only Bash command rules, rules on path-targeting tools (Read, Edit, Write, …), Skill name rules and WebFetch domain rules have a rule form in this version (got "${parsed.toolName}")`);
-        }
         return parsePathRuleContent(text, parsed.toolName, parsed.ruleContent, behavior);
     }
     const content = parsed.ruleContent;
@@ -353,14 +397,18 @@ export function parseRuleText(text, behavior) {
 export function formatRuleText(command, match, tool) {
     if (match === "subpath")
         return `${tool}(//${command.startsWith("/") ? command.slice(1) : command}/**)`;
-    if (match === "path" || match === "name")
+    if (match === "path")
         return `${tool}(${command})`;
+    if (match === "name")
+        return `${tool}(${keyedValueParamOf(tool) !== undefined ? `${keyedValueParamOf(tool)}:` : ""}${command})`;
     if (match === "host" || match === "subdomain")
         return `${tool}(domain:${match === "subdomain" ? "*." : ""}${command})`;
     return `${tool}(${command}${match === "prefix" || match === "name_prefix" ? ":*" : match === "wildcard" ? " *" : ""})`;
 }
 function parseNameRuleContent(text, tool, content, behavior, verifyCanonical = true) {
     const face = NAME_RULE_FACES[tool];
+    if (face?.words !== undefined)
+        return parseKeyedValueRuleContent(text, tool, content, behavior, { param: face.param, words: face.words });
     const bare = content.startsWith("/") ? content.slice(1) : content;
     const colon = bare.indexOf(":");
     if (face !== undefined && colon > 0 && face.params.includes(bare.slice(0, colon).trim())) {
@@ -389,6 +437,24 @@ function parseNameRuleContent(text, tool, content, behavior, verifyCanonical = t
     }
     return { rule };
 }
+function parseKeyedValueRuleContent(text, tool, content, behavior, face) {
+    const vocabulary = face.words.join(", ");
+    const colon = content.indexOf(":");
+    if (colon <= 0 || content.slice(0, colon).trim() !== face.param) {
+        return reject("invalid.grammar", `${tool} rules name the ${face.param}: ${tool}(${face.param}:<${face.param}>) with one of ${vocabulary} ("${text}") — a bare value, or a rule on another argument, has no rule form here`);
+    }
+    const word = content.slice(colon + 1).trim();
+    if (word === "") {
+        return reject("invalid.grammar", `the ${face.param} in "${text}" is empty — ${tool} rules name the ${face.param} exactly as the call carries it`);
+    }
+    if (word.includes("*")) {
+        return reject("unsupported.wildcard", `a \`*\` in the ${face.param} of "${text}" has no rule form — ${tool} rules name one ${face.param} (${vocabulary}); the whole tool is the bare ${tool} entry`);
+    }
+    if (!face.words.includes(word)) {
+        return reject("invalid.grammar", `"${word}" is not one of the ${face.param} values ${tool} declares (${vocabulary}) — the rule would never reach a call`);
+    }
+    return { rule: { behavior, rule: formatRuleText(word, "name", tool), tool, match: "name", command: word } };
+}
 export function nameRuleAdmits(rule, name) {
     if (rule.match === "name")
         return name === rule.command;
@@ -802,7 +868,7 @@ export function directoryIdentityOf(spelling, bases) {
     const r = pathIdentityOf(spelling, pathFamilyOf(bases), bases.root ?? bases.cwd);
     return r.ok ? r.identity : undefined;
 }
-const CD_TARGET_REJECT_CHARS = /[*?[\]{}$`\\'"<>\n\r]/;
+const CD_TARGET_REJECT_CHARS = new RegExp(String.raw `[*?[\]{}$` + "`" + String.raw `\\'"\n\r` + RULE_SPELLING_REJECT_BYTES + "]");
 function cdSegmentDirectoryOf(segment, opts) {
     if (/[^\S \t]/.test(segment))
         return undefined;
@@ -1033,8 +1099,16 @@ export function adjudicatePersistedPathRules(rules, call, views, anchorsOf, lead
     return undefined;
 }
 export function adjudicatePersistedNameRules(rules, call) {
-    if (call.name === undefined)
+    if (call.name === undefined) {
+        if (keyedValueAbsentReason(call.tool) === undefined)
+            return undefined;
+        for (const behavior of ["deny", "ask"]) {
+            const row = rules.find((rule) => rule.match === "name" && eligiblePersisted(rule, call, behavior));
+            if (row !== undefined)
+                return { behavior: "deny", rules: [row] };
+        }
         return undefined;
+    }
     for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
         for (const rule of rules) {
             if (eligiblePersisted(rule, call, behavior) && nameRuleAdmits(rule, call.name))

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

@@ -34,8 +34,30 @@
  * refused and disclosed — identity comparison alone cannot catch it, and an in-memory-only mark would
  * accept revision N−1 after a restart. Signature / predecessor chaining belongs to the privilege-
  * separation ticket; the high-water mark is the floor that needs no key distribution.
+ *
+ * ## One reading of a row
+ *
+ * A snapshot is installed and served on its ENVELOPE ({@link validateOrgSnapshot}: revision, observation
+ * time, a rules list) and the anti-rollback fence; what its rows say never decides which snapshot is in
+ * force. Whether the rules are a list is judged in ONE place ({@link listRefusalOf}) for the partition and for
+ * every store that hands a resolution over — rules that are not a list, or that carry more places than a rule set may
+ * (the same cap the rule compiler holds a set to), are governance nobody can read (the
+ * partition refuses the snapshot; the org lane answers unavailable), never a policy of zero rows — and ONE reader
+ * ({@link orgRuleListOf}) copies the whole list in one receipt: a member of a row that cannot be read is left out of
+ * that row's copy alone, and every row is judged on its copy. A snapshot the partition holds — fetched or read back
+ * from its persistence — is that same copy ({@link orgSnapshotCopyOf}). Every row is then read by ONE reader
+ * ({@link readOrgRules}), the same for every store that hands a resolution over, on its policy members
+ * ({@link ORG_ROW_POLICY_MEMBERS}): a row is READ when its behavior is `deny` or `ask` and its text is a shell command
+ * rule under that behavior. Any other row — another grammar's rule, a shell rule the validator refuses, a row
+ * with no text, a behavior this layer has no bucket for — is UNREADABLE, and stands at its strictest
+ * reading over the calls it may reach ({@link OrgRowReach}): an `ask` row asks a person, every other row
+ * refuses. Readable deny and ask rows hold as published beside it. One unreadable row therefore never
+ * takes the rest of the policy down with it, and never turns a published deny into a question; the
+ * snapshot is served DEGRADED, and every resolution and every adjudication over it names the unreadable
+ * rows ({@link describeUnreadableOrgRows}).
  */
-import { type PersistedRule, type RuleRejectCode } from "./permission-rule-model.js";
+import { type ParsedRule, type PersistedRule, type RuleRejectCode } from "./permission-rule-model.js";
+import type { DenyFace } from "../tools/fs/read-deny.js";
 import type { PermissionRuleStore } from "./permission-rule-provider.js";
 /** One org rule. There is structurally no allow bucket (design/179 §9: the org layer only tightens). */
 export interface OrgPermissionRule {
@@ -171,42 +193,146 @@ export declare const UNGOVERNED_ORG_RESOLUTION: Readonly<OrgRuleResolution>;
  *    bound is refused loudly, never coerced.
  */
 export declare function createOrgRulePartition(cfg: OrgRulePartitionConfig): OrgRulePartition;
+/** Whether two snapshots carry the same POLICY: row for row, the same policy members ({@link ORG_ROW_POLICY_MEMBERS}) — never
+ *  observation metadata, never a member no judgment reads (which a copy may carry or leave out). The ONE test of "the same
+ *  revision, the same content": the partition's equal-revision guard asks it of two snapshots it holds in one form
+ *  ({@link orgSnapshotCopyOf}), and a persistence backend asks it of what it stores. */
+export declare function sameOrgPolicyContent(a: OrgRuleSnapshot, b: OrgRuleSnapshot): boolean;
 /**
- * Which entries of an org snapshot the CURRENT rule validator refuses — the published deny/ask rules
- * that can match nothing on this build. Empty ⟺ every rule is enforceable.
+ * Which calls an UNREADABLE row may reach — the calls its strictest reading stands over.
  *
- * Separate from {@link validateOrgSnapshot} because BOTH gates need it: the install gate (a fetched
- * snapshot) and the serving gate (backlog #177 — a snapshot persisted by an earlier build is read back
- * and served without ever having met this validator). It reports every offender rather than the first,
- * since a refusal an administrator cannot act on names no line to fix.
+ * `"every"` when the row names no tool this layer can place: no rule text, a head the rule syntax cannot read, the lone
+ * `*`, or a tool with no rule grammar (a misspelled tool name and a tool this build does not know look the same, and
+ * both may be the shell). Otherwise the rule WORD it names — a shell tool's head is the command word, as a call's is —
+ * and, for a tool whose path rules speak for a face ({@link PATH_RULE_FACES}), the faces of the column its strictest
+ * behavior reads: such a row reaches what a readable rule of its tool could reach, and nothing else.
+ */
+export type OrgRowReach = "every" | {
+    readonly words: readonly string[];
+    readonly faces: readonly DenyFace[];
+};
+/**
+ * A row the layer cannot read: its text (as published; the rendering of the scalar its `rule` holds when that is not a string;
+ * `<unreadable>` when it holds none — a structure is no value, {@link orgRowPolicyOf}), its 1-based place in the
+ * snapshot, why (`code`, and `detail` for a row whose shape — not its text — is at fault), the behavior it stands at, and
+ * the calls it reaches. `behavior` is the row's STRICTEST reading: `ask` only when the row says `ask`, `deny` for a row
+ * that says `deny` and for one whose behavior cannot be read.
+ */
+export interface UnreadableOrgRow {
+    readonly kind: "unreadable";
+    readonly index: number;
+    readonly rule: string;
+    readonly code: RuleRejectCode;
+    readonly detail?: string;
+    readonly behavior: "deny" | "ask";
+    readonly reach: OrgRowReach;
+}
+/** A row the layer reads: a shell command rule under the behavior it publishes. */
+export interface ReadOrgRow {
+    readonly kind: "read";
+    readonly index: number;
+    readonly rule: string;
+    readonly behavior: "deny" | "ask";
+    readonly parsed: ParsedRule;
+}
+/** One call as the org layer judges it: the rule words it answers to (`laneToolNamesOf`; one word is enough), its shell
+ *  command when it is the shell tool's, and the face of its path target when it has one (`callPathFaceOf`). */
+export interface OrgRuleCall {
+    readonly tool: string | readonly string[];
+    readonly command?: string;
+    readonly face?: DenyFace;
+}
+/** Every row of a snapshot read once, and the one judgment of a call against them. */
+export interface OrgRulesReading {
+    readonly rows: readonly (ReadOrgRow | UnreadableOrgRow)[];
+    readonly unreadable: readonly UnreadableOrgRow[];
+    verdictFor(call: OrgRuleCall): OrgRuleVerdict | undefined;
+}
+/**
+ * The members of an org row the layer reads to judge a call — the row's POLICY. A row IS these members: every reader holds and
+ * judges a row as its policy ({@link orgRowPolicyOf}), and two rows with the same policy members are the same policy
+ * ({@link sameOrgPolicyContent}). Any other member a row carries is never judged, held, served or persisted (the receipt reads
+ * each of a row's own members once — a getter on one runs once — and copies none of what it holds beyond a scalar).
+ */
+export declare const ORG_ROW_POLICY_MEMBERS: readonly ["rule", "behavior"];
+/** A JSON scalar — the only value a member the partition keeps holds as data. */
+type Scalar = string | number | boolean | null;
+type ScalarMembers<K extends string> = {
+    [P in K]?: Scalar;
+};
+type OrgRowPolicy = Readonly<ScalarMembers<(typeof ORG_ROW_POLICY_MEMBERS)[number]>>;
+/**
+ * The envelope's rules LIST, read once: `refused` when it is not a list of at most the cap's places ({@link listRefusalOf} —
+ * judged before the list is received, so an oversized or sparse list builds no row) or cannot be received at all;
+ * otherwise its rows, each as its policy ({@link orgRowPolicyOf}) — the list received whole in one receipt
+ * ({@link ORG_RULES_RECEIPT}), so a row's member that cannot be read is that row's alone, a row that cannot be read at all (and
+ * a hole) is a row with nothing in it (`{}`: no rule text, read at its strictest reading) and the rows beside it are untouched.
+ * The ONE reader of the list — the partition holds a snapshot's rows as these, fetched and read back alike
+ * ({@link orgSnapshotCopyOf}), and every reading of rows ({@link readOrgRules}) reads them through it — so no store's rows can be
+ * read two ways, and no row can take the reading of another down with it.
+ */
+export declare function orgRuleListOf(rules: unknown): {
+    readonly rows: readonly OrgRowPolicy[];
+} | {
+    readonly refused: string;
+};
+/**
+ * The ONE reading of an org snapshot's rows: each row read once ({@link readOrgRow}), and the one judgment of a call
+ * against them. Every reader of org rows goes through it — the partition's degraded line, the lane's adjudication,
+ * {@link orgRuleVerdictFor}, {@link unenforceableOrgRules} and the shadow view — so no two of them can read one row two ways.
+ *
+ * A call meets the rows in three answers. DENY: a readable deny reaches one of its program runs, or an unreadable row
+ * standing at deny reaches the call — the first such row in snapshot order speaks. ASK: a readable rule the call cannot be
+ * READ against (the lexer's reason — a rule that cannot be judged may be a deny, so it outranks a reached ask), else a
+ * readable ask reaching it or an unreadable row standing at ask reaching it, the first in snapshot order. Otherwise none.
+ * An unreadable row's verdict carries its reason ({@link unreadableOrgRowReason}) beside its text.
+ *
+ * The rows are read off the one list reader's copy ({@link orgRuleListOf}): rules that are not a list come back `refused` —
+ * the org's rules cannot be read, which is never a policy of zero rows — and a row is judged on what its copy holds: a policy
+ * member that could not be read is one the row does not have (no `rule` ⇒ no rule text, every call; no `behavior` ⇒ its
+ * strictest reading over the calls of the tool it names), read like any other unreadable row while the rows beside it keep
+ * their effect.
+ */
+export declare function readOrgRules(rules: unknown): OrgRulesReading | {
+    readonly refused: string;
+};
+/**
+ * Which rows of an org snapshot this layer cannot read, each with its code — the rows that stand at their strictest
+ * reading instead of as published. Empty ⟺ every row is read. Every unreadable row is reported, a row with no rule text
+ * or a behavior other than deny / ask included (its text rendered when it is not a string). Rules that are not a list, or a
+ * list past the cap, throw the one list judgment's sentence ({@link readListedOrgRules}) — never a reading of fewer rows.
  */
 export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[]): Array<{
     rule: string;
     code: RuleRejectCode;
 }>;
+/** The reason an unreadable row's verdict carries — its place in the snapshot, its code, and the repair. */
+export declare function unreadableOrgRowReason(row: Pick<UnreadableOrgRow, "index" | "code" | "detail">): string;
+/** The ONE clause for an org verdict that carries an `unreadable` reason — a rule the call could not be read against, or
+ *  a row this layer cannot read — on a refusal and on a question alike. */
+export declare function orgUnreadableClause(reason: string): string;
 /**
- * design/182 §7.2 — which org rule speaks for this command, if any. Deny outranks ask; within a
- * behavior the first textual match wins (reporting order only — all denies are the same one answer).
- * Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
- * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a
- * legitimately wide tightening and matches; a segment hit is a hit; a call the lexer cannot read
- * against a rule is an ASK with the reason — fail closed, never silence).
- *
- * The skip below is a defensive floor, and what stands behind it is worth stating precisely: rules that
- * arrive from the org partition's `resolve` ({@link createOrgRulePartition}) have passed {@link validateOrgSnapshot} on BOTH the install
- * and the serving path (backlog #177), so an unenforceable entry cannot reach here through the overlay
- * — the whole snapshot is refused, or the resolution reports `unavailable`, and either way it is
- * disclosed. A caller that hands this function a snapshot it obtained ELSEWHERE gets no such guarantee:
- * the skip is silent, and naming the dead entries is that caller's job — {@link unenforceableOrgRules}
- * is the shared way to do it.
+ * The ONE line naming a snapshot's unreadable rows (count, the first {@link DISCLOSED_UNREADABLE_ROWS} by place, text and
+ * code, the rest summarized), or `undefined` when every row is read. The partition puts it on every resolution that
+ * serves such a snapshot, and the org lane hands it to its operator sink on every adjudication over one, so the two seats
+ * describe one snapshot in one sentence. Each text is escaped — the characters that most often make a row unreadable are
+ * exactly the ones that do not render.
  */
-export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: {
-    tool: string;
-    command: string;
-}): OrgRuleVerdict | undefined;
-/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the call could
- *  not be READ against the org's rules, the lexer's reason beside the first rule it could not judge
- *  (`behavior` is then `ask`: the org published a rule that may reach this call, and nobody can say). */
+export declare function describeUnreadableOrgRows(unreadable: readonly UnreadableOrgRow[], revision?: unknown): string | undefined;
+/**
+ * design/182 §7.2 — which org rule speaks for this call, if any: {@link readOrgRules}'s judgment, over a snapshot read for
+ * this call alone. Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
+ * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a legitimately wide tightening and
+ * matches; a segment hit is a hit; a call the lexer cannot read against a rule is an ASK with the reason — fail closed,
+ * never silence), and a row this layer cannot read stands at its strictest reading over the calls it may reach. A caller
+ * judging many calls against one snapshot reads it once with {@link readOrgRules} instead. Rules that are not a list, or a
+ * list past the cap, throw the one list judgment's sentence ({@link readListedOrgRules}) — never a verdict over fewer rows.
+ */
+export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: OrgRuleCall): OrgRuleVerdict | undefined;
+/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the rule could not be judged
+ *  against the call, why (`unreadable`): either the call could not be READ against it (the lexer's reason; `behavior` is
+ *  then `ask` — the org published a rule that may reach this call, and nobody can say), or the row is not one this layer
+ *  reads ({@link unreadableOrgRowReason}; `behavior` is the row's strictest reading). */
 export interface OrgRuleVerdict {
     readonly behavior: "deny" | "ask";
     readonly rule: string;
@@ -234,14 +360,18 @@ export interface OrgRuleVerdict {
  * either way. org ASK rules do not shadow: the personal lane never consumes a `requiresRealApproval`
  * ask, so the two never actually meet on one call.
  *
- * design/382 §2.6 — a Read directory rule is never org-shadowed in this version: the org layer has no
- * Read grammar (a snapshot carrying one refuses whole at the validator), so there is no deny that could
- * reach it, and its `command` is a PATH that must not be fed to the shell lane's segment reader as
- * though it were a command line.
+ * An UNREADABLE row standing at deny refuses every call it reaches ({@link readOrgRules}), so it shadows every personal
+ * rule of a tool it reaches — by the rule word, or by the face that tool's calls are on — exactly as the gate refuses
+ * those calls; one standing at ask does not shadow, as a readable ask does not.
+ *
+ * design/382 §2.6 — no READABLE org row reaches a Read directory rule in this version: the org layer has no Read
+ * grammar, and the rule's `command` is a PATH that must not be fed to the shell lane's segment reader as though it
+ * were a command line.
  */
 export declare function orgRuleShadows(orgRules: readonly OrgPermissionRule[], rule: Pick<PersistedRule, "tool" | "command">): boolean;
-/** The shadow predicate with the org denies parsed ONCE — what a read over many rows uses. */
+/** The shadow predicate with the org rows read ONCE — what a read over many rows uses. */
 export declare function compileOrgShadowPredicate(orgRules: readonly OrgPermissionRule[]): (rule: Pick<PersistedRule, "tool" | "command">) => boolean;
 /** Does this store carry a write face? Re-exported convenience for org-ticket integrations that need to
  *  distinguish a read-only projection from a writable personal bucket without importing the writer seam. */
 export declare function isWritablePermissionRuleStore(store: PermissionRuleStore): boolean;
+export {};