Query the record instead of reading it.

The record becomes queryable

Rulings, laws, experiments, handoffs, artifacts, phenomena and decisions are parsed out of a repo's own markdown into SQLite with an FTS5 index over it. Every row carries the file, the line, a human anchor to cite, and a locator string findable in the source.

Conventions are declared, not guessed

Which files carry rulings, which header forms open one, what the verdict vocabulary is, which corpora exist — a repo states all of it. There is no "if the repo did not say, use the first repo's value" branch anywhere in conventions.py, on purpose: that branch ships one repo's history as every other repo's silent default.

Every vocabulary reports what it dropped

An empty table and a table that silently discarded six artifacts are indistinguishable at the call site, and only one of them is correct. Each vocabulary declares a probe defining its population, and counts the inputs inside it that matched no entry — reported, never gating.

A repo declares its meaning — in full

Every one of the 52 fields is required. Absence is an error that names the field and is raised at load time, rather than surfacing as an empty table six steps later. A repo states its own meaning; it never inherits another repo's history by omission.

The tool supplies the mechanism

Parsing, ranking, determinism, the verify legs. Nobody adopting this has evidence to tune BM25 with, and inviting them to turn knobs they cannot evaluate is worse than a default.

Every tuning value carries its calibration

bm25(8.0, 1.0), 400 candidates, 3 phrase slots — each annotated at the site with the corpus and month it was fit on. That is the difference between a default and a number somebody once measured somewhere: a reader who wants to know whether 400 means anything for their record can see that it does not yet.

Arc is identity; experiment is grouping

The schema says both rather than picking one, because keying on the E-number alone collides on seven primary keys against a real corpus where one experiment ran two ruling series. That collision was measured before it was ruled on, and the extraction halted until it was.

1 — Determinism

Two builds from an unchanged record, compared byte for byte, with a pre-registered .dump-identity fallback for the case where SQLite's own file header defeats byte equality. The transcript names which leg held.

2 — Counts against the record's own numbering

Declared count checks grep the markdown and compare against the database; declared sequences report gaps in a numbered range. A record carrying more than a declared bound prints a completeness note — the bound stays as declared rather than silently widening.

3 — Zero dangling pointers

Every row in all seven tables plus the FTS index must name a file that exists and a locator string that occurs inside it. This is the leg that catches a pointer the tool invented.

4 — The seeded question set

A set of questions declared by the repo, each with the file and anchor that should answer it. The gate is that the target lands within the top N; a miss prints what came back instead.

The certificate is written by the same verb

build_and_certify builds, verifies in-process, and writes the certificate from that verify's own transcript and exit code. There is no path that writes a database without writing a certificate for it — because build and verify as separate verbs let a fresh database sit beside a stale certificate indefinitely, reading as verified.

Staleness warns; it does not refuse

The certificate carries the index's size and digest and a per-file manifest of the corpus, so a certificate found beside a different index is detected rather than trusted. A corpus that has moved since the build reports STALE and keeps serving, because bounded staleness is the normal state of a fresh clone.

The adapter a consuming repo writes

import record_index
from record_index import cli as _cli

BINDING = record_index.bind(__file__)
globals().update(BINDING.exports())


def main(argv=None):
    return _cli.run_contract(
        lambda a: _cli.main(BINDING, a), argv,
        db_env=BINDING.conv.db_env)

The exit-code contract it runs under

0  ok
1  the operator's invocation was wrong
2  the tool broke on something it did
   not expect
3  declared and DELIBERATELY UNUSED —
   no verb has a partial-completion
   path, and a code is not populated
   by inventing a path for it
4  the tool ran correctly and is
   telling you not to proceed