unknown-knowledge 2.1.0

package/payload/engine/commands/audit.js

@@ -0,0 +1,289 @@
+/**
+ * Reverse audit (KK-12) — the code→store scan (PRD §4). ADVISORY by design:
+ * it grows the map proposal-first — every unmatched anchor arrives as a
+ * drafted concept YAML ready for human review — and is never a CI gate.
+ *
+ *   node payload/engine/audit.js [--root <dir>] [--json] [--fail-on-findings]
+ *                                [--today <YYYY-MM-DD>] [--stale-days <n>]
+ *
+ * The scan surface IS the survey map (KK-25): git-tracked files, built-in
+ * denylist, anchor candidates from the shared signature table — and the
+ * survey-scope.yaml honor-it contract, so excluded areas are never rescanned
+ * (widening happens via retrieval-miss findings, never re-litigation). A
+ * malformed scope file is an engine failure (exit 2), never a silently
+ * ignored boundary.
+ *
+ * Findings (all advisory):
+ *   unmatched-anchor     an anchor candidate no concept points at — exports,
+ *                        registries, config keys, module directories. Carries
+ *                        `draft`: a proposed §3.1 concept record. The draft id
+ *                        is a deliberate NON-minted placeholder (K-XXX):
+ *                        pasting a draft unedited must fail validation, never
+ *                        silently mint an id outside the owning class's range
+ *                        (§3.5). Matching is pointer-prefix: a concept whose
+ *                        source-of-truth names a folder covers its subtree
+ *                        ("point at a folder for identity, at a file for
+ *                        facts").
+ *   stale-last-verified  an active concept whose last-verified predates
+ *                        --today by more than --stale-days (default 90).
+ *                        Checked ONLY when --today is given: diffable output
+ *                        never reads the wall clock (D-012); without --today
+ *                        the check reports itself skipped, never silently.
+ *
+ * The kit's own zone is never audited — the map must not be told to map
+ * itself. The store dir is discovered: `<root>/ontology` (stores at the scan
+ * root, the engine-fixture layout) or `<root>/unknown-knowledge/` (the D-016
+ * post-init default). A repo with no stores at all still audits — every
+ * anchor is a proposal.
+ *
+ * Suppressions (KK-27, D-013 §11.1 minimal core): a client-zone
+ * `suppressions.yaml` in the kit zone — `<kitRoot>/suppressions.yaml`, i.e.
+ * next to the stores (unknown-knowledge/suppressions.yaml in the D-016
+ * layout; at the scan root, beside survey-scope.yaml, when the stores live
+ * there). A YAML list of entries, each STRICTLY
+ * { term, sourcePath, reason, date } — exact match only, no patterns, no
+ * expiry (deferred §11.1). What the fields match, per finding code:
+ *   unmatched-anchor     the anchor path is the identity: `sourcePath` must
+ *                        equal the finding's path exactly, and `term` must
+ *                        equal the term the draft would carry (the path's
+ *                        basename without extension) — so a suppression stops
+ *                        matching the moment the file moves.
+ *   stale-last-verified  the concept is the identity and has no file path:
+ *                        BOTH `term` and `sourcePath` must equal the concept
+ *                        id (e.g. K-101) — one strict shape, no second
+ *                        entry grammar.
+ * Suppressed findings leave the finding list (and never trip
+ * --fail-on-findings); the human report shows the suppressed count, the JSON
+ * report the full stable-sorted suppressed list. Suppression is
+ * advisory-side and FAILS OPEN — the opposite of survey-scope.yaml: a
+ * malformed entry (or an unreadable/unparseable file) produces a warning and
+ * suppresses nothing, so the findings it would have hidden resurface; it is
+ * never an engine failure. A missing file is a plain no-op. Engine-internal
+ * noise heuristics (denylist, the "." root filter) stay engine-side — the
+ * client file is for client judgments only.
+ *
+ * Single health model (KK-04): a store with error-severity diagnostics is an
+ * engine failure (exit 2) — matching candidates against broken stores would
+ * misreport, and a check that never ran is a blocking defect, never a silent
+ * pass (PRD §5).
+ *
+ * Exit codes (PRD §5): 0 ran (findings are advisory), 2 engine failure.
+ * `--fail-on-findings` opts a HUMAN run into exit 1 on findings — never a
+ * shipped CI default (governance test lands with KK-27). Output is
+ * deterministic and stable-sorted; no wall-clock timestamps (drafted dates
+ * come from --today or are omitted).
+ */
+import process from 'node:process';
+import { readFileSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { dump, load } from 'js-yaml';
+import { buildSurveyMap } from './survey-map.js';
+import { locateKit, SCOPE_FILE } from '../lib/kit-root.js';
+import { loadSuppressions, partitionBySuppression, suppressibleBy, SUPPRESSIONS_FILE } from '../lib/suppressions.js';
+import { daysBetween, isCalendarDate, ISO_DATE } from '../lib/iso-date.js';
+import { loadStores, storeHealth } from '../lib/load-stores.js';
+import { compare } from '../lib/validate-record.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+import { parseArgs as parseFlags, rethrowIfBug, UsageError } from '../lib/cli.js';
+
+export const USAGE = 'usage: node payload/engine/audit.js [--root <dir>] [--json] [--fail-on-findings] [--today <YYYY-MM-DD>] [--stale-days <n>]';
+const STALE_DAYS_DEFAULT = 90;
+// Kit layout — where the stores live and what counts as kit zone — is
+// lib/kit-root.js's one job (UCS-934). The audit used to answer that itself,
+// with the opposite tie-break, and so read a different Store than every other
+// surface whenever a repo carried both layouts.
+export { SUPPRESSIONS_FILE };
+
+
+const underPrefix = (path, prefix) => path === prefix || path.startsWith(`${prefix}/`);
+
+/** Pointer-prefix matching: a folder pointer covers its subtree (§3.1). */
+function matchesPointer(path, pointerPaths) {
+  return pointerPaths.some((p) => underPrefix(path, p));
+}
+
+/** Drafted §3.1 concept record for one unmatched anchor (proposal-first). */
+function draftConcept(path, kinds, today) {
+  const record = {
+    // NOT a mintable K-NNN: the human mints the id inside the owning class's
+    // range at PR time (§3.5) — a paste-unedited draft must fail validation.
+    id: 'K-XXX',
+    term: basename(path, extname(path)),
+    class: 'TODO — owning class file; mint the id in its declared range (§3.5)',
+    summary: `TODO — drafted by reverse audit: ${kinds.join(', ')} anchor with no concept pointing at it`,
+    'source-of-truth': [path],
+    status: 'draft',
+    ...(today ? { 'last-verified': today } : {}),
+  };
+  return dump(record, { lineWidth: -1 });
+}
+
+
+/**
+ * Run the reverse audit: survey the repo at `root` (scope-honoring), load the
+ * stores, and report unmatched anchors + stale verifications. Throws on
+ * engine failure (unhealthy store, malformed scope, no git).
+ */
+export function runAudit(root, { today = null, staleDays = STALE_DAYS_DEFAULT } = {}) {
+  const map = buildSurveyMap(root);
+  const { kitRoot, kitPrefixes } = locateKit(root);
+  const model = loadStores(kitRoot);
+
+  const { errors } = storeHealth(model);
+  if (errors.length > 0) {
+    const detail = errors.map((d) => `  ${d.code}  ${d.file}${d.path ? `  ${d.path}` : ''}  ${d.message}`);
+    throw new Error(`the store loader reported ${errors.length} error(s) — auditing against broken stores would misreport (single health model, PRD §4):\n${detail.join('\n')}`);
+  }
+
+  const pointerPaths = [...model.pointers.keys()];
+  // One finding per path: a file matching several signatures is one anchor
+  // to propose, never a cascade of near-identical drafts.
+  const byPath = new Map();
+  let matched = 0;
+  for (const { kind, path } of map.candidates) {
+    if (path === '.') continue; // engine-side noise heuristic (D-013): a draft proposing "the repo root is a concept" is never actionable
+    if (kitPrefixes.some((p) => underPrefix(path, p))) continue; // the map never maps itself
+    if (matchesPointer(path, pointerPaths)) {
+      matched += 1;
+      continue;
+    }
+    if (!byPath.has(path)) byPath.set(path, []);
+    if (!byPath.get(path).includes(kind)) byPath.get(path).push(kind);
+  }
+
+  const findings = [];
+  for (const [path, kinds] of byPath) {
+    kinds.sort(compare);
+    findings.push(suppressibleBy({
+      code: 'unmatched-anchor', severity: 'advisory', path, kinds,
+      message: `no concept points at this ${kinds.join('/')} anchor — draft below is ready for human review`,
+      draft: draftConcept(path, kinds, today),
+      // A steward suppresses an anchor by the term the draft would have used
+      // and the path it sits at — the two things they actually read.
+    }, { term: basename(path, extname(path)), sourcePath: path }));
+  }
+
+  if (today) {
+    for (const { id, record } of model.concepts.values()) {
+      if (record.status !== 'active') continue; // draft/proposed are unverified by definition; deprecated needs no re-verification
+      const verified = record['last-verified'];
+      if (typeof verified !== 'string' || !ISO_DATE.test(verified)) continue; // presence/shape is KK-05's check
+      const days = daysBetween(verified, today);
+      if (days > staleDays) {
+        findings.push(suppressibleBy({
+          code: 'stale-last-verified', severity: 'advisory', concept: id,
+          'last-verified': verified, days, 'stale-days': staleDays,
+          message: `last verified ${days} day(s) ago — re-verify or deprecate (§3.1 rung 4)`,
+          // There is no anchor path here; the concept id names the finding in
+          // both fields, so one entry suppresses one concept's staleness.
+        }, { term: id, sourcePath: id }));
+      }
+    }
+  }
+
+  findings.sort((a, b) =>
+    compare(a.code, b.code) || compare(a.path ?? '', b.path ?? '') || compare(a.concept ?? '', b.concept ?? ''));
+
+  // Client-zone suppressions (KK-27): exact-match filter, fails open. Only
+  // well-formed entries suppress; the sort above keeps both lists stable. Each
+  // finding carries the identity it would be suppressed by, so nothing here
+  // has to know what codes exist.
+  const { entries: suppressionEntries, warnings } = loadSuppressions(kitRoot);
+  const { kept, suppressed } = partitionBySuppression(findings, suppressionEntries);
+
+  return {
+    checks: {
+      'unmatched-anchor': 'checked',
+      'stale-last-verified': today
+        ? `checked against --today ${today} (stale after ${staleDays} day(s))`
+        : 'skipped — pass --today YYYY-MM-DD to enable; diffable output never reads the wall clock (D-012)',
+    },
+    scope: map.scope.source === SCOPE_FILE ? SCOPE_FILE : 'unscoped (no confirmed survey-scope.yaml)',
+    counts: {
+      candidates: map.candidates.length,
+      matched,
+      findings: kept.length,
+      suppressed: suppressed.length,
+    },
+    findings: kept,
+    // Full suppressed list in JSON output (stable-sorted, same order as
+    // findings); the human renderer shows only the count. Warnings surface
+    // in both — a malformed entry must never vanish silently.
+    suppressions: { warnings, suppressed },
+  };
+}
+
+// ------------------------------------------------------------- CLI plumbing
+
+function parseArgs(argv) {
+  const { options } = parseFlags(argv, {
+    boolean: ['json', 'fail-on-findings'],
+    value: ['root', 'today', 'stale-days'],
+  });
+  const opts = {
+    root: resolve(options.root ?? process.cwd()),
+    json: !!options.json,
+    // Advisory by design (D-013): findings never gate. Only a HUMAN opting in
+    // with --fail-on-findings turns them into a non-zero exit, and it is never
+    // a shipped CI default.
+    failOnFindings: !!options['fail-on-findings'],
+    today: options.today ?? null,
+    staleDays: STALE_DAYS_DEFAULT,
+  };
+  if (opts.today !== null && !isCalendarDate(opts.today)) {
+    // Not just the shape: Date.parse rolls 2026-02-30 forward to March 2nd, and
+    // staleness would then be measured from a day the caller never named.
+    throw new UsageError(`--today must be a real calendar date (YYYY-MM-DD), got ${JSON.stringify(opts.today)}`);
+  }
+  if (options['stale-days'] !== undefined) {
+    opts.staleDays = Number(options['stale-days']);
+    if (!Number.isInteger(opts.staleDays) || opts.staleDays < 0) {
+      throw new UsageError(`--stale-days must be a non-negative integer, got ${JSON.stringify(options['stale-days'])}`);
+    }
+  }
+  return opts;
+}
+
+function renderHuman(payload) {
+  const lines = [];
+  const n = payload.counts.findings;
+  const s = payload.counts.suppressed;
+  lines.push(
+    `audit (advisory — proposals for human review, never a gate): `
+    + `${payload.counts.candidates} candidate(s), ${payload.counts.matched} matched, `
+    + `${n} finding${n === 1 ? '' : 's'}`
+    + (s > 0 ? `, ${s} suppressed (${SUPPRESSIONS_FILE})` : ''),
+    `scope: ${payload.scope}`,
+    `stale check: ${payload.checks['stale-last-verified']}`,
+  );
+  for (const w of payload.suppressions.warnings) lines.push(`warning: ${w}`);
+  for (const f of payload.findings) {
+    lines.push('', `${f.code}  ${f.path ?? f.concept}`, `  ${f.message}`);
+    if (f.draft) lines.push(...f.draft.trimEnd().split('\n').map((l) => `  | ${l}`));
+  }
+  if (n === 0) lines.push('', 'nothing to propose — every anchor is mapped');
+  return lines;
+}
+
+export function main(argv) {
+  const opts = parseArgs(argv); // a UsageError reaches the harness
+
+  let payload;
+  try {
+    payload = runAudit(opts.root, { today: opts.today, staleDays: opts.staleDays });
+  } catch (error) {
+    rethrowIfBug(error); // a bug is not a refusal — the harness prints its stack
+    // An EXPECTED engine failure (malformed scope, unhealthy store, no git):
+    // the audit never ran to completion — exit 2, never a plausible report.
+    // These are anticipated conditions with actionable messages, so they say
+    // what happened rather than dumping a stack; an UNEXPECTED throw anywhere
+    // else reaches the harness, which does dump one.
+    process.stderr.write(`audit: ${error.message}\n`);
+    return EXIT_CODES.FAILURE;
+  }
+
+  const lines = opts.json ? [JSON.stringify(payload, null, 2)] : renderHuman(payload);
+  process.stdout.write(`${lines.join('\n').replace(/\n+$/, '')}\n`);
+  // Advisory (D-013): findings alone never gate. Only the human opt-in does.
+  return opts.failOnFindings && payload.counts.findings > 0 ? EXIT_CODES.FINDINGS : EXIT_CODES.CLEAN;
+}

package/payload/engine/commands/derive.js

@@ -0,0 +1,334 @@
+/**
+ * The derived layer (UCS-1158) — generate the browse trees and resolution index.
+ *
+ * The second engine command that writes, and it follows the first one's shape
+ * (phoenix, UCS-1154): the read-only verb is the DEFAULT, and writing takes a
+ * word typed on purpose.
+ *
+ *   --check   (default) compute the layer and compare it to what is on disk.
+ *   --write   compute the layer and write it, replacing the directory whole.
+ *
+ * What makes this command different from phoenix is what it is allowed to
+ * destroy. Phoenix rewrites authored leaves, so its gate is total and a single
+ * finding refuses the event. This command writes only into `knowledge/derived/`,
+ * a directory whose entire contract is that deleting it loses nothing — so the
+ * dangerous direction is reversed. The risk is not that a write destroys
+ * something; it is that something starts DEPENDING on the output, at which
+ * point the layer is no longer disposable and the store has quietly acquired a
+ * second source of truth. Three things hold that line:
+ *
+ *   - the loader skips `derived/` by name, so no generated artifact can enter
+ *     the model or affect store health (lib/load-stores.js, DERIVED_DIR);
+ *   - `--check` exits FINDINGS when the on-disk layer differs from the computed
+ *     one, so a stale or hand-edited artifact is reported rather than believed;
+ *   - the round-trip test deletes the directory, regenerates, and asserts the
+ *     bytes are identical — which fails the moment anything unreproducible
+ *     starts living here.
+ *
+ * `--check` returning FINDINGS is the right code rather than FAILURE: the check
+ * RAN, and what it found is a real defect its author fixes by re-running with
+ * --write. Exit 2 stays reserved for a run that never happened.
+ *
+ * TIME VERDICTS NEED --today, ALWAYS INJECTED. The trees annotate stale leaves,
+ * and staleness is measured from an injected date — never the wall clock (D-012,
+ * PRD §5). Without `--today` the time verdicts are `skipped` and every artifact
+ * SAYS so in its header; it is never a silent pass, and the artifacts stay
+ * byte-stable across runs, which is the property baseline diffing rests on.
+ * That also means `--today` changes the output: two runs on different injected
+ * dates legitimately differ, and the check compares against whatever date this
+ * invocation named.
+ */
+import {
+  mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { locateKitRoot } from '../lib/kit-root.js';
+import { loadStores, storeHealth, healthSummary, DERIVED_DIR } from '../lib/load-stores.js';
+import {
+  AXES, DERIVED_BANNER, RECALL_SLOT, demotionsFor, deriveArtifacts,
+} from '../lib/derived.js';
+import { compare } from '../lib/validate-record.js';
+import { timeCheckStatus } from '../lib/time-verdicts.js';
+import { isCalendarDate } from '../lib/iso-date.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+import { parseArgs as parseFlags, rethrowIfBug, UsageError } from '../lib/cli.js';
+
+export const USAGE = 'usage: node payload/engine/derive.js [--write] [--check] [--root <dir>] [--today <YYYY-MM-DD>] [--json]';
+
+function parseArgs(argv) {
+  const { options } = parseFlags(argv, {
+    boolean: ['json', 'write', 'check'],
+    value: ['root', 'today'],
+  });
+  // Naming both verbs states two intentions whose difference is whether the
+  // directory gets rewritten. Refusing is the only reading that cannot silently
+  // pick the writing one.
+  if (options.write && options.check) {
+    throw new UsageError('--write and --check are the two verbs; name one');
+  }
+  const today = options.today ?? null;
+  if (today !== null && !isCalendarDate(today)) {
+    // The shape AND the calendar: 2026-02-30 matches the pattern and names no
+    // day, and an age measured from it is a number nobody's calendar agrees
+    // with (UCS-957). Same refusal the resolver makes.
+    throw new UsageError(`--today must be a real calendar date (YYYY-MM-DD), got ${JSON.stringify(today)}`);
+  }
+  return {
+    root: resolve(options.root ?? '.'),
+    json: !!options.json,
+    write: !!options.write,
+    today,
+  };
+}
+
+/**
+ * ENOENT is the ONLY read failure that means "this is not there".
+ *
+ * Every other errno means the engine could not LOOK: EACCES (no permission),
+ * EIO (the disk failed), EMFILE (out of descriptors), ENOTDIR (something on the
+ * path is a file). Reading any of those as an empty layer would let `--check`
+ * report the layer cleanly regenerable when nothing was actually examined —
+ * the silent pass the exit-code contract exists to prevent (PRD §5). A check
+ * that never ran is a blocking defect, so those rethrow and surface as exit 2.
+ *
+ * ENOTDIR is deliberately on the ERROR side of that line. If `knowledge/derived`
+ * exists as a FILE, the layer is not absent — it is corrupted, and `--write`
+ * would have to delete a file the engine never created. Reporting that as
+ * `derived-missing` would tell an author to regenerate, when what they need to
+ * know is that something is squatting on the directory's name.
+ *
+ * @param {unknown} error a caught filesystem error
+ * @returns {boolean} whether it means the path simply does not exist
+ */
+const isAbsent = (error) => error?.code === 'ENOENT';
+
+/**
+ * Every file currently under the derived directory, relative to the store root.
+ *
+ * A missing directory reads as no files, not as an error: the layer being absent
+ * is the ordinary state of a fresh clone (it is engine output), and it is the
+ * exact state the round-trip test creates on purpose. Every OTHER failure
+ * rethrows — see `isAbsent`.
+ *
+ * @param {string} root the store root
+ * @returns {string[]} sorted relative paths
+ * @throws when the directory exists but could not be read
+ */
+function existingArtifacts(root) {
+  const dir = join(root, 'knowledge', DERIVED_DIR);
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true, recursive: true });
+  } catch (error) {
+    if (isAbsent(error)) return [];
+    throw error;
+  }
+  return entries
+    .filter((e) => e.isFile())
+    .map((e) => {
+      // `parentPath` is absolute; make it relative to the store root and
+      // forward-slashed, so the comparison is platform-identical.
+      const rel = join(e.parentPath ?? dir, e.name).slice(root.length + 1);
+      return rel.split(/[\\/]/).join('/');
+    })
+    .sort(compare);
+}
+
+/**
+ * Compare the computed layer against what is on disk.
+ *
+ * Three defect classes, each its own finding code, because they call for
+ * different edits: a MISSING artifact means the layer was never generated (or
+ * was partly deleted), a STALE one means the store changed since it was, and an
+ * UNEXPECTED one means a file is living in the derived directory that no axis
+ * generates — which is the drift that would make the layer load-bearing.
+ *
+ * @param {string} root the store root
+ * @param {Array<{path: string, text: string}>} artifacts the computed layer
+ * @returns {Array<object>} findings, sorted
+ */
+function checkArtifacts(root, artifacts) {
+  const findings = [];
+  const expected = new Set(artifacts.map((a) => a.path));
+  for (const artifact of artifacts) {
+    let actual;
+    try {
+      actual = readFileSync(join(root, artifact.path), 'utf8');
+    } catch (error) {
+      // Same rule as `existingArtifacts`: only ENOENT is a missing artifact.
+      // An unreadable file is not an absent one, and calling it `derived-missing`
+      // would send an author to regenerate a layer whose real problem is that
+      // the engine could not read it.
+      if (!isAbsent(error)) throw error;
+      findings.push({
+        severity: 'error',
+        code: 'derived-missing',
+        file: artifact.path,
+        message: 'this derived artifact is absent — regenerate the layer with --write (nothing is lost by doing so)',
+      });
+      continue;
+    }
+    if (actual !== artifact.text) {
+      findings.push({
+        severity: 'error',
+        code: 'derived-stale',
+        file: artifact.path,
+        message: 'this derived artifact differs from what the store projects — the leaves changed, '
+          + 'or the file was hand-edited; regenerate with --write, and never edit a derived file',
+      });
+    }
+  }
+  for (const found of existingArtifacts(root)) {
+    if (expected.has(found)) continue;
+    findings.push({
+      severity: 'error',
+      code: 'derived-unexpected',
+      file: found,
+      message: 'no axis generates this file, so regenerating the layer would delete it — '
+        + 'nothing may live in the derived directory that the engine does not produce',
+    });
+  }
+  return findings.sort((a, b) => compare(a.file, b.file) || compare(a.code, b.code));
+}
+
+/**
+ * Replace the derived directory with the computed artifacts.
+ *
+ * Removes the whole directory first, deliberately. A merge-write would leave
+ * behind artifacts from a previous axis table — a tree for an axis that no
+ * longer exists, still looking authoritative — and the layer's promise is that
+ * what is there is what the store currently projects. Removing first is safe
+ * precisely because this directory holds nothing that is not regenerable, which
+ * is the same property the round-trip test asserts.
+ *
+ * @param {string} root the store root
+ * @param {Array<{path: string, text: string}>} artifacts
+ */
+function writeArtifacts(root, artifacts) {
+  rmSync(join(root, 'knowledge', DERIVED_DIR), { recursive: true, force: true });
+  for (const artifact of artifacts) {
+    const file = join(root, artifact.path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, artifact.text);
+  }
+}
+
+function render(payload) {
+  const { verb, findings, artifacts, counts } = payload;
+  const lines = [];
+  if (findings.length) {
+    lines.push(
+      `derive -> ${findings.length} finding(s) — the derived layer is not what the store projects`,
+    );
+    for (const f of findings) lines.push(`${f.severity}  ${f.code}  ${f.file}`, `    ${f.message}`);
+    lines.push('regenerate with --write; a derived artifact is never hand-edited');
+  } else {
+    lines.push(verb === 'write'
+      ? `derive -> WROTE ${artifacts.length} artifact(s) — ${counts.leaves} leaf/leaves across ${payload.axes.length} axes`
+      : `derive -> up to date — ${artifacts.length} artifact(s) match what the store projects`);
+  }
+  for (const a of artifacts) lines.push(`  ${a}`);
+  lines.push(`time verdicts: ${payload['time-check']}`);
+  lines.push(`demoted leaves: ${counts.demoted} (annotated in every tree, never hidden)`);
+  lines.push(`embedding recall: ${RECALL_SLOT.status} — ${RECALL_SLOT['out-of-scope-here']}`);
+  lines.push(DERIVED_BANNER);
+  return lines;
+}
+
+/**
+ * CLI entry. Exit codes per the engine contract (PRD §5): 0 the layer is
+ * up to date (or was written), 1 the on-disk layer differs from what the store
+ * projects, 2 the run never happened.
+ *
+ * @param {string[]} argv
+ * @returns {number} an exit code
+ */
+export function main(argv) {
+  const opts = parseArgs(argv); // a UsageError reaches the harness
+
+  let model;
+  try {
+    model = loadStores(locateKitRoot(opts.root));
+  } catch (error) {
+    rethrowIfBug(error); // a bug is not a refusal — the harness prints its stack
+    process.stderr.write(`derive: ${error.message}\n`);
+    return EXIT_CODES.FAILURE;
+  }
+
+  // A store the loader rejects cannot be projected: the trees would file leaves
+  // by facets no check approved, and under --write we would publish them. The
+  // derived layer's claim is that it says what the store says, and a store that
+  // does not load has not said anything yet. Exit 2 — the generation never ran.
+  if (!model.ok) {
+    const health = storeHealth(model);
+    process.stderr.write(
+      `derive: the store has ${health.errors.length} loader error(s); nothing is projected from a store that does not load\n`,
+    );
+    for (const d of health.errors) {
+      process.stderr.write(`  ${d.code}  ${d.file}${d.path ? `  ${d.path}` : ''}  ${d.message}\n`);
+    }
+    return EXIT_CODES.FAILURE;
+  }
+
+  const artifacts = deriveArtifacts(model.leaves.values(), opts.today);
+
+  let findings = [];
+  if (opts.write) {
+    try {
+      writeArtifacts(model.root, artifacts);
+    } catch (error) {
+      rethrowIfBug(error); // a bug is not a refusal — the harness prints its stack
+      // A filesystem failure part-way through leaves the directory incomplete.
+      // Exit 2, never 1: the generation did not finish, and an agent reading 1
+      // would conclude the layer was cleanly checked and found wanting. The
+      // remedy is the same either way and costs nothing — re-run with --write,
+      // because nothing here is authored.
+      process.stderr.write(
+        `derive: writing the derived layer FAILED part-way through — the directory is incomplete\n`
+        + `  ${error.message}\n`
+        + `  re-run with --write; the derived layer is regenerable, so nothing is lost\n`,
+      );
+      return EXIT_CODES.FAILURE;
+    }
+  } else {
+    try {
+      findings = checkArtifacts(model.root, artifacts);
+    } catch (error) {
+      rethrowIfBug(error); // a bug is not a refusal — the harness prints its stack
+      // The engine could not READ the layer — a permission, I/O, or ENOTDIR
+      // failure, never a merely absent directory (that returns cleanly, and is
+      // the ordinary state of a fresh clone). Exit 2, never 1: nothing was
+      // compared, so there are no findings to report, and an agent reading 1
+      // would conclude the layer had been checked and found wanting.
+      process.stderr.write(
+        `derive: the derived layer could not be READ, so nothing was checked\n`
+        + `  ${error.message}\n`
+        + `  this is not a stale layer — the engine never got to look; fix the path and re-run\n`,
+      );
+      return EXIT_CODES.FAILURE;
+    }
+  }
+
+  // Counted off the same predicate the trees annotate with, so the summary
+  // cannot report a different number of demoted leaves than the artifacts show.
+  let demoted = 0;
+  for (const entry of model.leaves.values()) {
+    if (demotionsFor(entry.record, opts.today).length) demoted += 1;
+  }
+
+  const payload = {
+    verb: opts.write ? 'write' : 'check',
+    directory: `knowledge/${DERIVED_DIR}`,
+    note: DERIVED_BANNER,
+    'time-check': timeCheckStatus(opts.today),
+    axes: AXES.map((a) => ({ key: a.key, label: a.label, audience: a.audience })),
+    'recall-slot': RECALL_SLOT,
+    'store-health': healthSummary(storeHealth(model)),
+    counts: { leaves: model.leaves.size, demoted, findings: findings.length },
+    artifacts: artifacts.map((a) => a.path),
+    findings,
+  };
+  const lines = opts.json ? [JSON.stringify(payload, null, 2)] : render(payload);
+  process.stdout.write(`${lines.join('\n').replace(/\n+$/, '')}\n`);
+  return findings.length ? EXIT_CODES.FINDINGS : EXIT_CODES.CLEAN;
+}