unknown-knowledge 2.1.0

package/payload/engine/lib/scoring.js

@@ -0,0 +1,150 @@
+/**
+ * The resolver's scoring table (UCS-1152) — every signal that moves a score,
+ * declared in one place, with the number it is worth.
+ *
+ * Extracted BEFORE the query-decomposition signals were added, on the survey's
+ * prefactor advice, and the ordering matters: scoring that lives inline in the
+ * matcher grows a new arm per signal, and by the fourth signal nobody can say
+ * what a score of 7 is made of without reading four functions. A table says it
+ * in one screen, and `explain()` turns any score back into the signals that
+ * produced it — which is the acceptance criterion "ranking is reproducible from
+ * the output", enforced by construction rather than by a comment asking future
+ * authors to remember.
+ *
+ * TWO FAMILIES, deliberately kept apart:
+ *
+ *   CONCEPT_SIGNALS   the pre-1152 ladder — a concept scores on the HIGHEST
+ *                     rung it reaches and rungs never add up. Unchanged numbers
+ *                     (100/80/60/50/40, -30 for draft), because published
+ *                     concept scores are a ranking consumers already depend on
+ *                     and this ticket had no reason to move them.
+ *   LEAF_SIGNALS      the structured joins a LEAF scores on, and these DO add
+ *                     up. A leaf reached by both a declared operation and a
+ *                     declared concept is more strongly the answer than one
+ *                     reached by either alone, and additive scoring is the only
+ *                     shape that says so.
+ *
+ * That the two families disagree about adding is the substantive modelling
+ * claim here, not an inconsistency. A concept match is one question asked five
+ * ways — "is this the term the user typed" — so the best answer wins and a
+ * second, weaker phrasing of the same question adds nothing. A leaf's joins are
+ * INDEPENDENT questions — does it declare this operation, this concept, does
+ * its term text match — and independent evidence accumulates.
+ *
+ * The leaf weights (3/2/1) are pinned: their ordering is the behavior the
+ * goldens mirror, and the ordering they encode is the defensible part — a
+ * DECLARED operation is
+ * the strongest join (the leaf's author named the verb this ask is about), a
+ * declared concept edge is next (curatorial, survives a rename), and term text
+ * is weakest (it is exactly as reliable as two authors choosing the same
+ * words). Absolute magnitudes matter only relative to each other.
+ */
+
+/**
+ * The concept ladder — highest rung reached wins, rungs never add (KK-06).
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const CONCEPT_SIGNALS = Object.freeze({
+  'exact-term': 100,
+  'exact-alias': 80,
+  'term-match': 60,
+  'alias-match': 50,
+  'summary-match': 40,
+});
+
+/**
+ * The structured joins a leaf scores on — these ADD (UCS-1152).
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const LEAF_SIGNALS = Object.freeze({
+  // The leaf declares the operation the query's verb resolved to. The strongest
+  // join in the table because it needed no noun guessing: the registry turned
+  // "add a tool" into `add-tool`, and the leaf had already declared it.
+  operation: 3,
+  // The leaf declares the concept the query's noun resolved to — the structural
+  // edge from UCS-1151, a curatorial claim that survives the concept being
+  // renamed.
+  concept: 2,
+  // The leaf's `terms` text matched query tokens. Weakest, and it is meant to
+  // be: it fires exactly when two authors happened to choose the same words.
+  term: 1,
+});
+
+/**
+ * The draft/proposed downrank applied to a CONCEPT score (§3.5).
+ *
+ * A subtraction with a floor of 1, never a filter: a draft concept that matches
+ * is still the best answer when it is the only answer, and hiding it would send
+ * the reader to invent one. Leaves take their pre-promotion demotion through
+ * the `downranked` ordering instead — see `demotionsOf` in the resolver — because
+ * a leaf's stage travels with a reason and sorts below rather than subtracting.
+ */
+export const STATUS_DOWNRANK = 30;
+
+/** Concept statuses the downrank applies to. */
+const DOWNRANKED_STATUSES = Object.freeze(['draft', 'proposed']);
+
+/**
+ * A concept's score: the rung it reached, less the draft downrank if it is one.
+ *
+ * Unchanged from the pre-1152 inline version, and pinned by the existing
+ * goldens — the extraction moved this arithmetic, it did not renegotiate it.
+ *
+ * @param {string} match the rung name, a key of CONCEPT_SIGNALS
+ * @param {unknown} status the concept's declared status
+ * @returns {number}
+ */
+export function conceptScore(match, status) {
+  const base = CONCEPT_SIGNALS[match];
+  return DOWNRANKED_STATUSES.includes(status) ? Math.max(1, base - STATUS_DOWNRANK) : base;
+}
+
+/**
+ * Total one leaf's structured-join signals, and keep the working.
+ *
+ * Returns BOTH the number and the signals that made it, because a score a
+ * reader cannot decompose is a ranking they cannot check. The acceptance
+ * criterion is literally "ranking is reproducible from the output": every
+ * published leaf carries its `signals`, so `sum(signal.score)` must equal the
+ * published `score` — an invariant a test can assert rather than a claim a
+ * comment makes.
+ *
+ * Signals arrive in join order and are NOT re-sorted here: the caller emits
+ * them operation-first, concept-next, term-last, which is descending weight, so
+ * the strongest reason a leaf surfaced reads first. Sorting by name would put
+ * `concept` above `operation` and bury the lead.
+ *
+ * @param {Array<{signal: string, via: string}>} signals the joins that fired
+ * @returns {{score: number, signals: Array<{signal: string, via: string, score: number}>}}
+ */
+export function leafScore(signals) {
+  const scored = signals.map(({ signal, via }) => ({
+    signal,
+    via,
+    // An unknown signal scores 0 rather than NaN. `undefined + n` is NaN, and a
+    // NaN score sorts unpredictably AND serializes to JSON as `null`, so one
+    // typo in a signal name would silently unrank a leaf and publish a null
+    // where every consumer reads a number.
+    score: LEAF_SIGNALS[signal] ?? 0,
+  }));
+  return { score: scored.reduce((total, s) => total + s.score, 0), signals: scored };
+}
+
+/**
+ * The published scoring table — the engine's own answer to "where do these
+ * numbers come from", carried in the payload rather than documented elsewhere.
+ *
+ * Emitted on every query payload so a consumer reproducing a ranking never has
+ * to hard-code the weights it is checking against. A table that lives only in
+ * source is one a downstream reader has to guess at or vendor a copy of, and a
+ * vendored copy is the thing that goes stale the first time a weight moves.
+ *
+ * @returns {{concept: Record<string, number>, leaf: Record<string, number>, 'status-downrank': number}}
+ */
+export const scoringTable = () => ({
+  concept: { ...CONCEPT_SIGNALS },
+  leaf: { ...LEAF_SIGNALS },
+  'status-downrank': STATUS_DOWNRANK,
+});

package/payload/engine/lib/suppressions.js

@@ -0,0 +1,172 @@
+/**
+ * Suppression — the steward's rejection memory (KK-27, D-013, PRD §11.1).
+ *
+ * A client-zone `suppressions.yaml` next to the stores, telling the reverse
+ * audit "this is deliberately not a Concept". It has real depth behind a small
+ * interface: a fails-open loader, a strict entry shape, and an exact-match
+ * filter that can only ever UNDER-suppress.
+ *
+ * Two rules give the whole module its shape:
+ *
+ * 1. IT FAILS OPEN, always. The opposite of the scope file. A missing file is a
+ *    no-op; anything malformed — the whole document, or one entry — becomes a
+ *    warning and suppresses nothing, so the findings it would have hidden come
+ *    back. Suppression is advisory-side; it must never be able to silence a
+ *    finding by being broken, and never raise an engine failure.
+ *
+ * 2. IDENTITY TRAVELS WITH THE FINDING. A Finding knows what a suppression
+ *    entry would have to say to silence it, because it is stamped at the place
+ *    the Finding is built. Nothing here switches on the Finding's code.
+ *
+ * Rule 2 is the point of this module existing. The identity used to be derived
+ * by a function that switched on `finding.code`, so a third Finding code was
+ * one forgotten `if` away from being permanently unsuppressable — silently, and
+ * only in a client's Store. Now a Finding without an identity is refused
+ * outright: `partitionBySuppression` throws rather than quietly keeping it.
+ *
+ * v1 is deliberately minimal (§11.1): exact match on `{ term, sourcePath }`.
+ * No patterns, no expiry, no globs. A suppression that could match something
+ * its author did not read is a suppression that can hide the finding they most
+ * needed to see.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { load } from 'js-yaml';
+import { SUPPRESSIONS_FILE } from './kit-root.js';
+import { isCalendarDate } from './iso-date.js';
+
+export { SUPPRESSIONS_FILE };
+
+/** The v1 entry shape, STRICTLY: exact-match identity + audit trail. */
+export const SUPPRESSION_FIELDS = Object.freeze(['term', 'sourcePath', 'reason', 'date']);
+
+/**
+ * The identity a Finding is suppressed by, carried on the Finding itself.
+ *
+ * A Symbol, so it never reaches the wire: `JSON.stringify` and `Object.keys`
+ * skip symbol keys, and the audit's `--json` payload is a published contract.
+ * It survives object spread, which is how findings are built.
+ */
+export const SUPPRESSION_IDENTITY = Symbol('suppression identity');
+
+
+/**
+ * Stamp a Finding with the exact-match identity that would silence it.
+ *
+ * Call this where the Finding is BUILT, where its shape is known. That is the
+ * whole design: no downstream function has to know every Finding code, so a new
+ * code cannot fall out of sync with a switch statement that forgot it.
+ *
+ * @param {object} finding
+ * @param {{ term: string, sourcePath: string }} identity
+ * @returns {object} the finding, carrying its identity
+ */
+export function suppressibleBy(finding, identity) {
+  if (typeof identity?.term !== 'string' || identity.term === ''
+    || typeof identity?.sourcePath !== 'string' || identity.sourcePath === '') {
+    throw new Error(`finding "${finding?.code}": a suppression identity needs a non-empty term and sourcePath`);
+  }
+  return { ...finding, [SUPPRESSION_IDENTITY]: Object.freeze({ ...identity }) };
+}
+
+/** Warning text for one malformed entry, or null when it is well-formed. */
+export function suppressionEntryProblem(entry) {
+  if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+    return 'not a mapping';
+  }
+  for (const field of SUPPRESSION_FIELDS) {
+    if (typeof entry[field] !== 'string' || entry[field].trim() === '') {
+      return `"${field}" must be a non-empty string`;
+    }
+  }
+  const unknown = Object.keys(entry).filter((k) => !SUPPRESSION_FIELDS.includes(k));
+  if (unknown.length > 0) {
+    return `unknown field(s) ${unknown.map((k) => `"${k}"`).join(', ')} — v1 entries are strictly { ${SUPPRESSION_FIELDS.join(', ')} } (no patterns, no expiry; §11.1)`;
+  }
+  if (!isCalendarDate(entry.date)) {
+    // A typo'd date drops the entry, which resurfaces its finding. That is the
+    // safe direction: suppression fails open, and only ever under-suppresses.
+    return `"date" must be an ISO date (YYYY-MM-DD), got ${JSON.stringify(entry.date)}`;
+  }
+  return null;
+}
+
+/** True when the document has anything but blank lines and `#` comments. */
+const hasContent = (text) =>
+  text.split('\n').some((line) => line.trim() !== '' && !line.trim().startsWith('#'));
+
+/**
+ * Load `<kitRoot>/suppressions.yaml`. FAILS OPEN by design.
+ *
+ * @returns {{ entries: object[], warnings: string[] }} only well-formed entries
+ */
+export function loadSuppressions(kitRoot) {
+  const warn = (msg) => ({ entries: [], warnings: [`${SUPPRESSIONS_FILE}: ${msg} — ignoring every entry (suppression fails open, findings resurface)`] });
+  let text;
+  try {
+    text = readFileSync(join(kitRoot, SUPPRESSIONS_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { entries: [], warnings: [] }; // no file, no-op
+    return warn(`cannot read: ${error.message}`);
+  }
+  // A file with nothing in it but blank lines and comments is a file with no
+  // entries — not a broken one. js-yaml raises "expected a document, but the
+  // input is empty" for all three, so a steward who commented out their last
+  // suppression used to be told their file was unparseable.
+  if (!hasContent(text)) return { entries: [], warnings: [] };
+
+  let doc;
+  try {
+    doc = load(text, { filename: SUPPRESSIONS_FILE });
+  } catch (error) {
+    return warn(`unparseable YAML: ${error.reason ?? error.message}`);
+  }
+  if (doc === null || doc === undefined) return { entries: [], warnings: [] }; // explicit `null`, no-op
+  if (!Array.isArray(doc)) return warn('must be a YAML list of { term, sourcePath, reason, date } entries');
+
+  const entries = [];
+  const warnings = [];
+  doc.forEach((entry, i) => {
+    const problem = suppressionEntryProblem(entry);
+    if (problem === null) {
+      entries.push(entry);
+    } else {
+      warnings.push(`${SUPPRESSIONS_FILE}: entry ${i + 1} ignored (fails open, its finding resurfaces): ${problem}`);
+    }
+  });
+  return { entries, warnings };
+}
+
+/**
+ * Split findings into those a suppression entry silences and those it does not.
+ *
+ * Exact match on both fields, in the order the findings arrive — callers sort
+ * first, so both lists stay stable.
+ *
+ * A Finding with no identity is a PROGRAMMING error, not a client-data one, so
+ * it is refused rather than passed through. Passing it through would make a new
+ * Finding code permanently unsuppressable, and nothing would ever say so: the
+ * audit would run clean, the entry the steward wrote would be ignored, and the
+ * finding they rejected would come back every run. Failing open is right for a
+ * malformed suppressions.yaml; it is wrong for a Finding the engine built.
+ *
+ * @param {object[]} findings each stamped by `suppressibleBy`
+ * @param {object[]} entries well-formed suppression entries
+ * @returns {{ kept: object[], suppressed: object[] }}
+ */
+export function partitionBySuppression(findings, entries) {
+  const kept = [];
+  const suppressed = [];
+  for (const finding of findings) {
+    const identity = finding[SUPPRESSION_IDENTITY];
+    if (identity === undefined) {
+      throw new Error(
+        `finding "${finding?.code}" carries no suppression identity — stamp it with suppressibleBy() `
+        + 'where it is built, or a steward could never suppress it',
+      );
+    }
+    const match = entries.some((e) => e.term === identity.term && e.sourcePath === identity.sourcePath);
+    (match ? suppressed : kept).push(finding);
+  }
+  return { kept, suppressed };
+}

package/payload/engine/lib/time-verdicts.js

@@ -0,0 +1,282 @@
+/**
+ * The Time facet (UCS-1150) — `verified` + `volatility`, and the one function
+ * that turns them into a trusted/stale verdict.
+ *
+ * Freshness made visible. A leaf records WHEN it was last verified and HOW FAST
+ * its subject moves; the engine turns those two facts into a verdict every
+ * projection can read. A fast-growing store cannot rot silently, because an
+ * agent never has to judge at query time whether a world-fact from eighteen
+ * months ago still holds — the verdict already said.
+ *
+ * ONE implementation, deliberately. Three surfaces demote on this today (the
+ * resolver's ranking, preflight's leaf verdicts, the validator's missing-date
+ * finding) and the derived-layer trees (UCS-1158) plus the resolution pipeline
+ * (UCS-1152) inherit it. That is exactly the shape that goes wrong when each
+ * surface computes its own: a leaf ranked stale by the resolver and verdicted
+ * trusted by preflight is one record wearing two answers, and the disagreement
+ * surfaces as a bug in whichever surface the reader happened to trust. The
+ * shared `isPrePromotionStatus` predicate exists for the same reason one rung
+ * up, and this is the time facet's half of that discipline.
+ *
+ * THRESHOLDS ARE PINNED, not configurable. `stable` stales after 365 days,
+ * `volatile` after 90, `static` never. A per-store threshold would make "stale"
+ * mean something different in every repo, and the verdict's whole value is that
+ * an agent reading it needs no local knowledge to act on it. Changing a number
+ * here is an engine release with a Decisions entry behind it, which is the
+ * governance the audit's `--stale-days` flag deliberately does NOT have (that
+ * one is advisory and never demotes anything).
+ *
+ * THE DATE IS INJECTED, never read from the wall clock (D-012, PRD §5). Without
+ * an injected `today` there is no verdict to compute, and the answer is
+ * `skipped` — a distinct verdict class that every surface must print, never a
+ * quiet `trusted`. A check that never ran is a blocking defect, never a silent
+ * pass; the audit's `stale-last-verified` established the rule and this follows
+ * it exactly, so baseline finding-set diffing survives.
+ */
+import { daysBetween, isCalendarDate } from './iso-date.js';
+
+/** The leaf front-matter field naming when this leaf was last verified. */
+export const VERIFIED_FIELD = 'verified';
+
+/** The leaf front-matter field naming how fast this leaf's subject moves. */
+export const VOLATILITY_FIELD = 'volatility';
+
+/**
+ * How long a leaf stays fresh, per volatility class — the pinned thresholds.
+ *
+ * `static` is `Infinity` rather than absent: a static leaf is IN the time
+ * facet and its verdict is that it never stales, which is a different claim
+ * from a leaf the facet does not govern at all. Modelling it as a missing row
+ * would collapse those two into one and lose the distinction the schema draws.
+ *
+ * Read as `age > limit`: a `stable` leaf verified exactly 365 days ago is
+ * fresh, and stales on day 366. The boundary is pinned that way in both
+ * directions by golden fixtures, because "more than a year old" and "a year or
+ * more old" differ by exactly one day and nothing in the phrase says which.
+ *
+ * NULL-PROTOTYPE, and that is a correctness requirement rather than a style
+ * preference. A plain object literal inherits `toString`, `constructor`,
+ * `valueOf` and the rest of Object.prototype, so `'toString' in LIMITS` is
+ * TRUE and `LIMITS['toString']` is a native function. A leaf spelling
+ * `volatility: toString` would then be treated as a known class whose limit is
+ * a function — and `age > someFunction` is always false, so a leaf verified in
+ * 2020 would read `trusted`, undemoted, with `limit` silently dropped from the
+ * JSON (JSON.stringify omits function values) and `[native code]` leaking into
+ * the reason a human reads.
+ *
+ * The schema enum already refuses such a leaf, so no VALIDATED store reaches
+ * it. That is not enough: the resolver deliberately never gates on store health
+ * — a lookup runs on whatever loaded (§4) — so it is precisely the surface that
+ * can be asked to publish a verdict on a leaf no check approved. Fixing it at
+ * the table rather than at each call site means a future consumer of this
+ * module cannot reintroduce the bug by reaching for `in` or `[]` itself.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const VOLATILITY_LIMITS = Object.freeze(Object.assign(Object.create(null), {
+  static: Infinity,
+  stable: 365,
+  volatile: 90,
+}));
+
+/** The closed volatility vocabulary, sorted — the schema enum's single source. */
+export const VOLATILITY_CLASSES = Object.freeze(Object.keys(VOLATILITY_LIMITS).sort());
+
+/** Verdict classes. `skipped` is one of them, and that is the point. */
+export const TIME_VERDICTS = Object.freeze({
+  TRUSTED: 'trusted',
+  STALE: 'stale',
+  SKIPPED: 'skipped',
+  EXEMPT: 'exempt',
+  UNDATED: 'undated',
+});
+
+/**
+ * A leaf's declared volatility class, or null when it declares none.
+ *
+ * The single reader of the `volatility` spelling, for the reason `leafStage` is
+ * the single reader of `facets.stage`: a later move of the field must not leave
+ * one surface silently reading `undefined` and quietly promoting a leaf the
+ * defect should have held back.
+ *
+ * A value outside the closed vocabulary reads as null rather than travelling
+ * on. The schema has already refused it, and handing an unknown class to the
+ * threshold table would produce `undefined > n` — which is `false`, i.e. a
+ * silent `trusted` for a leaf whose volatility nobody can interpret.
+ *
+ * Membership is an OWN-property test, never `in`. The table is null-prototype
+ * so `in` would be safe today, but this is the gate every unknown value passes
+ * through and it should be correct on its own terms rather than by depending on
+ * how the table above happens to be built — an inherited name like `toString`
+ * reading as a known class is the one failure this function exists to prevent.
+ *
+ * @param {object} record a leaf's front-matter record
+ * @returns {string|null}
+ */
+export function leafVolatility(record) {
+  const volatility = record?.[VOLATILITY_FIELD];
+  return typeof volatility === 'string' && Object.prototype.hasOwnProperty.call(VOLATILITY_LIMITS, volatility)
+    ? volatility
+    : null;
+}
+
+/**
+ * A leaf's declared verified date, or null when it declares none.
+ *
+ * Null covers a malformed date as well as an absent one — `2026-02-30` is not a
+ * day, and measuring an age from it would report a number nobody's calendar
+ * agrees with (the defect `isCalendarDate` was written for, UCS-957). The
+ * schema's pattern catches the SHAPE; this catches the calendar, and the
+ * validator reports the difference so a malformed date is never merely ignored.
+ *
+ * @param {object} record a leaf's front-matter record
+ * @returns {string|null}
+ */
+export function leafVerified(record) {
+  const verified = record?.[VERIFIED_FIELD];
+  return isCalendarDate(verified) ? verified : null;
+}
+
+/**
+ * The time verdict for one leaf — the whole facet, in one function.
+ *
+ * Returns a verdict object, never a bare boolean, because every surface has to
+ * show its WORK: the ticket's demand is that a demotion is never silent, and a
+ * `true` carries no reason a reader could act on. The shape is one stable set
+ * of keys whatever the verdict, so a consumer never needs a presence check to
+ * tell "not stale" from "this engine predates the time facet":
+ *
+ *   verdict     trusted | stale | skipped | exempt | undated
+ *   stale       the boolean every ranking sorts on — `true` ONLY for `stale`,
+ *               so a skipped or exempt leaf is never demoted by accident
+ *   volatility  the declared class, or null
+ *   verified    the declared date, or null
+ *   age         whole days from `verified` to `today`, or null when uncomputed
+ *   limit       the pinned threshold for this class, or null
+ *   reason      why this verdict, in words a reader can act on
+ *
+ * The five verdicts, and why each is its own class rather than folded into
+ * another:
+ *
+ *   skipped   no `today` was injected. NOT `trusted`: the check did not run,
+ *             and reporting a leaf as fresh because nobody asked what day it is
+ *             would be the silent pass this rule exists to prevent (D-012).
+ *   exempt    the leaf declares no volatility, so the store has not placed it
+ *             under time governance at all. Distinct from `trusted`, which is a
+ *             leaf the facet governs and finds fresh — collapsing them would
+ *             report an ungoverned leaf as having passed a check it never sat.
+ *   undated   the leaf declares a volatility but no usable `verified` date, so
+ *             its age is unknowable. NOT stale (nothing measured it) and not
+ *             trusted (nothing vouches for it): the validator raises the
+ *             missing-date finding, and this verdict is what every projection
+ *             says meanwhile. A leaf whose freshness cannot be computed must
+ *             not read as fresh.
+ *   stale     age exceeds the pinned limit for its class.
+ *   trusted   the check ran, and the leaf is inside its limit.
+ *
+ * @param {object} record a leaf's front-matter record
+ * @param {string|null} today the injected date (YYYY-MM-DD), or null
+ * @returns {{verdict: string, stale: boolean, volatility: string|null, verified: string|null, age: number|null, limit: number|null, reason: string}}
+ */
+export function timeVerdict(record, today) {
+  const volatility = leafVolatility(record);
+  const verified = leafVerified(record);
+  // `Infinity` is not JSON: `JSON.stringify(Infinity)` is `null`, silently. So
+  // static's limit is published as an explicit null rather than travelling as
+  // one by accident — the two are the same bytes, and only one of them is a
+  // decision. What distinguishes "never stales" from "no limit applies" on the
+  // wire is `volatility`, which is present either way and says which it is.
+  // The COMPARISON still uses the table's Infinity; this is the wire shape.
+  const limit = volatility === null || volatility === 'static'
+    ? null
+    : VOLATILITY_LIMITS[volatility];
+  const base = { volatility, verified, age: null, limit, stale: false };
+
+  // Order matters. `exempt` is asked FIRST, before the injected date: a leaf
+  // the facet does not govern has the same verdict on every run, and reporting
+  // it as `skipped` would tell a reader to pass --today to learn something
+  // --today cannot tell them.
+  if (volatility === null) {
+    return {
+      ...base,
+      verdict: TIME_VERDICTS.EXEMPT,
+      reason: `no ${VOLATILITY_FIELD} declared — this leaf is not under time governance, so no freshness verdict applies (UCS-1150)`,
+    };
+  }
+  // STATIC is settled here, before `today` and before the date check, because
+  // neither can change the answer: static knowledge never stales, so there is
+  // no age at which it would, and no date that would make it. Reporting it
+  // `skipped` would tell a reader to pass --today to learn something --today
+  // cannot tell them, and reporting it `undated` would demote a leaf whose
+  // whole declared property is that it cannot rot — the same asymmetry the
+  // validator's missing-verified finding draws, where a static leaf without a
+  // date is clean.
+  //
+  // The age is still computed and published when BOTH a date and a `today`
+  // are available: an author who wrote a date meant it, and a surface that
+  // showed nothing would be hiding a fact it holds. The verdict is trusted
+  // either way, which is the part that does not depend on the date.
+  if (volatility === 'static') {
+    const age = verified !== null && today ? daysBetween(verified, today) : null;
+    return {
+      ...base,
+      age,
+      verdict: TIME_VERDICTS.TRUSTED,
+      reason: age === null
+        ? `static knowledge never stales — no age is needed to say so (UCS-1150)`
+        : `static knowledge never stales — verified ${age} day(s) ago (UCS-1150)`,
+    };
+  }
+  if (!today) {
+    return {
+      ...base,
+      verdict: TIME_VERDICTS.SKIPPED,
+      reason: 'skipped — pass --today YYYY-MM-DD to enable time verdicts; diffable output never reads the wall clock (D-012)',
+    };
+  }
+  if (verified === null) {
+    return {
+      ...base,
+      verdict: TIME_VERDICTS.UNDATED,
+      reason: `${volatility} leaf carries no usable ${VERIFIED_FIELD} date — its age cannot be computed, so nothing vouches for its freshness (UCS-1150)`,
+    };
+  }
+  // `static` never stales: Infinity is never exceeded, so the comparison needs
+  // no special case and cannot acquire one by accident. Read from the TABLE,
+  // not from the published `limit` above — that one is nulled for static to
+  // survive JSON, and comparing against it would make every static leaf stale.
+  const age = daysBetween(verified, today);
+  if (age > VOLATILITY_LIMITS[volatility]) {
+    return {
+      ...base,
+      age,
+      verdict: TIME_VERDICTS.STALE,
+      stale: true,
+      reason: `verified ${age} day(s) ago, past the ${limit}-day limit for ${volatility} knowledge — re-verify against the cited sources, or treat the claim as unverified (UCS-1150)`,
+    };
+  }
+  // Only `stable` and `volatile` reach here — `static` returned above and
+  // `exempt` never had a class — so the limit is always a real number.
+  return {
+    ...base,
+    age,
+    verdict: TIME_VERDICTS.TRUSTED,
+    reason: `verified ${age} day(s) ago, within the ${limit}-day limit for ${volatility} knowledge (UCS-1150)`,
+  };
+}
+
+/**
+ * What a surface prints about whether time checks ran at all.
+ *
+ * Every projection that can demote on time must SAY whether it computed
+ * verdicts, and it must say so in one wording — a surface that phrased its own
+ * skip notice would eventually phrase it as silence. Mirrors the audit's
+ * `checks['stale-last-verified']` string exactly, so a reader who has seen one
+ * recognizes the other.
+ *
+ * @param {string|null} today the injected date, or null
+ * @returns {string}
+ */
+export const timeCheckStatus = (today) => (today
+  ? `checked against --today ${today} (stale after ${VOLATILITY_LIMITS.stable} days for stable, ${VOLATILITY_LIMITS.volatile} for volatile; static never stales)`
+  : 'skipped — pass --today YYYY-MM-DD to enable; diffable output never reads the wall clock (D-012)');

package/payload/engine/lib/usage-error.js

@@ -0,0 +1,14 @@
+/**
+ * The caller spelled the command wrong (UCS-944/948).
+ *
+ * A leaf module on purpose. `lib/cli.js` re-exports it for the shells, and the
+ * store loader raises a subclass of it — a `--concepts` id the ontology does
+ * not carry is a usage error, not an engine failure. Keeping the class here
+ * means the loader never has to import the command-line shell to say so.
+ *
+ * Every usage error exits 2. Never 1: exit 1 means findings, and a command that
+ * refused its own arguments never ran.
+ */
+export class UsageError extends Error {
+  name = 'UsageError';
+}