unknown-knowledge 2.1.0

package/payload/engine/commands/survey-map.js

@@ -0,0 +1,351 @@
+/**
+ * Survey map (KK-25) — deterministic traversal-surface builder (PRD §4), the
+ * token-efficiency backbone of bootstrap and audit. Agents TRIAGE this
+ * artifact; raw repo traversal is a protocol violation (§6).
+ *
+ *   - Git-tracked files only (`git ls-files --stage`) — never raw fs walks.
+ *   - Built-in denylist: dot-directories, vendored/generated dirs, lockfiles,
+ *     `*.gen.*`, binary extensions.
+ *   - Per-directory extension/count histograms (direct children).
+ *   - Anchor-candidate pre-scan: lexical sniff per §5.1 kind, sharing ONE
+ *     regex table with the extractors (lib/anchor-signatures.js). Ranked by
+ *     path/kind — a stable triage order, not a judgment call.
+ *   - Proposed include/exclude scope over top-level directories; once the
+ *     human-confirmed survey-scope.yaml exists it is HONORED: the map is
+ *     bounded to it, and audit/reflect share the same contract via
+ *     loadSurveyScope()/inScope(). A malformed scope file is an engine
+ *     failure (exit 2), never silently ignored.
+ *   - Explicit `unsurveyed:` disclosure — submodule gitlinks and out-of-root
+ *     symlinks the map could NOT see (§11.1). Blind spots exit 1 (findings),
+ *     never a silent pass.
+ *
+ * Deterministic by construction: stable sorting everywhere, no wall-clock
+ * timestamps, no network, and — D-014 — no import/eval/spawn of repo content;
+ * candidate scanning is lexical only.
+ */
+import { readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { basename, dirname, extname, isAbsolute, resolve, sep } from 'node:path';
+import { load, YAMLException } from 'js-yaml';
+import { ANCHOR_SIGNATURES } from '../lib/anchor-signatures.js';
+import { SCOPE_FILE } from '../lib/kit-root.js';
+import { validateStoreFile, 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 { SCOPE_FILE } from '../lib/kit-root.js';
+
+/** Vendored/generated directory names (any path segment). */
+const DENY_DIRS = new Set([
+  'node_modules', 'bower_components', 'vendor', 'vendors', 'third_party',
+  'third-party', 'Pods', 'Carthage', 'DerivedData', 'dist', 'build', 'out',
+  'coverage', '__pycache__', '.build',
+]);
+const DENY_LOCKFILES = new Set([
+  'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml',
+  'bun.lock', 'bun.lockb', 'deno.lock', 'Podfile.lock', 'Package.resolved',
+  'Cargo.lock', 'Gemfile.lock', 'composer.lock', 'poetry.lock', 'uv.lock',
+  'go.sum',
+]);
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.heic', '.ico', '.icns', '.pdf',
+  '.zip', '.gz', '.tgz', '.jar', '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.mp3', '.mp4', '.mov', '.wav', '.so', '.dylib', '.a', '.o', '.bin',
+  '.exe', '.dll', '.sqlite', '.realm', '.car', '.dat',
+]);
+/** Siblings (files sharing one extension, or module subfolders) before a dir reads as dir-modules. */
+const DIR_MODULES_MIN = 3;
+
+function denied(path) {
+  const name = basename(path);
+  if (DENY_LOCKFILES.has(name) || /\.gen\./.test(name)) return true;
+  if (BINARY_EXTENSIONS.has(extname(name).toLowerCase())) return true;
+  const dirs = path.split('/').slice(0, -1);
+  return dirs.some((d) => d.startsWith('.') || DENY_DIRS.has(d));
+}
+
+/**
+ * `git ls-files --stage` rows: { mode, path }. Throws on any git failure.
+ * Deduped by path: a merge-conflicted path emits one row per stage (1/2/3),
+ * which would otherwise inflate tracked counts and triplicate candidates.
+ */
+function gitLsFiles(root) {
+  const result = spawnSync('git', ['-C', root, 'ls-files', '-z', '--stage'], {
+    encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(`git ls-files failed in ${root}: ${result.error?.message ?? result.stderr.trim()}`);
+  }
+  const rows = [];
+  const seen = new Set();
+  for (const row of result.stdout.split('\0').filter(Boolean)) {
+    const tab = row.indexOf('\t');
+    const path = row.slice(tab + 1);
+    if (seen.has(path)) continue;
+    seen.add(path);
+    rows.push({ mode: row.slice(0, 6), path });
+  }
+  return rows;
+}
+
+/**
+ * True when a tracked symlink resolves outside the repo root (a blind spot).
+ * `realRoot` must be canonical (realpathSync'd once by the caller): comparing
+ * against a non-canonical root (/tmp/x when /tmp -> /private/tmp) would flag
+ * every absolute in-repo symlink as escaping. The landing point is
+ * canonicalized too, so an in-repo absolute target never false-positives.
+ */
+function escapesRoot(realRoot, path) {
+  try {
+    const target = readlinkSync(resolve(realRoot, path));
+    let landed = resolve(dirname(resolve(realRoot, path)), target);
+    try {
+      landed = realpathSync(landed);
+    } catch {
+      // dangling target: judge by the resolved path as-is
+    }
+    return landed !== realRoot && !landed.startsWith(realRoot + sep);
+  } catch {
+    return false; // unreadable link: surveyed as an ordinary tracked file
+  }
+}
+
+/**
+ * Load survey-scope.yaml from `root` — the shared honor-it contract for
+ * survey-map, audit (KK-12), and reflect. Returns { present:false } when the
+ * file does not exist; THROWS on unreadable/unparseable/invalid content — a
+ * scope the engine cannot honor must never degrade to "no scope".
+ */
+export function loadSurveyScope(root) {
+  let text;
+  try {
+    text = readFileSync(resolve(root, SCOPE_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { present: false, include: [], exclude: [] };
+    throw new Error(`${SCOPE_FILE}: cannot read: ${error.message}`);
+  }
+  let doc;
+  try {
+    doc = load(text, { filename: SCOPE_FILE });
+  } catch (error) {
+    const reason = error instanceof YAMLException ? error.reason ?? error.message : error.message;
+    throw new Error(`${SCOPE_FILE}: unparseable YAML: ${reason}`);
+  }
+  const { ok, errors } = validateStoreFile('survey-scope', doc);
+  if (!ok) {
+    const detail = errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+    throw new Error(`${SCOPE_FILE}: invalid scope file — ${detail}`);
+  }
+  return {
+    present: true,
+    include: doc.include.map(normalizePrefix).sort(compare),
+    exclude: (doc.exclude ?? []).map(normalizePrefix).sort(compare),
+  };
+}
+
+/** `src/` means `src` — a trailing slash must never make an include silently match nothing. */
+const normalizePrefix = (prefix) => {
+  const stripped = prefix.replace(/\/+$/, '');
+  return stripped === '' ? '.' : stripped;
+};
+
+/** `.` covers root-level files only; any other prefix covers itself and its subtree. */
+const underPrefix = (path, prefix) =>
+  prefix === '.' ? !path.includes('/') : path === prefix || path.startsWith(`${prefix}/`);
+
+/** The honor-it contract: include prefixes bound the sweep; exclude wins. */
+export function inScope(path, scope) {
+  if (!scope.present) return true;
+  if (scope.exclude.some((p) => underPrefix(path, p))) return false;
+  return scope.include.some((p) => underPrefix(path, p));
+}
+
+/** Lexical §5.1 pre-scan of one file; returns matched kinds (never executes). */
+function sniffKinds(root, path) {
+  const ext = extname(path).toLowerCase();
+  const sigs = ANCHOR_SIGNATURES.filter((s) => s.extensions?.includes(ext));
+  if (sigs.length === 0) return [];
+  let bytes;
+  try {
+    bytes = readFileSync(resolve(root, path));
+  } catch {
+    return []; // tracked but absent from the worktree: nothing to sniff
+  }
+  // UTF-16 BOM (legacy Xcode .strings exports): the UTF-8 sniff cannot read
+  // the content, so treat the file as candidate-by-extension rather than
+  // skipping it silently — the extractor decides, the map never hides.
+  if (bytes.length >= 2
+    && ((bytes[0] === 0xFF && bytes[1] === 0xFE) || (bytes[0] === 0xFE && bytes[1] === 0xFF))) {
+    return [...new Set(sigs.map((s) => s.kind))];
+  }
+  const text = bytes.toString('utf8');
+  return sigs.filter((s) => new RegExp(s.pattern, s.flags).test(text)).map((s) => s.kind);
+}
+
+/**
+ * Build the survey map for a git repo at `root`. Deterministic: same tree in,
+ * byte-identical map out. Throws on engine failure (no git, malformed scope).
+ */
+export function buildSurveyMap(root) {
+  const rows = gitLsFiles(root);
+  const scope = loadSurveyScope(root);
+  // Canonicalize ONCE: a root reached through a symlink (/tmp -> /private/tmp
+  // on macOS) must not flag every absolute in-repo symlink as out-of-root.
+  const realRoot = realpathSync(resolve(root));
+
+  // A scope that matches nothing would emit a plausible-looking empty survey —
+  // an engine failure (exit 2), never a silent surveyed:0 pass.
+  if (scope.present
+    && !rows.some(({ mode, path }) => mode !== '160000' && inScope(path, scope))) {
+    throw new Error(`${SCOPE_FILE}: include [${scope.include.join(', ')}] matches zero tracked files — refusing to emit a silent empty survey`);
+  }
+
+  const unsurveyed = [];
+  const surveyed = [];
+  let deniedCount = 0;
+  for (const { mode, path } of rows) {
+    if (mode === '160000') {
+      unsurveyed.push({ path, reason: 'submodule-gitlink' });
+    } else if (mode === '120000' && escapesRoot(realRoot, path)) {
+      unsurveyed.push({ path, reason: 'out-of-root-symlink' });
+    } else if (denied(path)) {
+      deniedCount += 1;
+    } else if (inScope(path, scope)) {
+      surveyed.push(path);
+    }
+  }
+  surveyed.sort(compare);
+  unsurveyed.sort((a, b) => compare(a.path, b.path));
+
+  // Per-directory histograms over direct children.
+  const byDir = new Map();
+  for (const path of surveyed) {
+    const dir = path.includes('/') ? dirname(path) : '.';
+    if (!byDir.has(dir)) byDir.set(dir, new Map());
+    const ext = extname(path) || '(none)';
+    const hist = byDir.get(dir);
+    hist.set(ext, (hist.get(ext) ?? 0) + 1);
+  }
+  const directories = [...byDir.keys()].sort(compare).map((dir) => {
+    const hist = byDir.get(dir);
+    const extensions = Object.fromEntries([...hist.entries()].sort((a, b) => compare(a[0], b[0])));
+    return { path: dir, files: [...hist.values()].reduce((a, b) => a + b, 0), extensions };
+  });
+
+  // Anchor candidates: content sniffs plus the structural dir-modules shapes —
+  // sibling FILES sharing one extension, or per-module SUBFOLDERS (the PRD's
+  // canonical modules/editor/, modules/prototyping/, modules/whiteboard/ layout).
+  const candidates = [];
+  for (const path of surveyed) {
+    for (const kind of sniffKinds(root, path)) candidates.push({ kind, path });
+  }
+  const childDirs = new Map(); // dir -> Set of direct child dirs holding tracked files
+  for (const path of surveyed) {
+    const segs = path.split('/');
+    let parent = '.';
+    for (let i = 0; i < segs.length - 1; i += 1) {
+      const dir = parent === '.' ? segs[i] : `${parent}/${segs[i]}`;
+      if (!childDirs.has(parent)) childDirs.set(parent, new Set());
+      childDirs.get(parent).add(dir);
+      parent = dir;
+    }
+  }
+  const dirModules = new Set();
+  for (const { path, extensions } of directories) {
+    if (Object.values(extensions).some((n) => n >= DIR_MODULES_MIN)) dirModules.add(path);
+  }
+  for (const [dir, kids] of childDirs) {
+    if (kids.size >= DIR_MODULES_MIN) dirModules.add(dir);
+  }
+  for (const path of dirModules) candidates.push({ kind: 'dir-modules', path });
+  candidates.sort((a, b) => compare(a.path, b.path) || compare(a.kind, b.kind));
+
+  // Scope: honor the confirmed file, else propose from top-level directories —
+  // include those with surveyed files, exclude those that are pure denylist.
+  let scopeOut;
+  if (scope.present) {
+    scopeOut = { source: SCOPE_FILE, include: scope.include, exclude: scope.exclude };
+  } else {
+    const topSurveyed = new Set();
+    const topDenied = new Set();
+    for (const { mode, path } of rows) {
+      if (mode === '160000') continue;
+      // Root-level files are proposed as '.' (root files only, no subtree) —
+      // accepting the proposal must never silently drop package.json et al.
+      const top = path.includes('/') ? path.slice(0, path.indexOf('/')) : '.';
+      (denied(path) ? topDenied : topSurveyed).add(top);
+    }
+    scopeOut = {
+      source: 'proposed',
+      include: [...topSurveyed].sort(compare),
+      exclude: [...topDenied].filter((d) => !topSurveyed.has(d)).sort(compare),
+    };
+  }
+
+  return {
+    counts: { tracked: rows.length, surveyed: surveyed.length, denied: deniedCount, unsurveyed: unsurveyed.length },
+    scope: scopeOut,
+    directories,
+    candidates,
+    unsurveyed,
+  };
+}
+
+// ---------------------------------------------------------------- CLI
+
+export const USAGE = 'usage: node payload/engine/survey-map.js [root] [--root <dir>] [--json]';
+
+function parseArgs(argv) {
+  const { options, positionals } = parseFlags(argv, {
+    boolean: ['json'],
+    value: ['root'],
+    positionals: true,
+  });
+  if (positionals.length > 1) {
+    throw new UsageError(`unexpected argument ${JSON.stringify(positionals[1])}`);
+  }
+  // The root may be named positionally or by flag, never both: two names for
+  // the root is exactly the ambiguity `locateKit` refuses to guess at.
+  if (options.root !== undefined && positionals.length) {
+    throw new UsageError(`the root is named twice: ${JSON.stringify(positionals[0])} and --root ${JSON.stringify(options.root)}`);
+  }
+  return { root: resolve(options.root ?? positionals[0] ?? '.'), json: !!options.json };
+}
+
+function printHuman(map) {
+  const lines = [
+    `surveyed ${map.counts.surveyed} tracked file(s) across ${map.directories.length} director(ies); ${map.counts.denied} denylisted`,
+    `scope (${map.scope.source}): include ${map.scope.include.join(', ') || '(none)'}; exclude ${map.scope.exclude.join(', ') || '(none)'}`,
+    `anchor candidates: ${map.candidates.length}`,
+    ...map.candidates.map((c) => `  ${c.kind.padEnd(18)} ${c.path}`),
+    map.unsurveyed.length === 0
+      ? 'nothing unsurveyed — the map saw every tracked path'
+      : `UNSURVEYED (blind spots the map could NOT see — disclose at the scope gate):`,
+    ...map.unsurveyed.map((u) => `  ${u.reason.padEnd(22)} ${u.path}`),
+  ];
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+/**
+ * CLI entry. Exit codes per the engine contract (PRD §5): 0 clean,
+ * 1 blind spots disclosed under unsurveyed:, 2 engine/environment failure.
+ */
+export function main(argv) {
+  const opts = parseArgs(argv); // a UsageError reaches the harness
+
+  let map;
+  try {
+    map = buildSurveyMap(opts.root);
+  } catch (error) {
+    rethrowIfBug(error); // a bug is not a refusal — the harness prints its stack
+    // An EXPECTED environment failure (no git, unparseable scope, a scope whose
+    // include matches nothing): the survey never ran, so it cannot report blind
+    // spots. Exit 2 — never 1, which would claim it ran and found them.
+    process.stderr.write(`survey-map: ${error.message}\n`);
+    return EXIT_CODES.FAILURE;
+  }
+
+  if (opts.json) process.stdout.write(`${JSON.stringify(map, null, 2)}\n`);
+  else printHuman(map);
+  return map.unsurveyed.length === 0 ? EXIT_CODES.CLEAN : EXIT_CODES.FINDINGS;
+}

package/payload/engine/commands/validate-values.js

@@ -0,0 +1,315 @@
+/**
+ * Value validator (KK-07) — blocking-grade rung-2 checks (PRD §4). Runs every
+ * `enumerates` recipe on the loaded ontology: parses the named source with the
+ * descriptor's extractor kind, extracts the actual value set, and diffs it
+ * against the claim IN BOTH DIRECTIONS. §3.5 equality: values are strings,
+ * compared byte-exact and case-sensitive, as sets — order irrelevant,
+ * duplicates in source are a finding.
+ *
+ *   node payload/engine/validate-values.js [--concepts <ids>] [--json] [--root <dir>]
+ *
+ * Findings (exit 1 when any is error-severity):
+ *   value-not-in-source    a claimed value the source does not carry
+ *   source-value-missing   a source value the claim does not carry
+ *   duplicate-source-value the source declares the same value twice (§3.5:
+ *                          sets — a duplicate is a defect, never a bigger set)
+ *   wrong-pointer          ALL claimed values missing from a real, parseable
+ *                          file — the descriptor points at the wrong place;
+ *                          one distinct finding, never a per-value cascade
+ *
+ * Hard errors (exit 2 — a check that never ran is a blocking defect, never a
+ * silent pass, PRD §5):
+ *   - a store the single health model marks unhealthy: every error-severity
+ *     loader diagnostic (including the KK-02 malformed-descriptor codes
+ *     non-string-enumerates-value / duplicate-enumerates-value /
+ *     enumerates-source-not-listed) is surfaced as a hard error and no value
+ *     check runs — an unprovable claim silently passing would re-open the gap
+ *     this validator closes
+ *   unknown-kind     the descriptor names an extractor kind the registry does
+ *                    not carry — nothing can re-derive the claim
+ *   source-missing   the named source file does not exist / is unreadable
+ *   out-of-envelope  an out-of-envelope sentinel appears in the matched span
+ *                    (PRD §5: a confident wrong parse is a false all-clear)
+ *   extract-failed   the kind's recipe could not parse the source
+ *
+ * §3.5 status semantics: draft/proposed concepts are skipped (structural
+ * checks only — preflight verdicts them unknown); active is blocking-grade;
+ * deprecated demotes value findings AND the path-existence/envelope hard
+ * errors to warnings — deprecation is precisely the state that stops the
+ * blocking check from dead-ending a legitimate source deletion (§3.5).
+ * A malformed descriptor or unknown kind stays hard on every status.
+ *
+ * Extractor kinds are registered by NAME in lib/extractor-kinds.js — a small
+ * deterministic recipe `extract(text, descriptor) -> string[]` that reads a
+ * value set out of a reified anchor, throwing EnvelopeError / ExtractError.
+ * KK-08 ships the TS/JS + JSON kinds; KK-09 the Swift/config kinds; KK-10
+ * dir-modules — the registry's one DIRECTORY kind (`{ reads: 'directory' }`),
+ * fed a deterministic listing instead of file text (dispatch seam in
+ * checkDescriptor); `test-lines` (newline-delimited registry files) proves
+ * dispatch, the envelope hard-error path, and determinism.
+ * D-014: kinds parse lexically only — the engine never executes client code.
+ *
+ * --root is the REPO root (default cwd): descriptor sources and
+ * source-of-truth pointers are repo-relative (§9.1 — a post-init repo nests
+ * the kit inside the codebase its pointers describe). The stores load from
+ * <root>/unknown-knowledge/ when that directory exists, else from <root>
+ * itself (the kit repo's own dogfood layout).
+ *
+ * Consumes the KK-04 loader's model — never re-parses stores. Output is
+ * deterministic and stable-sorted (findings by concept/path/code/value), no
+ * wall-clock timestamps. Exit codes (PRD §5, D-011): 0 clean, 1 findings,
+ * 2 engine failure / check-never-ran.
+ */
+import process from 'node:process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { healthSummary, loadStores, isPrePromotionStatus, normalizeConceptIds, selectConcepts, storeHealth, UnknownConceptsError } from '../lib/load-stores.js';
+import { locateKitRoot } from '../lib/kit-root.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+import { UsageError, parseArgs as parseFlags, rethrowIfBug } from '../lib/cli.js';
+import { compare } from '../lib/validate-record.js';
+import { KINDS, EnvelopeError, ExtractError, listDirectory } from '../lib/extractor-kinds.js';
+
+export const USAGE = 'usage: node payload/engine/validate-values.js [--concepts <ids>] [--json] [--root <dir>]';
+
+// ------------------------------------------------------------ the check body
+
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * Run one descriptor: dispatch to its kind, read the source, diff both ways.
+ * Pushes findings/hard-errors into ctx; never throws for check outcomes.
+ */
+function checkDescriptor(ctx, concept, descriptor, i) {
+  const { id, file } = concept;
+  const path = `enumerates[${i}]`;
+  const deprecated = concept.record.status === 'deprecated';
+  const severity = deprecated ? 'warning' : 'error';
+  // deprecated demotes path-existence/envelope to warning findings (§3.5);
+  // malformed/unknown-kind stay hard on every status.
+  const never = (code, message, extra = {}) => {
+    const entry = { concept: id, code, file, path, source: descriptor.source, message, ...extra };
+    if (deprecated && (code === 'source-missing' || code === 'out-of-envelope')) {
+      ctx.findings.push({ ...entry, severity: 'warning' });
+    } else {
+      ctx.hardErrors.push(entry);
+    }
+  };
+
+  const kind = KINDS[descriptor.kind];
+  if (!kind) {
+    ctx.hardErrors.push({
+      concept: id, code: 'unknown-kind', file, path, source: descriptor.source,
+      message: `extractor kind "${descriptor.kind}" is not registered — nothing can re-derive this claim, and an unprovable claim must never silently pass (PRD §4); registered kinds: ${Object.keys(KINDS).sort(compare).join(', ')}`,
+    });
+    return;
+  }
+
+  // Registry dispatch seam (KK-10): a plain function is a FILE kind fed the
+  // source text; a `{ reads: 'directory' }` entry is a DIRECTORY kind fed the
+  // deterministic listing. Either way the one filesystem read happens here,
+  // and an unreadable source (missing file, missing dir, a file where a
+  // directory kind expects a dir — ENOTDIR) is source-missing.
+  const readsDirectory = typeof kind !== 'function' && kind.reads === 'directory';
+  const extract = readsDirectory ? kind.extract : kind;
+
+  let input;
+  try {
+    input = readsDirectory
+      ? listDirectory(join(ctx.root, descriptor.source))
+      : readFileSync(join(ctx.root, descriptor.source), 'utf8');
+  } catch (error) {
+    never('source-missing', `cannot ${readsDirectory ? 'list source directory' : 'read source'} ${JSON.stringify(descriptor.source)}: ${error.message}`);
+    return;
+  }
+
+  let actual;
+  try {
+    actual = extract(input, descriptor);
+  } catch (error) {
+    if (error instanceof EnvelopeError) {
+      never('out-of-envelope', error.message);
+    } else if (error instanceof ExtractError) {
+      never('extract-failed', error.message);
+    } else {
+      throw error; // a kind bug is an engine failure, not a finding
+    }
+    return;
+  }
+
+  const claimed = descriptor.values;
+  const actualSet = new Set();
+  for (const value of actual) {
+    if (actualSet.has(value)) {
+      ctx.findings.push({
+        concept: id, code: 'duplicate-source-value', severity, file, path,
+        source: descriptor.source, value,
+        message: `source declares ${JSON.stringify(value)} more than once — values compare as sets (§3.5), so a duplicate is a source defect, never a bigger set`,
+      });
+    }
+    actualSet.add(value);
+  }
+
+  // Wrong-pointer signature (PRD §4): the file is real and parseable, yet
+  // carries NONE of the claimed values — one finding, not a cascade.
+  if (claimed.length && claimed.every((v) => !actualSet.has(v))) {
+    ctx.findings.push({
+      concept: id, code: 'wrong-pointer', severity, file, path,
+      source: descriptor.source,
+      message: `all ${claimed.length} claimed value(s) are missing from ${JSON.stringify(descriptor.source)} — the file exists and parses (${actualSet.size} value(s) extracted), so the descriptor points at the wrong place`,
+    });
+    return;
+  }
+
+  const claimedSet = new Set(claimed);
+  for (const value of claimed) {
+    if (!actualSet.has(value)) {
+      ctx.findings.push({
+        concept: id, code: 'value-not-in-source', severity, file, path,
+        source: descriptor.source, value,
+        message: `claimed value ${JSON.stringify(value)} is not in ${JSON.stringify(descriptor.source)} (byte-exact, case-sensitive, §3.5)`,
+      });
+    }
+  }
+  for (const value of actualSet) {
+    if (!claimedSet.has(value)) {
+      ctx.findings.push({
+        concept: id, code: 'source-value-missing', severity, file, path,
+        source: descriptor.source, value,
+        message: `source value ${JSON.stringify(value)} in ${JSON.stringify(descriptor.source)} is not claimed by the descriptor`,
+      });
+    }
+  }
+}
+
+/**
+ * Run every enumerates check over a loaded model — the reusable seam
+ * preflight (KK-26) consumes, so verdicts and this validator can never
+ * disagree. `conceptIds` null = all concepts; an unknown id throws (a check
+ * that never ran is a blocking defect). `repoRoot` is where descriptor
+ * sources resolve (§9.1 repo-relative); it defaults to the store root, the
+ * flat layout where both coincide. Returns { findings, hardErrors,
+ * checked }, stable-sorted.
+ */
+export function validateValues(model, conceptIds, repoRoot = model.root) {
+  // Sources are repo-relative (§9.1), not store-relative: in a seeded repo
+  // the stores sit at <repo>/unknown-knowledge/ but point at <repo>/src/....
+  const ctx = { root: repoRoot, findings: [], hardErrors: [], checked: [] };
+
+  // Single health model: the loader already validated every descriptor's
+  // shape (KK-02 codes). An unhealthy store means the value check cannot
+  // certify anything — surface the diagnostics as hard errors and stop.
+  const { errors: storeErrors } = storeHealth(model);
+  if (storeErrors.length) {
+    ctx.hardErrors = storeErrors.map(({ code, file, path, message }) => ({
+      concept: null, code, file, path, source: null, message,
+    }));
+    return ctx;
+  }
+
+  for (const concept of selectConcepts(model, conceptIds)) {
+    const { id, file, record } = concept;
+    const descriptors = Array.isArray(record.enumerates) ? record.enumerates : [];
+    const entry = { concept: id, status: record.status ?? null, descriptors: descriptors.length };
+    if (isPrePromotionStatus(record.status)) {
+      // §3.5: structural checks only; the resolver downranks, preflight
+      // verdicts unknown — the value check does not run.
+      entry.skipped = record.status;
+      ctx.checked.push(entry);
+      continue;
+    }
+    ctx.checked.push(entry);
+    descriptors.forEach((descriptor, i) => {
+      if (!isObject(descriptor)) return; // shape defects already hard-errored via the loader
+      checkDescriptor(ctx, { id, file, record }, descriptor, i);
+    });
+  }
+
+  ctx.checked.sort((a, b) => compare(a.concept, b.concept));
+  ctx.findings.sort((a, b) =>
+    compare(a.concept, b.concept) || compare(a.path, b.path) || compare(a.code, b.code)
+    || compare(a.value ?? '', b.value ?? ''));
+  ctx.hardErrors.sort((a, b) =>
+    compare(a.concept ?? '', b.concept ?? '') || compare(a.file ?? '', b.file ?? '')
+    || compare(a.path ?? '', b.path ?? '') || compare(a.code, b.code));
+  return ctx;
+}
+
+// ------------------------------------------------------------- CLI plumbing
+
+function parseArgs(argv) {
+  const { options } = parseFlags(argv, {
+    boolean: ['json'],
+    value: ['root'],
+    repeatable: ['concepts'],
+    allowEmpty: ['concepts'],
+  });
+  const opts = { json: !!options.json, root: options.root ?? process.cwd(), concepts: null };
+  if (options.concepts) {
+    opts.concepts = normalizeConceptIds(options.concepts.flatMap((v) => v.split(',')));
+    if (!opts.concepts.length) {
+      throw new UsageError('--concepts must name at least one concept id — a filter that never ran is a failure, never a silent pass');
+    }
+  }
+  return opts;
+}
+
+function renderHuman(payload) {
+  const lines = [];
+  const f = payload.findings.length;
+  const h = payload['hard-errors'].length;
+  const checked = payload.checked.filter((c) => !c.skipped).length;
+  const skipped = payload.checked.length - checked;
+  lines.push(
+    `validate-values: ${checked} concept(s) checked, ${skipped} skipped (draft/proposed), `
+    + `${f} finding${f === 1 ? '' : 's'}, ${h} hard error${h === 1 ? '' : 's'}`,
+    '',
+  );
+  for (const e of payload['hard-errors']) {
+    lines.push(`HARD ERROR ${e.code}  ${e.concept ?? e.file}${e.source ? `  (source: ${e.source})` : ''}`);
+    lines.push(`  ${e.message}`);
+  }
+  if (h) {
+    lines.push('', 'the check never ran on the entries above — fix the descriptors/store first (PRD §4: a malformed descriptor is a hard error, never skipped)', '');
+  }
+  for (const x of payload.findings) {
+    lines.push(`${x.severity === 'warning' ? 'warning' : 'FINDING'} ${x.code}  ${x.concept}${x.value !== undefined ? `  ${JSON.stringify(x.value)}` : ''}  (source: ${x.source})`);
+    lines.push(`  ${x.message}`);
+  }
+  if (!f && !h) lines.push('every enumerates claim agrees with its source (both directions, §3.5 set equality)');
+  return lines;
+}
+
+export function main(argv) {
+  {
+    const opts = parseArgs(argv);
+
+    let model;
+    try {
+      model = loadStores(locateKitRoot(opts.root));
+    } catch (error) {
+      // An EXPECTED refusal from the loader — an unreadable root, an ambiguous
+      // kit layout, a Store that will not load. The stores this command would
+      // check never loaded, so its checks never ran: exit 2, never 1.
+      process.stderr.write(`validate-values: ${error.message}\n`);
+      rethrowIfBug(error); // a bug, or a UsageError raised deep in the loader, is not ours to speak for
+      return EXIT_CODES.FAILURE;
+    }
+
+    const ctx = validateValues(model, opts.concepts, opts.root);
+    const hard = ctx.hardErrors.length > 0;
+    const blocking = ctx.findings.some((x) => x.severity === 'error');
+    const payload = {
+      ok: !hard && !blocking,
+      'store-health': healthSummary(storeHealth(model)),
+      checked: ctx.checked,
+      findings: ctx.findings,
+      'hard-errors': ctx.hardErrors,
+    };
+
+    const lines = opts.json ? [JSON.stringify(payload, null, 2)] : renderHuman(payload);
+    process.stdout.write(`${lines.join('\n').replace(/\n+$/, '')}\n`);
+    return hard ? EXIT_CODES.FAILURE : blocking ? EXIT_CODES.FINDINGS : EXIT_CODES.CLEAN;
+  }
+}