@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/orchestration_record.ts

@@ -28,6 +28,15 @@ import type { EvidenceBasis } from './evidence_basis.js';
 import type { NoFreeForm } from './runtime_journal.js';
 import { type PrivacyClass } from './privacy_class.js';
 import type { PhaseOutcome } from './outcome_vocabularies.js';
+import {
+    HAND_KINDS,
+    isUnpaid,
+    ROUTE_BILLINGS,
+    VERIFY_VERDICTS,
+    type HandKind,
+    type RouteBilling,
+    type VerifyVerdict,
+} from './hand_kinds.js';
 
 export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
 /** Which route the rung took: deterministic primitive (lean-init L0),
@@ -168,6 +177,8 @@ export interface RecordInput {
     first_pass_success?: boolean | undefined;
     /** QUALITY: slice retried on a higher tier after a verification failure. Optional boolean (null = not measured). */
     escalated?: boolean | undefined;
+    /** The tier of the failed attempt when this dispatch re-ran a slice one tier up. */
+    escalated_from?: TierChosen | null | undefined;
     /** U5 (reliability-measurement): the subagent-type combination this dispatch
      *  ran (ordered agent-type ids, e.g. ['implementer','implementer','judge']) —
      *  with `outcome`, lets the orchestrator prefer combos that worked. Ids only. */
@@ -233,6 +244,16 @@ export interface RecordInput {
     // same built-and-unreachable class the rest of this change detects, so it
     // goes rather than waiting behind a label. Re-adding them is one commit
     // once an observation source exists.
+    /** The typed kind a rung-0.5 hand was asked to do; null for an untyped ask or a spawn. */
+    hand_kind?: HandKind | null | undefined;
+    /** Whether the hand's return matched its kind's schema; a mismatch is a failed call. */
+    schema_valid?: boolean | undefined;
+    /** How the route that served this call is paid for. */
+    route_billing?: RouteBilling | null | undefined;
+    /** The head's verdict on the hand's return; required on an unpaid route's line. */
+    verified?: VerifyVerdict | null | undefined;
+    /** Tokens the head itself spent verifying the return — what limit relief is measured net of. */
+    verify_tokens?: number | null | undefined;
     // Audit-log envelope (sensible defaults for a dispatch record)
     phase?: LinePhase | undefined;
     outcome?: LineOutcome | undefined;
@@ -428,9 +449,14 @@ function modelDivergent(
 ): boolean | null {
     if (typeof requested !== 'string' || typeof served !== 'string') return null;
     if (!requested || !served) return null;
+    // A dispatch argument names a family alias (`haiku`), the host serves a
+    // full id of it; any other requested spelling is compared exactly.
+    if (MODEL_FAMILY_ALIASES.includes(requested)) return !served.toLowerCase().includes(requested);
     return requested !== served;
 }
 
+const MODEL_FAMILY_ALIASES: readonly string[] = ['haiku', 'sonnet', 'opus', 'fable'];
+
 /**
  * Build + validate the audit-log-v1 line. Returns `{line, errors}`; when
  * `errors` is non-empty, `line` is null and the caller must NOT write.
@@ -471,6 +497,9 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     if (input.tier_chosen != null && !TIERS_CHOSEN.includes(input.tier_chosen)) {
         errors.push(`tier_chosen must be one of ${TIERS_CHOSEN.join(' | ')} (or omitted)`);
     }
+    if (input.tier_chosen != null && (typeof input.model_requested !== 'string' || !input.model_requested)) {
+        errors.push('tier_chosen needs model_requested: a tier the dispatch did not carry is not checkable');
+    }
     if (input.tier_source != null && !TIER_SOURCES.includes(input.tier_source)) {
         errors.push(`tier_source must be one of ${TIER_SOURCES.join(' | ')} (or omitted)`);
     }
@@ -485,6 +514,9 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     if (input.first_pass_success !== undefined && typeof input.first_pass_success !== 'boolean') {
         errors.push('first_pass_success must be a boolean (true = return adopted without parent rework) or omitted');
     }
+    if (input.escalated_from != null && !TIERS_CHOSEN.includes(input.escalated_from)) {
+        errors.push(`escalated_from must be one of ${TIERS_CHOSEN.join(' | ')} (or omitted)`);
+    }
     if (input.escalated !== undefined && typeof input.escalated !== 'boolean') {
         errors.push('escalated must be a boolean (true = retried on a higher tier after verification failure) or omitted');
     }
@@ -547,6 +579,25 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         errors.push('rules_used cannot exceed rules_carried (a worker cannot apply a rule it was not given)');
     }
 
+    if (input.hand_kind != null && !HAND_KINDS.includes(input.hand_kind)) {
+        errors.push(`hand_kind must be one of ${HAND_KINDS.join(' | ')} (or omitted)`);
+    }
+    if (input.schema_valid !== undefined && typeof input.schema_valid !== 'boolean') {
+        errors.push('schema_valid must be a boolean or omitted');
+    }
+    if (input.route_billing != null && !ROUTE_BILLINGS.includes(input.route_billing)) {
+        errors.push(`route_billing must be one of ${ROUTE_BILLINGS.join(' | ')} (or omitted)`);
+    }
+    if (input.verified != null && !VERIFY_VERDICTS.includes(input.verified)) {
+        errors.push(`verified must be one of ${VERIFY_VERDICTS.join(' | ')} (or omitted)`);
+    }
+    if (input.route_billing != null && ROUTE_BILLINGS.includes(input.route_billing) && isUnpaid(input.route_billing) && input.verified == null) {
+        errors.push('verified is required on an unpaid route: every hand return is verified by the head, or recorded as skipped');
+    }
+    if (input.verify_tokens != null && (!isInt(input.verify_tokens) || input.verify_tokens < 0)) {
+        errors.push('verify_tokens must be a non-negative integer count');
+    }
+
     if (input.capsule_emitted !== undefined && typeof input.capsule_emitted !== 'boolean') {
         errors.push('capsule_emitted must be a boolean or omitted');
     }
@@ -593,6 +644,7 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         model_divergent: modelDivergent(input.model_requested, input.model_served),
         first_pass_success: input.first_pass_success ?? null,
         escalated: input.escalated ?? null,
+        escalated_from: input.escalated_from ?? null,
         agent_combo: input.agent_combo ?? [],
         // lean-init additive fields — readers ignore unknowns per audit-log-v1
         init_tokens: input.init_tokens ?? null,
@@ -613,6 +665,15 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         // capsule shadow-measurement — readers ignore unknowns per audit-log-v1
         capsule_emitted: input.capsule_emitted ?? null,
         capsule_entries: input.capsule_entries ?? null,
+        hand_kind: input.hand_kind ?? null,
+        schema_valid: input.schema_valid ?? null,
+        route_billing: input.route_billing ?? null,
+        verified: input.verified ?? null,
+        verify_tokens: input.verify_tokens ?? null,
+        // Derived: an unpaid return nobody verified is read as an escalation,
+        // so skipping the check can never look cheaper than doing it.
+        counts_as_escalation:
+            input.route_billing == null ? null : isUnpaid(input.route_billing) && input.verified === 'skipped',
     };
 
     const line: Record<string, unknown> = {

package/src/scripts/_lib/outcome_vocabularies.ts

@@ -33,13 +33,14 @@
  * `partial`. So: separate vocabularies, one registry, mappings only where
  * execution actually crosses.
  *
- * **Mappings are not written for symmetry.** Two crossings exist, and both are
- * places where execution actually translates: `DispatchOutcome` -> phase in
- * `orchestration_record.ts`, and `LadderAction` -> run in
- * `continuation_ladder.ts` (added 2026-09-03 with the seventh run state, so the
- * state has a producer rather than being a word nothing emits). A total
- * phase<->step<->run mapping would be nine relations of which two are real, and
- * the seven invented ones would read as contract.
+ * **Mappings are not written for symmetry.** One crossing exists, a place where
+ * execution actually translates: `DispatchOutcome` -> phase in
+ * `orchestration_record.ts`. A second, `LadderAction` -> run in
+ * `continuation_ladder.ts`, was added 2026-09-03 with the seventh run state and
+ * removed 2026-10-14 by owner decision together with that module, whose only
+ * caller had been withdrawn on its own kill date. A total phase<->step<->run
+ * mapping would be nine relations of which one is real, and the eight invented
+ * ones would read as contract.
  *
  * `revisit-if`: a producer needs a value its vocabulary cannot express, or a
  * second real crossing appears, or producer analysis shows two of the three
@@ -56,9 +57,14 @@
  * ({@link readRunTerminalState}), a declared downgrade
  * ({@link RUN_TERMINAL_STATE_DOWNGRADE}) and the rollback trigger below.
  *
+ * **Its producer is gone.** The ladder rung that emitted `premise-invalidated`
+ * left the tree on 2026-10-14, so no code writes the value today; it stays in
+ * the vocabulary because documents and persisted records may still carry it, and
+ * the tolerant read below is what keeps an old record readable.
+ *
  * **Rollback trigger, stated rather than instrumented.** Withdraw
- * `premise-invalidated` — remove it from {@link RUN_TERMINAL_STATES} and let the
- * ladder rung report its declared downgrade `blocked` instead — on EITHER of:
+ * `premise-invalidated` — remove it from {@link RUN_TERMINAL_STATES} and let a
+ * reader apply its declared downgrade `blocked` instead — on EITHER of:
  * (1) any consumer is observed failing (a throw, a refused write, a dropped
  * record) on encountering the value, or (2) `readRunTerminalState` returns
  * `null` for a persisted value in normal operation, which would mean a writer
@@ -228,20 +234,6 @@ export const CROSS_DOMAIN_MAPPINGS = [
          */
         semantics_version: 2,
     },
-    {
-        source: 'LadderAction',
-        target: 'run',
-        at: 'src/scripts/_lib/continuation_ladder.ts',
-        fn: 'terminalStateFor',
-        /**
-         * Version 1, and the mapping is TOTAL over `LadderAction` by
-         * construction: `TERMINAL_STATE_BY_ACTION` is a `Record<LadderAction,
-         * RunTerminalState | null>`, so adding a rung without deciding its
-         * terminal state does not compile. `engage` maps to null because it is
-         * the one action that is not terminal.
-         */
-        semantics_version: 1,
-    },
 ] as const;
 
 /** Is this string a phase outcome? The guard the audit-log consumer was missing. */

package/src/scripts/_lib/pin_advice.ts

@@ -0,0 +1,49 @@
+/**
+ * What lies between a project's `agent_config_version` pin and the latest
+ * release, read from the latest release's impact map. It proposes; moving the
+ * pin stays a team decision taken with `agent-config update`.
+ *
+ * Pure: the caller reads the pin and fetches the map. The map is registry input
+ * and untrusted, so an entry that does not parse is reported, never trusted.
+ */
+import { CONSUMER_IMPACT_VALUES } from './consumer_impact';
+import { compare_versions, parse_version } from './version_order';
+
+/** `impactMap` is `undefined` when it could not be fetched and `null` when the release carries none. */
+export function pin_advice_lines(pin: string, latest: string, impactMap: unknown, label: 'latest' | 'target' = 'latest'): string[] {
+    const order = compare_versions(latest, pin);
+    // An unparsable pin or candidate is said, not read as "nothing newer".
+    if (order === null) return [`Pinned at ${pin}; ${label} ${latest} — one of the two is not a version this check can read.`];
+    if (order !== 1) return [];
+    const head = `Pinned at ${pin}; ${label} is ${latest}.`;
+    const tail = 'Moving the pin is a team decision: `agent-config update` rewrites it, this check never does.';
+    if (impactMap === undefined) {
+        return [head, `  The releases in between cannot be read: the impact map of ${latest} could not be fetched.`, tail];
+    }
+    if (impactMap === null || typeof impactMap !== 'object' || Array.isArray(impactMap)) {
+        return [head, `  The releases in between cannot be read: ${latest} carries no impact map.`, tail];
+    }
+    const rows: Array<[string, string]> = [];
+    for (const [version, entry] of Object.entries(impactMap as Record<string, unknown>)) {
+        if (parse_version(version) === null) return [head, `  The impact map is not trustworthy: key '${version}' is not a version.`, tail];
+        if (compare_versions(version, pin) !== 1 || compare_versions(version, latest) === 1) continue;
+        const impact = (entry as Record<string, unknown> | null)?.['impact'];
+        if (!(CONSUMER_IMPACT_VALUES as readonly unknown[]).includes(impact)) {
+            return [head, `  The impact map is not trustworthy: ${version} has impact '${String(impact)}'.`, tail];
+        }
+        const security = (entry as Record<string, unknown>)['security'] === true ? ', security fix' : '';
+        rows.push([version, `${String(impact)}${security}`]);
+    }
+    rows.sort((a, b) => compare_versions(a[0], b[0]) ?? 0);
+    const body = rows.length === 0
+        ? ['  No release in between records a consumer impact.']
+        : rows.map(([v, what]) => `  ${v}  ${what}`);
+    const keys = Object.keys(impactMap as Record<string, unknown>).sort((a, b) => compare_versions(a, b) ?? 0);
+    const first = keys[0];
+    const uncovered = first === undefined
+        ? ['  The impact map is empty; the releases in between are not described.']
+        : compare_versions(pin, first) === -1
+            ? [`  The impact map's first entry is ${first}; releases between ${pin} and it may predate the map.`]
+            : [];
+    return [head, ...body, ...uncovered, tail];
+}

package/src/scripts/_lib/platform_anchor.ts

@@ -1051,3 +1051,225 @@ export function evaluateAnchor(
         evidence,
     };
 }
+
+/**
+ * Where the record of a bypass of the ratification gate lives — the owner's
+ * route of `docs/contracts/ratification-artifact.md` § Emergency use.
+ */
+export const BYPASS_RECORD_DIR = 'agents/evidence/bypass-records';
+
+/** The marker every bypass record carries below its frontmatter. */
+export const BYPASS_RECORD_MARKER = '<!-- evidence-type: bypass-record -->';
+
+/** A review of a restored bypass is overdue this long after `restored_at`. */
+export const BYPASS_REVIEW_DAYS = 7;
+
+/**
+ * `restore_by` may lie at most this long after the bypass. Without a ceiling a
+ * record could set it years ahead and stay open, quietly, for good.
+ */
+export const BYPASS_MAX_OPEN_DAYS = 7;
+
+/** More records than this, or a record larger than this, is read as unreadable. */
+export const BYPASS_RECORD_LIMIT = 200;
+export const BYPASS_RECORD_MAX_BYTES = 64 * 1024;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * A value or a path as it may appear inside a one-line finding: no control,
+ * format, line- or paragraph-separator character, and bounded, so a record's
+ * content or name cannot forge a second line of output.
+ */
+export function printable(value: string): string {
+    const flat = value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, ' ');
+    return flat.length > 200 ? `${flat.slice(0, 197)}...` : flat;
+}
+
+const shown = printable;
+
+/** The nine fields every bypass record carries; `restored_at` and `council_review` may read `pending`. */
+export const BYPASS_RECORD_FIELDS = [
+    'reason',
+    'subject',
+    'time',
+    'commit',
+    'ruleset_version_before',
+    'ruleset_version_after',
+    'restore_by',
+    'restored_at',
+    'council_review',
+] as const;
+
+export type BypassFindingCode =
+    | 'bypass-record-malformed'
+    | 'bypass-record-unreadable'
+    | 'bypass-record-removed'
+    | 'bypass-not-restored'
+    | 'bypass-unreviewed';
+
+export interface BypassFinding {
+    code: BypassFindingCode;
+    path: string;
+    message: string;
+}
+
+/** One record as the caller found it: its text, or `null` when it could not be read. */
+export interface BypassRecordInput {
+    path: string;
+    text: string | null;
+}
+
+const INSTANT_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/u;
+
+/**
+ * An ISO-8601 instant with a timezone, as epoch milliseconds — or `null` when
+ * the text is not one or names a date the calendar does not have. `Date.parse`
+ * alone would roll February 30 into March, so the components are read back.
+ */
+export function bypassInstant(value: string | undefined): number | null {
+    const m = value === undefined ? null : INSTANT_RE.exec(value);
+    if (m === null) {
+        return null;
+    }
+    const ms = Date.parse(value as string);
+    if (Number.isNaN(ms)) {
+        return null;
+    }
+    const zone = m[7] as string;
+    const offset = zone === 'Z' ? 0 : (zone.startsWith('-') ? -1 : 1) * (Number(zone.slice(1, 3)) * 60 + Number(zone.slice(4, 6)));
+    const local = new Date(ms + offset * 60_000);
+    const same =
+        local.getUTCFullYear() === Number(m[1]) &&
+        local.getUTCMonth() + 1 === Number(m[2]) &&
+        local.getUTCDate() === Number(m[3]) &&
+        local.getUTCHours() === Number(m[4]) &&
+        local.getUTCMinutes() === Number(m[5]);
+    return same ? ms : null;
+}
+
+/** The frontmatter's `key: value` lines, or a reason the block is not one. */
+function bypassFields(text: string): Map<string, string> | string {
+    if (!text.startsWith('---\n')) {
+        return 'no frontmatter';
+    }
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) {
+        return 'the frontmatter is not closed';
+    }
+    if (!text.slice(end + 5).split('\n').slice(0, 5).some((l) => l.trim() === BYPASS_RECORD_MARKER)) {
+        return `no \`${BYPASS_RECORD_MARKER}\` marker below the frontmatter`;
+    }
+    const fields = new Map<string, string>();
+    for (const line of text.slice(4, end).split('\n')) {
+        const m = /^([a-z_]+):[ \t]*(.*)$/u.exec(line);
+        if (m === null) {
+            return `unreadable frontmatter line \`${printable(line)}\` — one \`key: value\` per line, nothing else`;
+        }
+        const key = m[1] as string;
+        if (fields.has(key)) {
+            return `field \`${key}\` is recorded more than once`;
+        }
+        fields.set(key, (m[2] as string).trim().replace(/^(["'])(.*)\1$/u, '$2'));
+    }
+    return fields;
+}
+
+/**
+ * The bypass records that leave the route without a closing.
+ *
+ * Read fail-closed: a record that cannot be read, lacks one of the nine
+ * fields, repeats a key, carries an instant that is not a real calendar
+ * instant with a timezone, puts `restore_by` or `restored_at` before the
+ * bypass or `restored_at` after `now`, or names a council review that does not
+ * exist is `bypass-record-malformed` — an unreadable record cannot show it
+ * closed. Of the readable ones: still open at or after `restore_by` is
+ * `bypass-not-restored`; restored with `council_review: pending`
+ * {@link BYPASS_REVIEW_DAYS} days on is `bypass-unreviewed`.
+ *
+ * `reviewCovers` answers whether a `council_review` path names a committed
+ * council review that cites the record's `subject` digest and was first
+ * committed at or after the restore — so neither a review of some other change
+ * nor one written before the fact can close this one. It is injected so this
+ * module stays free of I/O.
+ */
+export function evaluateBypassRecords(
+    records: readonly BypassRecordInput[],
+    now: Date,
+    reviewCovers: (rel: string, subject: string, restoredAtMs: number) => boolean = () => false,
+): BypassFinding[] {
+    const findings: BypassFinding[] = [];
+    const t = now.getTime();
+    const malformed = (p: string, why: string): void => {
+        findings.push({ code: 'bypass-record-malformed', path: p, message: `${p} is not a readable bypass record — ${why}` });
+    };
+    for (const { path: rawPath, text } of records) {
+        const p = printable(rawPath);
+        if (text === null) {
+            findings.push({ code: 'bypass-record-unreadable', path: p, message: `${p} could not be read` });
+            continue;
+        }
+        const f = bypassFields(text);
+        if (typeof f === 'string') {
+            malformed(p, f);
+            continue;
+        }
+        const missing = BYPASS_RECORD_FIELDS.filter(
+            (k) => (f.get(k) ?? '') === '' || (f.get(k) === 'pending' && k !== 'restored_at' && k !== 'council_review'),
+        );
+        const unknown = [...f.keys()].filter((k) => !(BYPASS_RECORD_FIELDS as readonly string[]).includes(k));
+        if (missing.length > 0 || unknown.length > 0) {
+            malformed(
+                p,
+                [missing.length > 0 ? `missing: ${missing.join(', ')}` : '', unknown.length > 0 ? `unknown: ${unknown.join(', ')}` : '']
+                    .filter((s) => s !== '')
+                    .join('; '),
+            );
+            continue;
+        }
+        const time = bypassInstant(f.get('time'));
+        const restoreBy = bypassInstant(f.get('restore_by'));
+        const restoredRaw = f.get('restored_at') as string;
+        const restored = restoredRaw === 'pending' ? null : bypassInstant(restoredRaw);
+        const review = f.get('council_review') as string;
+        const problem = !/^[0-9a-f]{64}$/u.test(f.get('subject') ?? '')
+            ? '`subject` is not a 64-hex digest'
+            : !/^[0-9a-f]{40}$/u.test(f.get('commit') ?? '')
+              ? '`commit` is not a full 40-hex revision'
+              : time === null || restoreBy === null || (restored === null && restoredRaw !== 'pending')
+                ? 'an instant is not ISO-8601 with a timezone, or names a date the calendar does not have'
+                : time > t
+                  ? '`time` is in the future — a bypass not yet taken cannot be recorded'
+                : restoreBy < time || restoreBy - time > BYPASS_MAX_OPEN_DAYS * DAY_MS
+                  ? `\`restore_by\` is before the bypass or more than ${String(BYPASS_MAX_OPEN_DAYS)} days after it`
+                  : restored !== null && (restored < time || restored > t)
+                    ? '`restored_at` is before the bypass or in the future'
+                    : review !== 'pending' && restored === null
+                      ? '`council_review` is named while `restored_at` is pending — the review comes after the restore'
+                      : review !== 'pending' && restored !== null && !reviewCovers(review, f.get('subject') as string, restored)
+                        ? `\`council_review\` names \`${shown(review)}\`, which is not a committed council review citing this record's \`subject\`, first committed at or after \`restored_at\``
+                        : null;
+        if (problem !== null || time === null || restoreBy === null) {
+            malformed(p, problem ?? 'unreadable instant');
+            continue;
+        }
+        if (restored === null) {
+            if (t >= restoreBy) {
+                findings.push({
+                    code: 'bypass-not-restored',
+                    path: p,
+                    message: `${p}: the bypass is at or past \`restore_by\` ${shown(String(f.get('restore_by')))} and records no \`restored_at\``,
+                });
+            }
+            continue;
+        }
+        if (review === 'pending' && t >= restored + BYPASS_REVIEW_DAYS * DAY_MS) {
+            findings.push({
+                code: 'bypass-unreviewed',
+                path: p,
+                message: `${p}: restored ${restoredRaw}, and no council review is recorded ${String(BYPASS_REVIEW_DAYS)} days on`,
+            });
+        }
+    }
+    return findings;
+}

package/src/scripts/_lib/procedure_checks.ts

@@ -0,0 +1,5 @@
+/**
+ * The `check:` exit registry lives with the `/work` engine that runs it; the
+ * lint reads the same registry through this path.
+ */
+export * from '../../agent-src/templates/scripts/work_engine/procedure/checks.js';

package/src/scripts/_lib/project_tree_form.ts

@@ -0,0 +1,134 @@
+/**
+ * Where the PROJECT tree's rule-layer form comes from, now that no settings key
+ * carries it.
+ *
+ * WHY THIS EXISTS. ADR-293 removed `lean_projection.*`, and the shipped
+ * settings template was the last layer of the cascade `resolveLeanProjection`
+ * read — so the project tree on the first host got its `delivery` from a key
+ * that no longer exists. Removing the key with nothing in its place would have
+ * flipped that tree to the full form: a default change for a tree whose form
+ * ADR-267 decided ON EVIDENCE (616/616 byte-equal deliveries, 101/101 labelled
+ * rules reachable, 0 of 212 near-misses fired on the frozen routing-matrix
+ * corpus), with nothing measured against it. That is not a "no worse" move, and
+ * it would also leave Phase 5 with no live arm to compare.
+ *
+ * WHY IT IS NOT THE KEY UNDER ANOTHER NAME. `src/config/project-tree-form.json`
+ * is package-owned and ships in the repository: there is no consumer-writable
+ * layer, no cascade, and no merge. `modeExplicit` stays false for it, exactly as
+ * it did for the template, so nothing here is read as a consumer's consent. And
+ * it carries its own replacement condition rather than a value alone — a row
+ * without the measurement that justifies it is REFUSED, so the file cannot
+ * become a place to write a form someone merely wants.
+ *
+ * PRECEDENCE, WHICH IS THE WHOLE SAFETY ARGUMENT. A valid OBSERVED verdict from
+ * the layer-form decision function supersedes this record for that host, in both
+ * directions — an observed `full` wins over a record saying `delivery`. The
+ * record stands only while that function can answer nothing but
+ * `delivery-unobserved`, which is its state today for every host. Without that
+ * rule this file would be a permanent bypass of the decision function rather
+ * than a stand-in for it, which is the one risk the reviewing seat named.
+ *
+ * WHY ONE SEAT WAS ENOUGH TO BUILD ON, AND NOT ENOUGH TO CLOSE. The choice was
+ * reviewed at a degraded quorum, so step 3.6 stays open and its blocker carries
+ * the confirmation. Acting on it meanwhile is bounded by what the option does:
+ * it changes no behaviour at all — it reproduces what the shipped template
+ * produced — and every alternative did. The record lives with the roadmap.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { DEFAULT_LEAN_PROJECTION_MODE, type LeanProjectionMode } from './lean_projection_mode.js';
+
+export const PROJECT_TREE_FORM_REL = path.join('src', 'config', 'project-tree-form.json');
+
+/** One host's shipped form, with the evidence that justifies it. */
+export interface ProjectTreeForm {
+    readonly form: LeanProjectionMode;
+    readonly basis: string;
+}
+
+/** The shape this module needs from a decision verdict; the full type lives in `layer_form_decision.ts`. */
+export interface FormVerdict {
+    readonly form: 'full' | 'thinned';
+    readonly reason: string;
+}
+
+const FORMS: readonly string[] = ['eager-all', 'thin', 'delivery'];
+
+/**
+ * The reason that means "the function could not look", as opposed to a verdict
+ * it actually reached. Only this one yields to the shipped record.
+ */
+export const UNOBSERVED_REASON = 'delivery-unobserved';
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Every host row the record carries. A row without a `measured` block, or with
+ * a form the projector does not have, is dropped: this file records measured
+ * forms, and a row that records neither is not evidence.
+ */
+export function readProjectTreeForms(packageRoot: string): Map<string, ProjectTreeForm> {
+    const out = new Map<string, ProjectTreeForm>();
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(packageRoot, PROJECT_TREE_FORM_REL), 'utf8'));
+    } catch {
+        return out; // absent or unreadable: every host gets the full form
+    }
+    if (!isRecord(raw) || !isRecord(raw['hosts'])) return out;
+    for (const [host, row] of Object.entries(raw['hosts'])) {
+        if (!isRecord(row)) continue;
+        const form = row['form'];
+        if (typeof form !== 'string' || !FORMS.includes(form)) continue;
+        // At least one measured figure, each a non-empty string: `{}` records no measurement.
+        const measured = row['measured'];
+        if (!isRecord(measured)) continue;
+        const figures = Object.values(measured);
+        if (figures.length === 0 || !figures.every((v) => typeof v === 'string' && v.trim() !== '')) continue;
+        out.set(host, { form: form as LeanProjectionMode, basis: typeof row['basis'] === 'string' ? row['basis'] : 'unrecorded' });
+    }
+    return out;
+}
+
+/**
+ * The form the project tree is built with for `host`.
+ *
+ * `verdict` is the layer-form decision for this host where one exists. An
+ * observed verdict — anything whose reason is not {@link UNOBSERVED_REASON} —
+ * decides, and the record is not consulted. A host with no row and no observed
+ * verdict gets the full form, which is what an absent key always meant.
+ */
+export function projectTreeForm(
+    packageRoot: string,
+    host: string,
+    verdict: FormVerdict | null,
+): LeanProjectionMode {
+    if (verdict !== null && verdict.reason !== UNOBSERVED_REASON) {
+        return verdict.form === 'full' ? DEFAULT_LEAN_PROJECTION_MODE : (readProjectTreeForms(packageRoot).get(host)?.form ?? DEFAULT_LEAN_PROJECTION_MODE);
+    }
+    return readProjectTreeForms(packageRoot).get(host)?.form ?? DEFAULT_LEAN_PROJECTION_MODE;
+}
+
+/**
+ * The `{ mode, hosts }` pair the projector asks for, derived from the record.
+ *
+ * The record is per host, the projector's API is one mode plus the host list it
+ * applies to, and this is the one place the two shapes meet. `mode` is the
+ * strongest form any row carries — `delivery` over `thin` over `eager-all` —
+ * and `hosts` is every row carrying exactly that form. A tree with no record,
+ * or with rows the reader refused, gets the full form and no hosts, which is
+ * what an absent key always meant.
+ */
+export function shippedProjection(packageRoot: string): { mode: LeanProjectionMode; hosts: string[] } {
+    const forms = readProjectTreeForms(packageRoot);
+    const rank: Record<string, number> = { 'eager-all': 0, thin: 1, delivery: 2 };
+    let mode: LeanProjectionMode = DEFAULT_LEAN_PROJECTION_MODE;
+    for (const row of forms.values()) {
+        if ((rank[row.form] ?? 0) > (rank[mode] ?? 0)) mode = row.form;
+    }
+    const hosts = [...forms.entries()].filter(([, row]) => row.form === mode).map(([host]) => host).sort();
+    return { mode, hosts: mode === DEFAULT_LEAN_PROJECTION_MODE ? [] : hosts };
+}