@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/coverage.d.ts

@@ -0,0 +1,375 @@
+/**
+ * THE COVERAGE CHECKER (kernel plan M2, M2-P6).
+ *
+ * "No orphans" as a check with an exit code: every id in an INVENTORY
+ * document lands in exactly one row of a COVERAGE-TABLE document, a bucket
+ * value that does not match a declared kind is named rather than silently
+ * uncounted, a bucket kind that requires a note (`parked`) is red when the
+ * note is empty, and a coverage-table row whose id is absent from the
+ * inventory (a renumbering) is named as phantom coverage.
+ *
+ * HAZARD CLASS (T-007, M2-D-18): arithmetic over two documents that can
+ * drift, where a total can add up while a row is lost. Named defenses,
+ * each tied to a criterion:
+ *
+ *   - a renumbering that leaves a bucket row pointing at a dead id: the
+ *     PHANTOM check (every coverage-table row's id is required to be in
+ *     the inventory), independent of the orphan check (every inventory id
+ *     is required to have a coverage-table row).
+ *   - a duplicated id INSIDE the inventory document itself (fix round 1,
+ *     CR-985): counted once as a unit is not the same claim as "appears
+ *     once in the text", so `units` is the count of DISTINCT ids and a
+ *     repeated id is its own named finding (`duplicate-inventory-id`),
+ *     symmetric with the coverage side's `double-bucketed` check.
+ *     **CORRECTED CLAIM (fix round 1): an earlier revision of this comment
+ *     said the orphan and phantom checks "scan in opposite directions on
+ *     purpose, so neither can compensate for the other's blind spot." That
+ *     was false for cardinality: a duplicated inventory id defeated BOTH
+ *     of them (it is not an orphan, because a coverage row exists; it is
+ *     not phantom, because the id is genuinely in the inventory), and
+ *     inflated every count while staying green. The true property is
+ *     narrower: orphan and phantom together catch every EXISTENCE
+ *     mismatch (an id present on one side and not the other); cardinality
+ *     mismatches (an id present more than once on one side) need the
+ *     separate check named above, and a row lost from BOTH documents
+ *     needs the `expectedUnits` check below, because the two documents
+ *     still agree with each other in that case and existence/cardinality
+ *     checks over agreeing documents find nothing.
+ *   - a row lost from BOTH documents (fix round 1, CR-986): the previous
+ *     bullet's residue. An optional `expectedUnits` config field states
+ *     the anchor no arithmetic over the two documents alone can produce;
+ *     a computed unit count that does not equal it is the
+ *     `expected-units-mismatch` finding. This repository's real config
+ *     sets it to 115 (kernel plan v1 Appendix A's stated total).
+ *   - a bucket value matching no declared kind, silently uncounted: every
+ *     bucket-kind pattern is compiled ANCHORED (`^(?:pattern)$`) and tested
+ *     against the whole cell; a value none of them match is the
+ *     `unknown-kind` finding, named by id and value, never absorbed into a
+ *     nearby kind by a partial match.
+ *   - a bucket value matching MORE than one declared kind (fix round 1,
+ *     CR-992): resolved by silent first-match-wins until this round; now
+ *     the `ambiguous-kind` finding, naming every kind that matched, rather
+ *     than one kind's `requiresNote` silently never being consulted.
+ *   - an empty inventory producing a green with nothing examined: `units`
+ *     is always the number of DISTINCT ids the inventory actually
+ *     produced, and this module never constructs a `GateResult` except
+ *     through `makeGateResult`, whose M2-C-2 rewrite turns a
+ *     green-with-zero-units record into `error` with `vacuous: true`.
+ *     This gate does not duplicate that rule; it relies on the shared
+ *     constructor the way M2-C-6 requires reuse of `classifyEntry` rather
+ *     than a second implementation of "may this path be read".
+ *   - a milestone extraction that cannot produce the totals the plan
+ *     states: the milestone view and the kind view are two INDEPENDENT
+ *     tallies computed from the same classification pass (`perKind` keyed
+ *     by the bucket kind's name, `perMilestone` keyed by the pattern's
+ *     first capture group when present, else by the kind's own name), so
+ *     the two views can be compared against each other and against the
+ *     plan's stated totals rather than one being asserted to imply the
+ *     other.
+ *   - a finding whose outcome cell is present but empty:
+ *     `checkFindingOutcomeParity` treats an empty outcome as a named
+ *     failure distinct from a missing row, so "the row exists" and "the
+ *     row says something" are not conflated. Fix round 1, CR-987: "empty"
+ *     is ONE shared predicate (`isEmptyCell`, below), applied wherever a
+ *     note or an outcome is tested, so whitespace-only and zero-width-only
+ *     content (U+200B, which `String.prototype.trim` does not strip) is
+ *     empty on both sides rather than only where a trim happened to run.
+ *   - a finding-to-outcome report carrying a PHANTOM outcome (fix round 1,
+ *     CR-988): `checkFindingOutcomeParity` used to scan inventory ids
+ *     only, so a report row for an id absent from the inventory (the
+ *     renumbering shape the coverage side's phantom check exists for) was
+ *     silently accepted. Now symmetric: a phantom outcome row is named.
+ *
+ * M2-C-6: the inventory path, the coverage-table path and an optional
+ * `--config` document are all supplied by configuration and none of them
+ * is a path this module created, so every read goes through
+ * `readRegularFileIfPresent` (which itself routes through `classifyEntry`),
+ * never a bare `readFileSync`. A named pipe at any of the three paths is
+ * `error` naming the path and the observed type, and this module never
+ * blocks on one. Fix round 1, CR-989: the same discipline now applies to
+ * the WRITE side inside the evidence directory (`counts.json`): a refused
+ * or failed write there used to be computed and discarded, leaving a
+ * silent green with empty evidence; it is now loud and makes the gate
+ * `error`, the same way a refused result-path write already did.
+ *
+ * Fix round 1 also closes the REGEX MECHANISM (CR-990/991/992): every
+ * config-supplied pattern (both `idPattern`s and every `bucketKinds[].pattern`)
+ * is VALIDATED (compiles, and is rejected if it matches a known
+ * catastrophic-backtracking shape) before it is ever executed, and every
+ * EXECUTION of a config-supplied pattern is BOUNDED (`boundedExec`, below),
+ * so neither a malformed pattern (CR-990, used to
+ * throw with no result record written) nor a ReDoS pattern (CR-991, used
+ * to hang indefinitely) can defeat this gate. M4-P28 changed WHAT that
+ * bound measures, from elapsed wall clock to CPU work, because the first
+ * one reddened for well-behaved patterns whenever the machine was busy.
+ * CR-992 (overlapping kinds)
+ * is folded into the same fix because it is the same "a config string is
+ * trusted further than its syntax justifies" mechanism one property over.
+ */
+/** One row of the `bucketKinds` config. */
+export interface BucketKindConfig {
+    kind: string;
+    /** Regex source, compiled anchored `^(?:pattern)$` against a bucket value. */
+    pattern: string;
+    requiresNote: boolean;
+}
+export interface DocumentConfig {
+    path: string;
+    /** Regex source, compiled anchored, tested against a row's first cell. */
+    idPattern: string;
+}
+export interface CoverageTableConfig extends DocumentConfig {
+    /** 0-based cell index (cell 0 is the id) holding the bucket value. */
+    bucketColumn: number;
+    /** 0-based cell index holding the note. */
+    noteColumn: number;
+}
+export interface CoverageConfig {
+    inventory: DocumentConfig;
+    coverageTable: CoverageTableConfig;
+    bucketKinds: BucketKindConfig[];
+    /**
+     * CR-986: the exact expected count of DISTINCT inventory ids. Optional;
+     * when absent, no floor is enforced. A row deleted from BOTH documents
+     * leaves the two documents agreeing with each other, which every other
+     * check in this module is powerless against, so this is a config-stated
+     * anchor rather than a derived one.
+     */
+    expectedUnits?: number;
+}
+/**
+ * THE KERNEL CONFIG (kernel plan M2-P6 step 2): this repository's real
+ * pair and the four bucket kinds the plan states verbatim. It is a plain
+ * exported constant, not a checked-in data file, because M2-C-1's
+ * verification-first reading of the plan's files-to-touch list for this
+ * phase names the module, its schema and its test, and no committed
+ * configuration document alongside them; a `--config` flag (validated
+ * against `coverage-config.schema.json`) exists for a caller that wants a
+ * different pair, and every fixture test in `test/coverage-gate.test.ts`
+ * uses it rather than editing this constant.
+ */
+export declare const KERNEL_COVERAGE_CONFIG: CoverageConfig;
+/**
+ * THE SHARED EMPTINESS PREDICATE (fix round 1, CR-987).
+ *
+ * Before this round, `checkCoverage`'s note check compared a value already
+ * passed through `String.prototype.trim` (applied once, at extraction) to
+ * `""`, and `checkFindingOutcomeParity`'s outcome check compared a value
+ * that was never trimmed at all to `""`. Two definitions, only one of
+ * which trimmed, and NEITHER strips a zero-width character: `trim()`
+ * removes Unicode whitespace (which includes U+00A0 and U+FEFF) but not
+ * U+200B ZERO WIDTH SPACE, U+200C ZERO WIDTH NON-JOINER or U+200D ZERO
+ * WIDTH JOINER, so a cell or an outcome containing only one of those reads
+ * as non-empty to a bare `=== ""` comparison, trimmed or not. One
+ * predicate, called at every point this module asks "is this empty",
+ * closes both instances at once.
+ */
+export declare function isEmptyCell(value: string): boolean;
+/**
+ * THE VERDICT-PRODUCING BOUND IS CPU WORK, NOT ELAPSED TIME (M4-P28).
+ *
+ * What this constant replaces, and why the replacement is not a bigger
+ * number. Until this phase the bound was `REGEX_EXEC_TIMEOUT_MS = 250`,
+ * handed to `vm` as a WALL-CLOCK timeout, and exceeding it was reported as
+ * "did not complete within 250ms ... (possible catastrophic
+ * backtracking)". Elapsed wall time is complexity DIVIDED BY available
+ * CPU, so that condition did not test the property it named: it reddened
+ * whenever the machine was busy. Measured and recorded in
+ * delivery/verification/wall-clock-budgets-are-load-dependent.md:1, five
+ * independent witnesses hit it on six structurally different patterns,
+ * including `^(?:parked)$`, a doubly anchored literal with no quantifier,
+ * no character class and no alternation, which has nothing to backtrack
+ * over at any input length. One million executions of
+ * `^(?:R-[0-9]+[a-z]?)$` against `R-094a` take 154.2ms in total, so ONE is
+ * roughly 1.6 million times under the old budget; for one of them to
+ * exceed it the thread must be descheduled for a quarter of a second,
+ * which is a fact about the machine.
+ *
+ * Raising 250 to a larger number was considered and is REJECTED by the
+ * plan (delivery/plan/kernel-plan-m4.md:3784): it keeps the same
+ * instrument and only moves the load at which it lies.
+ *
+ * WHAT IS MEASURED NOW. `process.threadCpuUsage()` reports the CPU time
+ * this thread has consumed, in microseconds. Another process being busy
+ * does not add to it, because a descheduled thread consumes no CPU while
+ * it is not running. The regex runs on THIS thread inside
+ * `runInContext`, so the delta across that call is the work the regex
+ * did, and nothing else. On an interpreter without
+ * `process.threadCpuUsage` (added in Node 22.15; the package floor is 26)
+ * the fallback is `process.cpuUsage()`, which is process-wide and
+ * therefore an over-estimate, never an under-estimate, so the fallback
+ * cannot let a catastrophic pattern through.
+ */
+export declare const REGEX_EXEC_CPU_BUDGET_MS = 250;
+/**
+ * HOW LONG ONE ATTEMPT IS WILLING TO WAIT. This is PATIENCE, not a
+ * verdict: nothing is ever reported about a pattern because this elapsed.
+ * A wall-clock interrupt is still needed, because a catastrophic match
+ * never returns on its own and `vm`'s `timeout` is the only mechanism
+ * here that can stop one (v8 checks for the termination request during a
+ * regex match, not only between statements).
+ *
+ * It is set to TWICE the CPU budget so that a thread receiving at least
+ * half of one CPU reaches the budget inside a single attempt; measured on
+ * an unloaded box, `(a+)+b` against 30 a's consumes 230.6ms of CPU in a
+ * 252ms wall window, so a backstop equal to the budget would have needed
+ * a second attempt to reach a verdict it had nearly earned.
+ */
+export declare const REGEX_EXEC_WALL_BACKSTOP_MS = 500;
+/**
+ * How many interrupted attempts before this module admits it cannot
+ * reach a verdict. Each attempt doubles its own patience, and the CPU
+ * consumed ACCUMULATES across attempts, so a genuinely spinning pattern
+ * is still caught on a loaded machine (it burns CPU whenever it runs)
+ * while a benign one accumulates microseconds however often it is
+ * interrupted.
+ */
+export declare const REGEX_EXEC_MAX_ATTEMPTS = 4;
+/** The pattern did too much WORK. A verdict about the pattern. */
+export declare class RegexBoundExceededError extends Error {
+}
+/**
+ * No verdict was reached: every attempt was interrupted before the
+ * pattern finished, and the CPU it consumed never came near the budget,
+ * which is the signature of a thread that is not being scheduled rather
+ * than one that is spinning. Under M2-C-3 a check that cannot reach a
+ * verdict reports ERROR, never a verdict it did not earn, so this is
+ * deliberately NOT a subclass of `RegexBoundExceededError`: the two must
+ * not be confusable by a `catch` or an `instanceof`.
+ */
+export declare class RegexBudgetUndeterminedError extends Error {
+}
+/** Overrides for one call, used by the witness tests to stand in for a
+ * machine slower or busier than this one. Only the PATIENCE is varied
+ * there; the verdict instrument stays the CPU budget. */
+export interface RegexExecBounds {
+    cpuBudgetMs?: number;
+    wallBackstopMs?: number;
+    maxAttempts?: number;
+}
+/**
+ * Execute `compiled.exec(value)` inside a v8 context, bounded by the CPU
+ * WORK it does rather than by the time it takes.
+ *
+ * One attempt runs the match with a wall-clock interrupt. Whatever
+ * happens, the CPU consumed by this thread during that call is added to a
+ * running total:
+ *
+ *   - total CPU at or above the budget: the thread really did burn that
+ *     much CPU on this one match, which no anchored non-backtracking
+ *     pattern can do, so `RegexBoundExceededError` is thrown. A busy
+ *     machine cannot cause this, because a descheduled thread accumulates
+ *     no CPU.
+ *   - the match finished: return its result, which is the only path that
+ *     produces a match.
+ *   - interrupted with the total still far below the budget: the machine
+ *     was busy, not the pattern. Double the patience and try again.
+ *
+ * After `maxAttempts` interruptions with the CPU total still under
+ * budget, `RegexBudgetUndeterminedError` is thrown, naming the CPU
+ * consumed, the wall clock spent and the load average, so the record says
+ * what it observed instead of asserting something about the pattern.
+ *
+ * An error from `runInContext` that is NOT the timeout is also
+ * undetermined rather than a finding: the old code funnelled every throw
+ * into the catastrophic-backtracking message, which is the same
+ * substitution one cause over.
+ */
+export declare function boundedExec(compiled: RegExp, value: string, bounds?: RegexExecBounds): RegExpExecArray | null;
+/**
+ * A STATIC heuristic for the single most common catastrophic-backtracking
+ * shape (fix round 1, CR-991): a parenthesised group containing an
+ * unbounded quantifier (`+` or `*`), itself immediately followed by
+ * another unbounded quantifier, e.g. `(a+)+`, `(a*)+`, `(a+)*`. This is
+ * exactly the shape the round's own red witness constructs
+ * (`(a+)+b`). It is a heuristic, not a proof: it does not see every
+ * catastrophic shape (a documented residue below), which is why every
+ * EXECUTION is also bounded by `boundedExec` regardless of whether a
+ * pattern passes this check.
+ */
+export declare function catastrophicShapeReason(pattern: string): string | undefined;
+/**
+ * Validate one config-supplied pattern SOURCE before it is ever compiled
+ * into a live regex the gate will execute (fix round 1, CR-990/991):
+ * compiles cleanly, and does not match the static catastrophic-shape
+ * heuristic. `label` identifies which config field failed, so a config
+ * error names the field, not just "a pattern".
+ */
+export declare function validatePatternSource(label: string, pattern: string): string | undefined;
+/**
+ * Validate every config-supplied pattern this module will ever compile
+ * and execute: both `idPattern`s and every `bucketKinds[].pattern`. Run
+ * once per config, before the config is used, so a malformed or dangerous
+ * pattern is a named CONFIG error (a clean result record) rather than an
+ * uncaught exception with no record (CR-990) or an unbounded hang
+ * (CR-991).
+ */
+export declare function validateConfigPatterns(config: CoverageConfig): string | undefined;
+interface TableRow {
+    id: string;
+    cells: string[];
+    line: number;
+}
+/**
+ * Walk a document's lines and return every markdown-table row whose first
+ * cell matches `idPattern` (compiled anchored). Separator rows
+ * (`|---|:--:|---|`) are skipped by construction: every cell in one matches
+ * `/^:?-+:?$/`, which cannot also match a realistic id pattern, but the
+ * separator test is applied explicitly rather than relied on implicitly, so
+ * a future id pattern that could coincide does not silently absorb one.
+ * Every match against a config-supplied pattern is BOUNDED (fix round 1,
+ * `boundedExec`), so a hostile `idPattern` cannot hang this walk.
+ */
+export declare function extractIdRows(text: string, idPattern: string): TableRow[];
+export type CoverageFindingKind = "orphan" | "double-bucketed" | "phantom" | "unknown-kind" | "ambiguous-kind" | "missing-note" | "duplicate-inventory-id" | "expected-units-mismatch";
+export interface CoverageFinding {
+    kind: CoverageFindingKind;
+    id: string;
+    detail: string;
+}
+export interface CoverageReport {
+    totalInventoryIds: number;
+    perKind: Record<string, number>;
+    perMilestone: Record<string, number>;
+    findings: CoverageFinding[];
+}
+/**
+ * The core check. Pure: takes the two documents' TEXT (already read through
+ * M2-C-6's guarded read at the call site) and the config, and returns a
+ * report with nothing hidden inside a status string.
+ */
+export declare function checkCoverage(config: CoverageConfig, inventoryText: string, coverageTableText: string): CoverageReport;
+/**
+ * R-089b, THE FINDING-TO-OUTCOME PARITY CONTRACT (M2-P6 step 4).
+ *
+ * Section 2 item 2 of the M2 plan states that the report contract does not
+ * exist yet, so this module defines its own input shape and M3's report
+ * schema must emit it or supersede it. The shape declared here:
+ *
+ *   inventoryIds: string[]           every id that must be resolved
+ *   findings: { id: string; outcome: string }[]   the report's rows
+ *
+ * A CONFORMING future report is a list of `{id, outcome}` pairs, one row
+ * per id, `outcome` a non-empty string. This function does not care what
+ * the outcome STRING says (that is a judgement M3 owns); it only checks
+ * that every id got exactly one non-empty say. Fix round 1 adds the
+ * direction the original version lacked: a report row whose id is not in
+ * the inventory at all (CR-988, a PHANTOM outcome, symmetric with
+ * `checkCoverage`'s phantom finding) is also named, not silently accepted.
+ */
+export interface FindingOutcomeRow {
+    id: string;
+    outcome: string;
+}
+export interface FindingParityResult {
+    ok: boolean;
+    checked: number;
+    missing: string[];
+    duplicated: string[];
+    empty: string[];
+    /** CR-988: report rows whose id is absent from `inventoryIds`. */
+    phantom: string[];
+}
+export declare function checkFindingOutcomeParity(inventoryIds: string[], findings: FindingOutcomeRow[]): FindingParityResult;
+export declare function main(argv: string[]): number;
+export {};