@starci/skills 1.1.0

package/scripts/validate-operator.mjs

@@ -0,0 +1,125 @@
+// An operator.md package is closed when its own tables agree with each other, with the stop-code
+// registry, with the kind contracts, and with its Vietnamese mirror: Params ↔ Requirements, Steps ↔
+// Stops ↔ errors registry, Writes ↔ Outputs ↔ templates/kinds, Inputs ↔ templates/kinds, nested
+// exchanges ↔ a waiting step, en ↔ vi.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { loadOperatorPackages, cellCodes, cellParams, cellFiles, kindOf, isYes, exchangeOf } from './operator-md.mjs';
+import { loadErrorsRegistry } from './errors-registry.mjs';
+import { loadKindTemplates } from './validate-templates.mjs';
+
+const unquote = (s) => String(s ?? '').trim().replace(/^`|`$/g, '');
+const TABLES = ['context', 'inputs', 'requirements', 'steps', 'outputs', 'stops', 'next'];
+
+export async function validateOperators(root) {
+  const errors = [];
+  const packages = await loadOperatorPackages(root);
+  const registry = await loadErrorsRegistry(root);
+  errors.push(...registry.errors);
+  const kinds = await loadKindTemplates(root);
+  const ids = new Set(packages.map((p) => p.manifest.id));
+  let checked = 0;
+  for (const pkg of packages.filter((p) => p.shape === 'v9')) {
+    checked += 1;
+    const id = pkg.manifest.id;
+    const at = `operators/${pkg.name}/operator.md`;
+    const op = pkg.en;
+    if (op.id !== id) errors.push(`${at}: title ${op.id} must equal operator.json id ${id}`);
+    for (const key of TABLES) if (!op.tables[key]) errors.push(`${at}: no ${key} table`);
+    if (TABLES.some((k) => !op.tables[k])) continue;
+    for (const legacy of ['context.md', 'input.md', 'execute.md', 'output.md', 'input.schema.json', 'output.schema.json', 'validate-input.mjs', 'validate-output.mjs', 'validation.mjs']) {
+      if (existsSync(path.join(pkg.dir, legacy))) errors.push(`operators/${pkg.name}/${legacy}: an operator.md package carries no ${legacy}`);
+    }
+    for (const needed of ['validate.mjs', 'self-test.mjs']) if (!existsSync(path.join(pkg.dir, needed))) errors.push(`operators/${pkg.name}/${needed}: missing`);
+
+    // Params ↔ Requirements.
+    const fields = new Map(op.tables.requirements.rows.map((r) => [unquote(r.field), r]));
+    const usedFields = new Set();
+    for (const s of op.tables.steps.rows) for (const p of cellParams(s.params)) { usedFields.add(p); if (!fields.has(p)) errors.push(`${at}:${s._line}: step ${s.n} reads param ${p}, which Requirements does not declare`); }
+    for (const [f, r] of fields) if (!usedFields.has(f)) errors.push(`${at}:${r._line}: requirement ${f} is read by no step`);
+
+    // Steps ↔ Stops ↔ registry.
+    const stops = new Map(op.tables.stops.rows.map((r) => [unquote(r.code), r]));
+    const usedCodes = new Set();
+    for (const s of op.tables.steps.rows) for (const c of cellCodes(s.stops)) { usedCodes.add(c); if (!stops.has(c)) errors.push(`${at}:${s._line}: step ${s.n} stops with ${c}, which the Stops table omits`); }
+    for (const [c, r] of stops) {
+      if (!usedCodes.has(c)) errors.push(`${at}:${r._line}: stop ${c} is emitted by no step`);
+      const entry = registry.codes[c];
+      if (!entry) { errors.push(`${at}:${r._line}: stop ${c} is in no errors registry`); continue; }
+      if (!registry.allowed(c, id)) errors.push(`${at}:${r._line}: stop ${c} is scoped to ${entry.scope.join(', ')}, not ${id}`);
+      if (r.disposition.trim() !== entry.disposition) errors.push(`${at}:${r._line}: stop ${c} says ${r.disposition.trim()} but ${entry.home} says ${entry.disposition}`);
+      if (entry.unless && !fields.has(entry.unless.param)) errors.push(`${entry.home}: ${c} unless names param ${entry.unless.param}, which ${id} does not declare`);
+    }
+    for (const [c, e] of Object.entries(registry.codes)) if (e.scope.length === 1 && e.scope[0] === id && !stops.has(c)) errors.push(`${e.home}: ${c} is defined for ${id} but its Stops table omits it`);
+    if (!cellCodes(op.tables.steps.rows[0]?.stops ?? '').includes('INVALID_INPUT')) errors.push(`${at}: step 1 must be the gate and stop with INVALID_INPUT`);
+    if (!cellFiles(op.tables.steps.rows[0]?.reads ?? '').length && !/request\/request\.json/.test(op.tables.steps.rows[0]?.reads ?? '')) errors.push(`${at}: step 1 must read request/request.json`);
+
+    // Writes ↔ Outputs ↔ templates/kinds.
+    const outputs = new Map();
+    for (const r of op.tables.outputs.rows) {
+      const kind = kindOf(r.kind); const file = unquote(r.file); const type = r.type.trim();
+      if (outputs.has(kind)) errors.push(`${at}:${r._line}: output ${kind} is declared twice`);
+      outputs.set(kind, { ...r, file, type });
+      const inResponse = /^(?:[a-z][a-z-]*\/)?response\//.test(file);
+      if (!inResponse) errors.push(`${at}:${r._line}: output ${kind} must live under response/ or <exchange>/response/`);
+      if (type === 'md') { if (!kinds.has(kind)) errors.push(`${at}:${r._line}: output ${kind} is md but templates/kinds/${kind}.contract.json is missing`); if (!file.endsWith('.md')) errors.push(`${at}:${r._line}: md output ${kind} must be a .md file`); }
+      if (type === 'data') { if (!existsSync(path.join(root, 'templates', 'kinds', `${kind}.schema.json`))) errors.push(`${at}:${r._line}: output ${kind} is data but templates/kinds/${kind}.schema.json is missing`); if (!/\/data\/.+\.json$/.test(file)) errors.push(`${at}:${r._line}: data output ${kind} must live under response/data/ as .json`); }
+      if (type === 'artifact' && !/\/artifacts\//.test(file)) errors.push(`${at}:${r._line}: artifact output ${kind} must live under response/artifacts/`);
+    }
+    const written = new Set();
+    for (const s of op.tables.steps.rows) for (const f of cellFiles(s.writes)) written.add(f);
+    const outputFiles = new Set([...outputs.values()].map((o) => o.file));
+    for (const f of written) if (f !== 'response/response.json' && !outputFiles.has(f) && !exchangeOf(f)) errors.push(`${at}: a step writes ${f}, which Outputs does not declare`);
+    for (const f of outputFiles) if (!written.has(f) && !exchangeOf(f)) errors.push(`${at}: output ${f} is written by no step`);
+    if (!written.has('response/response.json')) errors.push(`${at}: no step writes response/response.json`);
+
+    // Nested exchanges: an Output under <exchange>/response/ needs one step that waits for it and reads it.
+    for (const ex of new Set([...outputFiles].map(exchangeOf).filter(Boolean))) {
+      const waiting = op.tables.steps.rows.filter((s) => /response\/response\.json/.test(s.writes) && /waiting/.test(s.writes) && s.reads.includes(`${ex}/response/`));
+      if (waiting.length !== 1) errors.push(`${at}: exchange ${ex} needs exactly one step that writes response/response.json (waiting) and reads ${ex}/response/…, found ${waiting.length}`);
+      for (const s of op.tables.steps.rows) for (const f of cellFiles(s.writes)) if (exchangeOf(f) === ex) errors.push(`${at}:${s._line}: step ${s.n} writes ${f}; only the exchange's own agent writes under ${ex}/response/`);
+    }
+
+    // Inputs ↔ templates/kinds; Next ↔ operators.
+    for (const r of op.tables.inputs.rows) {
+      const kind = kindOf(r.kind);
+      if (kind === '—' || kind === '') continue;
+      if (!kinds.has(kind) && !existsSync(path.join(root, 'templates', 'kinds', `${kind}.schema.json`))) errors.push(`${at}:${r._line}: input ${kind} has no contract or schema under templates/kinds`);
+    }
+    // Next may hand to another operator, or end automation the way routing.json does: `user` (a person
+    // decides or publishes) or `external` (the blocker is outside the runtime).
+    for (const r of op.tables.next.rows) { const target = unquote(r.operator); if (!ids.has(target) && target !== 'user' && target !== 'external') errors.push(`${at}:${r._line}: next names unknown operator ${target}`); }
+
+    // en ↔ vi.
+    if (!pkg.vi) { errors.push(`operators/${pkg.name}/operator.vi.md: missing`); continue; }
+    const vi = pkg.vi;
+    if (vi.id !== id) errors.push(`operators/${pkg.name}/operator.vi.md: title must be ${id}`);
+    for (const key of TABLES) {
+      const a = op.tables[key]; const b = vi.tables[key];
+      if (!b) { errors.push(`operators/${pkg.name}/operator.vi.md: no ${key} table`); continue; }
+      if (a.rows.length !== b.rows.length) { errors.push(`operators/${pkg.name}/operator.vi.md: ${key} has ${b.rows.length} rows, English has ${a.rows.length}`); continue; }
+      const firstKey = { context: 'alias', inputs: 'kind', requirements: 'field', steps: 'n', outputs: 'kind', stops: 'code', next: 'operator' }[key];
+      a.rows.forEach((ra, i) => {
+        const rb = b.rows[i];
+        if (unquote(ra[firstKey]) !== unquote(rb[firstKey])) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: ${key} row ${i + 1} is ${unquote(rb[firstKey])}, English has ${unquote(ra[firstKey])}`);
+        if (key === 'steps') {
+          if (cellCodes(ra.stops).join() !== cellCodes(rb.stops).join()) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: step ${ra.n} stop codes differ from English`);
+          if (cellParams(ra.params).join() !== cellParams(rb.params).join()) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: step ${ra.n} params differ from English`);
+          if (cellFiles(ra.writes).join() !== cellFiles(rb.writes).join()) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: step ${ra.n} writes differ from English`);
+        }
+        if (key === 'stops' && ra.disposition.trim() !== rb.disposition.trim()) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: ${unquote(ra.code)} disposition differs from English`);
+        if (key === 'outputs' && (ra.type.trim() !== rb.type.trim() || unquote(ra.file) !== unquote(rb.file))) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: output ${unquote(ra.kind)} file or type differs from English`);
+        if (key === 'requirements' && unquote(ra.default) !== unquote(rb.default)) errors.push(`operators/${pkg.name}/operator.vi.md:${rb._line}: requirement ${unquote(ra.field)} default differs from English`);
+      });
+    }
+  }
+  return { errors, checked, total: packages.length };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const { errors, checked, total } = await validateOperators(root);
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write(`operators closed: ${checked} operator.md packages of ${total}\n`);
+}

package/scripts/validate-request.mjs

@@ -0,0 +1,80 @@
+// The request half of one branch (step-N/parallel-M/request/request.json), checked before any agent
+// runs: the gate schema; the operator exists and is an operator.md package; every requirement key is
+// one the operator declares and every required one (Default —) has a value; every declared input is
+// present when required, points inside the session, and the file exists; a nested exchange's request
+// names an exchange the operator's Outputs declare. A request that fails here is the orchestrator's
+// or the person's mistake, never the agent's.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateAgainst } from './json-schema.mjs';
+import { loadOperatorPackages, kindOf, isYes, exchangeOf } from './operator-md.mjs';
+
+const unquote = (s) => String(s ?? '').trim().replace(/^`|`$/g, '');
+export const isRequiredField = (row) => row.default.trim().startsWith('—');
+export const isEmpty = (v) => v === undefined || v === null || v === '' || v === '—';
+
+// A branch dir is <session>/step-N/parallel-M; an exchange dir is <branch>/<exchange>.
+export function sessionRootOf(dir) {
+  let cur = path.resolve(dir);
+  for (let i = 0; i < 4; i += 1) { if (/^step-\d+$/.test(path.basename(cur))) return path.dirname(cur); cur = path.dirname(cur); }
+  return null;
+}
+
+export async function validateRequest(root, dir, packages) {
+  const errors = [];
+  const rel = (f) => path.relative(sessionRootOf(dir) ?? dir, path.join(dir, f)).split(path.sep).join('/');
+  const file = path.join(dir, 'request', 'request.json');
+  if (!existsSync(file)) return { errors: [`${rel('request/request.json')}: missing`], request: null };
+  let request; try { request = JSON.parse(await readFile(file, 'utf8')); } catch (e) { return { errors: [`${rel('request/request.json')}: ${e.message}`], request: null }; }
+  const schema = JSON.parse(await readFile(path.join(root, 'templates', 'step', 'request.schema.json'), 'utf8'));
+  errors.push(...validateAgainst(schema, request, rel('request/request.json')));
+  packages ??= await loadOperatorPackages(root);
+  const pkg = packages.find((p) => p.manifest.id === request.operatorId);
+  if (!pkg) { errors.push(`request.json: unknown operator ${request.operatorId}`); return { errors, request }; }
+  if (pkg.shape !== 'v9') { errors.push(`${request.operatorId} is not an operator.md package`); return { errors, request }; }
+  const op = pkg.en;
+  const sessionRoot = sessionRootOf(dir);
+
+  if (request.exchange) {
+    // A nested exchange: it must be one the operator's Outputs declare, and it carries no person-facing requirements.
+    const declared = (op.tables.outputs?.rows ?? []).map((r) => exchangeOf(unquote(r.file))).filter(Boolean);
+    if (!declared.includes(request.exchange)) errors.push(`request.json: exchange ${request.exchange} is not declared by an Output of ${op.id}`);
+    if (Object.keys(request.requirements ?? {}).length) errors.push('request.json: a nested exchange carries no requirements');
+  } else {
+    const declared = new Map((op.tables.requirements?.rows ?? []).map((r) => [unquote(r.field), r]));
+    for (const key of Object.keys(request.requirements ?? {})) if (!declared.has(key)) errors.push(`request.json: requirements.${key} is not a field ${op.id} declares`);
+    for (const [key, row] of declared) if (isRequiredField(row) && isEmpty(request.requirements?.[key])) errors.push(`request.json: required field ${key} has no value`);
+    const declaredInputs = new Map((op.tables.inputs?.rows ?? []).map((r) => [kindOf(r.kind), r]));
+    for (const kind of Object.keys(request.inputs ?? {})) if (!declaredInputs.has(kind)) errors.push(`request.json: inputs.${kind} is not an Input ${op.id} declares`);
+    for (const [kind, row] of declaredInputs) if (isYes(row.required) && isEmpty(request.inputs?.[kind])) errors.push(`request.json: required input ${kind} is absent`);
+  }
+  for (const [kind, p] of Object.entries(request.inputs ?? {})) {
+    if (!sessionRoot) { errors.push(`request.json: inputs.${kind} cannot be resolved; the branch is not under a session`); continue; }
+    if (!existsSync(path.join(sessionRoot, p))) errors.push(`request.json: inputs.${kind} = ${p} does not exist in the session`);
+  }
+  // The orchestrator hashes every request into state.json; a request that changed since is tampering.
+  if (sessionRoot && existsSync(path.join(sessionRoot, 'state.json'))) {
+    try {
+      const state = JSON.parse(await readFile(path.join(sessionRoot, 'state.json'), 'utf8'));
+      const key = `${request.step}/${request.parallel}${request.exchange ? `/${request.exchange}` : ''}`;
+      const expected = state.requestHashes?.[key];
+      if (expected) {
+        const { createHash } = await import('node:crypto');
+        const actual = `sha256:${createHash('sha256').update(await readFile(file)).digest('hex')}`;
+        if (actual !== expected) errors.push(`request.json: hash ${actual} differs from state.json requestHashes[${key}]`);
+      }
+    } catch (e) { errors.push(`state.json: ${e.message}`); }
+  }
+  return { errors, request, pkg };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node scripts/validate-request.mjs <session>/step-N/parallel-M[/<exchange>]\n'); process.exit(2); }
+  const { errors } = await validateRequest(root, path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('request valid\n');
+}

package/scripts/validate-resources.mjs

@@ -0,0 +1,117 @@
+// Resources close when: every profile declares, for every tool in resources/tools.json, what the runtime can do
+// (capabilities) and what the profile is allowed to do (permits), and never permits what it cannot; every
+// operator binds one profile and declares its tools as @tools/<id> with one mode the registry defines, each
+// permitted by its profile and supported by its runtime; resources/INDEX.md repeats the bindings exactly;
+// orchestrator.json fixes the agent contract and a symmetric profile equivalent on the other runtime.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const errors = [];
+
+const toolsDoc = JSON.parse(await readFile(path.join(root, 'resources', 'tools.json'), 'utf8'));
+if (toolsDoc.schemaVersion !== 9) errors.push('resources/tools.json: schemaVersion must be 9');
+const TOOLS = toolsDoc.tools ?? {};
+const RUNTIMES = Object.keys(toolsDoc.runtimes ?? {});
+for (const [id, tool] of Object.entries(TOOLS)) {
+  if (!/^[a-z][a-z0-9-]*$/.test(id)) errors.push(`resources/tools.json: tool id ${id} must be lowercase`);
+  if (!tool.purpose) errors.push(`resources/tools.json: ${id} needs a purpose`);
+  if (!tool.modes || !Object.keys(tool.modes).length) errors.push(`resources/tools.json: ${id} needs modes`);
+  for (const rt of RUNTIMES) if (typeof tool.support?.[rt]?.supported !== 'boolean' || !tool.support?.[rt]?.via) errors.push(`resources/tools.json: ${id} must say whether ${rt} supports it and via what`);
+}
+
+// One file per runtime under resources/agents/profiles; the file name is the runtime id.
+const profilesDir = path.join(root, 'resources', 'agents', 'profiles');
+const profiles = {};
+for (const file of (await readdir(profilesDir)).filter((f) => f.endsWith('.json')).sort()) {
+  const runtime = file.slice(0, -'.json'.length);
+  const group = JSON.parse(await readFile(path.join(profilesDir, file), 'utf8'));
+  if (group.runtime !== runtime) errors.push(`${file}: runtime must be "${runtime}", got "${group.runtime}"`);
+  if (!RUNTIMES.includes(runtime)) errors.push(`${file}: runtime ${runtime} is not declared in resources/tools.json`);
+  if (typeof group.provider !== 'string') errors.push(`runtime ${runtime}: provider must be a string`);
+  for (const [id, profile] of Object.entries(group.profiles ?? {})) {
+    if (profiles[id]) errors.push(`profile ${id}: declared in more than one runtime`);
+    profiles[id] = { ...profile, runtime, provider: group.provider };
+  }
+}
+for (const [id, profile] of Object.entries(profiles)) {
+  for (const tool of Object.keys(TOOLS)) {
+    const supported = TOOLS[tool].support?.[profile.runtime]?.supported === true;
+    if (typeof profile.capabilities?.[tool] !== 'boolean') errors.push(`profile ${id}: capabilities.${tool} must be true or false`);
+    if (typeof profile.permits?.[tool] !== 'boolean') errors.push(`profile ${id}: permits.${tool} must be true or false`);
+    if (profile.capabilities?.[tool] === true && !supported) errors.push(`profile ${id}: capabilities.${tool} is true but resources/tools.json says ${profile.runtime} does not support it`);
+    if (profile.permits?.[tool] === true && profile.capabilities?.[tool] !== true) errors.push(`profile ${id}: permits.${tool} but capabilities.${tool} is false`);
+  }
+  for (const key of Object.keys(profile.permits ?? {})) if (!TOOLS[key]) errors.push(`profile ${id}: permits unknown tool ${key}`);
+  if (profile.isolation !== 'fresh' || profile.forkTurns !== 'none') errors.push(`profile ${id}: material executions are fresh with no inherited turns`);
+}
+
+// Each operator binds one profile and declares its tools with modes.
+const operatorsDir = path.join(root, 'operators');
+const operators = new Map();
+for (const entry of await readdir(operatorsDir, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const manifest = JSON.parse(await readFile(path.join(operatorsDir, entry.name, 'operator.json'), 'utf8'));
+  operators.set(manifest.id, manifest.resources);
+}
+const used = new Set();
+for (const [id, resources] of operators) {
+  if (!resources || typeof resources !== 'object') { errors.push(`${id}: operator.json must declare resources { profile, grammarBound, tools }`); continue; }
+  const { profile: profileId, grammarBound, tools = {} } = resources;
+  const profile = profiles[profileId];
+  if (typeof profileId !== 'string' || !profile) { errors.push(`${id}: resources.profile ${profileId} is not a declared profile`); continue; }
+  used.add(profileId);
+  if (typeof grammarBound !== 'boolean') errors.push(`${id}: resources.grammarBound must be true or false`);
+  if (resources.requires || resources.policy) errors.push(`${id}: resources.requires and resources.policy are retired; declare resources.tools`);
+  for (const [ref, mode] of Object.entries(tools)) {
+    const m = /^@tools\/([a-z][a-z0-9-]*)$/.exec(ref);
+    if (!m) { errors.push(`${id}: tool ${ref} must be written @tools/<id>`); continue; }
+    const tool = TOOLS[m[1]];
+    if (!tool) { errors.push(`${id}: ${ref} is not in resources/tools.json`); continue; }
+    if (!tool.modes[mode]) errors.push(`${id}: ${ref} mode ${mode} is not one of ${Object.keys(tool.modes).join(', ')}`);
+    if (mode === 'never') errors.push(`${id}: ${ref} declared as never; leave it out instead`);
+    if (!profile.permits?.[m[1]]) errors.push(`${id}: declares ${ref} but profile ${profileId} does not permit it`);
+  }
+  if (!tools['@tools/fileread']) errors.push(`${id}: every operator reads its Context aliases; declare @tools/fileread`);
+}
+
+// resources/INDEX.md repeats the bindings: | `operator` | profile | grammar | tools | why |
+const index = await readFile(path.join(root, 'resources', 'INDEX.md'), 'utf8');
+const GRAMMAR_WORD = { true: 'yes', false: 'no' };
+const rows = new Map();
+for (const line of index.split(/\r?\n/)) {
+  const m = /^\| `([a-z.]+)` \| ([a-z-]+) \| (yes|no) \| ([^|]*) \|/.exec(line);
+  if (m) rows.set(m[1], { profile: m[2], grammar: m[3], tools: m[4].trim() });
+}
+for (const [id, resources] of operators) {
+  const row = rows.get(id);
+  if (!row) { errors.push(`resources/INDEX.md: no process-matrix row for ${id}`); continue; }
+  if (!resources) continue;
+  const expectTools = Object.entries(resources.tools ?? {}).map(([k, v]) => `\`${k.split('/')[1]}:${v}\``).join(', ');
+  const expect = { profile: resources.profile, grammar: GRAMMAR_WORD[resources.grammarBound], tools: expectTools };
+  for (const key of Object.keys(expect)) if (row[key] !== expect[key]) errors.push(`resources/INDEX.md: ${id} row says ${key} "${row[key]}", operator.json says "${expect[key]}"`);
+}
+for (const id of rows.keys()) if (!operators.has(id)) errors.push(`resources/INDEX.md: row for unknown operator ${id}`);
+
+// The orchestrator record turns operators into agents.
+const orchestrator = JSON.parse(await readFile(path.join(root, 'resources', 'orchestrator.json'), 'utf8'));
+if (orchestrator.agentPerOperator !== true) errors.push('orchestrator.json: agentPerOperator must be true');
+if (!Number.isInteger(orchestrator.maxConcurrentAgents) || orchestrator.maxConcurrentAgents < 1 || orchestrator.maxConcurrentAgents > 3) errors.push('orchestrator.json: maxConcurrentAgents must be an integer from 1 to 3');
+if (orchestrator.dispatch !== 'routing.json') errors.push('orchestrator.json: dispatch must be routing.json');
+const pairs = orchestrator.profileEquivalents?.pairs ?? {};
+for (const [id, profile] of Object.entries(profiles)) {
+  const eq = pairs[id];
+  if (!eq) { errors.push(`orchestrator.json: profileEquivalents lacks ${id}`); continue; }
+  if (!profiles[eq]) errors.push(`orchestrator.json: profileEquivalents maps ${id} to unknown profile ${eq}`);
+  else if (profiles[eq].runtime === profile.runtime) errors.push(`orchestrator.json: profileEquivalents maps ${id} to ${eq} on the same runtime`);
+  else if (pairs[eq] !== id) errors.push(`orchestrator.json: profileEquivalents is not symmetric for ${id} and ${eq}`);
+}
+
+if (errors.length > 0) {
+  process.stderr.write(`${errors.join('\n')}\n`);
+  process.exitCode = 1;
+} else {
+  process.stdout.write(`resources bound: ${RUNTIMES.length} runtimes, ${Object.keys(TOOLS).length} tools, ${Object.keys(profiles).length} profiles, ${operators.size} operators on ${used.size} profiles\n`);
+}

package/scripts/validate-response.mjs

@@ -0,0 +1,141 @@
+// The response half of one branch (step-N/parallel-M/response/), checked after the agent stops: the
+// gate schema; every Output the operator's operator.md declares is present when required and valid
+// when present (markdown kinds through templates/kinds/<kind>.contract.json, data kinds through
+// <kind>.schema.json, artifacts by existence); a blocked stop is a code the operator may emit whose
+// effective disposition is terminate; a taken fallback is one whose effective disposition is fallback
+// and is recorded under ## Fallbacks taken; a waiting status names a declared exchange; a nested
+// exchange's own response is checked the same way. Effective means after `unless` is evaluated
+// against request.json requirements. Operator-specific law lives in operators/<id>/validate.mjs.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateAgainst } from './json-schema.mjs';
+import { checkDocument, loadKindTemplates } from './validate-templates.mjs';
+import { loadOperatorPackages, kindOf, isYes, exchangeOf } from './operator-md.mjs';
+import { loadErrorsRegistry } from './errors-registry.mjs';
+import { sessionRootOf } from './validate-request.mjs';
+
+const unquote = (s) => String(s ?? '').trim().replace(/^`|`$/g, '');
+
+// Rows of the first table under `## <heading>`, cells unquoted.
+export function tableUnder(text, heading) {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === heading);
+  if (start === -1) return null;
+  const rows = [];
+  let inTable = false;
+  for (let i = start + 1; i < lines.length && !lines[i].startsWith('## '); i += 1) {
+    if (lines[i].startsWith('|') && /^\|\s*-{3,}/.test(lines[i + 1] ?? '')) { inTable = true; i += 1; continue; }
+    if (inTable) { if (!lines[i].startsWith('|')) break; rows.push(lines[i].split('|').slice(1, -1).map((c) => unquote(c))); }
+  }
+  return rows;
+}
+function patternOf(fileCell) {
+  const esc = unquote(fileCell).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/<[^>]+>/g, '[A-Za-z0-9_.-]+');
+  return new RegExp(`^${esc}$`);
+}
+export function effectiveDisposition(entry, requirements) {
+  if (entry.unless && String(requirements?.[entry.unless.param] ?? '') === String(entry.unless.equals)) return entry.unless.then;
+  return entry.disposition;
+}
+
+// `dir` is the branch (or exchange) folder; `requirements` come from the branch's request.json.
+export async function validateResponse(root, dir, { requirements = {}, exchange = null, packages, kinds, registry } = {}) {
+  const errors = [];
+  const rel = (f) => path.relative(sessionRootOf(dir) ?? dir, path.join(dir, f)).split(path.sep).join('/');
+  const file = path.join(dir, 'response', 'response.json');
+  if (!existsSync(file)) return { errors: [`${rel('response/response.json')}: missing`], response: null, present: new Set() };
+  let response; try { response = JSON.parse(await readFile(file, 'utf8')); } catch (e) { return { errors: [`${rel('response/response.json')}: ${e.message}`], response: null, present: new Set() }; }
+  const schema = JSON.parse(await readFile(path.join(root, 'templates', 'step', 'response.schema.json'), 'utf8'));
+  errors.push(...validateAgainst(schema, response, rel('response/response.json')));
+  if (response.status !== 'blocked' && response.stop !== undefined) errors.push(`${rel('response/response.json')}: only a blocked response carries a stop`);
+  if (response.status !== 'waiting' && response.awaiting !== undefined) errors.push(`${rel('response/response.json')}: only a waiting response carries awaiting`);
+  if ((response.exchange ?? null) !== exchange) errors.push(`${rel('response/response.json')}: exchange ${response.exchange ?? 'none'} does not match the folder ${exchange ?? 'none'}`);
+  packages ??= await loadOperatorPackages(root);
+  const pkg = packages.find((p) => p.manifest.id === response.operatorId);
+  if (!pkg) { errors.push(`response.json: unknown operator ${response.operatorId}`); return { errors, response, present: new Set() }; }
+  if (pkg.shape !== 'v9') { errors.push(`${response.operatorId} is not an operator.md package`); return { errors, response, present: new Set() }; }
+  kinds ??= await loadKindTemplates(root);
+  registry ??= await loadErrorsRegistry(root);
+  errors.push(...registry.errors);
+  const op = pkg.en;
+
+  // Which Outputs belong to this folder: the branch owns files without an exchange prefix, an exchange owns its own.
+  const outputs = (op.tables.outputs?.rows ?? []).filter((r) => exchangeOf(unquote(r.file)) === exchange);
+  const present = new Set();
+  for (const row of outputs) {
+    const kind = kindOf(row.kind);
+    const type = row.type.trim();
+    // Inside an exchange folder the declared file is <exchange>/response/x; the response.json there lists response/x.
+    const declaredFile = exchange ? unquote(row.file).replace(`${exchange}/`, '') : unquote(row.file);
+    const value = response.fields?.[kind];
+    const files = value === undefined ? [] : Array.isArray(value) ? value : [value];
+    if (files.length === 0) { if (isYes(row.required) && response.status === 'done') errors.push(`${rel('response/response.json')}: required output ${kind} is not in fields`); continue; }
+    present.add(kind);
+    const re = patternOf(declaredFile);
+    for (const f of files) {
+      if (!re.test(f)) errors.push(`${rel('response/response.json')}: fields.${kind} = ${f} does not match the declared file ${declaredFile}`);
+      const full = path.join(dir, f);
+      if (!existsSync(full)) { errors.push(`${rel(f)}: listed in response.json but missing`); continue; }
+      if (type === 'md') {
+        const contract = kinds.get(kind);
+        if (!contract) { errors.push(`templates/kinds/${kind}.contract.json: missing`); continue; }
+        errors.push(...checkDocument(rel(f), await readFile(full, 'utf8'), contract, 'en'));
+      } else if (type === 'data') {
+        const schemaPath = path.join(root, 'templates', 'kinds', `${kind}.schema.json`);
+        if (!existsSync(schemaPath)) { errors.push(`templates/kinds/${kind}.schema.json: missing`); continue; }
+        let value2; try { value2 = JSON.parse(await readFile(full, 'utf8')); } catch (e) { errors.push(`${rel(f)}: ${e.message}`); continue; }
+        errors.push(...validateAgainst(JSON.parse(await readFile(schemaPath, 'utf8')), value2, rel(f)));
+      }
+    }
+  }
+  for (const kind of Object.keys(response.fields ?? {})) if (!outputs.some((r) => kindOf(r.kind) === kind)) errors.push(`${rel('response/response.json')}: fields.${kind} is not an Output of ${op.id}${exchange ? ` in exchange ${exchange}` : ''}`);
+
+  // Stops, fallbacks, waiting.
+  const stopsTable = new Set((op.tables.stops?.rows ?? []).map((r) => unquote(r.code)));
+  const dispositionOf = (code) => { const e = registry.codes[code]; return e && registry.allowed(code, op.id) ? effectiveDisposition(e, requirements) : null; };
+  if (response.status === 'blocked') {
+    const d = dispositionOf(response.stop);
+    if (!stopsTable.has(response.stop)) errors.push(`${rel('response/response.json')}: stop ${response.stop} is not in the Stops table of ${op.id}`);
+    if (d === null) errors.push(`${rel('response/response.json')}: stop ${response.stop} is not a registered code ${op.id} may emit`);
+    else if (d !== 'terminate') errors.push(`${rel('response/response.json')}: ${response.stop} has disposition fallback under these requirements; the step should have continued`);
+  }
+  for (const code of response.fallbacks ?? []) {
+    const d = dispositionOf(code);
+    if (!stopsTable.has(code)) errors.push(`${rel('response/response.json')}: fallback ${code} is not in the Stops table of ${op.id}`);
+    if (d === null) errors.push(`${rel('response/response.json')}: fallback ${code} is not a registered code ${op.id} may emit`);
+    else if (d !== 'fallback') errors.push(`${rel('response/response.json')}: ${code} has disposition terminate under these requirements; it cannot be taken as a fallback`);
+  }
+  if (response.status === 'waiting') {
+    const declared = (op.tables.outputs?.rows ?? []).filter((r) => exchangeOf(unquote(r.file)) === response.awaiting?.exchange);
+    if (!declared.length) errors.push(`${rel('response/response.json')}: awaiting exchange ${response.awaiting?.exchange} is declared by no Output of ${op.id}`);
+    else if (!declared.some((r) => kindOf(r.kind) === response.awaiting?.kind)) errors.push(`${rel('response/response.json')}: awaiting kind ${response.awaiting?.kind} is not produced by exchange ${response.awaiting?.exchange}`);
+  }
+  const mainMd = outputs.find((r) => /\/response\.md$/.test(unquote(r.file)));
+  if (mainMd && present.has(kindOf(mainMd.kind))) {
+    const text = await readFile(path.join(dir, 'response', 'response.md'), 'utf8');
+    const taken = (tableUnder(text, '## Fallbacks taken') ?? []).map(([c]) => c);
+    const declaredTaken = new Set(response.fallbacks ?? []);
+    for (const c of taken) if (!declaredTaken.has(c)) errors.push(`${rel('response/response.md')}: Fallbacks taken lists ${c}, which response.json does not`);
+    for (const c of declaredTaken) if (!taken.includes(c)) errors.push(`${rel('response/response.json')}: fallback ${c} is not recorded under ## Fallbacks taken in response.md`);
+  }
+  for (const nextId of response.next ?? []) if (nextId !== 'user' && nextId !== 'external' && !packages.some((p) => p.manifest.id === nextId)) errors.push(`${rel('response/response.json')}: next names unknown operator ${nextId}`);
+  if (exchange && (response.next ?? []).length) errors.push(`${rel('response/response.json')}: a nested exchange does not route; next must be empty`);
+  return { errors, response, present, pkg };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node scripts/validate-response.mjs <session>/step-N/parallel-M[/<exchange>]\n'); process.exit(2); }
+  const dir = path.resolve(target);
+  // A branch is <session>/step-N/parallel-M (its parent is step-N); an exchange is <branch>/<exchange> (its parent is parallel-M).
+  const exchange = /^step-\d+$/.test(path.basename(path.dirname(dir))) ? null : path.basename(dir);
+  let requirements = {};
+  const reqFile = path.join(exchange ? path.dirname(dir) : dir, 'request', 'request.json');
+  if (existsSync(reqFile)) requirements = JSON.parse(await readFile(reqFile, 'utf8')).requirements ?? {};
+  const { errors } = await validateResponse(root, dir, { requirements, exchange });
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('response valid\n');
+}

package/scripts/validate-routing.mjs

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { parseOperatorMd, cellCodes } from './operator-md.mjs';
+import { loadErrorsRegistry } from './errors-registry.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const operatorsDir = path.join(root, 'operators');
+const routing = JSON.parse(await readFile(path.join(root, 'routing.json'), 'utf8'));
+const errors = [];
+
+const kinds = new Set(Object.keys(routing.kinds));
+const operators = new Map();
+const registry = await loadErrorsRegistry(root);
+errors.push(...registry.errors);
+
+for (const entry of await readdir(operatorsDir, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const dir = path.join(operatorsDir, entry.name);
+  const manifest = JSON.parse(await readFile(path.join(dir, 'operator.json'), 'utf8'));
+  if (existsSync(path.join(dir, 'operator.md'))) {
+    // An operator.md package emits exactly the domains of the stop codes its Stops table lists; `self`
+    // is the operator's own domain, which routing.json answers with kind "resume".
+    const op = parseOperatorMd(await readFile(path.join(dir, 'operator.md'), 'utf8'), 'en');
+    const domains = new Set();
+    for (const row of op.tables.stops?.rows ?? []) {
+      const code = cellCodes(row.code)[0] ?? row.code.trim();
+      const domain = registry.codes[code]?.domain;
+      if (!domain) continue; // validate-operator reports the unknown code
+      domains.add(domain === 'self' ? manifest.domain : domain);
+    }
+    operators.set(manifest.id, domains.size ? domains : null);
+    continue;
+  }
+  const schema = await readFile(path.join(dir, 'output.schema.json'), 'utf8');
+  const match = /"owningDomain"\s*:\s*\{[^}]*"enum"\s*:\s*(\[[^\]]*\])/s.exec(schema);
+  operators.set(manifest.id, match ? new Set(JSON.parse(match[1])) : null);
+}
+
+// Every operator must have a route table, and the table must cover exactly the domains
+// that operator can actually emit. A domain it can emit but cannot route is a dead end;
+// a route for a domain it never emits is a rule nobody reaches.
+for (const [id, domains] of operators) {
+  const table = routing.routes[id];
+  if (!table) {
+    errors.push(`${id}: no route table`);
+    continue;
+  }
+  if (domains === null) {
+    errors.push(`${id}: output schema declares no owningDomain enum`);
+    continue;
+  }
+  for (const domain of domains) {
+    if (!Object.hasOwn(table, domain)) errors.push(`${id}: emits "${domain}" with no route`);
+  }
+  for (const domain of Object.keys(table)) {
+    if (!domains.has(domain)) errors.push(`${id}: routes "${domain}" which it never emits`);
+  }
+}
+
+for (const id of Object.keys(routing.routes)) {
+  if (!operators.has(id)) errors.push(`routing.json names unknown operator ${id}`);
+}
+
+// A destination must resolve. An "operator" route needs a real target; the other kinds
+// must not carry one, or the map would silently disagree with itself.
+for (const [id, table] of Object.entries(routing.routes)) {
+  for (const [domain, route] of Object.entries(table)) {
+    if (!kinds.has(route.kind)) {
+      errors.push(`${id}.${domain}: unknown kind ${route.kind}`);
+      continue;
+    }
+    if (route.kind === 'operator') {
+      if (!route.target) errors.push(`${id}.${domain}: operator route needs a target`);
+      else if (!operators.has(route.target)) errors.push(`${id}.${domain}: targets unknown operator ${route.target}`);
+      else if (route.target === id) errors.push(`${id}.${domain}: targets itself; use kind "resume"`);
+    } else if (route.target !== undefined) {
+      errors.push(`${id}.${domain}: kind ${route.kind} must not carry a target`);
+    }
+  }
+}
+
+if (errors.length > 0) {
+  process.stderr.write(`${errors.join('\n')}\n`);
+  process.exitCode = 1;
+} else {
+  const routes = Object.values(routing.routes).reduce((total, table) => total + Object.keys(table).length, 0);
+  process.stdout.write(`routing map closed: ${operators.size} operators, ${routes} routes\n`);
+}

package/scripts/validate-step.mjs

@@ -0,0 +1,50 @@
+// One branch of one step, both halves: validate-request on request/request.json, validate-response on
+// response/, and the same pair on every nested exchange folder the response awaited or the operator
+// declares. Used by operator self-tests and audits; the orchestrator runs the halves separately, the
+// request before it spawns the agent and the response after.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateRequest } from './validate-request.mjs';
+import { validateResponse } from './validate-response.mjs';
+import { loadOperatorPackages, exchangeOf } from './operator-md.mjs';
+import { loadKindTemplates } from './validate-templates.mjs';
+import { loadErrorsRegistry } from './errors-registry.mjs';
+
+const unquote = (s) => String(s ?? '').trim().replace(/^`|`$/g, '');
+
+export async function validateStep(root, branchDir) {
+  const packages = await loadOperatorPackages(root);
+  const kinds = await loadKindTemplates(root);
+  const registry = await loadErrorsRegistry(root);
+  const req = await validateRequest(root, branchDir, packages);
+  const errors = [...req.errors];
+  const requirements = req.request?.requirements ?? {};
+  const res = await validateResponse(root, branchDir, { requirements, exchange: null, packages, kinds, registry });
+  errors.push(...res.errors);
+  const present = new Set(res.present);
+  const pkg = req.pkg ?? res.pkg;
+  if (pkg?.shape === 'v9') {
+    const exchanges = new Set((pkg.en.tables.outputs?.rows ?? []).map((r) => exchangeOf(unquote(r.file))).filter(Boolean));
+    for (const ex of exchanges) {
+      const exDir = path.join(branchDir, ex);
+      if (!existsSync(path.join(exDir, 'request', 'request.json'))) { if (res.response?.status === 'done') errors.push(`${ex}/: the operator declares this exchange and the branch is done, but it never ran`); continue; }
+      const exReq = await validateRequest(root, exDir, packages);
+      errors.push(...exReq.errors);
+      const exRes = await validateResponse(root, exDir, { requirements, exchange: ex, packages, kinds, registry });
+      errors.push(...exRes.errors);
+      for (const k of exRes.present) present.add(k);
+      if (res.response?.status === 'done' && exRes.response?.status !== 'done') errors.push(`${ex}/response/response.json: the branch is done but the exchange is ${exRes.response?.status ?? 'missing'}`);
+    }
+  }
+  return { errors, request: req.request, response: res.response, requirements, present, pkg };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node scripts/validate-step.mjs <session>/step-N/parallel-M\n'); process.exit(2); }
+  const { errors } = await validateStep(root, path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('step valid\n');
+}