backdraft 0.2.0__py3-none-any.whl

backdraft/gate/searcher.py

@@ -0,0 +1,123 @@
+"""The search side of the gate: FTS results that are themselves citable.
+
+A searched snippet is minted exactly like a read one. This is the whole point of
+routing search through the gate: in the app that preceded backdraft, search
+returned text with nothing citable attached, so every search was followed by a
+page read purely to obtain an anchor. Here the result *is* the anchor, and the
+read hint below the results is an affordance, not a prerequisite.
+
+Consumes the pinned registry surface (SPEC Addendum A) and nothing else.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..kernel.hashing import normalize
+
+from .reader import GateError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from ..registry.store import Registry, SearchHit
+
+__all__ = ["EXCERPT_CHARS", "PHRASE_FALLBACK_NOTE", "search", "render_search"]
+
+EXCERPT_CHARS = 160
+"""How much of a snippet a result line shows before deferring to a page read."""
+
+PHRASE_FALLBACK_NOTE = "(query retried as a phrase)"
+"""Shown when the registry could not parse the query as FTS5 syntax.
+
+The retry changes the question: `NOI 1.42x` as a boolean query asks for both
+terms anywhere, as a phrase it asks for those tokens adjacent and in order. A
+reader who is not told cannot distinguish "no such fact" from "not asked that
+way", so the gate says it — once, on its own line, rather than as an error.
+"""
+
+_ELLIPSIS = "..."
+_DEFAULT_LIMIT = 20
+"""Mirrors `Registry.search`'s own default, so the CLI and the store agree."""
+
+
+def search(
+    registry: Registry,
+    query: str,
+    *,
+    slug: str | None = None,
+    limit: int = _DEFAULT_LIMIT,
+    session: str | None = None,
+) -> str:
+    """Run `query` through the registry's FTS index and render the results.
+
+    Each hit is one line carrying its token, its document and page, and an
+    excerpt of its snippet; a read hint follows for every distinct page matched.
+    Every hit's anchor is recorded in `session` before the text is returned — a
+    result the writer saw is a result the writer may cite.
+
+    Raises `GateError` if `slug` names no document.
+    """
+    if slug is not None and registry.document(slug) is None:
+        raise GateError(f"no such document: {slug!r}")
+    hits = registry.search(query, slug=slug, limit=limit)
+    _mint(registry, session, hits)
+    return render_search(query, hits, slug=slug)
+
+
+def render_search(query: str, hits: Iterable[SearchHit], *, slug: str | None = None) -> str:
+    """Render search results. Pure: minting happens in `search`.
+
+    NOTE: the `phrase_fallback` flag is read *before* `hits` is copied into a
+    plain list — it rides on the result object the registry returned.
+    """
+    retried = bool(getattr(hits, "phrase_fallback", False))
+    hits = list(hits)
+    scope = f" in {slug}" if slug else ""
+    note = [PHRASE_FALLBACK_NOTE] if retried else []
+    if not hits:
+        return "\n".join(
+            [
+                f'No results for "{query}"{scope}.',
+                *note,
+                "",
+                "[List documents: backdraft read]",
+            ]
+        )
+
+    count = f"{len(hits)} result" if len(hits) == 1 else f"{len(hits)} results"
+    lines = [f'{count} for "{query}"{scope}', *note, ""]
+    for hit in hits:
+        lines.append(f"[{hit.anchor.token}]  {hit.slug} p{hit.page_number}")
+        lines.append(f"  {_excerpt(hit.anchor.receipt.snippet)}")
+        lines.append("")
+
+    seen: list[tuple[str, int]] = []
+    for hit in hits:
+        if (hit.slug, hit.page_number) not in seen:
+            seen.append((hit.slug, hit.page_number))
+    lines += [f"[Read the page: backdraft read {s} p{n}]" for s, n in seen]
+    return "\n".join(line.rstrip() for line in lines).rstrip("\n")
+
+
+def _excerpt(snippet: str) -> str:
+    """A snippet collapsed onto one line and cut to `EXCERPT_CHARS`.
+
+    NOTE: the cut is from the start rather than centred on the match. FTS5
+    decides what matched (stemming, phrase queries), and the gate does not
+    re-derive anything the registry owns; the token on the line above is the
+    thing to cite, and the read hint is the way to see the rest.
+    """
+    text = normalize(snippet)
+    return text if len(text) <= EXCERPT_CHARS else text[:EXCERPT_CHARS] + _ELLIPSIS
+
+
+def _mint(registry: Registry, session: str | None, hits: Iterable[SearchHit]) -> None:
+    """Record every result's anchor under the session."""
+    if session is None:
+        return
+    anchor_ids = sorted({hit.anchor.id for hit in hits if hit.anchor.id is not None})
+    if not anchor_ids:
+        return
+    session_id = registry.ensure_session(session)
+    registry.record_shown(session_id, anchor_ids)

backdraft/kernel/__init__.py

@@ -0,0 +1,17 @@
+"""The kernel: pure, stdlib-only, imports nothing else from the package.
+
+Grammar, hashing, chunking, claim parsing, the artifact format and the vocabulary
+of types. No I/O, no SQLite, no configuration. Everything above this layer —
+registry, extract, gate, bind, render — imports the kernel; the kernel imports
+none of them. `tests/test_invariants.py` enforces that by reading this source.
+
+**The module paths are the API.** There is deliberately no flat re-export surface
+here: callers write `from backdraft.kernel.tokens import parse`, not
+`from backdraft.kernel import parse_token`. Two reasons. The module a name lives
+in is information — `hashing.normalize` and a bare `normalize` are not equally
+readable — and a flat surface has to invent disambiguating aliases (`parse`, in
+three different modules, became `parse_token` / `parse_locator` /
+`parse_citation`) that name nothing actually defined anywhere. Each submodule's
+own `__all__` is its contract; this package has none.
+"""
+

backdraft/kernel/artifact.py

@@ -0,0 +1,234 @@
+"""The artifact format: its version string, its legend, its file names, its payload.
+
+Kernel-owned because the format is shared vocabulary: bind writes the sidecar,
+render reads and re-emits it, and neither may import the other. The prose spec
+is `spec/artifact.md`; this module is its single in-code copy.
+
+**Naming is part of the format.** What a bind run and a render run are called on
+disk is how a reader (person, agent, or another implementation) finds the pieces
+of one document's record, so the suffixes and the path math live here rather than
+in whichever layer happens to write each file. `spec/artifact.md` § Naming is the
+normative statement; the constants below are its in-code copy.
+
+NOTE on kernel purity: `pathlib` is imported for path *math* only. Nothing here
+touches the filesystem — these functions compute names, they do not read or write
+(`tests/test_invariants.py` enforces that distinction).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .model import BindReport
+
+__all__ = [
+    "FORMAT",
+    "LEGEND",
+    "ARTIFACT_SUFFIX",
+    "BOUND_SUFFIX",
+    "FOOTNOTES_SUFFIX",
+    "SIDECAR_SUFFIX",
+    "bound_path",
+    "sidecar_path",
+    "RECORDS_DIR",
+    "record_path",
+    "sidecar",
+    "dumps",
+]
+
+FORMAT = "backdraft/artifact-v1"
+"""The artifact format string. Readers match it exactly; see `LEGEND["version"]`."""
+
+# ---- the naming family ------------------------------------------------------
+#
+# Every name is `<stem of the authored document>` + one of these suffixes, so a
+# single `memo.md` produces `memo.bound.md`, `memo.backdraft.json`,
+# `memo.backdraft.html` and `memo.footnotes.md`, and a directory listing sorts
+# them together. The `.backdraft.*` pair is the artifact record proper — the same
+# payload, machine-readable and human-readable; the other two are projections.
+
+BOUND_SUFFIX = ".bound.md"
+"""bind's rewritten document: `memo.md` -> `memo.bound.md`."""
+
+SIDECAR_SUFFIX = ".backdraft.json"
+"""A document's sidecar sits beside it: `memo.md` -> `memo.backdraft.json`."""
+
+ARTIFACT_SUFFIX = ".backdraft.html"
+"""The self-contained artifact: `memo.md` -> `memo.backdraft.html`."""
+
+FOOTNOTES_SUFFIX = ".footnotes.md"
+"""render's markdown projection: `memo.md` -> `memo.footnotes.md`.
+
+Named for what it is rather than `.backdraft.md`, which would join the sidecar's
+family without being the record, and rather than `.bound.md`, which is bind's
+output and is a different document.
+"""
+
+
+def bound_path(doc_path: Path) -> Path:
+    """Where bind's rewritten document goes."""
+    return doc_path.with_name(doc_path.stem + BOUND_SUFFIX)
+
+
+def sidecar_path(doc_path: Path) -> Path:
+    """The beside-the-document record path: `memo.md` -> `memo.backdraft.json`.
+
+    This is the *portable* location — the one a reader handed a document and
+    its record uses. A project with a registry stores records out of sight
+    instead; see `record_path`.
+    """
+    return doc_path.with_name(doc_path.stem + SIDECAR_SUFFIX)
+
+
+RECORDS_DIR = "records"
+"""Records live under `.backdraft/records/`, mirroring each document's path
+relative to the project root — the authored directory shows only the document
+and its artifact."""
+
+
+def record_path(root: Path, doc_path: Path) -> Path:
+    """Where a project stores a document's record: out of the authored directory.
+
+    `<root>/.backdraft/records/<doc's path relative to root>` with the sidecar
+    suffix, so distinct documents can never collide. A document outside `root`
+    falls back to the beside-the-document path.
+
+    Pure path math (the kernel invariant): both arguments must already be
+    resolved to comparable absolute forms — callers hold the filesystem.
+    """
+    try:
+        relative = Path(doc_path).relative_to(Path(root))
+    except ValueError:
+        return sidecar_path(doc_path)
+    return (
+        Path(root) / ".backdraft" / RECORDS_DIR / relative.parent
+        / (relative.stem + SIDECAR_SUFFIX)
+    )
+
+
+LEGEND: dict[str, Any] = {
+    "what_this_is": (
+        "A bound document: every claim its author cited, recorded with the verbatim "
+        "evidence behind it. This legend describes the object around it so that a "
+        "reader who has never seen backdraft — person or model — can use the record "
+        "without any other file, any registry, and any network access."
+    ),
+    "how_to_read": [
+        "`claims` is the record, in document order. Each claim is a span of the "
+        "authored document: `text` is the words the citations support, and "
+        "`start`/`end` are character offsets into the authored source, bounding the "
+        "whole markdown construct the author wrote.",
+        "Each entry in a claim's `citations` names one anchor by its `token` and "
+        "carries what binding found: a `status`, an `anchor` when one was found, "
+        "`drifted_from` when the source moved, `error` when the token did not parse, "
+        "and `verdicts` from whichever verification methods were switched on.",
+        "An `anchor` is the receipt: `slug` names the source document, `locator` "
+        "names the place inside it, `snippet` is the verbatim text that was quoted, "
+        "and `snippet_sha256` is that snippet's hash. The snippet is present in "
+        "full — you never need the source document to read the evidence.",
+        "A claim with `unmatched` true is one that binding could not anchor at all. "
+        "It is listed because it was written, not because it was verified.",
+        "Every citation whose `status` is not `resolved` is a failure that was kept "
+        "rather than hidden. Read those first; they are the interesting part.",
+        "`summary` is derived from `claims` and is never authoritative on its own. "
+        "If the two disagree, recount from `claims`.",
+    ],
+    "token": (
+        "`bd:<slug>:<locator>:<hash>` is the textual name of an anchor. `hash` is the "
+        "leading 4 to 8 hex characters of sha256 over the normalized snippet, where "
+        "normalize is: Unicode NFC, then every whitespace run collapsed to one space, "
+        "then strip, case preserved."
+    ),
+    "locator_forms": {
+        "p8": "page or sheet 8, whole",
+        "p8.c3": (
+            "chunk 3 within page 8 — chunks are deterministic paragraph-scale "
+            "subdivisions of a page, numbered from 1"
+        ),
+        "rent-roll!B10": "sheet `rent-roll`, cell B10, A1 notation",
+        "rent-roll!B10:C12": "sheet `rent-roll`, rectangular range",
+    },
+    "citation_status": {
+        "resolved": (
+            "the anchor was found in the source document's current extraction; "
+            "`anchor.snippet` is what the source says now and what the author cited"
+        ),
+        "drifted": (
+            "the anchor was found only in a superseded extraction — the source changed "
+            "after the claim was written. `drifted_from` is the snippet the author saw; "
+            "`anchor.snippet` is what stands there now. Compare them before trusting "
+            "the claim"
+        ),
+        "not_shown": (
+            "a real anchor, but it was never shown to the writer in the recorded "
+            "session: the claim cites something its author did not read"
+        ),
+        "unresolved": (
+            "a well-formed token naming no anchor in any generation of any source. "
+            "Treat the claim as uncited"
+        ),
+        "malformed": (
+            "the citation text is not a token; `error` says why. Reported verbatim "
+            "rather than dropped"
+        ),
+    },
+    "verdict_status": {
+        "pass": "the method ran and the claim survived it",
+        "fail": "the method ran and the claim did not survive it",
+        "partial": "the method ran and found partial support; `detail` says how much",
+        "skip": "the method did not apply to this claim and citation",
+    },
+    "verdicts_are_evidence": (
+        "Verification methods are opt-in switches, never gates. A method missing from "
+        "a citation's `verdicts` was not run — that is not a pass. `summary.by_method` "
+        "counts only what actually ran, as {method: {verdict status: count}}."
+    ),
+    "verify_this_record": [
+        "1. For every citation carrying an `anchor`, recompute sha256 over the "
+        "normalized `snippet`: it must equal `anchor.snippet_sha256`, and the `hash` "
+        "segment of `token` must be a prefix of it.",
+        "2. The `slug` and `locator` segments of `token` must equal `anchor.slug` and "
+        "`anchor.locator`.",
+        "3. Recount `summary` from `claims`.",
+        "Steps 1 to 3 need nothing but this object. If you also hold the source "
+        "documents, look `locator` up in the document named by `slug` and compare its "
+        "text against `snippet`; that is the only check this record cannot make of "
+        "itself.",
+    ],
+    "evidence": (
+        "Optional. Evidence context for the cited sources, bounded by what is cited "
+        "— never the whole corpus. `documents` maps slug to {filename, media_type}. "
+        "`pages` maps `slug:pN` to a page image {format, width, height, data} where "
+        "`data` is base64; for a vision-model extraction this is the page as the "
+        "model was shown it. `pagetexts` maps `slug:pN` to that page's extracted "
+        "text. `windows` maps `slug:<locator>` to a small cell grid around a cited "
+        "cell: {sheet, cited, cols, rows}. `sheets` maps `slug:<sheet>` to the full "
+        "cited sheet's values: {name, nrows, ncols, rows}. A record without "
+        "`evidence` is still complete — evidence is context, snippets are the proof. "
+        "The HTML artifact may omit `pages[*].data` from its embedded copy of this "
+        "object when the same bytes are present in the page as image elements."
+    ),
+    "version": (
+        "The format string in `$format` is matched exactly, as an opaque string. A "
+        "reader that does not recognize `backdraft/artifact-v1` must not guess: later "
+        "versions may reuse these field names with different meanings. There is no "
+        "compatibility range and no minor-version negotiation."
+    ),
+}
+"""Normative. The artifact teaches its own decoding; `spec/artifact.md` specifies it."""
+
+
+def sidecar(report: BindReport) -> dict[str, Any]:
+    """The sidecar payload: `$format`, `$legend`, then the report, in that order."""
+    return {"$format": FORMAT, "$legend": LEGEND, **report.to_dict()}
+
+
+def dumps(report: BindReport) -> str:
+    """The sidecar as text: UTF-8, two-space indent, trailing newline.
+
+    Deterministic — the same report always produces the same bytes, so artifacts
+    diff cleanly.
+    """
+    return json.dumps(sidecar(report), indent=2, ensure_ascii=False) + "\n"

backdraft/kernel/chunking.py

@@ -0,0 +1,162 @@
+"""The deterministic chunker (normative prose copy in spec/chunking.md).
+
+`chunk(page_text) -> [Chunk(ordinal, text, start, end)]`. Pure and total: the
+same page text always yields the same chunks, and no input raises.
+
+Determinism is the whole point. A chunk's ordinal is half of its anchor identity
+(extraction, page number, ordinal), so a chunker that rebalanced or capped chunk
+counts would silently move every citation on the page. There is deliberately no
+per-page rebalancing and no chunk-count cap.
+
+The algorithm:
+
+1. Split on blank lines (``\\n\\s*\\n``).
+2. Merge forward: a segment shorter than 200 chars merges into the following
+   segment; the last segment merges backward instead.
+3. Split long: a segment longer than 2400 chars splits at the sentence boundary
+   nearest each 1200-char multiple. A sentence boundary is a terminal ``.!?``
+   followed by whitespace and an uppercase letter or digit — no abbreviation
+   table, because splitting slightly wrong only shifts a boundary, and it does so
+   deterministically. A final piece under 200 chars merges backward: step 2 ran
+   before the split and could not see it.
+4. Ordinals ``c1..cN`` in order.
+
+Offsets are exact: ``page_text[chunk.start:chunk.end] == chunk.text`` for every
+chunk. NOTE: a chunk's text is therefore the verbatim source region, including
+any blank-line separators that merging swallowed; only the outer edges are
+trimmed of whitespace. This keeps offsets meaningful for future span features and
+costs nothing, since `hashing.normalize` collapses interior whitespace anyway.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .model import Chunk
+
+__all__ = [
+    "MIN_CHARS",
+    "MAX_CHARS",
+    "TARGET_CHARS",
+    "chunk",
+]
+
+MIN_CHARS = 200
+"""Segments shorter than this merge into a neighbour."""
+
+MAX_CHARS = 2400
+"""Segments longer than this are split."""
+
+TARGET_CHARS = 1200
+"""Long segments split near each multiple of this."""
+
+_BLANK_LINE = re.compile(r"\n\s*\n")
+# NOTE: the spec says "terminal .!? + space"; we accept a run of whitespace so a
+# double space or a wrapped line still reads as a boundary.
+_SENTENCE_BOUNDARY = re.compile(r"[.!?]\s+(?=[A-Z0-9])")
+
+type _Span = tuple[int, int]
+
+
+def chunk(page_text: str) -> list[Chunk]:
+    """Chunk one page's text. Returns `[]` for empty or whitespace-only pages."""
+    spans: list[_Span] = []
+    for span in _merge_short(_split_paragraphs(page_text)):
+        spans.extend(_split_long(page_text, span))
+    return [
+        Chunk(ordinal=ordinal, text=page_text[start:end], start=start, end=end)
+        for ordinal, (start, end) in enumerate(spans, start=1)
+    ]
+
+
+def _split_paragraphs(text: str) -> list[_Span]:
+    """Blank-line separated regions, edge-trimmed, empties dropped."""
+    spans: list[_Span] = []
+    cursor = 0
+    for separator in _BLANK_LINE.finditer(text):
+        spans.append((cursor, separator.start()))
+        cursor = separator.end()
+    spans.append((cursor, len(text)))
+    return [span for span in (_trim(text, *raw) for raw in spans) if span[0] < span[1]]
+
+
+def _merge_short(spans: list[_Span]) -> list[_Span]:
+    """Merge forward while a group is under `MIN_CHARS`; the last merges backward.
+
+    NOTE: length is measured over the source region (`end - start`), which for a
+    single segment is exactly its character count and for a merged group also
+    counts the blank line it absorbed.
+    """
+    groups: list[_Span] = []
+    index = 0
+    while index < len(spans):
+        start, end = spans[index]
+        index += 1
+        while end - start < MIN_CHARS and index < len(spans):
+            end = spans[index][1]
+            index += 1
+        groups.append((start, end))
+    if len(groups) > 1 and groups[-1][1] - groups[-1][0] < MIN_CHARS:
+        last = groups.pop()
+        start, _ = groups.pop()
+        groups.append((start, last[1]))
+    return groups
+
+
+def _split_long(text: str, span: _Span) -> list[_Span]:
+    """Split a span over `MAX_CHARS` at sentence boundaries near each target."""
+    start, end = span
+    length = end - start
+    if length <= MAX_CHARS:
+        return [span]
+    boundaries = [
+        start + match.end() for match in _SENTENCE_BOUNDARY.finditer(text[start:end])
+    ]
+    if not boundaries:
+        return [span]
+
+    cuts: list[int] = []
+    previous = start
+    target = TARGET_CHARS
+    while target < length:
+        goal = start + target
+        # NOTE: nearest wins; ties go to the earlier boundary.
+        candidates = [offset for offset in boundaries if previous < offset < end]
+        if candidates:
+            best = min(candidates, key=lambda offset: (abs(offset - goal), offset))
+            cuts.append(best)
+            previous = best
+        target += TARGET_CHARS
+
+    edges = [start, *cuts, end]
+    pieces = [
+        _trim(text, edges[i], edges[i + 1]) for i in range(len(edges) - 1)
+    ]
+    return _absorb_tail([piece for piece in pieces if piece[0] < piece[1]])
+
+
+def _absorb_tail(pieces: list[_Span]) -> list[_Span]:
+    """Merge an undersized final piece backward, the way rule 2 merges backward.
+
+    Merging runs before splitting, so rule 2 cannot see the pieces rule 3 is
+    about to create: a 2500-char region splits near 1200 and leaves a ~100-char
+    tail that rule 2 would have absorbed had it been a paragraph. That tail is a
+    chunk in name only — too small to carry context, and it becomes an anchor
+    whose receipt is a sentence fragment. So rule 3 applies rule 2's backward
+    merge to its own output, which is where that rule already sends a trailing
+    short region. `pieces` is a fresh list and is mutated in place.
+    """
+    if len(pieces) > 1 and pieces[-1][1] - pieces[-1][0] < MIN_CHARS:
+        last = pieces.pop()
+        start, _ = pieces.pop()
+        pieces.append((start, last[1]))
+    return pieces
+
+
+def _trim(text: str, start: int, end: int) -> _Span:
+    """Shrink a span past leading and trailing whitespace."""
+    while start < end and text[start].isspace():
+        start += 1
+    while end > start and text[end - 1].isspace():
+        end -= 1
+    return (start, end)

backdraft/kernel/claims.py

@@ -0,0 +1,142 @@
+"""Reading claims out of authored markdown.
+
+The wire form is one markdown link per claim span — `[claim text](bd:...)` — and
+nothing else: no doc names, no footnotes, no display text. Which words an anchor
+supports can never be recovered later and can always be projected away, so it is
+captured here, at write time.
+
+`parse_claims` is total: it never raises. A token that does not parse becomes a
+`Citation` with status `malformed` carrying the reason, because bind must report
+every citation the author wrote — including the ones it cannot use.
+
+Scope, deliberately small (NOTE: the spec is silent on each of these):
+
+* Link text may contain balanced brackets, other inline formatting, and newlines.
+* Images (`![alt](...)`) are not claims.
+* An href is a citation href if any `;`-separated piece starts with `bd:`; the
+  pieces that do not are reported as malformed rather than dropped.
+* Code spans and fenced blocks are not special-cased — a token written inside one
+  is still read as a claim. Recognizing fences would require a markdown parser,
+  and a document that quotes tokens in prose is not the case worth optimizing.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .errors import MalformedTokenError, UnsupportedTokenError
+from .model import Citation, CitationStatus, Claim
+from .tokens import is_token_href, parse, split_href
+
+__all__ = ["parse_claims", "parse_citation"]
+
+_LINK_TITLE = re.compile(r"""\s+(?:"[^"]*"|'[^']*')$""")
+
+
+def parse_claims(source: str) -> list[Claim]:
+    """Every claim in an authored document, in document order.
+
+    A claim's `start`/`end` bound the whole markdown link, so
+    `source[claim.start:claim.end]` is the construct bind rewrites; `claim.text`
+    is the link text alone.
+    """
+    claims: list[Claim] = []
+    index = 0
+    length = len(source)
+    while index < length:
+        character = source[index]
+        if character == "\\":
+            index += 2
+            continue
+        if character != "[":
+            index += 1
+            continue
+        if index > 0 and source[index - 1] == "!":
+            index += 1
+            continue
+        link = _scan_link(source, index)
+        if link is None:
+            index += 1
+            continue
+        text_start, text_end, href, link_end = link
+        if not is_token_href(href):
+            index += 1
+            continue
+        claims.append(
+            Claim(
+                text=source[text_start:text_end],
+                start=index,
+                end=link_end,
+                citations=tuple(parse_citation(piece) for piece in split_href(href)),
+            )
+        )
+        index = link_end
+    return claims
+
+
+def parse_citation(token_text: str) -> Citation:
+    """One citation from one token's text. Never raises.
+
+    Unparseable tokens — including the reserved `bd:calc(...)` derivation form,
+    which is recognized but unsupported in v0 — come back with status
+    `malformed` and the reason in `error`.
+    """
+    try:
+        parse(token_text)
+    except (MalformedTokenError, UnsupportedTokenError) as error:
+        return Citation(
+            token=token_text, status=CitationStatus.MALFORMED, error=str(error)
+        )
+    return Citation(token=token_text, status=CitationStatus.UNRESOLVED)
+
+
+def _scan_link(source: str, open_bracket: int) -> tuple[int, int, str, int] | None:
+    """Scan `[text](href)` starting at `open_bracket`.
+
+    Returns `(text_start, text_end, href, link_end)`, or None if this bracket does
+    not open an inline link.
+    """
+    text_start = open_bracket + 1
+    text_end = _scan_balanced(source, text_start, "[", "]")
+    if text_end is None:
+        return None
+    if text_end + 1 >= len(source) or source[text_end + 1] != "(":
+        return None
+    href_start = text_end + 2
+    href_end = _scan_balanced(source, href_start, "(", ")")
+    if href_end is None:
+        return None
+    return (text_start, text_end, _clean_href(source[href_start:href_end]), href_end + 1)
+
+
+def _scan_balanced(source: str, start: int, opener: str, closer: str) -> int | None:
+    """Index of the `closer` matching an already-consumed `opener`, or None."""
+    depth = 1
+    index = start
+    length = len(source)
+    while index < length:
+        character = source[index]
+        if character == "\\":
+            index += 2
+            continue
+        if character == opener:
+            depth += 1
+        elif character == closer:
+            depth -= 1
+            if depth == 0:
+                return index
+        index += 1
+    return None
+
+
+def _clean_href(raw: str) -> str:
+    """The href as written, minus markdown's decorations.
+
+    NOTE: only a trailing quoted link title (`[x](bd:... "why")`) and enclosing
+    angle brackets are removed. Interior whitespace is kept, because the reserved
+    `bd:calc(...)` form contains it and a citation must be reported verbatim.
+    """
+    href = raw.strip()
+    if href.startswith("<") and href.endswith(">"):
+        href = href[1:-1].strip()
+    return _LINK_TITLE.sub("", href).strip()