@crewhaus/provability 0.0.0-stage → 0.8.1

package/dist/vacuous.js

@@ -0,0 +1,423 @@
+/**
+ * The vacuous-pass backstop (design §2, §0 A and B).
+ *
+ * An answer with no claims passes every floor with nothing to prove — the
+ * right verdict for a greeting, a clarifying question or a code block, and
+ * the wrong one for an answer whose claim the extractor failed to see.
+ * Review rounds one and two each found new shapes that merged a claim into
+ * a question or a heading — "30 days [1] — anything else?", "1,284.60; want
+ * the PDF?", a no-break space, a `<br>`, U+2028, a table row, a heading over
+ * a question — and claim-ledger's `extractClaims` saw none of them, so the
+ * gate served scenario A or B with a ✓. Each was fixed shape by shape, and
+ * each fix left the next shape open. So the verdict does not rest on the
+ * extractor alone: an answer may be vacuous only when what a reader sees
+ * of it, code and definition lines aside, carries
+ *
+ * - no citation marker at all, and
+ * - no figure outside a question,
+ *
+ * read by a segmenter far blunter than the extractor, which cuts at every
+ * line break (U+0085, U+2028, U+2029, `\f`, `\v` and `<br>` included),
+ * every sentence terminator whether a space follows it or not, every
+ * semicolon, em or en dash and table pipe — never at a comma. A heading
+ * is a title to the figure rule but for what it states after a label
+ * (claim-ledger's `headingClaim` reads the headings that state one); a
+ * marker in it still counts. Otherwise
+ * each segment that carries a marker, and each that states a figure and is
+ * no question, is a claim, verified like any other: "30 days" cut off a
+ * trailing "anything else?" is checked against the page, and fails where
+ * the page says 14.
+ *
+ * A question stays a question. A piece of text that ends in `?` is a
+ * question from the first segment in it that opens as one ("Which of the 4
+ * plans do you mean — Basic or Pro?", "Should I book 2 rooms\nfor Monday?")
+ * or ends as one; what comes before that segment is said, not asked ("The
+ * refund window is 30 days — anything else?"). A clarifying question with a
+ * figure in it ("Do you want 2 or 3 copies?"), a greeting, and an answer
+ * that is only code stay vacuous.
+ */
+import { citationMarkers, codeSpans, extractNumbers, isAssumptionMarker, lineIndex, plainClaim, } from "@crewhaus/claim-ledger";
+/** A definition line (`[1]: …`, `[^a]: …`), up to three spaces in. */
+const DEFINITION_LINE = /^[ \t]{0,3}\[\^?[^\]\s]+\]:[^\n]*/gm;
+/** A URL: its dots and slashes are not sentence ends. */
+const URL_TEXT = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`]+/gi;
+/** An HTML line break. */
+const BREAK_TAG = /<br\s*\/?>/gi;
+/**
+ * A list item's marker at the start of a line — `1.`, `2)`, `-`, `*`, `+`,
+ * a bold `**1.**` — inside block quotes too: a reader sees an item's number,
+ * not a figure the answer states ("1. Open Settings").
+ */
+const LIST_MARKER = /^([ \t]*(?:>[ \t]?)*[ \t]*)((?:\*\*|__)?(?:\d{1,9}[.)]|[-*+])(?:\*\*|__)?)(?=[ \t])/gm;
+/** Every character that breaks a line. */
+const LINE_BREAK = /[\n\r\v\f\u0085\u2028\u2029]/;
+/** What may close a sentence after its terminator: quotes, brackets, emphasis. */
+const CLOSERS = /["'”’»)\]*_~`]/;
+/**
+ * Words a question opens with — the interrogatives, the auxiliaries an
+ * inverted question starts on, and the openers of an elliptical one ("Want
+ * the PDF?", "Any of these work?"). A conjunction is not one: "And the
+ * window is 30 days; want details?" says something before it asks.
+ */
+const QUESTION_OPENERS = new Set([
+    "what",
+    "which",
+    "who",
+    "whom",
+    "whose",
+    "when",
+    "where",
+    "why",
+    "how",
+    "whether",
+    "do",
+    "does",
+    "did",
+    "don't",
+    "doesn't",
+    "didn't",
+    "is",
+    "isn't",
+    "are",
+    "aren't",
+    "was",
+    "wasn't",
+    "were",
+    "weren't",
+    "am",
+    "can",
+    "can't",
+    "could",
+    "couldn't",
+    "will",
+    "won't",
+    "would",
+    "wouldn't",
+    "shall",
+    "should",
+    "shouldn't",
+    "may",
+    "might",
+    "must",
+    "have",
+    "haven't",
+    "has",
+    "hasn't",
+    "had",
+    "want",
+    "wanna",
+    "need",
+    "any",
+    "anything",
+    "anyone",
+    "anybody",
+    "else",
+    "ok",
+    "okay",
+    "please",
+]);
+/** A sentence terminator. */
+const TERMINATOR = /[.!?…]/;
+/** What may open the segment glued to a terminator: a quote, a bracket, emphasis. */
+const OPENERS = /["'“‘(\[*_]/;
+/**
+ * The answer as the segmenter reads it, offsets kept (one character per
+ * UTF-16 unit): code (fenced and inline), definition lines, URLs and list
+ * item markers blanked, `<br>` turned into a line break.
+ */
+function visibleText(text) {
+    const out = text.split("");
+    const blank = (from, to) => {
+        for (let i = from; i < to; i++)
+            if (out[i] !== "\n")
+                out[i] = " ";
+    };
+    for (const [from, to] of codeSpans(text))
+        blank(from, to);
+    for (const m of text.matchAll(DEFINITION_LINE)) {
+        if (m.index !== undefined)
+            blank(m.index, m.index + m[0].length);
+    }
+    for (const m of text.matchAll(URL_TEXT)) {
+        if (m.index !== undefined)
+            blank(m.index, m.index + m[0].length);
+    }
+    for (const m of text.matchAll(LIST_MARKER)) {
+        if (m.index === undefined)
+            continue;
+        const from = m.index + m[1].length;
+        blank(from, from + m[2].length);
+    }
+    for (const m of text.matchAll(BREAK_TAG)) {
+        if (m.index === undefined)
+            continue;
+        blank(m.index, m.index + m[0].length);
+        out[m.index] = "\n";
+    }
+    return out.join("");
+}
+const isSpace = (c) => c !== undefined && /\s/u.test(c);
+const isLetter = (c) => c !== undefined && /\p{L}/u.test(c);
+const isDigit = (c) => c !== undefined && /\p{N}/u.test(c);
+const isBreak = (c) => c !== undefined && LINE_BREAK.test(c);
+/** Where the closers after a terminator that ends at `at` end. */
+function pastClose(text, at) {
+    let i = at;
+    while (i < text.length && CLOSERS.test(text[i]))
+        i++;
+    return i;
+}
+/**
+ * Past the markers that follow a sentence end on its line (`[1]` after
+ * "rose 12%." is that sentence's), by where each marker the citation
+ * grammar reads (`citationMarkers`) ends, keyed by where it starts.
+ */
+function pastMarkers(text, at, markers) {
+    let i = at;
+    for (;;) {
+        let j = i;
+        while (j < text.length && isSpace(text[j]) && !isBreak(text[j]))
+            j++;
+        const end = markers.get(j);
+        if (end === undefined)
+            return i;
+        i = end;
+    }
+}
+/**
+ * Is the `.` at `at` glued to a word that starts a new segment —
+ * "days.Anything", "1,284.50.want" — rather than inside a name ("Node.js",
+ * "e.g.", "policy.md")? A capital starts one; so does a lowercase word of
+ * four letters or more. A decimal point never does.
+ */
+function gluedFullStop(text, at) {
+    if (isDigit(text[at - 1]) && isDigit(text[at + 1]))
+        return false;
+    if (!isLetter(text[at + 1]))
+        return false;
+    let end = at + 1;
+    while (end < text.length && isLetter(text[end]))
+        end++;
+    const word = text.slice(at + 1, end);
+    return /^\p{Lu}/u.test(word) || word.length >= 4;
+}
+/**
+ * The answer cut into pieces — at a terminator a space or a line break
+ * follows, and at a blank line — and each piece into segments: at every
+ * other line break, at a terminator glued to the next word, and at every
+ * semicolon, em dash, en dash (not one between figures, a range) and pipe.
+ * Over {@link visibleText}.
+ */
+function segments(text) {
+    const out = [];
+    const markers = new Map(citationMarkers(text).map((m) => [m.at, m.end]));
+    let pieceStart = 0;
+    let partStart = 0;
+    let parts = [];
+    const cutPart = (end, next) => {
+        parts.push([partStart, end]);
+        partStart = next;
+    };
+    const cutPiece = (end, next) => {
+        cutPart(end, next);
+        out.push({ piece: [pieceStart, end], parts });
+        parts = [];
+        pieceStart = next;
+    };
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (TERMINATOR.test(c)) {
+            let end = i + 1;
+            while (end < text.length && TERMINATOR.test(text[end]))
+                end++;
+            const closed = pastClose(text, end);
+            if (closed >= text.length || isSpace(text[closed])) {
+                const after = pastMarkers(text, closed, markers);
+                cutPiece(after, after);
+                i = after;
+                continue;
+            }
+            const next = text[closed];
+            const glued = c === "." && end === i + 1
+                ? gluedFullStop(text, i)
+                : isLetter(next) || isDigit(next) || OPENERS.test(next);
+            if (glued)
+                cutPart(closed, closed);
+            i = glued ? closed : end;
+            continue;
+        }
+        if (isBreak(c)) {
+            let j = c === "\r" && text[i + 1] === "\n" ? i + 2 : i + 1;
+            while (j < text.length && /[ \t]/.test(text[j]))
+                j++;
+            if (j >= text.length || isBreak(text[j])) {
+                // A blank line: the piece ends.
+                let next = j;
+                while (next < text.length && isSpace(text[next]))
+                    next++;
+                cutPiece(i, next);
+                i = next;
+            }
+            else {
+                cutPart(i, i + 1);
+                i += 1;
+            }
+            continue;
+        }
+        const range = c === "–" && isDigit(text[i - 1]) && isDigit(text[i + 1]);
+        if (c === ";" || c === "|" || c === "—" || (c === "–" && !range))
+            cutPart(i, i + 1);
+        i += 1;
+    }
+    if (pieceStart < text.length)
+        cutPiece(text.length, text.length);
+    return out;
+}
+/** An ATX heading line, and a setext underline. */
+const ATX_HEADING = /^[ \t]{0,3}#{1,6}(?:[ \t]|$)/;
+const SETEXT_UNDERLINE = /^[ \t]{0,3}(?:=+|-{2,})[ \t]*$/;
+/** A line a list item or a block quote opens: its `---` is a break, not an underline. */
+const BLOCK_OPENER = /^[ \t]*(?:[-*+>]|\d{1,9}[.)])[ \t]/;
+/**
+ * The heading lines of `text`, as `[from, to)` spans: a line `#` opens, and
+ * the paragraph line a setext underline (`===`, `---`) sits under.
+ */
+function headingLines(text) {
+    const out = [];
+    let previous;
+    let at = 0;
+    for (const line of text.split("\n")) {
+        const span = [at, at + line.length];
+        if (ATX_HEADING.test(line))
+            out.push(span);
+        else if (SETEXT_UNDERLINE.test(line) &&
+            previous !== undefined &&
+            text.slice(...previous).trim() !== "" &&
+            !BLOCK_OPENER.test(text.slice(...previous)) &&
+            !SETEXT_UNDERLINE.test(text.slice(...previous))) {
+            out.push(previous);
+        }
+        previous = span;
+        at += line.length + 1;
+    }
+    return out;
+}
+/** What a heading states after a label ("Invoice total: 1,284.50"), or nothing. */
+function labelled(heading) {
+    const colon = heading.indexOf(":");
+    return colon === -1 ? "" : heading.slice(colon + 1);
+}
+/** `text[from, to)` with its edges trimmed, as a span. */
+function trimmed(text, [from, to]) {
+    let a = from;
+    let b = to;
+    while (a < b && isSpace(text[a]))
+        a++;
+    while (b > a && isSpace(text[b - 1]))
+        b--;
+    return [a, b];
+}
+/** Does `text` end as a question once its closers and the markers after it are set aside? */
+function endsAsQuestion(text) {
+    const ends = new Map(citationMarkers(text).map((m) => [m.end, m.at]));
+    let end = text.length;
+    while (end > 0) {
+        const mark = ends.get(end);
+        if (mark !== undefined)
+            end = mark;
+        else if (isSpace(text[end - 1]) || CLOSERS.test(text[end - 1]))
+            end -= 1;
+        else
+            break;
+    }
+    return text[end - 1] === "?";
+}
+/** Does `text` open as a question: its first word, past bullets, figures and marks, an opener? */
+function opensAsQuestion(text) {
+    const word = /[\p{L}][\p{L}'’]*/u.exec(text)?.[0];
+    return word !== undefined && QUESTION_OPENERS.has(word.toLowerCase().replace(/’/g, "'"));
+}
+/**
+ * Claims the backstop reads in an answer the extractor found nothing to
+ * count in (see the module doc), numbered from `firstIndex`. Each is the
+ * segment as written (`raw`, markers in it), read as `plainClaim` reads a
+ * sentence, citing the markers it carries — a marker the document defines,
+ * a numeral, a footnote or an assumption id; a segment that is only
+ * markers gives them to the segment before it. A segment the extractor
+ * already returned (an assumption it read) is not read twice. Empty when
+ * the answer may be vacuous.
+ */
+export function backstopClaims(text, definitions, extracted, firstIndex) {
+    const visible = visibleText(text);
+    const lineOf = lineIndex(text);
+    // A heading is a title to the figure rule — "## Refund options for 2024"
+    // over "Which option do you want?" has nothing to prove; claim-ledger's
+    // `headingClaim` decides which heading states one. What one states after
+    // a label ("## Invoice total: 1,284.50") is read, and a marker in one
+    // still makes it a claim.
+    const headings = headingLines(visible);
+    const inHeading = ([from]) => headings.some(([a, b]) => from >= a && from < b);
+    const known = extracted.map((claim) => claim.text.replace(/\s+/g, " ").trim().toLowerCase());
+    const citing = (id, caret) => definitions.has(id) || caret || /^\d+$/.test(id) || isAssumptionMarker(id);
+    const out = [];
+    for (const { piece, parts: spans } of segments(visible)) {
+        const pieceText = visible.slice(...trimmed(visible, piece));
+        const asked = endsAsQuestion(pieceText);
+        const parts = [];
+        // In a piece that ends as a question: asked from the segment that
+        // opens one to the segment that ends one; said before it.
+        let questioning = false;
+        for (const raw of spans) {
+            const span = trimmed(visible, raw);
+            const shown = visible.slice(...span);
+            if (shown === "")
+                continue;
+            const markers = [];
+            for (const m of citationMarkers(shown)) {
+                if (citing(m.marker, m.caret) && !markers.includes(m.marker))
+                    markers.push(m.marker);
+            }
+            const words = plainClaim(shown);
+            if (words === "" && markers.length > 0 && parts.length > 0) {
+                // Markers on their own: the segment before them is what they cite.
+                const before = parts[parts.length - 1];
+                for (const marker of markers)
+                    if (!before.markers.includes(marker))
+                        before.markers.push(marker);
+                before.span = [before.span[0], span[1]];
+                continue;
+            }
+            const ends = endsAsQuestion(shown);
+            if (asked && opensAsQuestion(words))
+                questioning = true;
+            parts.push({
+                span,
+                markers,
+                figure: extractNumbers(inHeading(span) ? labelled(words) : words).length > 0,
+                question: questioning || ends,
+            });
+            if (ends)
+                questioning = false;
+        }
+        for (const part of parts) {
+            if (part.markers.length === 0 && (!part.figure || part.question))
+                continue;
+            const raw = text.slice(...part.span).trim();
+            const claimText = plainClaim(raw);
+            if (claimText === "")
+                continue;
+            const folded = claimText.replace(/\s+/g, " ").trim().toLowerCase();
+            if (known.some((seen) => seen.includes(folded) || folded.includes(seen)))
+                continue;
+            out.push({
+                index: firstIndex + out.length,
+                text: claimText,
+                raw,
+                line: lineOf(part.span[0]),
+                markers: part.markers,
+            });
+        }
+    }
+    return out;
+}

package/dist/verify.d.ts

@@ -0,0 +1,176 @@
+import { type ProofBundle, type ProofClaim, type ProvabilityConfig, type UnmetReason, type VerifyOptions } from "./types";
+/**
+ * Distinct URLs one verification sends a HEAD to under `sources.resolve:
+ * head` (design §6.1). The answer is model-written, so without a ceiling it
+ * decides how many outbound requests the gate makes and how long it waits
+ * on them; a URL past the ceiling is `unresolved` — not checked is not
+ * reachable — and the detail names the cap.
+ */
+export declare const MAX_HEAD_REQUESTS = 50;
+/**
+ * How many of those HEADs are in flight at once, and how long one
+ * verification waits on them in all (design §6.1, §18: the gate's cost is
+ * bounded). Sent one at a time under a per-request timeout alone, fifty
+ * URLs on hosts that never answer held one pass for minutes, and again on
+ * every retry; past the deadline a URL is `unresolved` — not checked is not
+ * reachable — whatever is still pending.
+ */
+export declare const HEAD_CONCURRENCY = 6;
+export declare const HEAD_DEADLINE_MS = 15000;
+/**
+ * Fetched text one verification reads while grounding, in tokens: each
+ * claim reads every body it cites end to end, so a long answer citing a
+ * large page costs claims × body — 200 claims over a 4 MB page held the
+ * harness thread for twelve seconds per pass. Past this a source binding
+ * is not read for grounding: it reaches `cited` and, at a higher floor,
+ * reads `below_floor` with a detail naming the cap (§18: bounded gate
+ * cost). The verifier also yields to the event loop between claims, so
+ * the work it does do never holds the process for long at a stretch.
+ */
+export declare const MAX_GROUNDING_TOKENS = 40000000;
+/** Test seam: a smaller grounding budget, or (no argument) {@link MAX_GROUNDING_TOKENS} again. */
+export declare function _setGroundingBudgetForTest(tokens?: number): void;
+/**
+ * Whitespace collapsed, cut to `max` with an ellipsis. Only a prefix of a
+ * long text is collapsed — a 2 MB tool result clipped to 240 characters
+ * must not be rewritten whole — unless that prefix is so full of
+ * whitespace that it collapses to fewer than `max` characters.
+ */
+export declare function clip(text: string, max: number): string;
+/**
+ * At most `max` characters of `text` around `[from, to)`, whitespace
+ * collapsed, an ellipsis marking each cut: the frozen excerpt of a long
+ * body or result, centred on what met the floor (design §5.3: a bundle
+ * stays human-checkable after the body is gone, so its excerpt must show
+ * the figure or the words that grounded the claim, not the text's first
+ * 240 characters). When `[from, to)` itself is longer, its start is kept.
+ */
+export declare function clipAround(text: string, from: number, to: number, max: number): string;
+/**
+ * The reasons a claim is unmet: `no_citation` for a claim with no marker at
+ * all (it has zero bindings — the representation design §5.1's nudge reads),
+ * else the reason of every binding that is not `ok`, in order, each once. An
+ * empty list for a met or assumption claim.
+ */
+export declare function claimReasons(claim: ProofClaim): UnmetReason[];
+/**
+ * Is a recorded tool name on `execution.allow`? The IR carries CANONICAL
+ * entries (ir `IrProvability.execution.allow`): a builtin is its spec key
+ * (`moneyAdd`), anything else its exact name. A recorded builtin name
+ * (`MoneyAdd`) is mapped to its key case-insensitively, the way the compiler
+ * maps `tools:`; a non-builtin name (`mcp__calc__add`) must match exactly,
+ * because MCP tool names are case-sensitive.
+ */
+export declare function isToolAllowed(toolName: string, allow: ReadonlyArray<string>): boolean;
+/**
+ * Result tokens the figure polarity rule has read into a statement's table
+ * of words: for a test to count with, as claim-ledger's `scanMeter` is.
+ * Only ever added to.
+ */
+export declare const polarityMeter: {
+    tokens: number;
+};
+/**
+ * Why the answer's sentence does not state what a proof's recorded claim
+ * says, or `undefined` when it does (design §6.4): "the grounded coverage
+ * test", read the way `grounded` reads it — the words, AND the figures and
+ * the negations that coverage alone cannot see.
+ *
+ * - Words: the artifact claim's content tokens covered by the sentence's
+ *   at the grounded bar, so an accepted proof of something else cannot be
+ *   pinned to this sentence.
+ * - Figures: the same figures on both sides (`two` and `2` are one). A
+ *   proof about meetings 1 and 2 does not prove a sentence about all six,
+ *   and `contentTokens` drops one- and two-digit numbers.
+ * - Polarity, word by word: each word of the proof's claim (a figure by its
+ *   value) is denied on both sides or on neither, as claim-ledger's
+ *   `governingNegation` scopes a negation, wherever the sentence uses it.
+ *   `contentTokens` drops "no" (two letters) and "not" (a stopword), so
+ *   without this an accepted proof that two of the six meetings overlap
+ *   would prove "no two of the six meetings overlap" — acceptance scenario
+ *   C served false. Read per word, not per sentence, because the sentence
+ *   may say more than the proof (design §6.4): "no discount was applied, so
+ *   the invoice total is 1,284.50 EUR" states the proved total, and its
+ *   "no" denies a discount the proof never mentions. A word one side both
+ *   states and denies is not compared, and a negation that moves from one
+ *   word to another ("no two of the meetings overlap", "two of the
+ *   meetings didn't overlap") is a different statement. A partitive denial
+ *   of the whole statement ("none of the 3 invoices is overdue") is read
+ *   too ({@link partitiveDenial}), and so is a frame that negates it ("it
+ *   is not true that …", {@link negationFrames}): one side framed and the
+ *   other not states the opposite (acceptance C).
+ *
+ * What it cannot see is a sentence that adds a clause of its own to the
+ * proved statement ("…, and the CEO approved it"): the coverage runs from
+ * the proof's claim into the sentence, as the design specifies, so the
+ * sentence may carry more words. That residual, like the formalization gap
+ * itself, is shown beside the claim (the statement), not closed here.
+ */
+export declare function statementMismatch(proved: string, sentence: string, bar: number): string | undefined;
+/**
+ * An evidence id as the model may have dressed it — `` tool:`toolu_01` ``,
+ * `proof:prf_….` at the end of a sentence — down to the id. Ids are
+ * `[A-Za-z0-9_-]` runs, so wrapping quotes, backticks and angle brackets and
+ * trailing sentence punctuation are never part of one. Trimmed by walking
+ * in from each end: an end-anchored pattern (`/[…]+$/`) restarts at every
+ * character of a long run of them that does not end the id — quadratic in
+ * text the model writes, six seconds for 80 000 dots.
+ */
+export declare function bareId(id: string): string;
+/**
+ * What `grounded.independent` counts as one origin: the registrable domain
+ * of a URL (`docs.acme.example` and `www.acme.example` are one publisher), a
+ * DOI's registrant prefix (`10.1000` — one publisher's papers are one
+ * origin, like one site's pages), and a workspace file's own path.
+ */
+export declare function independenceKey(origin: string): string;
+/**
+ * `sha256:<hex>` over the canonical JSON (keys sorted recursively) of every
+ * field of the bundle except `bundleHash` itself — what the audit record
+ * and the trace line carry, so a stored bundle can be shown to be the one
+ * that was graded.
+ */
+export declare function bundleHash(bundle: Omit<ProofBundle, "bundleHash"> | ProofBundle): string;
+/**
+ * The bundle for a verifier that THREW (design §5.1): grading
+ * infrastructure failed, the gate fails open, and the bundle says so rather
+ * than printing a ✓ — `verdict: "unverified"`, no claims, the error clipped.
+ * Only the floor and the threshold are read, so the runtime gate — which
+ * holds `RunProvability`, not the lowered IR block — can build one too.
+ */
+export declare function unverifiedBundle(config: Pick<ProvabilityConfig, "level" | "threshold">, error: unknown, retryIndex?: number, now?: Date | (() => Date)): ProofBundle;
+/**
+ * Citations the up-front HEAD collection in {@link verifyDocument} has
+ * examined: for a test to count with, as claim-ledger's `scanMeter` is.
+ * Only ever added to.
+ */
+export declare const headCollectMeter: {
+    markers: number;
+};
+/**
+ * Verify every claim of `text` against `opts.evidence` at `opts.config`'s
+ * floor, and return the proof bundle (design §5.3).
+ *
+ * - Claims are claim-ledger's `extractClaims` — plus the text any
+ *   definition line shows beyond what it names, read as claims citing that
+ *   definition (see `definitionClaims`); a claim with no marker is unmet
+ *   with zero bindings (`no_citation`), one with a dangling marker is unmet
+ *   (`no_definition`).
+ * - Each marker binds to its definition, classified by claim-ledger's
+ *   evidence-ref grammar: a source (cited → grounded), `tool:` (checked),
+ *   `proof:` (proven) or `assume:` (an assumption).
+ * - A binding records the highest rung it reached and, when that is below
+ *   the floor, the FIRST check it failed. Rungs above the floor are still
+ *   computed — `achieved` is "the highest floor this answer would have
+ *   passed" — but the three outside calls are made only where the floor
+ *   needs them: `resolveHead` at `cited`/`grounded` (no source can meet a
+ *   higher floor), `judgeWaiver` at `grounded` (for a coverage-only
+ *   paraphrase miss), `replay` at `checked`. So `achieved` above the floor
+ *   is computed without them.
+ * - `scope: turn` (`turnNumbers`) restricts the evidence to those turns.
+ *
+ * Never throws for anything a document or its evidence can contain — an
+ * unreadable artifact, a failing judge or replay, a refused HEAD are each a
+ * binding's reason. Throws only for a malformed config (a programmer error).
+ */
+export declare function verifyDocument(text: string, opts: VerifyOptions): Promise<ProofBundle>;