unknown-knowledge 2.1.0

package/payload/engine/lib/validate-record.js

@@ -0,0 +1,504 @@
+/**
+ * Schema validation for store records (KK-02) — the layer the store loader
+ * (KK-04) calls before indexing anything.
+ *
+ * The formal contract lives in ../../schemas/*.schema.json (JSON Schema
+ * draft 2020-12, consumable by any external tool). This module interprets
+ * those documents directly — no schema library (D-002: js-yaml and little
+ * else) — supporting exactly the subset the schemas use: type, required,
+ * properties, additionalProperties:false, items, enum, pattern, minItems,
+ * minimum, and $ref into #/$defs.
+ *
+ * On top of the schemas it enforces the PRD §3.5 conventions JSON Schema
+ * cannot express record-locally:
+ *   - enumerates values are strings, byte-exact, case-sensitive, as sets;
+ *     non-string scalars hard-error (`non-string-enumerates-value`) — the
+ *     YAML 1.1 coercion trap. Callers must parse YAML with types intact
+ *     (js-yaml default schema) and pass the parsed document unchanged.
+ *   - multi-entry source-of-truth: the first entry is the primary owner,
+ *     additional entries are secondary references; every enumerates
+ *     descriptor's source must name a listed entry
+ *     (`enumerates-source-not-listed`).
+ *   - every store file carries an integer schema-version >= 1; value defects
+ *     there are normalized to `invalid-schema-version` (a stray record-level
+ *     key stays `unknown-property` — the fix is to remove it, not retype it).
+ *     Evolution is additive-only (D-013 generalized).
+ *
+ * Diagnostics carry a closed set of typed codes (PRD §5: protocol conduct
+ * keys on codes, not prose) and are stable-sorted by path then code so
+ * run-over-run diffs mean something.
+ */
+import { readFileSync } from 'node:fs';
+import { ID_GRAMMARS, SCHEMA_DEFS } from './id-grammars.js';
+
+/** Record kind → schema document shipped in payload/schemas/. */
+const KIND_SCHEMA_FILES = Object.freeze({
+  'ontology-concept': 'ontology-concept.schema.json',
+  'knowledge-leaf': 'knowledge-leaf.schema.json',
+  'decision-entry': 'decision-entry.schema.json',
+  'finding': 'finding.schema.json',
+  'miss': 'miss.schema.json',
+  'gap': 'gap.schema.json',
+  'survey-scope': 'survey-scope.schema.json',
+  'catalog': 'catalog.schema.json',
+  'rules': 'rules.schema.json',
+  'registry': 'registry.schema.json',
+  'phoenix-event': 'phoenix-event.schema.json',
+  'graduation-categories': 'graduation-categories.schema.json',
+});
+
+export const KINDS = Object.freeze(Object.keys(KIND_SCHEMA_FILES));
+
+export const ERROR_CODES = Object.freeze([
+  'wrong-type',
+  'missing-required',
+  'unknown-property',
+  'invalid-enum-value',
+  'pattern-mismatch',
+  'too-few-items',
+  'out-of-range',
+  'invalid-schema-version',
+  'non-string-enumerates-value',
+  'duplicate-enumerates-value',
+  'enumerates-source-not-listed',
+  'lifecycle-field-mismatch',
+  'locator-shape',
+]);
+
+/**
+ * The JSON Schema subset this module interprets. Schemas must not use
+ * keywords outside this set — an unenforced keyword is silent contract
+ * drift (tests/store-schemas.test.js walks every schema against it).
+ */
+export const SUPPORTED_KEYWORDS = Object.freeze([
+  '$schema', '$id', '$defs', '$ref',
+  'title', 'description',
+  'type', 'required', 'properties', 'additionalProperties',
+  'items', 'enum', 'pattern', 'minItems', 'minimum',
+]);
+
+/**
+ * Lexicographic comparator shared by every engine surface that emits
+ * stable-sorted, diffable output (PRD §5) — one ordering, one copy.
+ */
+export const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+const schemaCache = new Map();
+
+/**
+ * Bind the shared id grammars onto a freshly parsed schema (UCS-1142).
+ *
+ * The schema files keep their own `$defs` copies so each stays self-contained
+ * for external consumers, but the ENGINE validates against lib/id-grammars.js
+ * — the one module that owns each id space's pattern. Overwriting rather than
+ * asserting is deliberate: a drifted copy is corrected here, so the engine can
+ * only ever enforce the live grammar. (tests/id-grammars.test.js pins that the
+ * shipped copies agree, which is what keeps the published documents honest.)
+ *
+ * The grammar's HINT is bound alongside its pattern, under a key the schema
+ * keyword set does not interpret, so a pattern-mismatch on an id can say what
+ * shape was expected instead of quoting a regex at an author. That matters most
+ * where the shape CHANGED: since UCS-1147 a leaf citation must be an accession,
+ * and `"700.2" does not match ^L-[0-9]{6}$` tells an author what failed while
+ * naming neither the remedy nor the migration that moved it. The hint travels
+ * from the same frozen entry as the pattern, for the reason id-grammars.js
+ * exists — a hint that drifted from its pattern would describe the wrong shape.
+ */
+function bindIdGrammars(schema) {
+  for (const [space, def] of Object.entries(SCHEMA_DEFS)) {
+    const node = schema.$defs?.[def];
+    if (node) {
+      node.pattern = ID_GRAMMARS[space].pattern;
+      node.hint = ID_GRAMMARS[space].hint;
+    }
+  }
+  return schema;
+}
+
+function schemaFor(kind) {
+  const file = KIND_SCHEMA_FILES[kind];
+  if (!file) {
+    throw new TypeError(`unknown record kind "${kind}" (expected one of: ${KINDS.join(', ')})`);
+  }
+  if (!schemaCache.has(kind)) {
+    const url = new URL(`../../schemas/${file}`, import.meta.url);
+    schemaCache.set(kind, bindIdGrammars(JSON.parse(readFileSync(url, 'utf8'))));
+  }
+  return schemaCache.get(kind);
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function describe(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (value instanceof Date) return 'date (quote it)';
+  return typeof value;
+}
+
+function typeMatches(type, value) {
+  if (Array.isArray(type)) return type.some((t) => typeMatches(t, value));
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'integer': return Number.isInteger(value);
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'array': return Array.isArray(value);
+    case 'object': return isPlainObject(value);
+    case 'null': return value === null;
+    default: throw new Error(`schema uses unsupported type "${type}"`);
+  }
+}
+
+function joinPath(base, key) {
+  return base ? `${base}.${key}` : key;
+}
+
+const regexCache = new Map();
+
+function regexFor(pattern) {
+  let re = regexCache.get(pattern);
+  if (!re) {
+    re = new RegExp(pattern);
+    regexCache.set(pattern, re);
+  }
+  return re;
+}
+
+const refCache = new WeakMap();
+
+function resolveRef(root, ref) {
+  if (ref === '#') return root;
+  let refs = refCache.get(root);
+  if (!refs) {
+    refs = new Map();
+    refCache.set(root, refs);
+  }
+  let target = refs.get(ref);
+  if (target === undefined) {
+    const match = /^#\/\$defs\/([^/]+)$/.exec(ref);
+    target = (match && root.$defs?.[match[1]]) ?? null;
+    refs.set(ref, target);
+  }
+  if (!target) throw new Error(`schema $ref "${ref}" does not resolve`);
+  return target;
+}
+
+/**
+ * The id-grammar hint a required property carries, if it declares one.
+ *
+ * Only reaches a hint bound by bindIdGrammars — a property whose shape is an id
+ * space. Everything else returns null and the plain message stands, which is
+ * the right default: "required property "heading" is missing" needs no gloss,
+ * and a hint invented per field would be prose with nothing keeping it true.
+ *
+ * A `$ref` that does not resolve is swallowed rather than thrown: this runs
+ * only to DECORATE a defect the validator has already found, and a schema
+ * authoring error must not turn a legitimate finding into a crash.
+ *
+ * @param {object} root the schema document, for $defs resolution
+ * @param {object} schema the object schema declaring the required property
+ * @param {string} required the missing property's name
+ * @returns {string|null} the hint, or null when the property declares none
+ */
+function requiredHint(root, schema, required) {
+  const property = schema.properties?.[required];
+  if (!property) return null;
+  try {
+    const target = property.$ref ? resolveRef(root, property.$ref) : property;
+    return typeof target.hint === 'string' ? target.hint : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Interpret the supported JSON Schema subset against a value. */
+function check(root, schema, value, path, errors) {
+  if (schema.$ref) {
+    check(root, resolveRef(root, schema.$ref), value, path, errors);
+    return;
+  }
+  if (schema.type && !typeMatches(schema.type, value)) {
+    errors.push({
+      path,
+      code: 'wrong-type',
+      message: `expected ${schema.type}, got ${describe(value)}`,
+    });
+    return; // deeper checks are meaningless on the wrong shape
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push({
+      path,
+      code: 'invalid-enum-value',
+      message: `${JSON.stringify(value)} is not one of: ${schema.enum.join(' | ')}`,
+    });
+  }
+  if (schema.pattern && typeof value === 'string' && !regexFor(schema.pattern).test(value)) {
+    errors.push({
+      path,
+      code: 'pattern-mismatch',
+      // An id-space pattern arrives with the hint bound by bindIdGrammars, and
+      // the hint REPLACES the regex rather than trailing it: it says everything
+      // the pattern says and says it to a human, so printing both would just
+      // make the author read the regex first. Patterns from the schema files
+      // themselves carry no hint and keep quoting the regex — there is nothing
+      // better to say about them, and inventing prose per pattern here would be
+      // the drift id-grammars.js exists to prevent.
+      message: schema.hint
+        ? `${JSON.stringify(value)} is not a valid id here — expected ${schema.hint}`
+        : `${JSON.stringify(value)} does not match ${schema.pattern}`,
+    });
+  }
+  if (schema.minimum !== undefined && typeof value === 'number' && value < schema.minimum) {
+    errors.push({
+      path,
+      code: 'out-of-range',
+      message: `${value} is below the minimum of ${schema.minimum}`,
+    });
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push({
+        path,
+        code: 'too-few-items',
+        message: `expected at least ${schema.minItems} item(s), got ${value.length}`,
+      });
+    }
+    if (schema.items) {
+      value.forEach((item, i) => check(root, schema.items, item, `${path}[${i}]`, errors));
+    }
+  }
+  if (isPlainObject(value)) {
+    for (const required of schema.required ?? []) {
+      if (!Object.hasOwn(value, required)) {
+        // A missing property has no value to test, so the pattern branch above
+        // can never speak for it — yet "required property "id" is missing" is
+        // exactly the finding an author gets for a leaf that mints no accession,
+        // and on its own it names neither the shape to write nor why the field
+        // became required. So the hint is read from the property's OWN grammar
+        // here, through the same `$defs` binding: one fact, quoted wherever the
+        // author meets it.
+        const hint = requiredHint(root, schema, required);
+        errors.push({
+          path: joinPath(path, required),
+          code: 'missing-required',
+          message: hint
+            ? `required property "${required}" is missing — expected ${hint}`
+            : `required property "${required}" is missing`,
+        });
+      }
+    }
+    const properties = schema.properties ?? {};
+    for (const [key, propertyValue] of Object.entries(value)) {
+      if (Object.hasOwn(properties, key)) {
+        check(root, properties[key], propertyValue, joinPath(path, key), errors);
+      } else if (schema.additionalProperties === false) {
+        errors.push({
+          path: joinPath(path, key),
+          code: 'unknown-property',
+          message: `unknown property "${key}" (additive schema evolution edits the schema; unknown keys are typos)`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * PRD §3.5 conventions on one ontology concept — the checks JSON Schema
+ * cannot express record-locally.
+ */
+function conceptConventions(record, basePath, errors) {
+  if (!isPlainObject(record) || !Array.isArray(record.enumerates)) return;
+  const sourceOfTruth = new Set(Array.isArray(record['source-of-truth'])
+    ? record['source-of-truth'].filter((entry) => typeof entry === 'string')
+    : []);
+  record.enumerates.forEach((descriptor, i) => {
+    if (!isPlainObject(descriptor)) return;
+    const descriptorPath = joinPath(basePath, `enumerates[${i}]`);
+    if (Array.isArray(descriptor.values)) {
+      const seen = new Set();
+      descriptor.values.forEach((value, j) => {
+        if (typeof value !== 'string') {
+          errors.push({
+            path: `${descriptorPath}.values[${j}]`,
+            code: 'non-string-enumerates-value',
+            message: `enumerates values are strings compared byte-exact and case-sensitive (§3.5); got ${describe(value)} (${JSON.stringify(value)}) — YAML coerces bare scalars like true/1.0/null, so quote the value in the store file`,
+          });
+        } else if (seen.has(value)) {
+          errors.push({
+            path: `${descriptorPath}.values[${j}]`,
+            code: 'duplicate-enumerates-value',
+            message: `duplicate enumerates value ${JSON.stringify(value)} — values are compared as sets (§3.5), so a duplicate is a malformed descriptor, never a bigger set`,
+          });
+        } else {
+          seen.add(value);
+        }
+      });
+    }
+    if (typeof descriptor.source === 'string' && !sourceOfTruth.has(descriptor.source)) {
+      errors.push({
+        path: `${descriptorPath}.source`,
+        code: 'enumerates-source-not-listed',
+        message: `enumerates source ${JSON.stringify(descriptor.source)} must name a listed source-of-truth entry (§3.5: first entry is the primary owner, the rest are secondary references)`,
+      });
+    }
+  });
+}
+
+/**
+ * §3.4 lifecycle invariants on one log fragment (finding/miss/gap) — the
+ * checks JSON Schema cannot express record-locally. The schema gate matches
+ * what the transition helper (log-entry.js) enforces on its write path, so a
+ * hand-edited fragment can't carry an inconsistent lifecycle:
+ *   - verified ⇔ status resolved (both directions)
+ *   - rejected ⇒ non-empty reason; reason travels only with rejected
+ */
+function lifecycleConventions(record, basePath, errors) {
+  if (!isPlainObject(record) || typeof record.status !== 'string') return;
+  const { status } = record;
+  if (Object.hasOwn(record, 'verified') !== (status === 'resolved')) {
+    errors.push({
+      path: joinPath(basePath, 'verified'),
+      code: 'lifecycle-field-mismatch',
+      message: status === 'resolved'
+        ? 'a resolved entry carries the verified date the validator re-run stamped (§8)'
+        : `verified travels only with status "resolved", not ${JSON.stringify(status)} — re-opening drops it (§8)`,
+    });
+  }
+  const hasReason = typeof record.reason === 'string' && record.reason !== '';
+  if (status === 'rejected' ? !hasReason : Object.hasOwn(record, 'reason')) {
+    errors.push({
+      path: joinPath(basePath, 'reason'),
+      code: 'lifecycle-field-mismatch',
+      message: status === 'rejected'
+        ? 'rejecting requires a non-empty reason — rejections record the reason (§8)'
+        : `reason travels only with status "rejected", not ${JSON.stringify(status)} — re-opening drops it (§8)`,
+    });
+  }
+}
+
+/**
+ * A document candidate's `section` locator addresses ONE coordinate system
+ * (UCS-1160). `lib/coverage.js` emits `{line, endLine}` for line-addressed
+ * sources and `{page, object}` for page-addressed ones (pdf) — never both,
+ * because a section does not have a line number AND a page number in the same
+ * document. So the finding fragment must carry exactly one:
+ *   - NEITHER is an underspecified locator — "somewhere in this document" is
+ *     the coordinate-free claim the locator exists to replace, and reflect
+ *     would have to re-read the document it was meant to avoid opening.
+ *   - BOTH is contradictory — two coordinate systems disagreeing about where
+ *     the section is, with nothing to say which one a reader should trust.
+ *
+ * This is a CONVENTION rather than a schema keyword because the JSON Schema
+ * subset this module interprets (SUPPORTED_KEYWORDS) has no conditionals —
+ * no `oneOf`, `anyOf`, `allOf`, or `not`. Writing one into the schema would
+ * add a keyword nothing enforces, which is silent contract drift: the schema
+ * would promise a rule no validator checks. The rule lives here, where finding
+ * records are already judged, and the schema's description says so.
+ */
+function locatorConventions(record, basePath, errors) {
+  if (!isPlainObject(record) || !isPlainObject(record.section)) return;
+  const { section } = record;
+  const hasLine = Object.hasOwn(section, 'line');
+  const hasPage = Object.hasOwn(section, 'page');
+  if (hasLine === hasPage) {
+    errors.push({
+      path: joinPath(basePath, 'section'),
+      code: 'locator-shape',
+      message: hasLine
+        ? 'a section locator addresses one coordinate system: line (line-addressed sources) or page (pdf), never both — coverage emits exactly one (UCS-1160)'
+        : 'a section locator needs a coordinate: line for line-addressed sources, page for pdf — a locator with neither cannot open the section it addresses (UCS-1160)',
+    });
+  }
+}
+
+/**
+ * Findings carry the lifecycle every log fragment carries, plus the locator
+ * shape only they can have (a miss/gap has no `section`).
+ */
+function findingConventions(record, basePath, errors) {
+  lifecycleConventions(record, basePath, errors);
+  locatorConventions(record, basePath, errors);
+}
+
+/** Record-local convention checks, keyed by kind (one lookup, both entry points). */
+const CONVENTIONS = Object.freeze({
+  'ontology-concept': conceptConventions,
+  finding: findingConventions,
+  miss: lifecycleConventions,
+  gap: lifecycleConventions,
+});
+
+/**
+ * schema-version defects where the envelope legitimately carries the key are
+ * normalized to `invalid-schema-version`. Only value defects qualify — an
+ * `unknown-property` at that path means the key is misplaced (it belongs on
+ * the store-file envelope), which is the opposite remediation.
+ */
+const SCHEMA_VERSION_VALUE_DEFECTS = new Set(['wrong-type', 'missing-required', 'out-of-range']);
+
+/**
+ * Dedupe (convention codes own their paths over generic schema codes),
+ * normalize schema-version value defects to one code, and stable-sort.
+ */
+function finish(errors, { fileEnvelope }) {
+  const conventionPaths = new Set(
+    errors
+      .filter((e) => e.code === 'non-string-enumerates-value')
+      .map((e) => e.path),
+  );
+  const cleaned = errors
+    .filter((e) => e.code === 'non-string-enumerates-value' || !conventionPaths.has(e.path))
+    .map((e) => (fileEnvelope && e.path === 'schema-version' && SCHEMA_VERSION_VALUE_DEFECTS.has(e.code)
+      ? { ...e, code: 'invalid-schema-version', message: `${e.message} — every store file carries an integer schema-version >= 1 (§3.5)` }
+      : e));
+  cleaned.sort((a, b) => compare(a.path, b.path) || compare(a.code, b.code));
+  return { ok: cleaned.length === 0, errors: cleaned };
+}
+
+function runConventions(kind, record, basePath, errors) {
+  CONVENTIONS[kind]?.(record, basePath, errors);
+}
+
+/**
+ * Validate a single record of the given kind against its shipped schema.
+ * For one-record-per-file kinds (knowledge-leaf, finding, catalog, rules)
+ * the record is the whole store file, schema-version included.
+ *
+ * @param {string} kind one of KINDS
+ * @param {unknown} record the YAML document (or entry), parsed with types intact
+ * @returns {{ ok: boolean, errors: Array<{path: string, code: string, message: string}> }}
+ */
+export function validateRecord(kind, record) {
+  const schema = schemaFor(kind);
+  const errors = [];
+  check(schema, schema, record, '', errors);
+  runConventions(kind, record, '', errors);
+  // One-record-per-file kinds ARE the store file (schema-version at the root);
+  // multi-entry kinds carry it on the envelope, not the record.
+  return finish(errors, { fileEnvelope: !schema.$defs?.storeFile });
+}
+
+/**
+ * Validate a whole store file of the given kind. Multi-entry kinds
+ * (ontology-concept, decision-entry) are wrapped in the $defs/storeFile
+ * envelope ({ schema-version, entries: [...] }); one-record-per-file kinds
+ * validate as the record itself.
+ *
+ * @param {string} kind one of KINDS
+ * @param {unknown} doc the parsed store file
+ * @returns {{ ok: boolean, errors: Array<{path: string, code: string, message: string}> }}
+ */
+export function validateStoreFile(kind, doc) {
+  const schema = schemaFor(kind);
+  const fileSchema = schema.$defs?.storeFile;
+  if (!fileSchema) return validateRecord(kind, doc);
+  const errors = [];
+  check(schema, fileSchema, doc, '', errors);
+  if (isPlainObject(doc) && Array.isArray(doc.entries)) {
+    doc.entries.forEach((entry, i) => runConventions(kind, entry, `entries[${i}]`, errors));
+  }
+  return finish(errors, { fileEnvelope: true });
+}

package/payload/engine/log-entry.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * engine/log-entry.js — the entry shim (UCS-956).
+ *
+ * This file statically imports NOTHING. That is its entire job.
+ *
+ * Node exits 1 on an unhandled ES module load error, and exit 1 means FINDINGS
+ * (PRD §5). A SyntaxError in a lib/ module, or a missing `js-yaml`, must not
+ * tell an agent that the check ran and found problems. So the engine is reached
+ * only through `import()`, where a load failure is an ordinary catchable
+ * rejection rather than a process-level crash.
+ *
+ * Both specifiers are string literals naming the engine's own files. D-014
+ * forbids importing REPO CONTENT — the client's code — and nothing here can
+ * name it: there is no variable to point somewhere else.
+ *
+ * The command lives in commands/log-entry.js. Its invocation path is unchanged.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/log-entry.js'),
+  ]);
+  // exitCode, never process.exit(): exit() drops queued async stdout writes, so
+  // piped --json output would truncate at the pipe buffer — corrupt output
+  // wearing a clean exit code. Node exits on its own once stdout drains.
+  process.exitCode = await boot('log-entry', command);
+} catch (error) {
+  // The engine could not be loaded, so no check ran. Exit 2 — never 1.
+  // Hardcoded, because reading it from lib/exit-codes.js is the very thing
+  // that may have just failed.
+  process.stderr.write(`log-entry: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/payload/engine/phoenix.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * engine/phoenix.js — the entry shim (UCS-956).
+ *
+ * This file statically imports NOTHING. That is its entire job.
+ *
+ * Node exits 1 on an unhandled ES module load error, and exit 1 means FINDINGS
+ * (PRD §5). A SyntaxError in a lib/ module, or a missing `js-yaml`, must not
+ * tell an agent that the check ran and found problems. So the engine is reached
+ * only through `import()`, where a load failure is an ordinary catchable
+ * rejection rather than a process-level crash.
+ *
+ * The stakes are highest here: this is the one command that WRITES to a store
+ * (UCS-1154). A load failure that wore exit 1 would read as "the event was
+ * refused with findings" — which is the one outcome that also means "nothing
+ * was written", and would be indistinguishable from an event that half-applied.
+ *
+ * Both specifiers are string literals naming the engine's own files. D-014
+ * forbids importing REPO CONTENT — the client's code — and nothing here can
+ * name it: there is no variable to point somewhere else.
+ *
+ * The command lives in commands/phoenix.js. Its invocation path is unchanged.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/phoenix.js'),
+  ]);
+  // exitCode, never process.exit(): exit() drops queued async stdout writes, so
+  // piped --json output would truncate at the pipe buffer — corrupt output
+  // wearing a clean exit code. Node exits on its own once stdout drains.
+  process.exitCode = await boot('phoenix', command);
+} catch (error) {
+  // The engine could not be loaded, so no event ran. Exit 2 — never 1.
+  // Hardcoded, because reading it from lib/exit-codes.js is the very thing
+  // that may have just failed.
+  process.stderr.write(`phoenix: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/payload/engine/preflight.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * engine/preflight.js — the entry shim (UCS-956).
+ *
+ * This file statically imports NOTHING. That is its entire job.
+ *
+ * Node exits 1 on an unhandled ES module load error, and exit 1 means FINDINGS
+ * (PRD §5). A SyntaxError in a lib/ module, or a missing `js-yaml`, must not
+ * tell an agent that the check ran and found problems. So the engine is reached
+ * only through `import()`, where a load failure is an ordinary catchable
+ * rejection rather than a process-level crash.
+ *
+ * Both specifiers are string literals naming the engine's own files. D-014
+ * forbids importing REPO CONTENT — the client's code — and nothing here can
+ * name it: there is no variable to point somewhere else.
+ *
+ * The command lives in commands/preflight.js. Its invocation path is unchanged.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/preflight.js'),
+  ]);
+  // exitCode, never process.exit(): exit() drops queued async stdout writes, so
+  // piped --json output would truncate at the pipe buffer — corrupt output
+  // wearing a clean exit code. Node exits on its own once stdout drains.
+  process.exitCode = await boot('preflight', command);
+} catch (error) {
+  // The engine could not be loaded, so no check ran. Exit 2 — never 1.
+  // Hardcoded, because reading it from lib/exit-codes.js is the very thing
+  // that may have just failed.
+  process.stderr.write(`preflight: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/payload/engine/resolve.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * engine/resolve.js — the entry shim (UCS-956).
+ *
+ * This file statically imports NOTHING. That is its entire job.
+ *
+ * Node exits 1 on an unhandled ES module load error, and exit 1 means FINDINGS
+ * (PRD §5). A SyntaxError in a lib/ module, or a missing `js-yaml`, must not
+ * tell an agent that the check ran and found problems. So the engine is reached
+ * only through `import()`, where a load failure is an ordinary catchable
+ * rejection rather than a process-level crash.
+ *
+ * Both specifiers are string literals naming the engine's own files. D-014
+ * forbids importing REPO CONTENT — the client's code — and nothing here can
+ * name it: there is no variable to point somewhere else.
+ *
+ * The command lives in commands/resolve.js. Its invocation path is unchanged.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/resolve.js'),
+  ]);
+  // exitCode, never process.exit(): exit() drops queued async stdout writes, so
+  // piped --json output would truncate at the pipe buffer — corrupt output
+  // wearing a clean exit code. Node exits on its own once stdout drains.
+  process.exitCode = await boot('resolve', command);
+} catch (error) {
+  // The engine could not be loaded, so no check ran. Exit 2 — never 1.
+  // Hardcoded, because reading it from lib/exit-codes.js is the very thing
+  // that may have just failed.
+  process.stderr.write(`resolve: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/payload/engine/survey-map.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * engine/survey-map.js — the entry shim (UCS-956).
+ *
+ * This file statically imports NOTHING. That is its entire job.
+ *
+ * Node exits 1 on an unhandled ES module load error, and exit 1 means FINDINGS
+ * (PRD §5). A SyntaxError in a lib/ module, or a missing `js-yaml`, must not
+ * tell an agent that the check ran and found problems. So the engine is reached
+ * only through `import()`, where a load failure is an ordinary catchable
+ * rejection rather than a process-level crash.
+ *
+ * Both specifiers are string literals naming the engine's own files. D-014
+ * forbids importing REPO CONTENT — the client's code — and nothing here can
+ * name it: there is no variable to point somewhere else.
+ *
+ * The command lives in commands/survey-map.js. Its invocation path is unchanged.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/survey-map.js'),
+  ]);
+  // exitCode, never process.exit(): exit() drops queued async stdout writes, so
+  // piped --json output would truncate at the pipe buffer — corrupt output
+  // wearing a clean exit code. Node exits on its own once stdout drains.
+  process.exitCode = await boot('survey-map', command);
+} catch (error) {
+  // The engine could not be loaded, so no check ran. Exit 2 — never 1.
+  // Hardcoded, because reading it from lib/exit-codes.js is the very thing
+  // that may have just failed.
+  process.stderr.write(`survey-map: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}