@bendyline/gezel 0.1.0

package/dist/checks/index.d.ts

@@ -0,0 +1,693 @@
+/**
+ * ─ Shared deliverable checks ─────────────────────────────────────────
+ *
+ * Pure, dependency-free predicates over file content and file listings.
+ * The ONE source of truth consumed by three surfaces that must agree:
+ *
+ *   1. the gate engine's declarative checks (service/tasks/gate-eval.ts)
+ *   2. the standard gate-script library (packages/script-stdlib, via the
+ *      bundled `@bendyline/gezel-sdk/checks` re-export)
+ *   3. the eval harness's success sniffs (evals/src)
+ *
+ * Keep this directory zod-free and Node-API-free: it is bundled into the
+ * sandbox SDK (`noExternal`), and its failure prose is shown verbatim to
+ * users and models.
+ */
+/** Read-only view of a workspace the file checks evaluate against. */
+interface WorkspaceLike {
+    /** File content (relative path), or null if absent. */
+    read(file: string): Promise<string | null>;
+    /** Relative paths of all files (for count/scan checks). */
+    list(): Promise<string[]>;
+    /**
+     * Raw bytes (relative path), or null if absent. OPTIONAL: only the
+     * surfaces that can serve bytes implement it, and only the checks that
+     * genuinely need bytes (image-signature validation) call it. Text
+     * checks must keep using `read` — decoding binary through `read`
+     * is lossy, which is precisely why an extension-only image count was
+     * gameable with text stubs. A check that requires bytes must degrade
+     * explicitly when this is absent rather than silently passing.
+     */
+    readBytes?(file: string): Promise<Uint8Array | null>;
+}
+interface CheckResult {
+    ok: boolean;
+    /**
+     * One human-readable line. On failure: the concrete gap to fix (this
+     * exact prose lands in gate-rejection messages). On success: a brief
+     * diagnostic ("index.html is 4312 bytes").
+     */
+    detail: string;
+}
+
+/**
+ * HTML deliverable checks: truncation detection, inline-script
+ * extraction, V8 syntax validation, and the two content sniffs the
+ * craftbook runtime uses (`html-complete`, `html-game`).
+ *
+ * Ported from evals/src/html-validation.ts and the service's
+ * chat/step-sniff.ts so all three consumers share one implementation —
+ * including the wild-caught failure modes documented inline.
+ */
+/**
+ * Minimum inline JS bytes for an "interactive game" page to count as
+ * non-skeleton. matrix calibration: a tight tic-tac-toe game
+ * (state, win-detect, click handler, reset) fits cleanly in ~2.5 KB; 4 KB
+ * rejected real working games; 2 KB rejects skeletons while letting
+ * tight implementations through.
+ */
+declare const MIN_INLINE_JS_BYTES = 2048;
+/**
+ * Count `<script>` openers vs `</script>` closers. When closers <
+ * openers the document was truncated mid-script and inline-JS
+ * extraction silently dropped a real body.
+ */
+declare function detectUnclosedScript(html: string): {
+    opens: number;
+    closes: number;
+    unclosed: boolean;
+};
+interface InlineScript {
+    /** The raw inline JS body (between `<script>` open and close). */
+    body: string;
+    /** Attribute string after the `<script` tag name (e.g. `type="module"`). */
+    attrs: string;
+}
+/**
+ * Every inline `<script>` body in document order. External scripts
+ * (`src=`) and non-JS types (JSON-LD etc.) are skipped.
+ */
+declare function extractInlineScripts(html: string): InlineScript[];
+interface ScriptValidation {
+    /** Sum of `body.length` across all inline non-empty scripts. */
+    totalBytes: number;
+    /** True iff every script body parses without SyntaxError. */
+    allParse: boolean;
+    /** Per-script parse status. */
+    perScript: Array<{
+        bytes: number;
+        parses: boolean;
+        error?: string;
+    }>;
+    /** First parse error encountered, for the failure line. */
+    firstError?: string;
+}
+/**
+ * Try-parse each script body via `new Function(body)` — V8's parser.
+ * `type="module"` scripts skip the parse (top-level `import` fails under
+ * the function-body parser) but still count toward size; a genuinely
+ * broken module fails at the runtime-render layer instead.
+ */
+declare function validateScriptSyntax(scripts: ReadonlyArray<InlineScript>): ScriptValidation;
+/**
+ * Conservative sniff for TypeScript-only constructs inside a script that
+ * already FAILED to parse as JavaScript. Only patterns that are never
+ * valid JS: postfix non-null assertions, `as` casts before a delimiter,
+ * parameter/property type annotations with a following identifier-ish
+ * type, and `interface`/`enum` declarations. Returns a short description
+ * of the first construct found (with an excerpt), or null.
+ */
+declare function detectTypeScriptOnlySyntax(body: string): string | null;
+/** Total trimmed bytes of inline `<script>` bodies. */
+declare function inlineJsBytes(html: string): number;
+/**
+ * Generic "this HTML file isn't truncated": balanced `<script>` tags
+ * (the truncation failure mode is an open `<script>` with no closer)
+ * AND a closing `</body>` or `</html>`.
+ */
+declare function htmlCompleteSniff(html: string): boolean;
+/**
+ * "Plausibly a real browser game": a game *surface*, at least one CLOSED
+ * script, and non-trivial inline JS (default floor 400 bytes —
+ * `advanceWhen.minBytes` guards total size separately).
+ *
+ * A "surface" is a canvas/SVG render target OR a real animation/tick loop
+ * (`requestAnimationFrame`, `setInterval`/`setTimeout`, or a conventional
+ * frame function). The loop branch matters: plenty of legitimate games —
+ * board games, multi-screen arcade games, anything that animates by
+ * mutating the DOM each frame — never touch `<canvas>`. Requiring a
+ * canvas held 2 of 3 genuinely-passing DOM arcade games at the build gate
+ * gate-liveness run, while the eval grader (which
+ * treats render-surface as one optional signal of six) passed all three.
+ * The gate must agree with the grader on what "is a game" means — canvas
+ * is one way to be a game, not the definition. The closed-script +
+ * substantial-JS floors still exclude static pages and truncated stubs.
+ */
+declare function htmlGameSniff(html: string, minJsBytes?: number): boolean;
+
+/**
+ * File-fact checks: sizes, counts, CSS volume, content patterns. Ported
+ * verbatim from service/src/tasks/gate-eval.ts so the failure prose
+ * users see is byte-identical wherever a check runs.
+ */
+declare function fileMinBytes(ws: WorkspaceLike, file: string, bytes: number, trim?: boolean): Promise<CheckResult>;
+declare function fileMinLines(ws: WorkspaceLike, file: string, minLines: number): Promise<CheckResult>;
+declare function totalMinBytes(ws: WorkspaceLike, files: string[], bytes: number): Promise<CheckResult>;
+declare function fileCountByExt(ws: WorkspaceLike, ext: string[], min: number, dir?: string, opts?: {
+    verifyImageBytes?: boolean;
+}): Promise<CheckResult & {
+    matched: string[];
+}>;
+/**
+ * `<style>` blocks + inline `style=""` attributes + linked local
+ * stylesheets in `file` total ≥ `bytes`. Style attributes count because a
+ * fully-inline-styled page is real CSS work — ignoring them false-failed
+ * valid pages that never opened a `<style>` block.
+ */
+declare function cssMinBytes(ws: WorkspaceLike, bytes: number, file?: string): Promise<CheckResult>;
+declare function containsPattern(ws: WorkspaceLike, file: string, pattern: string, flags?: string, label?: string): Promise<CheckResult>;
+declare function notContainsPattern(ws: WorkspaceLike, file: string, pattern: string, flags?: string, label?: string): Promise<CheckResult>;
+/**
+ * Grep-returns-results across the workspace: at least `minMatches` files
+ * (optionally under `dir`, optionally filtered to `ext`) whose content
+ * matches `pattern`.
+ */
+declare function grepMatches(ws: WorkspaceLike, pattern: string, opts?: {
+    dir?: string;
+    ext?: string[];
+    flags?: string;
+    minMatches?: number;
+}): Promise<CheckResult & {
+    matched: string[];
+}>;
+
+/**
+ * Reference-resolution checks: do the things a document points at
+ * actually exist? Ported from the petShop eval sniff
+ * (evals/src/success-check.ts) — its "working image link" rule caught
+ * the most common broken-deliverable mode: assets generated but linked
+ * from the wrong path.
+ */
+declare const IMG_EXT: RegExp;
+/**
+ * Resolve a relative path against a base file's directory using POSIX
+ * semantics (`..` walks up, `.` is no-op, leading `/` is project root).
+ * Returns null for external/anchor/data refs or paths escaping the root.
+ */
+declare function resolveRelative(basePath: string, srcRaw: string): string | null;
+/** Every `<img src="…">` value in document order. */
+declare function findImageRefs(html: string): string[];
+interface ImageRefsReport {
+    ok: boolean;
+    detail: string;
+    /** Refs that point at image files which do NOT exist in the project. */
+    broken: string[];
+    /** Count of refs that resolve to real files. */
+    working: number;
+    /** Total image-shaped refs found. */
+    total: number;
+}
+/**
+ * Check that `<img>` refs in `html` resolve to real files.
+ * `requireAll: false` (default) = at least one working image ref;
+ * `true` = every image-shaped ref must resolve.
+ */
+declare function imageRefsResolve(html: string, htmlPath: string, projectFiles: readonly string[], requireAll?: boolean): ImageRefsReport;
+
+/**
+ * Static-scan an ESM/JS/TS file for two high-confidence import errors that
+ * break the module at LOAD time (so nothing runs) yet slip past the
+ * inline-`<script>` JS-parse gate — which skips `type="module"` and never
+ * sees a standalone `.mjs`/`.ts`:
+ *
+ *  1. A named import pulled from the WRONG `node:` builtin (the canonical
+ *     case: `import { dirname } from 'node:url'` — `dirname` is `node:path`).
+ *     Throws `SyntaxError: … does not provide an export named …`.
+ *  2. `require(...)` inside a `.mjs` file — `require` is not defined in ESM
+ *     and throws at runtime. (Restricted to `.mjs`, where ESM is
+ *     unambiguous; a bare `.js`/`.ts` may legitimately be CommonJS.)
+ *
+ * Returns the FIRST issue with a prescriptive fix (the "name one gap"
+ * discipline). A file with no `node:` named imports — and no require() in a
+ * `.mjs` — passes; there is nothing this check can be confident about.
+ */
+declare function esmImports(content: string, file?: string): CheckResult;
+/**
+ * Standalone-file parse floor for `.js`/`.mjs` sources, without the
+ * TypeScript compiler (usable from the sandboxed stdlib). Import/export
+ * statements are textually stripped (top-level module syntax can't be
+ * function-parsed), then the remainder must parse via `new Function` —
+ * catching the dominant truncation / unbalanced-brace failure class the
+ * way `validateScriptSyntax` does for inline HTML scripts. TypeScript
+ * sources need the service-side `sourceParses` gate check instead.
+ */
+declare function standaloneJsParses(content: string, file?: string): CheckResult;
+
+/**
+ * Text/structure checks: distinct-match counting, ordered Markdown
+ * sections, JSON validity. Ported from evals/src/success-check.ts
+ * (incident-postmortem's citation + section rules).
+ */
+
+type JsonScalar = string | number | boolean | null;
+interface JsonPathEqualsResult extends CheckResult {
+    actual?: unknown;
+}
+/**
+ * Count DISTINCT regex matches in `text` (distinct by capture group 1
+ * when present, else by the whole match, case-insensitive). A file cited
+ * six times counts once.
+ */
+declare function countDistinctMatches(text: string, pattern: RegExp): number;
+/**
+ * Verify `text` contains each header in `headers` IN ORDER (later
+ * headers must appear AFTER earlier ones). Headers match `^#+\s+<h>$`
+ * (case-insensitive, multi-line) — `#`/`##`/`###` all qualify.
+ */
+declare function requireOrderedSections(text: string, headers: readonly string[]): {
+    ok: true;
+} | {
+    ok: false;
+    missing: string;
+    foundIndex: number;
+};
+declare function jsonValid(content: string): {
+    ok: boolean;
+    error?: string;
+};
+declare function jsonPathEquals(ws: WorkspaceLike, file: string, path: string, expected: JsonScalar, label?: string): Promise<JsonPathEqualsResult>;
+
+/**
+ * Grounding + citation checks — the anti-fabrication vocabulary.
+ *
+ * Ported from the eval graders (evals/src/scenarios/decoy-research.ts) so
+ * the gate that fires in production is byte-identical to the one the eval
+ * suite proved out:
+ *
+ *   - `valueGrounding` generalizes decoy-research's `checkBriefing`:
+ *     required facts must be present, forbidden (decoy) values must be
+ *     absent anywhere — even to contrast them.
+ *   - `citationsResolve` is the squisq lesson as a mechanical gate: every
+ *     source a deliverable cites must resolve to a real file (no
+ *     fabricated paths). URLs can't be fetched offline, so they fail
+ *     open unless an explicit corpus allowlist is supplied.
+ */
+/**
+ * Collapse digit-grouping separators so "$4,217,300", "4 217 300", and
+ * "4217300" all compare equal. Only separators between a digit and a
+ * 3-digit group are touched, so list punctuation ("1, 2, 3") and prose
+ * spacing survive. (Ported verbatim from decoy-research.)
+ */
+declare function normalizeDigitGroups(text: string): string;
+/** A single grounded fact: at least one `required` form must appear and no
+ *  `forbidden` (decoy) form may. Values are regex sources, matched
+ *  case-insensitively against the (optionally digit-normalized) text. */
+interface GroundingFact {
+    /** Stable id, surfaced in the failure message. */
+    id: string;
+    /** Short human label ("Q3 revenue"); falls back to `id`. */
+    label?: string;
+    /** Value(s) that MUST appear — the fact passes when ANY one matches. */
+    required: string[];
+    /** Value(s) that must NOT appear anywhere (the decoy twins). */
+    forbidden?: string[];
+}
+interface GroundingResult extends CheckResult {
+    /** Ids of facts that passed. */
+    signals: string[];
+    /** Forbidden (decoy) values that were detected, for logs/facts.json. */
+    decoysDetected: string[];
+}
+/**
+ * Behavioral fact-check over a deliverable's text: for each fact an
+ * authorized value must be present and every forbidden twin absent.
+ * Pure (string in, verdict out) so it drives gate scripts and the eval
+ * grader from one codebase. Reports the FIRST failing fact concretely
+ * (Law 3: name the gap, not the rule).
+ */
+declare function valueGrounding(text: string, facts: readonly GroundingFact[], opts?: {
+    normalizeDigits?: boolean;
+}): GroundingResult;
+interface CitationsResult extends CheckResult {
+    /** Cited paths that resolved to a real workspace file. */
+    resolved: string[];
+    /** Cited paths/URLs that did NOT resolve. */
+    unresolved: string[];
+    /** Cited URLs (not checked offline unless a corpus allowlist is given). */
+    urls: string[];
+}
+/**
+ * Every source `file` cites must exist. File-path citations are resolved
+ * against the workspace listing (tolerant of leading `./`, `/`, and
+ * `workspace/`, case-insensitive). URLs cannot be fetched offline, so
+ * they pass unless `corpus` is supplied, in which case every cited path
+ * AND URL must be a member of the allowlist. The anti-fabrication gate.
+ */
+declare function citationsResolve(ws: WorkspaceLike, file: string, opts?: {
+    pattern?: string;
+    flags?: string;
+    minCitations?: number;
+    corpus?: string[];
+}): Promise<CitationsResult>;
+/** Spec for {@link valuesSubsetOf}. */
+interface ValuesSubsetSpec {
+    /**
+     * Regex source with ONE capture group; every match's group 1 in the
+     * output and in each source is a "value". Matched with `g` plus any
+     * extra `flags`.
+     */
+    pattern: string;
+    flags?: string;
+    /**
+     * Presence floor: the output must contain at least this many values
+     * (default 0 — a subset check alone passes an output with no values;
+     * pair with a shape check, or set a floor here, when values are
+     * mandatory).
+     */
+    minMatches?: number;
+}
+interface ValuesSubsetResult extends CheckResult {
+    /** Distinct values found in the output. */
+    checked: number;
+    /** Output values that appear in NO source (dedup, output order). */
+    invented: string[];
+}
+/**
+ * Value-conservation check for transform/ETL deliverables: every value the
+ * output carries (per `pattern`) must appear verbatim in at least one
+ * source text. Catches the classic integrity failure where a model
+ * regenerates identifiers instead of preserving them — renumbered record
+ * ids, invented ticket refs, made-up SKUs — which survives every
+ * shape/schema check because the output LOOKS right. Wild-caught
+ * core sweep: 7 of 8 local models failed precision ETL solely
+ * by renumbering source ids. Pure (strings in, verdict out) so it drives
+ * gate checks, gate scripts, and eval graders from one codebase.
+ */
+declare function valuesSubsetOf(outputText: string, sourceTexts: readonly string[], spec: ValuesSubsetSpec): ValuesSubsetResult;
+
+interface SecurityReportOptions {
+    /** Path to the machine-readable findings JSON. */
+    findings?: string;
+    /** Section headings the report must contain. */
+    requiredSections?: string[];
+    /** Minimum systemic themes required once findings ≥ themeThreshold. */
+    minThemes?: number;
+    /** Findings count at/above which systemic-theme synthesis is required. */
+    themeThreshold?: number;
+}
+interface SecurityReportResult extends CheckResult {
+    findingCount: number;
+    /** Cited files that don't exist in the workspace, for logs/facts. */
+    fabricated: string[];
+}
+declare function securityReport(ws: WorkspaceLike, reportFile: string, opts?: SecurityReportOptions): Promise<SecurityReportResult>;
+
+/** ISO yyyy-mm-dd AND a real calendar date (ported from data-wrangle). */
+declare function isRealIsoDate(value: string): boolean;
+/**
+ * Built-in cell/field types, or any other string is treated as a regex
+ * source the value must match. Returns `detail` describing the mismatch.
+ */
+type CellType = 'string' | 'nonempty' | 'number' | 'integer' | 'boolean' | 'date' | 'iso-date' | 'email' | (string & {});
+interface ParsedTable {
+    headers: string[];
+    rows: string[][];
+}
+/** Parse the first GitHub-flavored Markdown table (header row, a `|---|`
+ *  delimiter row, then contiguous body rows). Returns null if none. */
+declare function parseMarkdownTable(text: string): ParsedTable | null;
+interface TableShapeSpec {
+    /** Header names that must be present (case-insensitive). */
+    requiredColumns?: string[];
+    /** Minimum body-row count. */
+    minRows?: number;
+    /** Per-column value type (built-in CellType or a regex source). */
+    columnTypes?: Record<string, CellType>;
+}
+interface TableShapeResult extends CheckResult {
+    headers: string[];
+    rowCount: number;
+}
+/** Validate the first Markdown table in `text`: required header set, row
+ *  floor, and per-column value types. */
+declare function tableShape(text: string, spec: TableShapeSpec): TableShapeResult;
+/**
+ * Minimal RFC-4180-ish CSV parser: quoted fields, embedded commas,
+ * escaped double-quotes (""), CRLF, and a leading UTF-8 BOM. Returns a
+ * grid of trimmed-on-cell cells (callers trim further as needed).
+ */
+declare function parseCsv(text: string): string[][];
+/**
+ * Cheap, dependency-free sniff: does `text` look like a produced DATA
+ * deliverable — a non-empty JSON array of records, a comma-delimited
+ * table with a header + at least one data row, or a Markdown table —
+ * rather than an empty file or the transform *script* that would
+ * produce it? This is the data-class analogue of `htmlCompleteSniff`:
+ * it answers "is this plausibly the real output", not "is every value
+ * correct" (that's {@link recordSchema}'s job, used when a field schema
+ * is known). The shared-column-shape requirement on the delimited path
+ * keeps a source file accidentally read as CSV (ragged, mostly
+ * single-column lines) from passing as data.
+ */
+declare function dataTableSniff(text: string): boolean;
+interface CsvShapeSpec {
+    /** Header names that must be present exactly. */
+    requiredColumns?: string[];
+    /** Complete header row, in order. When set, no extra/missing columns are allowed. */
+    exactColumns?: string[];
+    /** Minimum data-row count, excluding the header row. */
+    minRows?: number;
+    /** Reject rows whose cell count differs from the header. Defaults to true. */
+    consistentColumns?: boolean;
+    /** Per-column allowed values. Empty cells are ignored here; use exactColumns/requiredColumns for shape. */
+    allowedValues?: Record<string, string[]>;
+}
+interface CsvShapeResult extends CheckResult {
+    headers: string[];
+    rowCount: number;
+}
+/** Validate CSV file shape: header, row count, ragged rows, and optional picklist values. */
+declare function csvShape(text: string | null, spec: CsvShapeSpec): CsvShapeResult;
+interface RecordFieldSpec {
+    name: string;
+    /** Value type; omit (or 'string') for any non-empty string. */
+    type?: CellType;
+    /** Defaults to true. */
+    required?: boolean;
+}
+interface RecordSchemaSpec {
+    fields: RecordFieldSpec[];
+    /** Reject rows carrying fields not in `fields`. Defaults to false. */
+    allowExtraFields?: boolean;
+    minRows?: number;
+    /** Field whose values must be unique across all rows. */
+    uniqueBy?: string;
+    /** 'json' | 'csv' | 'auto' (default 'auto' — sniff by first char). */
+    format?: 'json' | 'csv' | 'auto';
+}
+interface RecordSchemaResult extends CheckResult {
+    rowCount: number;
+}
+/**
+ * Validate a JSON array (or CSV) of records against a declared schema.
+ * Checks run in a fixed order and STOP at the first failure, naming
+ * exactly one gap with the offending value (the data-wrangle discipline).
+ * `null` text means the deliverable doesn't exist yet.
+ */
+declare function recordSchema(text: string | null, spec: RecordSchemaSpec): RecordSchemaResult;
+
+interface WordBandResult extends CheckResult {
+    words: number;
+}
+/** Word count within `[min, max]` (either bound optional). */
+declare function wordBand(text: string, opts?: {
+    min?: number;
+    max?: number;
+    stripMarkdown?: boolean;
+}): WordBandResult;
+interface ReadingLevelResult extends CheckResult {
+    /** Flesch-Kincaid grade level. */
+    grade: number;
+    /** Flesch reading-ease (higher = easier). */
+    ease: number;
+    words: number;
+    sentences: number;
+}
+/**
+ * Flesch-Kincaid grade level and Flesch reading-ease, banded by any of
+ * `minGrade`/`maxGrade`/`minEase`/`maxEase`. Reports the first band the
+ * text falls outside of.
+ */
+declare function readingLevel(text: string, opts?: {
+    minGrade?: number;
+    maxGrade?: number;
+    minEase?: number;
+    maxEase?: number;
+    stripMarkdown?: boolean;
+}): ReadingLevelResult;
+/** A canonical term plus the spellings/numberings that should NOT appear. */
+interface EntitySpec {
+    canonical: string;
+    /** Forbidden variants (drifted spellings, wrong numbers). */
+    variants: string[];
+}
+interface EntitiesResult extends CheckResult {
+    violations: Array<{
+        canonical: string;
+        variant: string;
+    }>;
+}
+interface UnsupportedClaimPattern {
+    /** Regex for a high-risk claim phrase whose wording must be source-grounded. */
+    pattern: string;
+    /** Repair guidance shown when this pattern matches unsupported prose. */
+    label?: string;
+}
+interface UnsupportedClaimViolation {
+    pattern: string;
+    label?: string;
+    match: string;
+}
+interface UnsupportedClaimsResult extends CheckResult {
+    violations: UnsupportedClaimViolation[];
+    missingSources: string[];
+}
+/**
+ * Fail if any declared `variant` of an entity appears in `text` — i.e.
+ * the document drifted from the canonical spelling/number somewhere.
+ * Case-sensitive (so "ACME" vs "Acme" is caught). Reports the first
+ * inconsistency.
+ */
+declare function namedEntitiesConsistent(text: string, entities: readonly EntitySpec[]): EntitiesResult;
+/**
+ * Fail when high-risk claim wording appears in `file` but the exact
+ * matched phrase is absent from the declared source files. This is a
+ * deterministic middle ground for factual comms gates: it catches common
+ * overclaim/tone drift while still allowing loaded phrases that the source
+ * brief explicitly authorized.
+ */
+declare function unsupportedClaims(ws: WorkspaceLike, file: string, sourceFiles: readonly string[], patterns: readonly UnsupportedClaimPattern[], opts?: {
+    flags?: string;
+    maxViolations?: number;
+}): Promise<UnsupportedClaimsResult>;
+
+/**
+ * Plain-language hints derived from runtime/test output. Failure lines
+ * from assertion harnesses name the mismatch but not the mistake; small
+ * models keep patching the wrong thing until a hint names it. Generalized
+ * from the eval harness's perf-budget `wrapperReturnHint` (0/3 → 3/3 once
+ * the wrapper misread was named).
+ */
+/**
+ * Detect the "returned a wrapper object where an array was expected"
+ * shape in assertion output lines (`… expected [...], got {...}`) and
+ * name it. Returns null when no line matches — a bare array with wrong
+ * contents is a genuinely different mistake and gets no hint.
+ */
+declare function wrapperReturnHint(outputLines: readonly string[]): string | null;
+
+interface MarkdownHeadingsMatchResult extends CheckResult {
+    outlineHeadings: string[];
+    documentHeadings: string[];
+    mismatchIndex?: number;
+}
+/**
+ * Compare a Markdown deck's H1 boundaries with a locked outline whose slides
+ * are authored as `## Slide N — Title` (also accepts `## N. Title`).
+ */
+declare function markdownHeadingsMatch(ws: WorkspaceLike, file: string, outlineFile: string): Promise<MarkdownHeadingsMatchResult>;
+
+/**
+ * Human-line explainers for the step sniffs. A gate verdict that says
+ * "index.html failed the html-game check" restates the rule; one that
+ * says "no render surface and no frame loop — add the game loop" names
+ * the model's actual gap (Law 3 of the task-completion strategy: the
+ * verdict must quote the failing observation, not the rule). Composed
+ * from the same primitives the sniffs themselves use, so the diagnosis
+ * can never disagree with the verdict.
+ */
+type ExplainableSniff = 'html-complete' | 'html-game' | 'nonempty' | 'json-valid' | 'data-table';
+/**
+ * One imperative line explaining why `content` fails the named sniff.
+ * Callers only invoke this AFTER the sniff returned false; for content
+ * that actually passes, a generic line is returned rather than lying
+ * about a defect.
+ */
+declare function explainSniff(name: ExplainableSniff, content: string): string;
+
+/**
+ * Pure helpers for the LLM-judge gate check (`kind: 'judge'`) —
+ * prompt building, verdict parsing, and the verbatim-evidence wall.
+ * No LLM calls, no filesystem: the service's gate evaluator supplies
+ * the artifact text and the one-shot executor.
+ *
+ * The evidence wall is the growth-proposals pattern (packages/service/
+ * src/growth/proposals.ts): a quote survives only when it matches the
+ * artifact exactly or as a ≥24-char normalized substring — a judge
+ * that fabricates its evidence loses the verdict.
+ */
+declare const MIN_JUDGE_EVIDENCE_SUBSTRING = 24;
+interface JudgeVerdict {
+    verdict: 'pass' | 'fail';
+    reasons: string[];
+    evidence: string[];
+    confidence?: 'low' | 'medium' | 'high';
+}
+declare function buildJudgePrompt(opts: {
+    rubric: string;
+    file: string;
+    artifactText: string;
+    sources?: Array<{
+        path: string;
+        text: string;
+    }>;
+    requireEvidence?: boolean;
+}): string;
+/**
+ * Extract and validate a JudgeVerdict from a raw model reply. Accepts
+ * a ```json fenced block, a bare JSON object, or JSON embedded in
+ * surrounding prose (first `{` to last `}`) — the keurmeester parse
+ * ladder. Throws when nothing validates.
+ */
+declare function parseJudgeVerdict(raw: string): JudgeVerdict;
+/**
+ * The verbatim wall: keep only the quotes that actually appear in the
+ * artifact (whitespace-normalized exact match, or a substring of the
+ * artifact at ≥ MIN_JUDGE_EVIDENCE_SUBSTRING chars).
+ */
+declare function validateJudgeEvidence(verdict: JudgeVerdict, artifactText: string): {
+    kept: string[];
+    dropped: number;
+};
+
+/**
+ * Structural plan validation (`kind: 'planStructure'`) — the Planner
+ * role's mechanical floor. Validates the FIRST Markdown table in the
+ * text against the plan contract: `ID | Task | Owner | Depends on |
+ * Done when` (+ optional `Estimate`), owners on-roster, dependencies
+ * that resolve, contain no cycles, and (by default) point only at
+ * EARLIER rows, and done-states long enough to be checkable.
+ *
+ * Law-3 details: every failure names the offending row and cell
+ * verbatim so the rejection is the fix instruction.
+ */
+interface PlanStructureSpec {
+    minRows?: number;
+    /** When given, every Owner must be one of these names (case-insensitive). */
+    ownerRoster?: readonly string[];
+    /** Rows may only depend on earlier rows (default true). */
+    requireEarlierOnly?: boolean;
+    /** Minimum Done-when cell length (default 12 chars). */
+    doneWhenMinChars?: number;
+}
+interface PlanRow {
+    id: string;
+    task: string;
+    owner: string;
+    dependsOn: string[];
+    doneWhen: string;
+    estimate?: string;
+}
+interface PlanStructureResult {
+    ok: boolean;
+    /** First failure, row+cell named (empty when ok). */
+    detail: string;
+    rows: PlanRow[];
+    unknownDeps: string[];
+    cycleIds: string[];
+    missingOwners: string[];
+    weakDoneStates: string[];
+}
+declare function planStructure(text: string, spec?: PlanStructureSpec): PlanStructureResult;
+
+export { type CellType, type CheckResult, type CitationsResult, type CsvShapeResult, type CsvShapeSpec, type EntitiesResult, type EntitySpec, type ExplainableSniff, type GroundingFact, type GroundingResult, IMG_EXT, type ImageRefsReport, type InlineScript, type JsonPathEqualsResult, type JsonScalar, type JudgeVerdict, MIN_INLINE_JS_BYTES, MIN_JUDGE_EVIDENCE_SUBSTRING, type MarkdownHeadingsMatchResult, type ParsedTable, type PlanRow, type PlanStructureResult, type PlanStructureSpec, type ReadingLevelResult, type RecordFieldSpec, type RecordSchemaResult, type RecordSchemaSpec, type ScriptValidation, type SecurityReportOptions, type SecurityReportResult, type TableShapeResult, type TableShapeSpec, type UnsupportedClaimPattern, type UnsupportedClaimViolation, type UnsupportedClaimsResult, type ValuesSubsetResult, type ValuesSubsetSpec, type WordBandResult, type WorkspaceLike, buildJudgePrompt, citationsResolve, containsPattern, countDistinctMatches, cssMinBytes, csvShape, dataTableSniff, detectTypeScriptOnlySyntax, detectUnclosedScript, esmImports, explainSniff, extractInlineScripts, fileCountByExt, fileMinBytes, fileMinLines, findImageRefs, grepMatches, htmlCompleteSniff, htmlGameSniff, imageRefsResolve, inlineJsBytes, isRealIsoDate, jsonPathEquals, jsonValid, markdownHeadingsMatch, namedEntitiesConsistent, normalizeDigitGroups, notContainsPattern, parseCsv, parseJudgeVerdict, parseMarkdownTable, planStructure, readingLevel, recordSchema, requireOrderedSections, resolveRelative, securityReport, standaloneJsParses, tableShape, totalMinBytes, unsupportedClaims, validateJudgeEvidence, validateScriptSyntax, valueGrounding, valuesSubsetOf, wordBand, wrapperReturnHint };