create-agent-rig 0.7.1 → 0.9.0

package/packages/cli/dist/index.js

@@ -2,13 +2,16 @@
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
+import { execFileRunner, setupSubsystems } from './commands/setup.js';
 import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
 import { readManifest } from './lib/manifest.js';
+import { SubsystemsError, refreshSubsystems, subsystemsManifestPath } from './lib/subsystems.js';
 import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
-import { packageVersion } from './lib/version.js';
+import { packageVersion, rigHandshake } from './lib/version.js';
+import { runMemory } from './commands/memory.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
 Scaffolds a new project into <dir>: a Claude Code + Codex agent operating system
@@ -20,7 +23,8 @@ Options
                     required when not a terminal — default: ${DEFAULT_TARGET})
   --no-git          skip git init + the pristine-template baseline commit
   --no-color        plain output (NO_COLOR is respected too)
-  --version         print the version
+  --version         print the version (--version --json: the contract handshake,
+                    one JSON object with the name, version and contract version)
   -h, --help        this text
 
 Also: create-agent-rig init [--dry-run]
@@ -32,7 +36,68 @@ Also: create-agent-rig init [--dry-run]
 
 Also: create-agent-rig upgrade [--dry-run] [--yes]
   Bring the rig in the CURRENT repo up to this version. Replaces the files it
-  installed and you did not touch; everything else is reported, never merged.`;
+  installed and you did not touch; everything else is reported, never merged.
+  Re-runs the subsystem manifest derivation when one exists (see setup).
+
+Also: create-agent-rig setup --memory-root <checkout> [--memory-ref <sha>] [--dry-run]
+  Record the Memory executable in this machine's subsystem manifest
+  (~/.config/create-agent-rig/subsystems.json; %APPDATA% on Windows) from the
+  one declared root. Performs the --version --json handshake first and refuses
+  a foreign contract major with exit 4 before writing anything.
+
+Also: create-agent-rig memory <doctor|load> [args…]
+  Run a Memory verb through the registered executable: the --version --json
+  handshake first (a foreign contract major exits 4 and the verb never runs),
+  then the verb and its arguments verbatim, Memory's answer passed through
+  unchanged. No manifest answers unsupported/absent (exit 0); an invalid
+  invocation exits 2.`;
+async function runSetup(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: {
+                'memory-root': { type: 'string' },
+                'memory-ref': { type: 'string' },
+                'dry-run': { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const memoryRoot = values['memory-root'];
+    if (memoryRoot === undefined) {
+        process.stderr.write(`setup needs --memory-root <checkout>\n\n${USAGE}\n`);
+        return 1;
+    }
+    try {
+        const result = await setupSubsystems({
+            memoryRoot,
+            memoryRef: values['memory-ref'] ?? null,
+            dryRun: values['dry-run'] === true,
+        });
+        if (result.outcome === 'refused') {
+            process.stderr.write(`Memory handshake: ${JSON.stringify(result.handshake)}\n`);
+            return result.exitCode;
+        }
+        process.stdout.write(`Memory handshake: ${JSON.stringify(result.handshake)}\n` +
+            (result.outcome === 'dry-run'
+                ? `Dry run — nothing written (would write ${result.file}).\n`
+                : `Wrote ${result.file}\n`));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError) {
+            process.stderr.write(`setup: ${error.message} (${error.code})\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
 async function runInit(rawArgs) {
     let values;
     try {
@@ -219,15 +284,47 @@ async function runUpgrade(rawArgs) {
     }
     const result = await applyUpgrade(cwd, plan);
     process.stdout.write(`\nWrote ${result.written.length} files.\n`);
+    // The subsystem manifest is machine-scoped and written by `setup`; an
+    // upgrade re-runs the same derivation so `installedVersion` follows the
+    // executable the root now holds. It is never part of the rig manifest or of
+    // `result.written` — that file list is the repository's, this one is the
+    // user's. Absent stays absent: creating it is `setup`'s act.
+    try {
+        const refreshed = await refreshSubsystems({
+            file: subsystemsManifestPath(process.env, process.platform),
+            run: execFileRunner,
+            nodeExecutable: process.execPath,
+            platform: process.platform,
+        });
+        if (refreshed !== 'absent')
+            process.stdout.write(`Subsystem manifest: ${typeof refreshed === 'string' ? refreshed : JSON.stringify(refreshed)}\n`);
+    }
+    catch (error) {
+        if (!(error instanceof SubsystemsError))
+            throw error;
+        process.stdout.write(`Subsystem manifest: not refreshed — ${error.message} (${error.code})\n`);
+    }
     return 0;
 }
 async function main() {
     if (process.argv[2] === 'init') {
         return runInit(process.argv.slice(3));
     }
+    if (process.argv[2] === 'setup') {
+        return runSetup(process.argv.slice(3));
+    }
     if (process.argv[2] === 'upgrade') {
         return runUpgrade(process.argv.slice(3));
     }
+    if (process.argv[2] === 'memory') {
+        // The consumer path of the RP-19 handshake: manifest → `--version --json`
+        // → exit 4 on a foreign major → doctor/load passed through verbatim.
+        const [verb = '', ...args] = process.argv.slice(3);
+        const result = await runMemory({ verb, args });
+        process.stdout.write(result.stdout);
+        process.stderr.write(result.stderr);
+        return result.exitCode;
+    }
     let positionals;
     let values;
     try {
@@ -237,6 +334,9 @@ async function main() {
                 help: { type: 'boolean', short: 'h' },
                 target: { type: 'string' },
                 version: { type: 'boolean' },
+                // `--json` is read on `--version` alone: the handshake object of
+                // docs/command-contract.md, one JSON line and nothing else on stdout.
+                json: { type: 'boolean' },
                 'no-git': { type: 'boolean' },
                 'no-color': { type: 'boolean' },
             },
@@ -248,6 +348,10 @@ async function main() {
         return 1;
     }
     if (values.version) {
+        if (values.json) {
+            process.stdout.write(`${JSON.stringify(await rigHandshake())}\n`);
+            return 0;
+        }
         process.stdout.write(`${await packageVersion()}\n`);
         return 0;
     }

package/packages/cli/dist/lib/subsystems.js

@@ -0,0 +1,269 @@
+// The machine-scoped subsystem manifest (ADR-RP-002 R6, RP-147): installation
+// metadata, not a service registry. One writer (`setup`; `upgrade` re-runs the
+// same derivation), one scope (the user's configuration root), one entry per
+// subsystem carrying the resolved executable invocation and the contract major
+// it must answer. No search path, no fallback chain, no PATH scan: the
+// executable is derived from the one root the owner declared, and every
+// substantive call performs the `--version --json` handshake first.
+//
+// Handshake results carry no path — a status is machine JSON a consumer may
+// print, and the manifest itself is the only place a location is written.
+import { statSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+export const SUBSYSTEMS_SCHEMA_VERSION = 1;
+export const MEMORY_CONTRACT_MAJOR = 1;
+const MEMORY_EXECUTABLE_REL = ['shared-memory', 'memory.mjs'];
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+export class SubsystemsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SubsystemsError';
+        this.code = code;
+    }
+}
+/**
+ * Exactly one location per platform. An unset root is refused, not guessed:
+ * a manifest written under a guessed home is a manifest nothing else reads.
+ */
+export function subsystemsManifestPath(env, platform) {
+    if (platform === 'win32') {
+        const root = env.APPDATA;
+        if (!root)
+            throw new SubsystemsError('config-root-unavailable', 'APPDATA is not set');
+        return path.join(root, 'create-agent-rig', 'subsystems.json');
+    }
+    const home = env.HOME;
+    if (!home)
+        throw new SubsystemsError('config-root-unavailable', 'HOME is not set');
+    return path.join(home, '.config', 'create-agent-rig', 'subsystems.json');
+}
+/** The path module of the DECLARED platform, so an entry's encoding is pinned by the platform argument, not by the host. */
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+export function memoryExecutablePath(memoryRoot, platform) {
+    return pathFor(platform).join(memoryRoot, ...MEMORY_EXECUTABLE_REL);
+}
+/**
+ * The pure half of the derivation: root → invocation, in the declared
+ * platform's encoding. The root is the single declared input
+ * (`setup --memory-root`), so it must be absolute under that platform — a
+ * relative root would make the entry mean a different executable from every
+ * working directory. No filesystem here, so both encodings are pinned by tests
+ * on any host.
+ */
+export function memoryInvocation(input, platform) {
+    if (!pathFor(platform).isAbsolute(input.memoryRoot))
+        throw new SubsystemsError('memory-root-relative', 'the Memory root must be an absolute path');
+    return [input.nodeExecutable, memoryExecutablePath(input.memoryRoot, platform)];
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The whole derivation: the invocation above, plus the check that the
+ * executable is already there on this host — the manifest records what
+ * exists, it does not promise what an install will bring. So `platform` is
+ * the host's here; the pure half is what a foreign platform's encoding is
+ * tested through.
+ */
+export function deriveMemoryEntry(input, platform) {
+    const invocation = memoryInvocation(input, platform);
+    if (!isFile(invocation[1]))
+        throw new SubsystemsError('memory-executable-absent', `no ${MEMORY_EXECUTABLE_REL.join('/')} under the declared Memory root`);
+    return {
+        memoryRoot: input.memoryRoot,
+        invocation,
+        contractMajor: MEMORY_CONTRACT_MAJOR,
+        memoryRef: input.memoryRef,
+        installedVersion: input.installedVersion,
+    };
+}
+const majorOf = (contractVersion) => {
+    const match = /^(\d+)\.\d+$/.exec(contractVersion);
+    return match ? Number(match[1]) : null;
+};
+/**
+ * `--version --json` and its classification. The consumer compares the
+ * contract major alone; a foreign major is the consumer's refusal (exit 4 in
+ * `setup`), never something Memory emits. A failure payload is
+ * INTEGRATION-FAILED, never absence: the executable answered.
+ */
+export async function handshake(entry, run, options = {}) {
+    const [file, script] = entry.invocation;
+    // Absence is the runner's answer (ENOENT), not a pre-check: the executable
+    // the manifest names is exactly what this call must exercise.
+    const result = await run(file, [script, '--version', '--json'], {
+        timeoutMs: options.timeoutMs ?? HANDSHAKE_TIMEOUT_MS,
+    });
+    if (result.spawnError) {
+        if (result.spawnError.code === 'ENOENT')
+            return { status: 'unsupported', reason: 'absent' };
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(result.stdout);
+    }
+    catch {
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    }
+    if (typeof payload !== 'object' || payload === null)
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    const record = payload;
+    // The executable answered, and answered a failure — a broken VERSION file is
+    // the Memory-side shape (RP-19). The manifest's promise about what is
+    // installed no longer holds, so this is `manifest-stale`, never absence.
+    if (result.code !== 0 || record.result === 'integration-failed')
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    const { name, version, contractVersion } = record;
+    if (typeof version !== 'string' || typeof contractVersion !== 'string')
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    if (name !== 'memory')
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    const major = majorOf(contractVersion);
+    if (major === null)
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    if (major !== MEMORY_CONTRACT_MAJOR)
+        return { status: 'foreign-major', contractVersion, requiredMajor: MEMORY_CONTRACT_MAJOR };
+    return { status: 'ok', version, contractVersion };
+}
+/** Stable bytes: fixed key order, two-space indent, trailing newline. */
+export function serializeSubsystemsManifest(manifest) {
+    const memory = manifest.entries.memory;
+    const ordered = {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: {
+            memory: {
+                memoryRoot: memory.memoryRoot,
+                invocation: [memory.invocation[0], memory.invocation[1]],
+                contractMajor: MEMORY_CONTRACT_MAJOR,
+                memoryRef: memory.memoryRef,
+                installedVersion: memory.installedVersion,
+            },
+        },
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+const isString = (value) => typeof value === 'string';
+export function parseSubsystemsManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const root = parsed;
+    if (root.schemaVersion !== SUBSYSTEMS_SCHEMA_VERSION)
+        return null;
+    const entries = root.entries;
+    if (typeof entries !== 'object' || entries === null)
+        return null;
+    const memory = entries.memory;
+    if (typeof memory !== 'object' || memory === null)
+        return null;
+    const m = memory;
+    const invocation = m.invocation;
+    if (!isString(m.memoryRoot) ||
+        !Array.isArray(invocation) ||
+        invocation.length !== 2 ||
+        !invocation.every(isString) ||
+        m.contractMajor !== MEMORY_CONTRACT_MAJOR ||
+        !(m.memoryRef === null || isString(m.memoryRef)) ||
+        !isString(m.installedVersion))
+        return null;
+    return {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: {
+            memory: {
+                memoryRoot: m.memoryRoot,
+                // `every(isString)` above proved both elements are strings, but
+                // Array.prototype.every does not narrow a tuple's element type.
+                invocation: [invocation[0], invocation[1]],
+                contractMajor: MEMORY_CONTRACT_MAJOR,
+                // Checked above as `null` or a string; the `||` chain does not narrow `m.memoryRef`.
+                memoryRef: m.memoryRef,
+                installedVersion: m.installedVersion,
+            },
+        },
+    };
+}
+/** `null` when absent — no evidence; a present file that does not parse is an error, not silence. */
+export async function readSubsystemsManifest(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new SubsystemsError('manifest-unreadable', `cannot read ${path.basename(file)}`);
+    }
+    const manifest = parseSubsystemsManifest(text);
+    if (manifest === null)
+        throw new SubsystemsError('manifest-unreadable', `${path.basename(file)} is not a schemaVersion ${SUBSYSTEMS_SCHEMA_VERSION} subsystem manifest`);
+    return manifest;
+}
+/**
+ * Atomic and idempotent: the bytes land in a sibling temp file and are renamed
+ * over the target, so a reader never sees a torn manifest and a re-run of the
+ * same derivation produces no diff of its own.
+ */
+export async function writeSubsystemsManifest(file, manifest) {
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true });
+    const temp = path.join(dir, `.${path.basename(file)}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`);
+    try {
+        await writeFile(temp, serializeSubsystemsManifest(manifest));
+        await rename(temp, file);
+    }
+    catch (error) {
+        // See packages/cli/test/subsystems.test.ts › "removes its temp file and
+        // rethrows when the rename is refused".
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+/**
+ * What `upgrade` re-runs: the same derivation from the recorded root, the same
+ * handshake, and a rewrite only when the handshake is ok. A manifest that is
+ * absent is left absent (`setup` is the one writer that creates it); one whose
+ * executable no longer answers is left untouched and the result says why.
+ */
+export async function refreshSubsystems(options) {
+    const manifest = await readSubsystemsManifest(options.file);
+    if (manifest === null)
+        return 'absent';
+    const previous = manifest.entries.memory;
+    let entry;
+    try {
+        entry = deriveMemoryEntry({
+            memoryRoot: previous.memoryRoot,
+            nodeExecutable: options.nodeExecutable,
+            memoryRef: previous.memoryRef,
+            installedVersion: previous.installedVersion,
+        }, options.platform);
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError && error.code === 'memory-executable-absent')
+            return { status: 'unsupported', reason: 'absent' };
+        throw error;
+    }
+    const result = await handshake(entry, options.run);
+    if (result.status !== 'ok')
+        return result;
+    await writeSubsystemsManifest(options.file, {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: { memory: { ...entry, installedVersion: result.version } },
+    });
+    return 'refreshed';
+}

package/packages/cli/dist/lib/version.js

@@ -13,3 +13,18 @@ export async function packageVersion() {
     const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
     return pkg.version;
 }
+/**
+ * The version of the command contract (`docs/command-contract.md`) this rig
+ * implements. Independent of the package version: many releases ship against
+ * one contract, and a consumer compares this field's major alone.
+ */
+export const RIG_CONTRACT_VERSION = '1.0';
+/** What `--version --json` answers — the handshake object of the contract. */
+export async function rigHandshake() {
+    return {
+        schemaVersion: 1,
+        name: 'create-agent-rig',
+        version: await packageVersion(),
+        contractVersion: RIG_CONTRACT_VERSION,
+    };
+}

package/packages/cli/dist/policy/benchmark/corpus.js

@@ -0,0 +1,165 @@
+import { CAPABILITY_STATES } from '../core/vocabulary.js';
+export const BENCHMARK_CLASSIFICATIONS = Object.freeze([
+    'equivalent',
+    'intentional-degradation',
+    'unsupported',
+]);
+const MEASUREMENT_KINDS = Object.freeze([
+    'capability-probe',
+    'guard-enforcement',
+    'compatibility-rejection',
+]);
+const REQUIRED_SCENARIO_IDS = [
+    'real-wiring',
+    'unwired-enforcement',
+    'disabled-enforcement',
+    'narrowed-enforcement',
+    'bypassed-enforcement',
+    'unreadable-input',
+    'hook-input',
+    'protected-rulebook',
+    'widening',
+    'foreign-major',
+];
+const requiredScenarioIds = new Set(REQUIRED_SCENARIO_IDS);
+const scenario = (id, fixture, mutation, action, measurementKind, expectedStates) => Object.freeze({
+    id,
+    fixture,
+    mutation,
+    action,
+    measurementKind,
+    expectedStates: Object.freeze([...expectedStates]),
+});
+export const BENCHMARK_CORPUS = Object.freeze({
+    contractMajor: 1,
+    scenarios: Object.freeze([
+        scenario('real-wiring', 'universal-rig', 'none', 'exercise protected write', 'capability-probe', ['SUPPORTED']),
+        scenario('unwired-enforcement', 'universal-rig', 'remove hook registration', 'exercise protected write', 'capability-probe', ['UNSUPPORTED']),
+        scenario('disabled-enforcement', 'universal-rig', 'disable all hooks', 'exercise protected write', 'capability-probe', ['UNSUPPORTED']),
+        scenario('narrowed-enforcement', 'universal-rig', 'narrow matcher', 'exercise omitted protected write', 'capability-probe', ['DEGRADED']),
+        scenario('bypassed-enforcement', 'universal-rig', 'bypass guard command', 'exercise protected write', 'capability-probe', ['INTEGRATION-FAILED']),
+        scenario('unreadable-input', 'universal-rig', 'make snapshot unreadable', 'exercise protected write', 'capability-probe', ['INTEGRATION-FAILED']),
+        scenario('hook-input', 'universal-rig', 'make tool_input unreadable', 'exercise protected write', 'guard-enforcement', ['SUPPORTED']),
+        scenario('protected-rulebook', 'universal-rig', 'none', 'edit protected rulebook', 'guard-enforcement', ['SUPPORTED']),
+        scenario('widening', 'universal-rig', 'widen authorization allow-list', 'attempt unauthorized widening', 'guard-enforcement', ['SUPPORTED']),
+        scenario('foreign-major', 'contracts/session-messaging/v1/fixtures/negative/envelope-foreign-major.json', 'foreign schema major', 'check policy compatibility', 'compatibility-rejection', ['UNSUPPORTED']),
+    ]),
+});
+const canonicalScenarios = new Map(BENCHMARK_CORPUS.scenarios.map((entry) => [entry.id, entry]));
+export const classifyCapability = (state) => {
+    switch (state) {
+        case 'SUPPORTED':
+            return { classification: 'equivalent', integrationFailed: false };
+        case 'DEGRADED':
+            return { classification: 'intentional-degradation', integrationFailed: false };
+        case 'UNSUPPORTED':
+            return { classification: 'unsupported', integrationFailed: false };
+        case 'INTEGRATION-FAILED':
+            return { classification: 'unsupported', integrationFailed: true };
+        default:
+            throw new Error(`Unknown capability state: ${String(state)}`);
+    }
+};
+const isOwnDataRecord = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    return Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => descriptor.enumerable === true && 'value' in descriptor);
+};
+const isDataArray = (value) => {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === undefined || descriptor.enumerable !== true || !('value' in descriptor))
+            return false;
+    }
+    return true;
+};
+const hasOnlyKeys = (value, keys) => {
+    const actual = Object.keys(value);
+    return actual.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+};
+const nonBlank = (value) => typeof value === 'string' && value.trim() !== '';
+const invalidCorpus = (reason) => {
+    throw new Error(`Invalid benchmark corpus: ${reason}`);
+};
+export const parseBenchmarkCorpus = (input) => {
+    if (!isOwnDataRecord(input) || !hasOnlyKeys(input, ['contractMajor', 'scenarios'])) {
+        return invalidCorpus('must be a plain corpus with contractMajor and scenarios');
+    }
+    if (input.contractMajor !== 1)
+        return invalidCorpus('unsupported contract major; expected 1');
+    if (!isDataArray(input.scenarios))
+        return invalidCorpus('scenarios must be a data array');
+    if (input.scenarios.length !== REQUIRED_SCENARIO_IDS.length) {
+        return invalidCorpus('must include every required scenario exactly once');
+    }
+    const ids = new Set();
+    const scenarios = [];
+    for (const value of input.scenarios) {
+        if (!isOwnDataRecord(value) ||
+            !hasOnlyKeys(value, [
+                'id',
+                'fixture',
+                'mutation',
+                'action',
+                'measurementKind',
+                'expectedStates',
+            ])) {
+            return invalidCorpus('each scenario must have only id, fixture, mutation, action, measurementKind, and expectedStates');
+        }
+        const { id, fixture, mutation, action, measurementKind, expectedStates } = value;
+        if (!nonBlank(id) || !requiredScenarioIds.has(id))
+            return invalidCorpus(`unknown scenario ${String(id)}`);
+        if (ids.has(id))
+            return invalidCorpus(`scenario ${id} is duplicated`);
+        if (!nonBlank(fixture) || !nonBlank(mutation) || !nonBlank(action)) {
+            return invalidCorpus(`scenario ${id} has empty metadata`);
+        }
+        if (typeof measurementKind !== 'string' ||
+            !MEASUREMENT_KINDS.includes(measurementKind)) {
+            return invalidCorpus(`scenario ${id} has an unknown measurement kind`);
+        }
+        if (!isDataArray(expectedStates) || expectedStates.length === 0) {
+            return invalidCorpus(`scenario ${id} must name expected capability states`);
+        }
+        const states = new Set();
+        for (const expectedState of expectedStates) {
+            if (typeof expectedState !== 'string' ||
+                !CAPABILITY_STATES.includes(expectedState)) {
+                return invalidCorpus(`scenario ${id} has an unknown capability state`);
+            }
+            if (states.has(expectedState))
+                return invalidCorpus(`scenario ${id} repeats a capability state`);
+            states.add(expectedState);
+        }
+        const canonical = canonicalScenarios.get(id);
+        if (fixture !== canonical.fixture ||
+            mutation !== canonical.mutation ||
+            action !== canonical.action ||
+            measurementKind !== canonical.measurementKind) {
+            return invalidCorpus(`scenario ${id} changes its canonical metadata`);
+        }
+        if (expectedStates.length !== canonical.expectedStates.length ||
+            expectedStates.some((state, index) => state !== canonical.expectedStates[index])) {
+            return invalidCorpus(`scenario ${id} changes its expected capability states`);
+        }
+        ids.add(id);
+        scenarios.push(Object.freeze({
+            id,
+            fixture,
+            mutation,
+            action,
+            measurementKind: measurementKind,
+            expectedStates: Object.freeze([...states]),
+        }));
+    }
+    for (const id of REQUIRED_SCENARIO_IDS) {
+        if (!ids.has(id))
+            return invalidCorpus(`required scenario ${id} is missing`);
+    }
+    return Object.freeze({ contractMajor: 1, scenarios: Object.freeze(scenarios) });
+};

package/packages/cli/dist/policy/core/adapter.js

@@ -0,0 +1,18 @@
+/**
+ * The contract a harness adapter satisfies (RP-76).
+ *
+ * The core knows that a harness exists and has a hook-wiring surface; it does
+ * not know any harness's name, event vocabulary, tool names or paths. Those
+ * belong to the adapter, one module per harness under `../harness/`, and
+ * adding a harness means adding one such module and registering it — pinned in
+ * `test/template/policy-declaration.test.ts` under "adding a harness touches
+ * adapters only", whose two tests name exactly the files that may mention each
+ * harness. Their names carry the harness words this file may not, which is why
+ * the describe is cited here rather than either test.
+ *
+ * An adapter is a mapping, not a compiler: given a declaration it names the
+ * event, matcher and hook path the harness wires for it. The correspondence
+ * between that answer and the snapshot the rig actually ships is a test, in
+ * both directions, in the same file.
+ */
+export {};