@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/layer_form_corpus.ts

@@ -0,0 +1,165 @@
+/**
+ * The comparison set Phase 5 of `road-to-a-setup-that-decides-itself` reads —
+ * step 0.2, "corpus by reuse".
+ *
+ * WHY A MANIFEST AND NOT A NEW CORPUS. The step forbids authoring one: every
+ * arm must name an artefact the tree already carries, so that the comparison
+ * measures the package's own cases rather than cases written to be passed. The
+ * manifest in `src/config/layer-form-comparison-corpus.json` is therefore a
+ * list of resolvers over existing files, and this module is the one reader of
+ * it.
+ *
+ * ABSENT IS A STATE, NOT A GAP TO FILL WITH SOMETHING NEARBY. Two of the four
+ * sources the step names do not exist: there is no `host-graded` case set in
+ * this tree, and `tests/conformance/` carries a retrieval-envelope validator
+ * rather than adjudicated cases. Each is recorded `absent` with its reason and
+ * the condition that reopens it. Substituting the nearest measurable set would
+ * make the comparison read as if it covered an axis it never touched, which is
+ * the one failure the step's own text rules out.
+ *
+ * THE SEAL IS KEPT BY REFUSAL. The trigger-corpus arm goes through
+ * `loadTrainCases`, which decides the partition from the skill DIRECTORY NAME
+ * and never opens a holdout `evals/triggers.json`. This module adds no second
+ * path to that corpus, so there is nothing here that could reach a sealed file;
+ * `tests/scripts/layer_form_corpus.test.ts` asserts it over the real reads,
+ * with a control that a train corpus was opened at all.
+ *
+ * Pure of network and of clock; reads files and nothing else.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { readConsequenceClass } from './rule_consequence_class.js';
+import { loadTrainCases } from './routing_corpus.js';
+
+export const COMPARISON_CORPUS_REL = path.join('src', 'config', 'layer-form-comparison-corpus.json');
+
+/** A source the tree carries, with the resolver that counts its cases. */
+export interface PresentSource {
+    readonly id: string;
+    readonly state: 'present';
+    readonly resolver: string;
+    readonly path: string;
+    readonly what: string;
+}
+
+/** A source the step names that the tree does not carry. */
+export interface AbsentSource {
+    readonly id: string;
+    readonly state: 'absent';
+    readonly why: string;
+    readonly reopens_when: string;
+}
+
+export type ManifestSource = PresentSource | AbsentSource;
+
+export interface ComparisonManifest {
+    readonly schema_version: number;
+    readonly sources: readonly ManifestSource[];
+}
+
+/** One resolved source: the manifest row plus the cases it resolved to. */
+export type ResolvedSource = ManifestSource & { readonly cases: number };
+
+export interface ComparisonCorpus {
+    readonly sources: readonly ResolvedSource[];
+    /** Cases across every present source. Absent sources contribute nothing. */
+    readonly total: number;
+}
+
+/** Raised when the manifest is missing or is not the shape this module reads. */
+export class ComparisonManifestError extends Error {}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The committed manifest. A malformed one throws rather than resolving to fewer sources. */
+export function readComparisonManifest(repoRoot: string): ComparisonManifest {
+    const file = path.join(repoRoot, COMPARISON_CORPUS_REL);
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (cause) {
+        throw new ComparisonManifestError(`${COMPARISON_CORPUS_REL} is missing or unparseable`, { cause });
+    }
+    if (!isRecord(raw) || !Array.isArray(raw['sources'])) {
+        throw new ComparisonManifestError(`${COMPARISON_CORPUS_REL} carries no \`sources\` array`);
+    }
+    const sources: ManifestSource[] = [];
+    for (const entry of raw['sources'] as unknown[]) {
+        if (!isRecord(entry) || typeof entry['id'] !== 'string') {
+            throw new ComparisonManifestError(`${COMPARISON_CORPUS_REL} carries a source with no \`id\``);
+        }
+        const id = entry['id'];
+        if (entry['state'] === 'present') {
+            if (typeof entry['resolver'] !== 'string' || typeof entry['path'] !== 'string' || typeof entry['what'] !== 'string') {
+                throw new ComparisonManifestError(`present source \`${id}\` is missing \`resolver\`, \`path\` or \`what\``);
+            }
+            sources.push({ id, state: 'present', resolver: entry['resolver'], path: entry['path'], what: entry['what'] });
+            continue;
+        }
+        if (entry['state'] === 'absent') {
+            if (typeof entry['why'] !== 'string' || typeof entry['reopens_when'] !== 'string') {
+                throw new ComparisonManifestError(`absent source \`${id}\` is missing \`why\` or \`reopens_when\``);
+            }
+            sources.push({ id, state: 'absent', why: entry['why'], reopens_when: entry['reopens_when'] });
+            continue;
+        }
+        throw new ComparisonManifestError(`source \`${id}\` carries no \`state\` of \`present\` or \`absent\``);
+    }
+    return { schema_version: typeof raw['schema_version'] === 'number' ? raw['schema_version'] : 0, sources };
+}
+
+/** The ids the manifest records as absent, so a reader of a result can name them. */
+export function absentSources(manifest: ComparisonManifest): string[] {
+    return manifest.sources.filter((s) => s.state === 'absent').map((s) => s.id);
+}
+
+/** Prompts and near-misses in the per-rule routing matrix. */
+function countRoutingMatrix(dir: string): number {
+    if (!fs.existsSync(dir)) return 0;
+    let n = 0;
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!name.endsWith('.yaml')) continue;
+        // A case is one `- prompt:` row; the matrix is flat YAML with no nested prompts.
+        for (const line of fs.readFileSync(path.join(dir, name), 'utf8').split('\n')) {
+            if (/^\s*-\s+prompt:/.test(line)) n += 1;
+        }
+    }
+    return n;
+}
+
+/** Rules that must fire under every input: the consequence class plus the `safety-floor` tier. */
+export function obligationRuleIds(repoRoot: string): Set<string> {
+    const ids = new Set<string>(Object.keys(readConsequenceClass(repoRoot).members));
+    const dir = path.join(repoRoot, 'src', 'rules');
+    if (!fs.existsSync(dir)) return ids;
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!name.endsWith('.md')) continue;
+        const text = fs.readFileSync(path.join(dir, name), 'utf8');
+        const end = text.indexOf('\n---', 3);
+        const head = text.startsWith('---') && end > 0 ? text.slice(0, end) : '';
+        if (/^tier:\s*["']?safety-floor["']?\s*$/m.test(head)) ids.add(name.slice(0, -3));
+    }
+    return ids;
+}
+
+/** Every present source resolved to a case count, in manifest order. */
+export function loadComparisonCorpus(repoRoot: string): ComparisonCorpus {
+    const manifest = readComparisonManifest(repoRoot);
+    const sources = manifest.sources.map((source): ResolvedSource => {
+        if (source.state === 'absent') return { ...source, cases: 0 };
+        switch (source.resolver) {
+            case 'routing-matrix-yaml':
+                return { ...source, cases: countRoutingMatrix(path.join(repoRoot, source.path)) };
+            case 'routing-corpus-train-slice':
+                return { ...source, cases: loadTrainCases(repoRoot).length };
+            case 'obligation-class':
+                return { ...source, cases: obligationRuleIds(repoRoot).size };
+            default:
+                throw new ComparisonManifestError(`source \`${source.id}\` names resolver \`${source.resolver}\`, which this module does not carry`);
+        }
+    });
+    return { sources, total: sources.reduce((sum, s) => sum + s.cases, 0) };
+}

package/src/scripts/_lib/layer_form_decision.ts

@@ -0,0 +1,248 @@
+/**
+ * Which form a rule layer takes on one host and machine — `full` or `thinned` —
+ * computed from evidence, never read from a settings key
+ * (road-to-a-setup-that-decides-itself step 3.1).
+ *
+ * FULL IS THE ANSWER TO EVERY QUESTION THAT IS NOT ANSWERED. `thinned` is
+ * returned only when every condition holds; the first condition that fails
+ * names the reason code, so `doctor` can say why a machine stayed full without a
+ * second reader re-deriving it. The order of the checks is the order of the
+ * reasons below and is part of the contract: a test pins that each condition
+ * failing ALONE yields `full` with its own code.
+ *
+ * NO SETTINGS KEY IS READ HERE, AND NONE MAY BE. The `lean_projection.mode`
+ * module records the failure this exists to remove: a concern read a settings
+ * file that does not exist on a normal install and closed its own gate while
+ * thin stubs were on disk. The caller gathers the evidence; this function only
+ * weighs it, and holds no I/O of its own beyond the brake-table loader.
+ *
+ * ABSENT EVIDENCE IS `full`. The arrival record (step 2.1) and the carrier
+ * probe (road-to-a-hook-carrier-that-is-never-silent step 2.2) are typed here
+ * as the minimum this function needs from them; `layer_form_evidence.ts` reads
+ * both from the machine, and where either is missing the caller passes `null` /
+ * `'unknown'`, so the machine stays on today's full form.
+ *
+ * `deliveryObserved` IS STRICTER THAN THE STEP'S WORDING, DELIBERATELY. The step
+ * asks for "delivery mechanics observed" in `host-injection-effect.json`, but
+ * that record carries one axis, the behavioural effect; it has no mechanics
+ * field. {@link deliveryObservedFor} therefore requires `observed-true`, which
+ * no host carries today. A stricter reading can only keep a machine full, never
+ * thin one that should not be.
+ *
+ * PER RULE, TWO CLASSES ARE NEVER THINNED under any input: the consequence class
+ * (`src/config/rule-consequence-class.json`) and the `safety-floor` tier.
+ * {@link ruleForm} applies that after the layer decision, so a `thinned` layer
+ * still carries those rules in full.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { THINNABLE_HOSTS } from './lean_projection_mode.js';
+import { loadRecord, stateFor, type InjectionRecord } from './injection_effect.js';
+
+export type LayerForm = 'full' | 'thinned';
+
+/** Reason codes, in check order. `all-conditions-hold` is the only `thinned` one. */
+export const FORM_REASONS = [
+    'user-pin',
+    'release-brake',
+    'host-not-thinnable',
+    'delivery-unobserved',
+    'no-arrival-record',
+    'arrival-host-version-mismatch',
+    'arrival-stubs-missing',
+    'arrival-standing-law-missing',
+    'carrier-probe-not-passing',
+    'demoted',
+    'version-skew',
+    'all-conditions-hold',
+] as const;
+export type FormReason = (typeof FORM_REASONS)[number];
+
+/** The minimum the step-2.1 arrival record must supply. Names and booleans only. */
+export interface ArrivalEvidence {
+    readonly hostVersion: string;
+    readonly stubsLoaded: boolean;
+    readonly standingLawsLoaded: boolean;
+}
+
+/** One release-brake row (step 3.4): forces `full`, maintainer-owned, never a consumer surface. */
+export interface ReleaseBrakeRow {
+    readonly host: string;
+    /** Matches this host version exactly. At least one of the two versions is set. */
+    readonly host_version?: string;
+    /** Matches this package version exactly. */
+    readonly package_version?: string;
+    readonly reason: string;
+}
+
+export interface LayerFormInput {
+    /** Package host id, as in {@link THINNABLE_HOSTS}. */
+    readonly host: string;
+    readonly hostVersion: string | null;
+    readonly packageVersion: string;
+    readonly deliveryObserved: boolean;
+    readonly arrival: ArrivalEvidence | null;
+    readonly carrierProbe: 'pass' | 'fail' | 'unknown';
+    readonly demoted: boolean;
+    /** Version of the staged payload and of the layer on disk; both must be known and equal. */
+    readonly payloadVersion: string | null;
+    readonly layerVersion: string | null;
+    readonly brakes: readonly ReleaseBrakeRow[];
+    /** The step-3.5 receipt field written by `install --full`. */
+    readonly userPin: boolean;
+}
+
+export interface LayerFormDecision {
+    readonly form: LayerForm;
+    readonly reason: FormReason;
+}
+
+function full(reason: FormReason): LayerFormDecision {
+    return { form: 'full', reason };
+}
+
+/** True when a brake row covers this host and either its host or its package version. */
+export function brakeApplies(
+    row: ReleaseBrakeRow,
+    host: string,
+    hostVersion: string | null,
+    packageVersion: string,
+): boolean {
+    if (row.host !== host) return false;
+    const byHost = row.host_version !== undefined && hostVersion !== null && row.host_version === hostVersion;
+    const byPackage = row.package_version !== undefined && row.package_version === packageVersion;
+    return byHost || byPackage;
+}
+
+/** Decide the form of one layer. Pure; the first failing condition names the reason. */
+export function decideLayerForm(input: LayerFormInput): LayerFormDecision {
+    if (input.userPin) return full('user-pin');
+    if (input.brakes.some((b) => brakeApplies(b, input.host, input.hostVersion, input.packageVersion))) {
+        return full('release-brake');
+    }
+    if (!THINNABLE_HOSTS.includes(input.host)) return full('host-not-thinnable');
+    if (!input.deliveryObserved) return full('delivery-unobserved');
+    const a = input.arrival;
+    if (a === null) return full('no-arrival-record');
+    if (input.hostVersion === null || a.hostVersion !== input.hostVersion) {
+        return full('arrival-host-version-mismatch');
+    }
+    if (!a.stubsLoaded) return full('arrival-stubs-missing');
+    if (!a.standingLawsLoaded) return full('arrival-standing-law-missing');
+    if (input.carrierProbe !== 'pass') return full('carrier-probe-not-passing');
+    if (input.demoted) return full('demoted');
+    if (input.payloadVersion === null || input.layerVersion === null || input.payloadVersion !== input.layerVersion) {
+        return full('version-skew');
+    }
+    return { form: 'thinned', reason: 'all-conditions-hold' };
+}
+
+/** The rules a thinned layer still carries in full, whatever the layer decision. */
+export interface NeverThinned {
+    readonly consequenceClass: ReadonlySet<string>;
+    readonly safetyFloor: ReadonlySet<string>;
+}
+
+/** Form of one rule inside a decided layer. */
+export function ruleForm(ruleId: string, layer: LayerFormDecision, never: NeverThinned): LayerForm {
+    if (never.consequenceClass.has(ruleId) || never.safetyFloor.has(ruleId)) return 'full';
+    return layer.form;
+}
+
+/**
+ * Host-id spelling of the effect record. The record names the first host
+ * `claude`; the package names it `claude-code`. A host with no mapping is looked
+ * up under its own id and, absent there, reads `unobserved`.
+ */
+const EFFECT_RECORD_KEY: Readonly<Record<string, string>> = { 'claude-code': 'claude' };
+
+export function deliveryObservedFor(rec: InjectionRecord, host: string): boolean {
+    return stateFor(rec, EFFECT_RECORD_KEY[host] ?? host) === 'observed-true';
+}
+
+export const BRAKES_REL = path.join('src', 'config', 'layer-form-brakes.json');
+
+/**
+ * Load the shipped brake table. An unreadable or malformed file yields a single
+ * catch-all row per thinnable host — a brake that cannot be read is a brake that
+ * is ON, because the table exists to force `full` and failing open would invert
+ * it.
+ */
+export function loadBrakes(root: string, packageVersion: string): ReleaseBrakeRow[] {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(root, BRAKES_REL), 'utf-8')) as { rows?: unknown };
+        if (!Array.isArray(raw.rows)) throw new Error('rows is not an array');
+        return raw.rows.map((r: unknown) => {
+            const o = r as Record<string, unknown>;
+            const hv = o['host_version'];
+            const pv = o['package_version'];
+            if (typeof o['host'] !== 'string' || typeof o['reason'] !== 'string') throw new Error('bad row');
+            if (typeof hv !== 'string' && typeof pv !== 'string') throw new Error('row names no version');
+            return {
+                host: o['host'],
+                reason: o['reason'],
+                ...(typeof hv === 'string' ? { host_version: hv } : {}),
+                ...(typeof pv === 'string' ? { package_version: pv } : {}),
+            };
+        });
+    } catch {
+        return THINNABLE_HOSTS.map((host) => ({
+            host,
+            package_version: packageVersion,
+            reason: `${BRAKES_REL} unreadable — brake held on`,
+        }));
+    }
+}
+
+/**
+ * Evidence the shadow run can gather TODAY (step 3.2): the two shipped tables
+ * and the package version. The arrival record, the carrier probe, demotion
+ * state and the layer's own version have no producer yet, so they are passed
+ * as absent — which is why every host reads `full` until those land.
+ */
+export function gatherShippedEvidence(
+    packageRoot: string,
+    packageVersion: string,
+): (host: string) => LayerFormInput {
+    const rec = loadRecord(packageRoot);
+    const brakes = loadBrakes(packageRoot, packageVersion);
+    return (host) => ({
+        host,
+        hostVersion: null,
+        packageVersion,
+        deliveryObserved: deliveryObservedFor(rec, host),
+        arrival: null,
+        carrierProbe: 'unknown',
+        demoted: false,
+        payloadVersion: null,
+        layerVersion: null,
+        brakes,
+        userPin: false,
+    });
+}
+
+/**
+ * The `doctor` record for the shadow decision. SHADOW, NOT ACTION: it computes
+ * and prints `would-be: <form> (<reason>)` per thinnable host and touches no
+ * file — the layer on disk is whatever install wrote, until step 5.3 enables
+ * promotion. Always `ok`: a machine staying full is today's behaviour, not a
+ * fault.
+ */
+export function shadowLayerFormCheck(gather: (host: string) => LayerFormInput): {
+    id: string;
+    status: 'ok';
+    message: string;
+    remedy: string;
+} {
+    const parts = THINNABLE_HOSTS.map((host) => {
+        const d = decideLayerForm(gather(host));
+        return `${host} would-be: ${d.form} (${d.reason})`;
+    });
+    return {
+        id: 'layer-form',
+        status: 'ok',
+        message: `shadow decision, nothing on disk changed — ${parts.join(' · ')}`,
+        remedy: '',
+    };
+}

package/src/scripts/_lib/layer_form_evidence.ts

@@ -0,0 +1,112 @@
+/**
+ * The machine half of the layer-form evidence, and the declaration `doctor`
+ * prints from it.
+ *
+ * {@link gatherShippedEvidence} reads the two shipped tables; this adds what
+ * only the machine knows: the last arrival record, the carrier probe and
+ * demotion state under `<machine root>/runtime/`, and the `install --full` pin.
+ * The arrival record and carrier state describe the claude layer only, so they
+ * feed `claude-code` alone; the pin covers every host, because it is a brake on
+ * the machine.
+ *
+ * The current host version is read from the environment the host exposes to
+ * its hooks. A `doctor` run from a plain terminal has none, so there the
+ * decision reads a version mismatch and stays full — a terminal is not the
+ * launch context the record was taken in, which is the point of comparing them.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { readCarrierState, runtimeRootFor, type CarrierState } from '../../install/stagedRuntime.js';
+import { readUserPin } from '../../install/userPin.js';
+import { arrivalEvidence, arrivalsDirUnder, latestArrivalRecord, readObserverLines, type ArrivalRecord } from './arrival_record.js';
+import { hostVersionFromEnv } from './instructions_loaded_classify.js';
+import { THINNABLE_HOSTS } from './lean_projection_mode.js';
+import { decideLayerForm, gatherShippedEvidence, type LayerFormDecision, type LayerFormInput } from './layer_form_decision.js';
+import { readConsequenceClass } from './rule_consequence_class.js';
+
+export interface MachineEvidence {
+    readonly arrival: ArrivalRecord | null;
+    readonly carrier: CarrierState;
+    readonly userPin: boolean;
+    readonly hostVersion: string | null;
+    readonly standingLaws: ReadonlySet<string>;
+}
+
+export function readMachineEvidence(packageRoot: string, env: NodeJS.ProcessEnv = process.env): MachineEvidence {
+    const runtimeRoot = runtimeRootFor(env);
+    let standingLaws: ReadonlySet<string> = new Set();
+    try {
+        standingLaws = new Set(Object.keys(readConsequenceClass(packageRoot).members));
+    } catch {
+        // A sentinel no rule file can be named, so an unreadable class can never read as "every law loaded".
+        standingLaws = new Set(['<consequence-class unreadable>']);
+    }
+    return {
+        arrival: latestArrivalRecord(readObserverLines(arrivalsDirUnder(runtimeRoot))),
+        carrier: readCarrierState(runtimeRoot),
+        userPin: readUserPin(runtimeRoot) !== null,
+        hostVersion: hostVersionFromEnv(env),
+        standingLaws,
+    };
+}
+
+/** Overlay the machine evidence onto one host's shipped input. */
+export function withMachineEvidence(shipped: LayerFormInput, m: MachineEvidence): LayerFormInput {
+    const base = { ...shipped, userPin: m.userPin };
+    if (shipped.host !== 'claude-code') return base;
+    const probe = m.carrier.probe;
+    return {
+        ...base,
+        hostVersion: m.hostVersion,
+        arrival: arrivalEvidence(m.arrival, m.standingLaws),
+        carrierProbe: probe === null ? 'unknown' : probe.outcome === 'reached' ? 'pass' : 'fail',
+        demoted: m.carrier.layer === 'demoted',
+    };
+}
+
+export interface HostDeclaration {
+    readonly host: string;
+    readonly decision: LayerFormDecision;
+}
+
+/**
+ * The step-3.7 declaration: per host the shadow form and its reason code, then
+ * the last arrival record and the claude layer's state on disk.
+ */
+export function declareLayerForm(decisions: readonly HostDeclaration[], m: MachineEvidence): string[] {
+    const lines = decisions.map((d) => `${d.host} would-be: ${d.decision.form} (${d.decision.reason})`);
+    const a = m.arrival;
+    lines.push(
+        a === null
+            ? 'last arrival record: none — the InstructionsLoaded observer has not seen a session on this machine'
+            : `last arrival record: session ${a.session}, host version ${a.host_version ?? 'unknown'}, ${a.status}${a.unknown_reason ? ` (${a.unknown_reason})` : ''}`,
+    );
+    lines.push(`claude layer on disk: ${m.carrier.layer}${m.userPin ? ' · pinned full by install --full' : ''}`);
+    return lines;
+}
+
+/** The doctor entry point: shipped tables plus machine evidence, at the installed package's version. */
+export function layerFormDoctorCheck(packageRoot: string, env: NodeJS.ProcessEnv = process.env): {
+    id: string;
+    status: 'ok';
+    message: string;
+    remedy: string;
+} {
+    let version = 'unknown';
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')) as { version?: unknown };
+        if (typeof raw.version === 'string' && raw.version.trim()) version = raw.version.trim();
+    } catch {
+        // An unreadable package.json leaves the version unknown; no package-version brake row can match it.
+    }
+    const shipped = gatherShippedEvidence(packageRoot, version);
+    const m = readMachineEvidence(packageRoot, env);
+    const decisions = THINNABLE_HOSTS.map((host) => ({ host, decision: decideLayerForm(withMachineEvidence(shipped(host), m)) }));
+    return {
+        id: 'layer-form',
+        status: 'ok',
+        message: `shadow decision, nothing on disk changed — ${declareLayerForm(decisions, m).join(' · ')}`,
+        remedy: '',
+    };
+}