@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/checks.d.ts

@@ -0,0 +1,828 @@
+/**
+ * THE DERIVED-CHECK REGISTRY (kernel plan M3, section 2.3 Kind B; step 8).
+ *
+ * JSON Schema expresses properties of ONE document reachable by one keyword.
+ * A property that compares array elements to each other, resolves a reference
+ * into another document, computes arithmetic over sibling fields or touches
+ * the filesystem is not expressible by any keyword under any DR-0013 option,
+ * and this module is where the plan stopped pretending otherwise (M3R-002).
+ *
+ * Each check runs AFTER schema validation succeeds and reports through the
+ * same contract with its own id attached:
+ *
+ *   INVALID <json-pointer> <message> (check: <check-id>)
+ *
+ * A check that needs a CONTEXT it was not given reports
+ * `SKIPPED <check-id> no context` and the command exits nonzero. That is the
+ * whole point of the mechanism: a cross-document rule must never be able to
+ * pass BY NOT RUNNING, which is the vacuous-pass shape SC-011 and M2-C-2 both
+ * exist to prevent, one layer up.
+ *
+ * DR-0013 clause 8: Kind B rules stay HERE and are never encoded as Ajv
+ * extensions. The Kind A / Kind B boundary is binding.
+ *
+ * D-M3-22: a check that belongs in section 2.3's table and is not in it is a
+ * PLAN DEFECT to escalate, not a script to add quietly.
+ */
+import type { Diagnostic } from "./validate.ts";
+/** What one derived check produced. */
+export interface CheckOutcome {
+    /** Violations, each of which makes the command exit nonzero. */
+    violations: Diagnostic[];
+    /**
+     * Lines the check REPORTS rather than fails on. `plan-dispatchable` is the
+     * instance: a phase whose `fill-in` is present and unfilled is valid for
+     * REVIEW and invalid for DISPATCH, so the validator computes and reports
+     * it instead of rejecting the document.
+     */
+    reports: string[];
+}
+export interface DerivedCheck {
+    id: string;
+    /** The artifact type this check is registered for. */
+    type: string;
+    /**
+     * THE OTHER artifact types this check must ALSO run on. Added by M3-P4 fix
+     * round 2 for CR-001, whose MECHANISM is worth stating at the field rather
+     * than at the one check that tripped over it:
+     *
+     *   A DERIVED CHECK IS REGISTERED PER TYPE AND READS A TYPE-SPECIFIC KEY,
+     *   WHILE THE `$defs` IT GUARDS ARE SHARED ACROSS TYPES BY `$ref`.
+     *   SHARING A DEFINITION THEREFORE DOES NOT SHARE ITS CHECK.
+     *
+     * Keywords travel through a `$ref` and derived checks do not, so a schema
+     * author who moves a rule into a shared definition gets the keyword half of
+     * the sharing for free and the Kind B half not at all. That asymmetry is
+     * invisible at the definition site, which is why `schemas/report.schema.json`
+     * could carry a comment saying a check applied where it did not.
+     *
+     * `guards` below names the shared definitions this check enforces, and
+     * `test/report-contract.test.ts` walks the TRANSITIVE closure of `$ref` in
+     * `schemas/`, failing when a guarded definition is reachable from a type
+     * this check does not list, or when a `guards` pointer resolves to nothing.
+     * REACHABLE was false of the ONE-HOP walk shipped before M3-P4 round 3.
+     */
+    alsoTypes?: readonly string[];
+    /**
+     * The shared `$def`s this check enforces, written as the pointer a
+     * cross-document `$ref` uses (`report.schema.json#/$defs/gateResult`).
+     * Absent means the check enforces nothing shared, which is the ordinary
+     * case: `plan-dispatchable` reads properties that exist in one document
+     * type only.
+     */
+    guards?: readonly string[];
+    /**
+     * True when the check resolves references into documents OTHER than the
+     * instance, so `--context <dir>` is required and its absence is a SKIP
+     * with a nonzero exit rather than a silent pass.
+     */
+    requiresContext: boolean;
+    run(instance: unknown, contextDirectory: string | undefined): CheckOutcome;
+}
+/** Every artifact type one check runs on, `type` first and then `alsoTypes`. */
+export declare function typesOf(check: DerivedCheck): readonly string[];
+/**
+ * A `report-code-disagreement` entry with `verified: false` names a claim
+ * that has NOT been confirmed against the code. R-012 says such a claim
+ * becomes a verification-first step: step 1 is confirm, write down, then
+ * build. So the owning phase must carry a step with `kind:
+ * verification-first`.
+ *
+ * No schema keyword reaches this: it matches an element of ONE array against
+ * a step nested inside an element of ANOTHER array, selected by phase id. A
+ * foreign-key lookup across arrays is not a keyword property.
+ */
+export declare const planVerificationFirstPresent: DerivedCheck;
+/**
+ * A phase whose `fill-in` is present and unfilled is VALID FOR REVIEW and
+ * INVALID FOR DISPATCH. That is a derived boolean over the slots rather than
+ * a property of any one field, so the validator computes and REPORTS it. A
+ * schema cannot express it, and rejecting the document would be wrong: the
+ * plan is legitimately reviewable in that state.
+ */
+export declare const planDispatchable: DerivedCheck;
+/**
+ * Every `hazard-classes[].addressed-by` must RESOLVE. Its two arms resolve
+ * against DIFFERENT things, which is why one witness is not a class here:
+ *
+ *   `criterion <id>`     resolves into the SAME phase's `acceptance[]` ids;
+ *   `later-phase: <id>`  resolves into the PLAN's `phases[]` ids.
+ *
+ * `enum` cannot express either, because the admissible values are computed
+ * per phase rather than fixed. The schema's `pattern` is the Kind A half and
+ * checks only the SHAPE of the string; a shape that resolves to nothing is
+ * precisely the defect section 2.6 was written after finding: a hazard class
+ * that names a criterion which does not exist has documented an obligation
+ * instead of creating one.
+ */
+export declare const planHazardClassesAddressedByResolves: DerivedCheck;
+/**
+ * "Downgrades are declared, never improvised" (blueprint section 8), made
+ * falsifiable: every stage the reference mode `full` runs and this mode does
+ * not must appear in this mode's `skips[]`.
+ *
+ * NO SCHEMA KEYWORD REACHES THIS. It is a set difference between the
+ * `pipeline` of ONE array element and the `pipeline` of a SIBLING element,
+ * selected by id, compared against a third field of the first (M3R-002). The
+ * schema's whole share is that `skips` exists and holds stage ids.
+ *
+ * TWO STRUCTURALLY DIFFERENT WAYS TO EVADE IT, and both are violations here
+ * rather than one being left implied:
+ *
+ *   1. a mode omits a stage and declares NOTHING (`skips: []`);
+ *   2. a mode omits two stages and declares ONE of them, so the document reads
+ *      as a mode that has accounted for itself while one downgrade is silent.
+ *
+ * AND A THIRD, WHICH IS WHY THE MISSING REFERENCE IS A VIOLATION AND NOT A
+ * QUIET RETURN: deleting the `full` mode from the document disables the
+ * comparison for every remaining mode at once, so a document with one
+ * `direct-pr` mode, an empty `skips[]` and no `clean-room-review` would pass a
+ * check that returned early. That is the same defect one level up, so the
+ * absent reference fails closed.
+ *
+ * SOUNDNESS, THE CONVERSE DIRECTION, ADDED IN ROUND 9 (CR-002). Everything
+ * above asks ONE question: is every stage this mode omits DECLARED? It never
+ * asked the converse: is every stage this mode DECLARES actually omitted? A
+ * set checked in one direction only is a set nothing constrains, and `skips[]`
+ * is shipped DATA that any edit can change. The measured consequence was not
+ * hypothetical: `full` keeping its complete twelve-stage pipeline and gaining
+ * ONE bogus `skips[]` entry validated at exit 0, and `tiphys mode show --mode
+ * full` then printed that no phase of the tiphys project had ever been
+ * delivered under the mode this project has delivered every phase under
+ * (delivery/review/clean-room-m3-p3-r8-criteria.md:217).
+ *
+ * SOUNDNESS HAS TWO DIRECTIONS AND ROUND 9 SHIPPED ONE (round 10, V-1).
+ * `skips[]` is defined by the document itself as every stage in `full`'s
+ * pipeline that this mode's pipeline omits AND NOTHING ELSE, so "actually
+ * omitted" is measured against the REFERENCE and an entry can fail it two
+ * ways: (A) this mode's own pipeline runs the stage, and (B) NOTHING runs it,
+ * that is, it is absent from this mode's pipeline and from `full`'s as well.
+ * Round 9 implemented the predicate the reviewer wrote down (A) rather than
+ * the property the same reviewer described thirteen lines earlier, and then
+ * recorded in two shipped documents that the check ran in both directions.
+ * B was reachable on the shipped data with a one-line edit, because the stage
+ * vocabulary has thirteen ids and `full`'s pipeline has twelve: `direct-pr`
+ * gaining `orchestrator-diff-review` validated at exit 0 and `tiphys mode
+ * show` then reported a skipped-stage count one too high with a `skips:` row
+ * naming a stage that is no downgrade at all.
+ *
+ * WHICH SIDE OF THE COMPARISON IS EDITED DOES NOT MATTER, and that is why B is
+ * not merely "a typo in skips". Shrinking `full`'s PIPELINE, touching no
+ * `skips[]` anywhere, turns every other mode's previously correct entry for
+ * that stage into a phantom. The reference is one half of the relation and
+ * either half moving breaks it.
+ *
+ * THE DIRECTION-A PREDICATE RUNS OVER EVERY MODE INCLUDING THE REFERENCE, and
+ * that is load-bearing rather than a detail. The completeness loop `continue`s
+ * past `full` because a mode cannot omit a stage relative to itself; the
+ * soundness question is well posed for `full` too, and `full` is precisely the
+ * mode the sharpest member targeted. A soundness loop that inherited the
+ * completeness loop's skip would have been green against the finding that
+ * caused it to be written.
+ *
+ * DIRECTION A NEEDS NO REFERENCE MODE, so it runs BEFORE the reference is
+ * resolved and its violations survive an absent `full`. A document that both
+ * deletes `full` and carries a contradictory `skips[]` reports both facts
+ * rather than the first one only. DIRECTION B cannot: it is defined by the
+ * reference pipeline, so it runs after the resolution and an absent `full` is
+ * already a violation in its own right.
+ */
+export declare const modeNoUndeclaredDowngrade: DerivedCheck;
+/**
+ * R-024: an adversarial plan review happens before anyone builds.
+ *
+ * THE RELATIVE POSITION OF TWO VALUES IN A VARIABLE-LENGTH ARRAY IS NOT A
+ * KEYWORD PROPERTY (M3R-002). `contains` can say both are present and nothing
+ * in the vocabulary can say which comes first.
+ *
+ * The rule has TWO ARMS because there are two ways to build before a review,
+ * and the plan states both: reorder them, or delete the review. So a mode
+ * whose pipeline contains `implement` and NOT `adversarial-plan-review` must
+ * list the review in `skips[]`, which is the same declared-downgrade
+ * discipline applied to the one stage R-024 is about.
+ */
+export declare const modeStageOrder: DerivedCheck;
+/**
+ * Every `gate-sets[]` entry RESOLVES against `gate-registry.yaml`.
+ *
+ * WHAT "RESOLVES" MEANS HERE, stated because a checker whose promise is vague
+ * is a checker nobody can falsify: the entry names a gate the registry
+ * declares, AND that gate's own `modes` list names this mode. Both halves are
+ * needed, because a reference that resolves to a gate which never runs in this
+ * mode is a mode whose assurance is a name with no gates behind it, which is
+ * the hazard exactly as the plan words it.
+ *
+ * `requiresContext` is TRUE, so invoking the validator without `--context`
+ * prints `SKIPPED mode-gate-sets-resolve no context` and exits nonzero. That
+ * is the point of the mechanism (M3-P1 criterion 4c): a cross-document rule
+ * must never be able to pass BY NOT RUNNING.
+ */
+export declare const modeGateSetsResolve: DerivedCheck;
+/**
+ * The charter schema's mode enums equal the ids declared here.
+ *
+ * `schemas/charter.schema.json` declares the mode vocabulary a project charter
+ * may use, and this document declares what those modes ARE. Two lists, one
+ * fact. Without this check they are a duplication that drifts silently the
+ * first time a mode is added, which is the same drift hole M3-P2 closed for
+ * the gate list.
+ *
+ * BOTH FIELDS, not one. The charter carries `delivery-mode` AND
+ * `assurance-tier`, M3-P1 shipped the identical placeholder enum on both, and
+ * step 4 names both ("Add `mode` and `assurance-tier` validation to the
+ * charter schema's enum"). A check that watched only one would leave the other
+ * free to drift, which is the hazard rather than a smaller version of it.
+ */
+export declare const charterModeEnumMatchesModes: DerivedCheck;
+/** `modes[].id` selects exactly one mode. */
+export declare const modeIdsAreUnique: DerivedCheck;
+/**
+ * `roles[].role` selects exactly one binding. B-004: the SAME defect, in the
+ * document nothing consumes yet, which is why it was latent rather than
+ * demonstrable. It is fixed in the same act because the mechanism is one thing.
+ */
+export declare const roleIdsAreUnique: DerivedCheck;
+/**
+ * The QUOTABLE UNITS of a prose record: every top-level PARAGRAPH and every
+ * OUTERMOST LIST ITEM, each with its marker stripped and its whitespace
+ * normalized.
+ *
+ * WHY THIS EXISTS, and it is the whole of fix round 2. The first version of
+ * this check asked whether each condition OCCURRED ANYWHERE in the record, as
+ * one normalized blob. That is a CONTAINMENT predicate standing in for an
+ * EQUALITY predicate, and containment is trivially satisfiable by short
+ * strings: `conditions: ["a", "the", "review", "merge", "is", "of"]` replaced
+ * every one of DR-0012's six merge-authority conditions with junk and the
+ * check exited 0. Every one of those words occurs in the record.
+ *
+ * The signal was already in this phase's own evidence and was read past: an
+ * earlier probe fabricated `"one"` through `"six"` and got findings for
+ * indices 3, 4 and 5 ONLY, because "one", "two" and "three" occur inside the
+ * record's prose. Three of six caught looked like the check working.
+ *
+ * Comparing against UNITS rather than against the blob makes the predicate an
+ * equality: a condition matches only if it is a WHOLE quoted item of the
+ * record. Both halves matter. Whole, so a fragment cannot match; item rather
+ * than whole document, so a record may carry other prose around the conditions
+ * without anyone having to say which section holds them, which is the
+ * structure assumption that would have made this check project-specific.
+ *
+ * THE COST, stated because it is a real constraint on a consuming project: a
+ * condition must be quoted as a complete list item or paragraph of the record.
+ * A condition that paraphrases, or that quotes half of a longer item, is now
+ * a violation. That is what "quoted from the decision record rather than
+ * summarized" already claimed to mean, and it is now enforced rather than
+ * asserted.
+ *
+ * A LIST ITEM'S UNIT IS THE WHOLE ITEM. An item's continuation paragraphs and
+ * its nested sub-items are CONTENT OF THE ITEM in CommonMark, so emitting them
+ * as units of their own would leave the item's FIRST PARAGRAPH standing as a
+ * whole unit while the item itself carried more, which is a fragment passing as
+ * a whole quote: the defect this check exists to prevent, arriving through the
+ * extractor. It is live in this repository:
+ * `delivery/decisions/DR-0004-elevated-permissions.md` has the shape (an item,
+ * a blank, then its commands indented under it) and
+ * `delivery/decisions/DR-0013-schema-validator-implementation.md` has the
+ * nested-list form. THE COST, stated because it is real: a nested sub-item is
+ * not separately quotable, so a record whose conditions are sub-bullets must
+ * quote the enclosing item whole.
+ *
+ * ------------------------------------------------------------------
+ * THE BLOCK STRUCTURE IS READ FROM A COMMONMARK PARSER (DR-0022, owner
+ * decision, option A2). THE TEXT IS SLICED FROM THE ORIGINAL SOURCE.
+ * ------------------------------------------------------------------
+ *
+ * What stood here until 2026-08-09 was a HAND-ROLLED CommonMark block parser:
+ * a line loop carrying fence state, indented-code state, a list content column
+ * and a deferred-blank flag, with six sites that could end a unit. It took FIVE
+ * fix rounds and produced FIVE defects, the fifth a regression of a shape the
+ * fourth had correct. The owner's decision records the measurement that ended
+ * it: against two independent conformant parsers over 15,000 generated
+ * documents, the hand-rolled loop agreed on about 35 per cent of them.
+ *
+ * The reason the rounds could not converge is worth keeping, because it is a
+ * property of the problem and not of the agents. Whether a line is prose
+ * depends on which block encloses it, and which block encloses it depends on
+ * lines above and sometimes below (a setext underline retroactively makes the
+ * block above it a heading). A loop that decides one line at a time is
+ * reconstructing a parser, and every reconstruction has to be kept in agreement
+ * with the reference BY HAND, with no mechanism that detects divergence. That
+ * is the "guard narrower than the property" family, and this repository has now
+ * recorded it five times in this one function.
+ *
+ * TWO OF THE ELEVEN FINDINGS ACROSS THOSE ROUNDS WERE NOT DEFECTS AT ALL. V-3
+ * ("adjacent paragraphs merge") and the fifth member of V-5 (a nested sub-item
+ * followed by a dedented line) were both cases where a hand-reading of markdown
+ * disagreed with CommonMark and the HAND-READING WAS WRONG: lazy continuation
+ * makes both fusions correct. A round can only find defects it already believes
+ * in, which is the other half of the cost.
+ *
+ * WHY `sourcepos` SLICING AND NOT THE PARSER'S INLINE TEXT, which is the whole
+ * of A2 versus A and is the single most expensive detail here. Walking the AST
+ * and reading each paragraph's inline text is the obvious implementation and it
+ * SILENTLY CHANGES THE SHIPPED CONTRACT, because inline text drops markup:
+ * `` `delivery/review/` `` becomes `delivery/review/`. DR-0012's first
+ * merge-authority condition contains exactly that, so `assurance-modes.yaml`
+ * stops resolving, and 11 of this repository's 19 decision records produce
+ * different unit sets. Slicing the ORIGINAL SOURCE by the parser's own
+ * `sourcepos` offsets keeps the bytes as written, which is what every existing
+ * record and every existing condition relies on.
+ *
+ * SO: this function reads the parser for STRUCTURE ONLY. It never reads
+ * `literal` and never concatenates inline nodes, and a change that starts doing
+ * either is option A, which is a defect. `CommonMarkNode` above declares six
+ * members and none of them is inline text, so the type is the guard.
+ *
+ * WHAT THE FOUR PREVIOUSLY UNMODELLED BLOCK FORMS DO NOW, since the old
+ * docstring listed them as latent hazards:
+ *   - block quote: its contents are treated like the document's, so the quoted
+ *     paragraph is a unit and the `>` marker is NOT part of it. This is a
+ *     DECLARED POLICY CHOICE (see `collectUnits`), not a derivation.
+ *   - HTML block: contributes no unit. Corrected in round 7 (CR-003): it is
+ *     listed in `NOT_QUOTABLE`, but under `commonmark` 0.31.2 that listing is
+ *     not what excludes it. An `html_block` is an AST LEAF, and a unit is only
+ *     ever emitted for a `paragraph` child, so it could contribute nothing even
+ *     if the set were empty. Read `NOT_QUOTABLE`'s own docstring for what the
+ *     set is really for.
+ *   - link reference definition: excluded, and by construction rather than by a
+ *     rule, because the parser removes it before this walk sees the document.
+ *   - pipe table: never was a hazard. CommonMark core has no tables, so a table
+ *     IS a paragraph and treating its lines as prose is correct.
+ *
+ * WHERE THIS IS STILL NOT AN ORACLE: it is right in the sense of "agrees with
+ * `commonmark` 0.31.2". Two conformant CommonMark implementations disagree on
+ * roughly half a per cent of generated documents (an indented line immediately
+ * after a link reference definition is the measured instance), and any
+ * structure-reading option inherits that.
+ */
+export declare function quotableUnits(text: string): Set<string>;
+export declare const modeConditionsQuoteGrantedBy: DerivedCheck;
+/**
+ * WHERE THE SHARED `gateResult` DEFINITION IS REACHED FROM, one row per
+ * artifact type, naming the KEY that type stores its gate results under.
+ *
+ * This table is the concrete form of CR-001's mechanism. The definition is
+ * one object reached by `$ref` from two documents; the PROPERTY NAME differs
+ * between them (`gate-results` in a report, `gate-evidence` in a work
+ * history), so a check that hard-codes one key is blind on the other type
+ * even after it is registered for it. Both halves are needed and only one of
+ * them is visible from the `$ref`.
+ */
+export declare const GATE_RESULT_SITES: readonly {
+    readonly type: string;
+    readonly key: string;
+}[];
+/**
+ * `discovered == passed + failed + skipped + did-not-run`, over one gate
+ * result's sibling fields.
+ *
+ * NO SCHEMA KEYWORD COMPUTES ARITHMETIC over sibling fields, which is what
+ * makes this Kind B rather than a keyword (M3R-002 corrected revision 0's
+ * classification of exactly this check). The property it guards is R-048's:
+ * a suite that reports fewer tests than it discovered is the
+ * silently-dropped-tests case, and it adds up to a green everywhere else.
+ *
+ * THREE THINGS THIS CHECKS, and the second and third are the CONVERSES the
+ * criterion's letter does not name. The plan's criterion 2b(a) names only
+ * `discovered` EXCEEDING the sum. A check that tested only that direction
+ * would pass a record whose sum exceeds `discovered`, which is a different
+ * lie with the same shape, so the test here is EQUALITY. And a count field
+ * that is NEGATIVE is arithmetic nonsense that equality alone can satisfy
+ * (`discovered: 0` with `passed: 1` and `failed: -1` adds up); negativity is
+ * not reachable by any keyword in the declared authoring vocabulary, which
+ * has no `minimum`, so it is checked here beside the sum rather than left to
+ * a keyword that does not exist.
+ *
+ * WHAT IT DOES NOT REACH, stated rather than implied: a gate result carrying
+ * NO count field at all is not examined, because the schema requires the six
+ * counts only of a `green`, and a `red` result that records none of them is a
+ * legitimate record rather than a false one. So this check cannot see a
+ * dropped test in a run nobody counted; it sees one in a run that claims a
+ * count. Nor does it reach a BALANCED loss: an author who drops the same row
+ * from `discovered` and from a bucket satisfies the identity, because nothing
+ * here anchors `discovered` to what the wrapper actually discovered.
+ *
+ * WHERE IT RUNS, and this is CR-001's whole content. It runs on EVERY type
+ * that reaches the shared `gateResult` definition, enumerated by
+ * `GATE_RESULT_SITES` rather than by one hard-coded key. Until M3-P4 fix
+ * round 2 it was registered for `report` alone and read `gate-results` alone,
+ * so a work history recording 9999 discovered and 1 passed exited 0 while the
+ * identical counts in a report exited 1, and the shared definition's own
+ * comment said the check applied.
+ */
+export declare const reportParityArithmetic: DerivedCheck;
+/**
+ * Every id in `inputs[]` appears in `input-findings[]`, exactly once, and no
+ * `input-findings[]` row names an id `inputs[]` does not carry.
+ *
+ * A CROSS-ARRAY COMPLETENESS PROPERTY, which no keyword reaches: `contains`
+ * asks about a fixed shape, not about a value computed from a sibling array.
+ * Revision 0 of the plan listed this once as a schema witness, which was
+ * wrong (M3R-002).
+ *
+ * THREE DIRECTIONS, and only the first is in the criterion's letter. The
+ * criterion names the ORPHAN: an id in `inputs[]` with no row. The PHANTOM
+ * (a row whose id is not an input) and the DUPLICATE (two rows for one id)
+ * are the converses, and they are here because M2-P6 paid for both by
+ * measurement rather than by argument: CR-988 records that its parity mode
+ * scanned inventory ids only, so a row for a renumbered id was silently
+ * accepted, and CR-985 records that a duplicated id defeated the orphan and
+ * phantom checks TOGETHER while inflating every count. A guard narrower than
+ * its own description is what this project keeps re-buying, so the check is
+ * as wide as the relation.
+ *
+ * WHAT IT DOES NOT REACH: a finding dropped from BOTH arrays. The two
+ * documents then agree with each other, and no comparison between them can
+ * see it. That is the same residue `src/gates/coverage.ts` answers with a
+ * config-stated `expectedUnits` anchor, and this schema has no such anchor
+ * because nothing in the plan states one.
+ */
+export declare const finalReportFindingParity: DerivedCheck;
+/**
+ * A report with an EMPTY `findings` array carries a `no-findings-statement`,
+ * and a report that files findings does NOT carry one.
+ *
+ * KIND B BY NECESSITY, AND THE NECESSITY IS MEASURED RATHER THAN ASSERTED.
+ * The natural keyword shape is `if findings has maxItems 0 then require
+ * no-findings-statement`, and `maxItems` is ABSENT from the sixteen keywords
+ * of `AUTHORING_VOCABULARY` (src/validate.ts:111). No other permitted keyword
+ * says "this array is empty": `minItems` says the opposite, `contains` asks
+ * about a member that exists, and `const: []` is not reachable because `const`
+ * is used on scalars here and an array `const` would pin the CONTENTS. So the
+ * emptiness of a sibling array is not a keyword property, which is the same
+ * boundary `report-parity-arithmetic` sits on one field over.
+ *
+ * WHY IT IS HERE AT ALL. `no-findings-statement` exists to price silence: a
+ * report claiming nothing was found must say WHY nothing was found. Optional,
+ * it is absent in exactly the situation it exists for, and the shipped schema
+ * disclosed that as a residue rather than closing it. The orchestrator's
+ * arbitration of M3-P4 round 1 amended section 2.3's table to three rows for
+ * this phase and directed the check to be written; D-M3-22 is satisfied by
+ * that amendment, not by this comment.
+ *
+ * BOTH DIRECTIONS, because the phase's own converse discipline demands it.
+ * The requirement's letter names only the empty-with-no-statement case. A
+ * report that files three findings and ALSO carries "no findings were found"
+ * is the opposite misdeclaration and is equally a false record, so it is a
+ * violation too.
+ *
+ * WHAT IT DOES NOT REACH: whether the statement SAYS anything. The schema
+ * makes an empty or whitespace-only one impossible; a statement reading "n/a"
+ * satisfies both this check and those keywords, and that is M3-P7's
+ * `contract-avoidance` probe rather than anything a schema or a check can see.
+ * It also does not reach a report with NO `findings` key at all, because
+ * `findings` is `required` and the schema rejects that before any check runs.
+ */
+export declare const reportNoFindingsStatement: DerivedCheck;
+/**
+ * No two probes in one checklist share an `id`.
+ *
+ * KIND B, AND THE REASON IS A KEYWORD'S SEMANTICS RATHER THAN A DOCUMENT
+ * BOUNDARY. `uniqueItems` compares WHOLE array items, so two probes sharing
+ * an id and differing in any other field are already unique to it, and the
+ * pair that shares an id is exactly the dangerous instance: `checklist
+ * resolve` looks a probe up by id, so a duplicate makes the resolved list
+ * depend on which one the lookup reached. Uniqueness of a NESTED PROPERTY
+ * across array items is not a keyword property under any DR-0013 option,
+ * which is why the review did not name it and why it lands here.
+ *
+ * `requiresContext` is FALSE: the whole comparison is inside one document.
+ */
+export declare const checklistProbeIdsUnique: DerivedCheck;
+/**
+ * No two framings in one checklist share an `id`.
+ *
+ * THE SAME SHAPE AND THE SAME KEYWORD LIMITATION AS THE PROBE CHECK ABOVE,
+ * one array along. `uniqueItems` on `framings` compares WHOLE items, so two
+ * framings sharing an id and differing in their entry point or their scope
+ * order are already unique to it, and that pair is exactly the dangerous
+ * instance: `resolveChecklist` looks a framing up with `.find()`, first match
+ * wins, so which of two declared entry points a reviewer is handed depends on
+ * FILE POSITION and nothing says so.
+ *
+ * WHY IT MATTERS MORE HERE THAN THE PROBE CASE LOOKS LIKE IT WOULD. A
+ * framing IS the entry point, and T-001's lesson that decorrelation comes
+ * from the starting question is the whole reason `--framing` exists. A
+ * duplicate id means the reviewer's starting question is decided by which
+ * copy sat first in the file, which is the phase's own hazard class ("a
+ * framing that reorders the list without changing the entry point") reached
+ * from the other side.
+ *
+ * `requiresContext` is FALSE: the whole comparison is inside one document.
+ */
+export declare const checklistFramingIdsUnique: DerivedCheck;
+/**
+ * The join M3-P2 deliberately left open, closed in BOTH DIRECTIONS.
+ *
+ * `gate-registry.yaml` carries entries whose `verified-by` is
+ * `clean-room-checklist` and whose `probe` names a probe id this phase
+ * supplies. Nothing on the registry side can check that the probe exists,
+ * because the checklist did not exist when the registry shipped.
+ *
+ * DIRECTION 1, REGISTRY TO CHECKLIST (criterion 3). Every registry entry
+ * verified by a checklist names a probe that RESOLVES in that checklist, and
+ * that probe carries the `verifies-gate` back-reference to the entry. WHICH
+ * checklist is derived from the registry's own vocabulary rather than
+ * hardcoded: `verified-by: clean-room-checklist` names the checklist whose id
+ * is `clean-room`, so an entry is only asserted against the document it
+ * actually names, and running this check on `plan-review.yaml` does not
+ * demand the clean-room probes there.
+ *
+ * DIRECTION 2, CHECKLIST TO REGISTRY (criterion 3c). Every probe carrying
+ * `verifies-gate` names a gate id present in the registry. THE ASYMMETRY IS
+ * THE WHOLE POINT: direction 1 starts from the registry and therefore cannot
+ * see a probe pointing at a gate that no longer exists, which is what the
+ * phase's own hazard class calls an orphan invisible by construction. The two
+ * ways a registry edit orphans a probe fail through DIFFERENT lookups: a gate
+ * id RENAMED leaves the probe pointing at a name that never existed, and a
+ * gate entry DELETED leaves it pointing at a name that used to. Both land
+ * here; neither is reachable from direction 1.
+ *
+ * `requiresContext` is TRUE, so invoking the validator without `--context`
+ * prints `SKIPPED gate-probes-resolve no context` and exits nonzero. A
+ * cross-document rule must never be able to pass BY NOT RUNNING.
+ */
+export declare const gateProbesResolve: DerivedCheck;
+/**
+ * A verdict's `criteria[]` carries one entry per acceptance criterion of the
+ * plan phase it reviews.
+ *
+ * THE DANGEROUS INSTANCE is a review that quietly skipped a criterion: every
+ * entry present is well formed, the schema is satisfied, and the one
+ * criterion nobody walked is invisible. R-053 says each criterion is quoted
+ * with evidence and a verdict, and "each" is a comparison against a DIFFERENT
+ * document, which no keyword reaches.
+ *
+ * BOTH DIRECTIONS, because they are different mistakes. A criterion the
+ * verdict omits is an unwalked criterion; a verdict entry naming a criterion
+ * the phase does not declare is a review walking something that is not in the
+ * contract, usually a criterion id left behind by a plan revision.
+ */
+export declare const verdictCriteriaComplete: DerivedCheck;
+/**
+ * A verdict's `deviations-judged[]` carries one entry per deviation declared
+ * in the phase's work history.
+ *
+ * M3R-005 IS WHY THIS IS A CHECK AND NOT A PROBE. R-057b's "judged, never
+ * assumed by the implementer" has exactly the same completeness shape as
+ * criteria coverage, and revision 0 had left it as a bare probe question for
+ * no stated reason, so a reviewer could silently skip judging one of three
+ * declared deviations and every criterion still passed.
+ *
+ * THE OTHER DOCUMENT IS `work-history.yaml` in the context directory, and it
+ * must be the work history OF THE PHASE THIS VERDICT NAMES: a work history
+ * for another phase would let the check pass by comparing against the wrong
+ * deviation list, which is a vacuous pass wearing a cross-document check's
+ * clothes.
+ */
+export declare const verdictDeviationsJudged: DerivedCheck;
+/**
+ * A HAZARD verdict's `hazard-classes-addressed[]` carries one entry per
+ * hazard class declared by the plan phase it reviews.
+ *
+ * T-007 IS THE INPUT AND M3R-005 IS THE SHAPE. This has exactly the shape
+ * `verdict-criteria-complete` has for criteria, one field along, and for
+ * exactly the same reason: a reviewer could otherwise silently skip one of
+ * three declared hazard classes while every other criterion still passed.
+ * T-007's measured case is a phase meeting fifteen of fifteen executed
+ * criteria while live-locking every supervision command.
+ *
+ * IT APPLIES EXACTLY WHERE THE CONTRACT APPLIES. A verdict whose
+ * `review-contract` is `criteria` is not asserted against, because the
+ * criteria contract is not the one that owes hazard statements, and a check
+ * that reddened on it would push reviewers to fill the array with nothing.
+ * That the criteria arm is unaffected is asserted by a test rather than left
+ * as an implication.
+ */
+export declare const verdictHazardClassesAddressed: DerivedCheck;
+/**
+ * Every `hazard-classes-addressed[].finding` names a `findings[].id` that
+ * exists in the SAME verdict.
+ *
+ * KIND B FOR THE SAME REASON `checklist-probe-ids-unique` IS, AND IT IS THE
+ * ONLY INTRA-DOCUMENT ID REFERENCE THE SHIPPED SCHEMAS DECLARE. The
+ * verdict schema's own `$comment` on `finding` calls it "the `findings[].id`
+ * this class produced", so the join is DECLARED; nothing resolved it, so it
+ * was a bare string with `minLength: 1`. Resolving one array's entry against
+ * another array's ids is not a keyword property under any DR-0013 option,
+ * which is why it lands here and not in the schema.
+ *
+ * WHAT IT PROTECTS, and it is not merely tidiness. The verdict schema ships
+ * exactly ONE rule that can force a verdict off APPROVE: a `findings[]` set
+ * containing a `high` or `critical` entry must carry FIX-ROUND-NEEDED. That
+ * rule reads `findings[]` and nothing else. So a hazard reviewer who records
+ * a class as having produced a finding, and leaves that finding out of
+ * `findings[]`, gets a schema-valid APPROVE with an empty findings array and
+ * the escalation rule never sees the finding it would have fired on. Measured
+ * at 4bfa790 before this check: such a document validated at exit 0, and the
+ * same document with the finding moved into `findings[]` at `severity: high`
+ * exited 1.
+ *
+ * A DANGLING REFERENCE IS ITSELF THE ERROR, not only one that lets the
+ * escalation be evaded, and the reason is that the narrower rule is not
+ * computable. A finding absent from `findings[]` has NO severity, so nothing
+ * can decide whether it would have escalated; the narrower reading would have
+ * to guess, and would clear exactly the document that withheld the most.
+ * Requiring the reference to resolve is decidable, and it puts the severity
+ * back under the escalation rule where the reader can see it.
+ *
+ * `requiresContext` is FALSE: the whole comparison is inside one document.
+ */
+export declare const verdictFindingReferencesResolve: DerivedCheck;
+/**
+ * A `structural-consequence` marked `applied` names a target path that EXISTS.
+ *
+ * KIND B BY NECESSITY: it resolves a string against the filesystem, which no
+ * keyword under any DR-0013 option reaches. `requiresContext` is TRUE, so
+ * running the validator without `--context` prints `SKIPPED
+ * tuition-target-exists no context` and exits nonzero rather than passing by
+ * not running.
+ *
+ * ONLY `applied` IS CHECKED, and that is the point rather than a limitation.
+ * `proposed` names a change nobody has made and `ticketed` names one carried
+ * by a record, so neither claims anything about the tree; `applied` claims the
+ * change is IN the tree, and T-003 is the entry recording that a document can
+ * carry exactly that claim falsely.
+ *
+ * WHAT IT DOES NOT REACH, named here because criterion 3 reads at a glance as
+ * though it covered the whole hazard: whether the file CONTAINS the change
+ * claimed. That is a semantic relation between a prose sentence and a file,
+ * and the plan's own hazard table assigns it to review rather than to a check
+ * (section 2.6 reason 1). The two halves are exactly what this project has
+ * repeatedly found to differ, so the check states which half it is.
+ */
+export declare const tuitionTargetExists: DerivedCheck;
+/**
+ * A PATH REFERENCE inside a `mechanisms[]` entry resolves against the tree,
+ * and a `machine-readable-form` resolves to a real document AND a real key
+ * inside it.
+ *
+ * T-005's checkability rule has two halves and they need two instruments. The
+ * SCHEMA half is `evidence` with `minItems: 1`: a rule with no citation is not
+ * a rule. THIS half is that a citation naming a file which does not exist is
+ * not a citation, which is a filesystem question and therefore Kind B.
+ *
+ * WHAT COUNTS AS A PATH REFERENCE, stated mechanically because a checker whose
+ * subject is vague cannot be falsified: a whitespace-delimited token holding at
+ * least one `/` and ending in a short extension, with surrounding backticks,
+ * brackets and trailing punctuation stripped. Real evidence in this feed reads
+ * `delivery/review/verification-m1-p3-fix-round.md V-1 and V-3`, so the
+ * reference is a token inside a sentence rather than the whole string.
+ *
+ * A `path.ext:LINE` CITATION IS A PATH REFERENCE (HRB-1, fix round 3). It is the
+ * form CLAUDE.md:155 mandates, and the earlier token test silently dropped every
+ * one of them; see `pathReferencesIn` for the measurement and the grammar.
+ *
+ * WHAT IT DOES NOT REACH, and these are real holes rather than tidy ones.
+ *
+ * PROSE-ONLY evidence. `M1-P5 round 4, verified pre-existing against a pristine
+ * build` names no path, so nothing about it is resolvable and this check says
+ * nothing about it. Requiring every citation to be a path would redden entries
+ * whose evidence is a measurement rather than a document, which is a real form
+ * of evidence this project uses. The residue is therefore deliberate: the check
+ * establishes that the paths cited EXIST, never that a rule is supported.
+ *
+ * A CITATION INTO A TREE THIS CONTEXT DOES NOT HAVE (HRB-8, fix round 3). The
+ * feed ships and `delivery/` does not, so in a consumer's install most citations
+ * name a repository that is not there. Those are REPORTED, with their count and
+ * the trees involved, and never counted as violations; see
+ * `unresolvableCitationTree` for why that is the correct answer rather than a
+ * softening, and for the reason it is not a silent pass.
+ *
+ * REGISTERED FOR BOTH TYPES. `mechanisms[]` appears in a tuition entry (where
+ * a rule is authored) and in the mechanism index (where it is projected). A
+ * check registered only for the first would leave the shipped index unchecked,
+ * which is the shared-definition asymmetry `alsoTypes` exists for.
+ */
+export declare const mechanismRuleEvidenceResolves: DerivedCheck;
+/**
+ * Every path-like token in one prose reference. See the check's header for the
+ * definition and for what it deliberately does not treat as a path.
+ *
+ * THE `:LINE` SUFFIX IS STRIPPED BEFORE THE EXTENSION TEST (HRB-1, M3-P8 fix
+ * round 3). CLAUDE.md:155 makes `path.ext:LINE` THE citation form in this
+ * project ("a bare path is not a citation at all") and src/gates/citations.ts
+ * is the gate that enforces it. The earlier form tested the extension at
+ * end-of-string, and a line number sits after it, so every citation written the
+ * way this repository REQUIRES resolved to nothing: an entry whose paths were
+ * entirely fabricated validated at exit 0, and the byte-identical entry with
+ * the suffixes removed went red. A check that passes exactly the mandated form
+ * is not a check.
+ *
+ * The suffix grammar is the citations gate's own, narrowed to what a suffix can
+ * be rather than re-derived: `:<line>`, an optional `-<line>` range, and an
+ * optional `@sha256:<hex>` content pin (src/gates/citations.ts:453). Stripping
+ * is deliberately conservative: a token that does not match keeps its colon and
+ * is then judged by the extension test as before, so `http://x/y.md` and
+ * `a/b.md:notaline` are unchanged.
+ */
+export declare function pathReferencesIn(reference: string): string[];
+/**
+ * THE TREE A CITATION IS ROOTED IN, when this context does not contain it.
+ * Returns that top-level name, or undefined when the citation IS resolvable
+ * here and absence would therefore be a real defect.
+ *
+ * WHY (HRB-8, M3-P8 fix round 3). A citation is relative to the repository that
+ * AUTHORED it. The tuition feed and its index ship in the npm package;
+ * `delivery/`, `src/`, `scripts/` and `test/` do not (package.json's `files`).
+ * So the checks that resolve a document-supplied path were asking a consumer's
+ * install a question only the kernel repository can answer, and answering it
+ * INVALID. Measured at 26ee653: the shipped index produced 16 INVALID lines
+ * from a pristine `npm pack` extraction, and eight of the fifteen shipped
+ * entries produced more. CI never saw it because this repository has
+ * `delivery/`, which is T-009's shape one scope out.
+ *
+ * schemas/mechanism-index.schema.json:5 already stated the governing fact
+ * before this round: resolution "is not computable from an installed package".
+ * This is that sentence made operative rather than decorative.
+ *
+ * THE PREDICATE IS THE TOP-LEVEL SEGMENT, and it is the coarsest one that still
+ * catches everything the kernel repository could catch before. A citation into a
+ * tree that IS present must still resolve, so a fabricated
+ * `delivery/review/invented.md` is as red here as it ever was; only a citation
+ * into a tree that is wholly absent is excused. A path with no directory
+ * component is NEVER excused, because the context root always exists: measured
+ * against the real feed, every `applied` root-level target ships, and the one
+ * root-level absentee (`AGENTS.md`) is `ticketed`, which the check does not read.
+ *
+ * THIS IS NOT A LICENCE TO GO QUIET. Every caller REPORTS what it declined to
+ * resolve and why. "Nothing to check here" and "everything checked and fine"
+ * must never print the same line, which is the SC-011 shape the plan's hazard
+ * row at delivery/plan/kernel-plan-m3.md:4042 polices.
+ */
+export declare function unresolvableCitationTree(contextDirectory: string, path: string): string | undefined;
+/** The three dimensions two verdicts of one head must differ on. */
+export declare const DECORRELATION_DIMENSIONS: readonly string[];
+/** The merge-authority value that makes decorrelation a precondition of merge. */
+export declare const DELEGATED_MERGE_AUTHORITY = "delegated-under-conditions";
+/**
+ * DR-0012's merge precondition, made into a comparison a command can make
+ * against the verdict FILES rather than against a session's memory (M3R-004).
+ *
+ * WHY THIS IS KIND B AND COULD NOT BE A KEYWORD. Every dimension it compares
+ * lives in a DIFFERENT DOCUMENT from the instance: distinctness is a property
+ * of a PAIR of verdicts, and no keyword under any DR-0013 option can see the
+ * sibling.
+ *
+ * IT ESTABLISHES PRESENCE ITSELF AND DOES NOT BORROW IT FROM THE SCHEMA. An
+ * earlier version of this comment said the verdict schema's `required` buys
+ * absence-freedom, so this check only had to decide difference. That division of
+ * labour was never composed: nothing on the shipped path validates the SIBLING
+ * documents, so a document with `kind: verdict` and a missing required field is
+ * loaded here and compared. The rule the whole section now follows is
+ * `establishField`, one screen up: a value is not comparable until it has been
+ * established, and absence, unusability and difference are three verdicts, not
+ * one.
+ *
+ * IT APPLIES EXACTLY WHERE THE GRANT APPLIES. The regime is read from the
+ * declared mode, not assumed: `charter.yaml` names the delivery mode and
+ * `assurance-modes.yaml` says what that mode's `merge-authority` is. A mode
+ * whose authority is not a delegated grant has no decorrelation precondition to
+ * satisfy, and this check REPORTS that rather than passing silently, because
+ * "nothing to check here" and "everything checked and fine" must never print
+ * the same line (SC-011).
+ *
+ * FIVE DIMENSIONS, AND (e) IS NOT A REFINEMENT OF (b). T-007's whole finding is
+ * that model decorrelation and CONTRACT decorrelation are different properties
+ * and this project had the second by accident: two reviewers on different model
+ * families walked all fifteen criteria of one phase, agreed on every mechanical
+ * fact, and one missed a high-severity defect because both had been given the
+ * criteria contract. So `review-contract` is compared separately and is
+ * witnessed separately (criterion 7b).
+ *
+ * WHAT IT DOES NOT REACH, named rather than left to be found. Condition (d) of
+ * step 3b, that neither verdict carries an unresolved high or medium finding,
+ * is NOT checked here: the verdict schema's own root `if`/`then` already
+ * forbids APPROVE beside a high or critical finding, and "unresolved" is a
+ * state of the review thread rather than of the document. Nothing here decides
+ * whether the two verdicts describe the same HEAD either: the verdict schema
+ * carries no head field, so `phase` is the join key and the DIRECTORY is what
+ * scopes a set of verdicts to one head. Both are stated in
+ * delivery/work-history/m3-p9.md as declared readings rather than absorbed.
+ */
+export declare const dualReviewDecorrelation: DerivedCheck;
+/** Register a check. Later phases append their own (section 2.3's table). */
+export declare function registerCheck(check: DerivedCheck): void;
+/** Remove a check by id. Returns whether one was removed. */
+export declare function deregisterCheck(id: string): boolean;
+/** Every check registered for an artifact type, in stable id order. */
+export declare function checksFor(type: string): DerivedCheck[];
+/** Every registered check, in registration order. Read by the enumeration. */
+export declare function registeredChecks(): readonly DerivedCheck[];
+/** The outcome of running every check registered for a type. */
+export interface ChecksRun {
+    /** Lines to print, in the order they should appear. */
+    lines: string[];
+    /** True when at least one check violated or was skipped for want of context. */
+    failed: boolean;
+}
+/**
+ * Run every registered check for `type`.
+ *
+ * A check whose `requiresContext` is true and which was given none is
+ * SKIPPED and the run FAILS. It is deliberately not an ordinary violation:
+ * "this rule did not run" and "this rule found a problem" are different
+ * facts and a reader must be able to tell them apart, but both are reasons
+ * not to trust a green.
+ */
+export declare function runChecks(type: string, instance: unknown, contextDirectory: string | undefined): ChecksRun;