approval-md 0.0.1 → 0.2.0

package/dist/src/core/prompt-layout.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Prompt layout: which INFORMATIONAL rows a channel puts in front of an
+ * approver, as a policy decision rather than a code decision (APRV-218).
+ *
+ * SPEC.md §5.2 gains `channels.<name>.prompt`; SPEC.md §10.3 already says a
+ * channel holds no truth, and this module is what keeps that so — the block
+ * decides what is SHOWN, never what is true, and every field it can reach was
+ * already on the `ChannelRequest` and already in `--json`, `approval queue` and
+ * the web page. Nothing here reads the log, and no key added here lets a
+ * channel learn anything about it.
+ *
+ * ## Why this is a policy key at all
+ *
+ * The Telegram prompt was slimmed deliberately: APRV-143 dropped the `ttl` row
+ * because the `waiting … expires HH:MM UTC` line already states the deadline,
+ * and APRV-163 dropped six bookkeeping rows and made three health rows render
+ * only when abnormal. That layout fits ONE operator's workflow. Another wants
+ * the budget line on every prompt, or the TTL as a duration, or the task id
+ * always visible. Those are preferences about a screen, and preferences about a
+ * screen belong in the policy file beside the other things an operator chooses,
+ * not in a `git blame` argument about a default.
+ *
+ * ## What a layout may NOT do
+ *
+ * A layout chooses among rows the approver may read. It cannot touch what the
+ * approver SIGNS. Three things are therefore out of its reach entirely:
+ *
+ * 1. **The canonical block** (SPEC.md §9's "what you see is what you sign") is
+ *    not a row. It carries the payload bytes, the renderer version, the class,
+ *    the kind and the bound `payload sha256`, it is rendered verbatim, and no
+ *    key in this module can reorder, shorten, or remove it.
+ * 2. **The computed/claimed split.** A row's side of the boundary is a property
+ *    of the field (`TaggedField.kind`), not of the layout. `rows` reorders; it
+ *    cannot move a claimed line into the computed block, because a channel
+ *    partitions by kind AFTER it applies the order. That is the property
+ *    APRV-144's CLAIMED heading exists for, and a test pins it.
+ * 3. **{@link REQUIRED_PROMPT_ROWS}**, the rows the contract marks as required
+ *    for a decision. Naming one in `hide` is a policy that fails to load.
+ *
+ * The buttons are not a row either, for the same reason the block is not: a
+ * prompt with no way to answer it is not a prompt.
+ *
+ * ## Fail directions
+ *
+ * Soft on ABSENCE, closed on INVALIDITY, which is the split every other policy
+ * key in this runtime keeps. No `prompt` block, or a policy that did not load,
+ * means today's rows: a layout is not a permission, and an unrelated typo in a
+ * class rule must not silently redecorate a phone screen. An unknown row name
+ * or a required row in `hide` is a statement the runtime cannot honour, so the
+ * WHOLE policy fails schema validation and every class resolves to `manual` —
+ * the operator repairs the file, and until they do the gate is at its
+ * strictest.
+ *
+ * Pure: no clock, no IO, no environment. It sits in `core/` rather than in
+ * `channels/` for `core/telegram-config.ts`'s reason — more than one layer asks
+ * "which rows does this policy want?" and none of them may answer differently —
+ * and it imports nothing from `channels/`, so `tests/layering.test.ts` stays
+ * true. The row names below are the `ChannelRequest` member names spelled as
+ * plain strings for exactly that reason.
+ */
+import type { Policy, PolicyLoadResult } from "./policy-load.js";
+import type { ValidationError } from "./validate.js";
+/**
+ * The row vocabulary: every `ChannelRequest` member a channel renders as a row.
+ *
+ * Closed, and closed for `delivery`'s reason (APRV-216): a name this runtime
+ * cannot place is a row the author believes is in force that nothing reads, and
+ * guessing at it would be the silent no-op the whole policy schema is shaped to
+ * prevent.
+ *
+ * `fullPayload` is deliberately ABSENT. The canonical block is not a row.
+ */
+export declare const PROMPT_ROWS: readonly ["action_key", "task", "class", "command_breakdown", "protected_path", "policy_diff", "policy_load", "autonomy", "provenance", "state", "requested_ts", "waiting", "ttl_remaining_ms", "payload_hash", "attestation", "budgets", "chain", "token_delivery", "est_cost_usd", "gloss", "summary", "rationale", "confidence"];
+/** One row name from {@link PROMPT_ROWS}. */
+export type PromptRow = (typeof PROMPT_ROWS)[number];
+/** Whether a string is a row name this runtime knows how to place. */
+export declare function isPromptRow(value: unknown): value is PromptRow;
+/**
+ * The rows an operator may reorder but never remove.
+ *
+ * Each is required for a DECISION rather than for a screen. `action_key`
+ * identifies which request the gesture answers; `class` is the resolution the
+ * whole gate turns on; `command_breakdown` and `protected_path` are APRV-144
+ * and APRV-143's answer to "what does this command actually do, and which
+ * protected path earned the class", derived from the bound bytes by the same
+ * classifier the hook decided with; `policy_diff` and `policy_load` are what
+ * SPEC.md §10.3 requires of an attestation prompt, where "a prompt carrying
+ * only a hash asks a human to sign for sixty-four characters and is a
+ * conformance failure".
+ *
+ * `payload_hash` is NOT here, and its absence is not an oversight. The bound
+ * hash is stated inside the canonical block on every channel, and the block is
+ * out of a layout's reach, so an operator who hides the row removes a
+ * duplicate rather than the binding. Telegram's default layout already does
+ * exactly that (APRV-163).
+ *
+ * A required row a request does not CARRY renders nothing, as it does today.
+ * Requirement is about what a policy may instruct, not about what a particular
+ * request happens to hold.
+ */
+export declare const REQUIRED_PROMPT_ROWS: readonly PromptRow[];
+/**
+ * How a row renders when nothing in the policy says otherwise.
+ *
+ * - `always` — on every prompt the request carries the field for.
+ * - `abnormal` — only when the value is the reason to look. APRV-163's
+ *   argument: a row that says "everything is fine" on every ordinary request is
+ *   a row a reader learns to skip, and the skipping does not stop on the one
+ *   request where it says something else.
+ * - `off` — the channel does not render it by default. The field still travels
+ *   on the request, so `--json`, `approval queue` and the web page carry it.
+ */
+export type RowVisibility = "always" | "abnormal" | "off";
+/** A resolved layout: the order rows render in, and each row's visibility. */
+export interface PromptLayout {
+    /** Every row in {@link PROMPT_ROWS}, in render order. */
+    order: readonly PromptRow[];
+    /** Visibility per row. Total: every row name has an entry. */
+    visibility: Readonly<Record<PromptRow, RowVisibility>>;
+}
+/** The channels this runtime ships (SPEC.md §10.3). */
+export declare const PROMPT_CHANNELS: readonly ["cli", "web", "telegram"];
+/** One of the three shipped channel names. */
+export type PromptChannel = (typeof PROMPT_CHANNELS)[number];
+/**
+ * Telegram's default layout: the slimmed phone prompt, exactly as APRV-143 and
+ * APRV-163 left it.
+ *
+ * The ORDER of the rows that render is load-bearing and must not drift: it is
+ * the sequence a reader's eye has learned. The `off` rows are interleaved where
+ * they belong if an operator turns them on, which costs nothing while they are
+ * off and saves an operator from writing a `rows` list to get a sensible
+ * position.
+ *
+ * `action_key` is `off` here because Telegram renders it STRUCTURALLY, as the
+ * message's second line in a `<code>` span. It is required, so it cannot be
+ * hidden, and it is not a bullet, so promoting it changes nothing.
+ */
+export declare const TELEGRAM_PROMPT_LAYOUT: PromptLayout;
+/**
+ * The CLI channel's default layout: every row the request carries.
+ *
+ * A terminal has room, and a one-shot rendering an operator asked for by typing
+ * a verb is not the place to economise on lines the way a push notification is.
+ */
+export declare const CLI_PROMPT_LAYOUT: PromptLayout;
+/** The web channel's default layout. Same reasoning as the CLI's: a page scrolls. */
+export declare const WEB_PROMPT_LAYOUT: PromptLayout;
+/** Default layout per shipped channel. What an absent `prompt` block means. */
+export declare const DEFAULT_PROMPT_LAYOUTS: Readonly<Record<PromptChannel, PromptLayout>>;
+/**
+ * A `channels.<name>.prompt` block as a policy may write it.
+ *
+ * Three keys, and each does ONE thing, because a key that both orders and
+ * hides would leave an operator guessing which of the two a short list meant:
+ *
+ * - `rows` — ORDER ONLY. The rows it names render in that order, ahead of every
+ *   row it does not name; those keep their default relative order behind them.
+ *   It is never a whitelist, so a `ChannelRequest` widened by a later task
+ *   cannot silently lose a field to a list written before that field existed —
+ *   the same property `orderedFields` has held since APRV-23.
+ * - `always` — visibility UP. A row that is `abnormal` or `off` by default
+ *   renders on every prompt.
+ * - `hide` — visibility DOWN. A row never renders. Refused for
+ *   {@link REQUIRED_PROMPT_ROWS}.
+ *
+ * `always` and `hide` naming the same row is refused rather than resolved by
+ * precedence: a policy that says both things about one row has an author who
+ * believes one of them, and picking for them is the guess this schema does not
+ * make.
+ */
+export interface PromptBlock {
+    rows?: PromptRow[];
+    always?: PromptRow[];
+    hide?: PromptRow[];
+}
+/**
+ * The layout in force for `channel`.
+ *
+ * Fail-soft in the same direction as `telegramDeliveryFor`: a policy that did
+ * not load declares nothing, an absent block declares nothing, and a layout is
+ * not a permission. Anything structurally wrong that reaches here (a hand-built
+ * load result, a key from a later version) falls back to the default rather
+ * than being guessed at — a LOADED policy cannot carry such a block, because
+ * {@link promptBlockErrors} refuses it at load.
+ */
+export declare function promptLayoutFor(load: PolicyLoadResult, channel: string): PromptLayout;
+/**
+ * Apply a block to a layout. Pure, total, and exported so a caller holding a
+ * block already can resolve it without going back through a policy file, which
+ * is what the tests do and what a future `approval policy explain` of a channel
+ * would need. Nothing outside the tests calls it today, and that is fine: the
+ * split keeps {@link promptLayoutFor} to one job, reading the block.
+ */
+export declare function applyPromptBlock(base: PromptLayout, block: PromptBlock): PromptLayout;
+/** The machine-readable reasons a `prompt` block refuses (APRV-218). */
+export declare const PROMPT_BLOCK_ERROR_KEYWORDS: readonly [
+/** A row name this runtime cannot place. */
+"prompt-row-unknown", 
+/** {@link REQUIRED_PROMPT_ROWS} named in `hide`. */
+"prompt-row-required", 
+/** `rows`, `always` or `hide` is not an array of strings. */
+"prompt-block-shape", 
+/** One row named by both `always` and `hide`. */
+"prompt-row-conflict", 
+/** A key the `prompt` block does not define. */
+"prompt-key-unknown"];
+/**
+ * Validate every `channels.<name>.prompt` in a policy. Empty means clean.
+ *
+ * This runs on top of the JSON Schema rather than instead of it, and the
+ * duplication is deliberate. The schema types the three channels this runtime
+ * ships and closes the row enum there, which is where SPEC.md §8's
+ * validate-at-the-write-boundary rule wants it; but `channels` admits UNKNOWN
+ * channel names as free-form objects on purpose, so a third-party transport
+ * plugin does not invalidate a whole policy, and a `prompt` block written under
+ * such a name would otherwise reach a renderer unchecked. Both nets return the
+ * same verdict — the policy does not load, everything is `manual` — so an
+ * operator never has to know which one caught them.
+ */
+export declare function promptBlockErrors(policy: Policy): ValidationError[];

package/dist/src/core/prompt-layout.js

@@ -0,0 +1,422 @@
+/**
+ * Prompt layout: which INFORMATIONAL rows a channel puts in front of an
+ * approver, as a policy decision rather than a code decision (APRV-218).
+ *
+ * SPEC.md §5.2 gains `channels.<name>.prompt`; SPEC.md §10.3 already says a
+ * channel holds no truth, and this module is what keeps that so — the block
+ * decides what is SHOWN, never what is true, and every field it can reach was
+ * already on the `ChannelRequest` and already in `--json`, `approval queue` and
+ * the web page. Nothing here reads the log, and no key added here lets a
+ * channel learn anything about it.
+ *
+ * ## Why this is a policy key at all
+ *
+ * The Telegram prompt was slimmed deliberately: APRV-143 dropped the `ttl` row
+ * because the `waiting … expires HH:MM UTC` line already states the deadline,
+ * and APRV-163 dropped six bookkeeping rows and made three health rows render
+ * only when abnormal. That layout fits ONE operator's workflow. Another wants
+ * the budget line on every prompt, or the TTL as a duration, or the task id
+ * always visible. Those are preferences about a screen, and preferences about a
+ * screen belong in the policy file beside the other things an operator chooses,
+ * not in a `git blame` argument about a default.
+ *
+ * ## What a layout may NOT do
+ *
+ * A layout chooses among rows the approver may read. It cannot touch what the
+ * approver SIGNS. Three things are therefore out of its reach entirely:
+ *
+ * 1. **The canonical block** (SPEC.md §9's "what you see is what you sign") is
+ *    not a row. It carries the payload bytes, the renderer version, the class,
+ *    the kind and the bound `payload sha256`, it is rendered verbatim, and no
+ *    key in this module can reorder, shorten, or remove it.
+ * 2. **The computed/claimed split.** A row's side of the boundary is a property
+ *    of the field (`TaggedField.kind`), not of the layout. `rows` reorders; it
+ *    cannot move a claimed line into the computed block, because a channel
+ *    partitions by kind AFTER it applies the order. That is the property
+ *    APRV-144's CLAIMED heading exists for, and a test pins it.
+ * 3. **{@link REQUIRED_PROMPT_ROWS}**, the rows the contract marks as required
+ *    for a decision. Naming one in `hide` is a policy that fails to load.
+ *
+ * The buttons are not a row either, for the same reason the block is not: a
+ * prompt with no way to answer it is not a prompt.
+ *
+ * ## Fail directions
+ *
+ * Soft on ABSENCE, closed on INVALIDITY, which is the split every other policy
+ * key in this runtime keeps. No `prompt` block, or a policy that did not load,
+ * means today's rows: a layout is not a permission, and an unrelated typo in a
+ * class rule must not silently redecorate a phone screen. An unknown row name
+ * or a required row in `hide` is a statement the runtime cannot honour, so the
+ * WHOLE policy fails schema validation and every class resolves to `manual` —
+ * the operator repairs the file, and until they do the gate is at its
+ * strictest.
+ *
+ * Pure: no clock, no IO, no environment. It sits in `core/` rather than in
+ * `channels/` for `core/telegram-config.ts`'s reason — more than one layer asks
+ * "which rows does this policy want?" and none of them may answer differently —
+ * and it imports nothing from `channels/`, so `tests/layering.test.ts` stays
+ * true. The row names below are the `ChannelRequest` member names spelled as
+ * plain strings for exactly that reason.
+ */
+/**
+ * The row vocabulary: every `ChannelRequest` member a channel renders as a row.
+ *
+ * Closed, and closed for `delivery`'s reason (APRV-216): a name this runtime
+ * cannot place is a row the author believes is in force that nothing reads, and
+ * guessing at it would be the silent no-op the whole policy schema is shaped to
+ * prevent.
+ *
+ * `fullPayload` is deliberately ABSENT. The canonical block is not a row.
+ */
+export const PROMPT_ROWS = [
+    "action_key",
+    "task",
+    "class",
+    "command_breakdown",
+    "protected_path",
+    "policy_diff",
+    "policy_load",
+    "autonomy",
+    "provenance",
+    "state",
+    "requested_ts",
+    "waiting",
+    "ttl_remaining_ms",
+    "payload_hash",
+    "attestation",
+    "budgets",
+    "chain",
+    "token_delivery",
+    "est_cost_usd",
+    "gloss",
+    "summary",
+    "rationale",
+    "confidence",
+];
+/** Whether a string is a row name this runtime knows how to place. */
+export function isPromptRow(value) {
+    return typeof value === "string" && PROMPT_ROWS.includes(value);
+}
+/**
+ * The rows an operator may reorder but never remove.
+ *
+ * Each is required for a DECISION rather than for a screen. `action_key`
+ * identifies which request the gesture answers; `class` is the resolution the
+ * whole gate turns on; `command_breakdown` and `protected_path` are APRV-144
+ * and APRV-143's answer to "what does this command actually do, and which
+ * protected path earned the class", derived from the bound bytes by the same
+ * classifier the hook decided with; `policy_diff` and `policy_load` are what
+ * SPEC.md §10.3 requires of an attestation prompt, where "a prompt carrying
+ * only a hash asks a human to sign for sixty-four characters and is a
+ * conformance failure".
+ *
+ * `payload_hash` is NOT here, and its absence is not an oversight. The bound
+ * hash is stated inside the canonical block on every channel, and the block is
+ * out of a layout's reach, so an operator who hides the row removes a
+ * duplicate rather than the binding. Telegram's default layout already does
+ * exactly that (APRV-163).
+ *
+ * A required row a request does not CARRY renders nothing, as it does today.
+ * Requirement is about what a policy may instruct, not about what a particular
+ * request happens to hold.
+ */
+export const REQUIRED_PROMPT_ROWS = [
+    "action_key",
+    "class",
+    "command_breakdown",
+    "protected_path",
+    "policy_diff",
+    "policy_load",
+];
+/** The channels this runtime ships (SPEC.md §10.3). */
+export const PROMPT_CHANNELS = ["cli", "web", "telegram"];
+function layoutOf(order, visibility) {
+    const full = {};
+    for (const row of PROMPT_ROWS)
+        full[row] = visibility[row] ?? "off";
+    return { order, visibility: full };
+}
+/**
+ * Telegram's default layout: the slimmed phone prompt, exactly as APRV-143 and
+ * APRV-163 left it.
+ *
+ * The ORDER of the rows that render is load-bearing and must not drift: it is
+ * the sequence a reader's eye has learned. The `off` rows are interleaved where
+ * they belong if an operator turns them on, which costs nothing while they are
+ * off and saves an operator from writing a `rows` list to get a sensible
+ * position.
+ *
+ * `action_key` is `off` here because Telegram renders it STRUCTURALLY, as the
+ * message's second line in a `<code>` span. It is required, so it cannot be
+ * hidden, and it is not a bullet, so promoting it changes nothing.
+ */
+export const TELEGRAM_PROMPT_LAYOUT = layoutOf([
+    "action_key",
+    "task",
+    "class",
+    "command_breakdown",
+    "protected_path",
+    "policy_diff",
+    "policy_load",
+    "autonomy",
+    "budgets",
+    "attestation",
+    "provenance",
+    "state",
+    "requested_ts",
+    "waiting",
+    "ttl_remaining_ms",
+    "payload_hash",
+    "chain",
+    "token_delivery",
+    "gloss",
+    "summary",
+    "est_cost_usd",
+    "rationale",
+    "confidence",
+], {
+    class: "always",
+    command_breakdown: "always",
+    protected_path: "always",
+    policy_diff: "always",
+    policy_load: "always",
+    autonomy: "abnormal",
+    budgets: "abnormal",
+    attestation: "abnormal",
+    waiting: "always",
+    gloss: "always",
+    summary: "always",
+    est_cost_usd: "always",
+    rationale: "always",
+    confidence: "always",
+});
+/**
+ * The order the terminal and the page have used since APRV-23: computed
+ * identity and authority first, claimed persuasion last, so a reader who stops
+ * halfway has read the runtime's answer and not the agent's pitch.
+ *
+ * `token_delivery` sits at the end because that is where it lands today —
+ * neither channel's `FIELD_ORDER` named it, and both append a member they do
+ * not list. Naming it here makes it reachable by `hide` and `rows` without
+ * moving it.
+ */
+const FULL_ROW_ORDER = [
+    "action_key",
+    "task",
+    "class",
+    "command_breakdown",
+    "protected_path",
+    "policy_diff",
+    "policy_load",
+    "autonomy",
+    "provenance",
+    "state",
+    "requested_ts",
+    "waiting",
+    "ttl_remaining_ms",
+    "payload_hash",
+    "attestation",
+    "budgets",
+    "chain",
+    "est_cost_usd",
+    "gloss",
+    "summary",
+    "rationale",
+    "confidence",
+    "token_delivery",
+];
+const ALL_ALWAYS = Object.fromEntries(PROMPT_ROWS.map((row) => [row, "always"]));
+/**
+ * The CLI channel's default layout: every row the request carries.
+ *
+ * A terminal has room, and a one-shot rendering an operator asked for by typing
+ * a verb is not the place to economise on lines the way a push notification is.
+ */
+export const CLI_PROMPT_LAYOUT = layoutOf(FULL_ROW_ORDER, ALL_ALWAYS);
+/** The web channel's default layout. Same reasoning as the CLI's: a page scrolls. */
+export const WEB_PROMPT_LAYOUT = layoutOf(FULL_ROW_ORDER, ALL_ALWAYS);
+/** Default layout per shipped channel. What an absent `prompt` block means. */
+export const DEFAULT_PROMPT_LAYOUTS = {
+    cli: CLI_PROMPT_LAYOUT,
+    web: WEB_PROMPT_LAYOUT,
+    telegram: TELEGRAM_PROMPT_LAYOUT,
+};
+/**
+ * The layout in force for `channel`.
+ *
+ * Fail-soft in the same direction as `telegramDeliveryFor`: a policy that did
+ * not load declares nothing, an absent block declares nothing, and a layout is
+ * not a permission. Anything structurally wrong that reaches here (a hand-built
+ * load result, a key from a later version) falls back to the default rather
+ * than being guessed at — a LOADED policy cannot carry such a block, because
+ * {@link promptBlockErrors} refuses it at load.
+ */
+export function promptLayoutFor(load, channel) {
+    const base = DEFAULT_PROMPT_LAYOUTS[channel] ?? CLI_PROMPT_LAYOUT;
+    if (!load.ok)
+        return base;
+    const block = readBlock(load.policy.channels?.[channel]);
+    if (block === null)
+        return base;
+    return applyPromptBlock(base, block);
+}
+/**
+ * Apply a block to a layout. Pure, total, and exported so a caller holding a
+ * block already can resolve it without going back through a policy file, which
+ * is what the tests do and what a future `approval policy explain` of a channel
+ * would need. Nothing outside the tests calls it today, and that is fine: the
+ * split keeps {@link promptLayoutFor} to one job, reading the block.
+ */
+export function applyPromptBlock(base, block) {
+    const named = (block.rows ?? []).filter(isPromptRow);
+    const order = [];
+    for (const row of named)
+        if (!order.includes(row))
+            order.push(row);
+    for (const row of base.order)
+        if (!order.includes(row))
+            order.push(row);
+    const visibility = { ...base.visibility };
+    for (const row of block.always ?? [])
+        if (isPromptRow(row))
+            visibility[row] = "always";
+    for (const row of block.hide ?? [])
+        if (isPromptRow(row))
+            visibility[row] = "off";
+    return { order, visibility };
+}
+/**
+ * The `prompt` block under one channel entry, or `null` when there is none.
+ *
+ * Structural only. Every semantic check lives in {@link promptBlockErrors} and
+ * has already run at load, so a block reaching here from a loaded policy is
+ * known-good; this function's `null` returns are for the hand-built and
+ * future-version cases the fail-soft rule above covers.
+ */
+function readBlock(entry) {
+    if (entry === null || typeof entry !== "object")
+        return null;
+    const raw = entry["prompt"];
+    if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const block = raw;
+    const list = (key) => {
+        const value = block[key];
+        if (!Array.isArray(value))
+            return undefined;
+        return value.filter(isPromptRow);
+    };
+    const rows = list("rows");
+    const always = list("always");
+    const hide = list("hide");
+    return {
+        ...(rows === undefined ? {} : { rows }),
+        ...(always === undefined ? {} : { always }),
+        ...(hide === undefined ? {} : { hide }),
+    };
+}
+/** The machine-readable reasons a `prompt` block refuses (APRV-218). */
+export const PROMPT_BLOCK_ERROR_KEYWORDS = [
+    /** A row name this runtime cannot place. */
+    "prompt-row-unknown",
+    /** {@link REQUIRED_PROMPT_ROWS} named in `hide`. */
+    "prompt-row-required",
+    /** `rows`, `always` or `hide` is not an array of strings. */
+    "prompt-block-shape",
+    /** One row named by both `always` and `hide`. */
+    "prompt-row-conflict",
+    /** A key the `prompt` block does not define. */
+    "prompt-key-unknown",
+];
+const PROMPT_BLOCK_KEYS = ["rows", "always", "hide"];
+/**
+ * Validate every `channels.<name>.prompt` in a policy. Empty means clean.
+ *
+ * This runs on top of the JSON Schema rather than instead of it, and the
+ * duplication is deliberate. The schema types the three channels this runtime
+ * ships and closes the row enum there, which is where SPEC.md §8's
+ * validate-at-the-write-boundary rule wants it; but `channels` admits UNKNOWN
+ * channel names as free-form objects on purpose, so a third-party transport
+ * plugin does not invalidate a whole policy, and a `prompt` block written under
+ * such a name would otherwise reach a renderer unchecked. Both nets return the
+ * same verdict — the policy does not load, everything is `manual` — so an
+ * operator never has to know which one caught them.
+ */
+export function promptBlockErrors(policy) {
+    const errors = [];
+    const channels = policy.channels;
+    if (channels === undefined || channels === null || typeof channels !== "object")
+        return errors;
+    for (const channel of Object.keys(channels).sort()) {
+        const entry = channels[channel];
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const raw = entry["prompt"];
+        if (raw === undefined)
+            continue;
+        const at = `/channels/${channel}/prompt`;
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            errors.push({
+                path: at,
+                keyword: "prompt-block-shape",
+                message: "expected an object with any of `rows`, `always`, `hide`",
+            });
+            continue;
+        }
+        const block = raw;
+        for (const key of Object.keys(block).sort()) {
+            if (!PROMPT_BLOCK_KEYS.includes(key)) {
+                errors.push({
+                    path: `${at}/${key}`,
+                    keyword: "prompt-key-unknown",
+                    message: `unknown key; the prompt block defines ${PROMPT_BLOCK_KEYS.join(", ")}`,
+                });
+            }
+        }
+        const seen = {};
+        for (const key of PROMPT_BLOCK_KEYS) {
+            const value = block[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value)) {
+                errors.push({
+                    path: `${at}/${key}`,
+                    keyword: "prompt-block-shape",
+                    message: "expected an array of row names",
+                });
+                continue;
+            }
+            const names = new Set();
+            value.forEach((row, index) => {
+                if (!isPromptRow(row)) {
+                    errors.push({
+                        path: `${at}/${key}/${String(index)}`,
+                        keyword: "prompt-row-unknown",
+                        message: `unknown row name ${JSON.stringify(row)}; known rows are ${PROMPT_ROWS.join(", ")}`,
+                    });
+                    return;
+                }
+                names.add(row);
+                if (key === "hide" && REQUIRED_PROMPT_ROWS.includes(row)) {
+                    errors.push({
+                        path: `${at}/${key}/${String(index)}`,
+                        keyword: "prompt-row-required",
+                        message: `row ${JSON.stringify(row)} is required for a decision and may be reordered but not hidden; required rows are ${REQUIRED_PROMPT_ROWS.join(", ")}`,
+                    });
+                }
+            });
+            seen[key] = names;
+        }
+        for (const row of seen["always"] ?? new Set()) {
+            if (seen["hide"]?.has(row) === true) {
+                errors.push({
+                    path: `${at}/hide`,
+                    keyword: "prompt-row-conflict",
+                    message: `row ${JSON.stringify(row)} is named by both \`always\` and \`hide\`; say one of them`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=prompt-layout.js.map

package/dist/src/core/prompt-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-layout.js","sourceRoot":"","sources":["../../../src/core/prompt-layout.ts"],"names":[],"mappings":"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"}