Package passports

A passport describes an exact release, its interface, sources, dependencies, author limitations, and build results. Separate reports add quality checks, replay compatibility, and performance measurements.

Author description

Next to law.toml you may add package-info.json:

{
  "format": "law.package-info/0.1",
  "purpose": "Учебный расчёт тарифов архива",
  "limitations": ["Право вымышленного города используется для обучения"],
  "examples": ["tests/tariffs.lawtest"]
}

String fields maintainer, license, repository are also allowed. Purpose and limitations are the author’s claims. Name, jurisdiction, and source status stay in the existing law.toml metadata. Do not write numbers into the description. Examples must exist inside the source snapshot and have the .lawtest suffix.

Release and observations

A release is built with the pinned package toolchain: a static law CLI and a standalone package.py, downloaded by version and verified against the SHA-256 in toolchain.lock.json. A published canon repository, such as arxohq/arxo-bgb, ships the lock file and tools/toolchain.py next to its packages; Python 3.12+ is all it needs.

python3 tools/toolchain.py download --lock toolchain.lock.json --out /tmp/law-tools
python3 /tmp/law-tools/package.py packages/<name> \
    --lawc /tmp/law-tools/law-cli --offline --out /tmp/<name>-release

The build compiles the package, runs its scenarios, replays the saved evaluations, rebuilds the release from itself, and writes passport.json into the release directory. A failure of any step stops the build; a release without a passport is not a release.

Quality and compatibility reports and the performance measurement are added later by the registry maintainer, in the repository’s own CI: they read the finished release and store hash-addressed reports next to it without touching its files. The library used for a measurement is named explicitly; build-profile is a claim about how it was built, identity is pinned by hash.

A failed benchmark is stored as a failed report; timeout bounds a single process. Every successful measurement passes the author’s expectations. There are no time thresholds in CI. Quantiles are nearest-rank. Raw times and sizes are stored inside the report, so separate unattached files are not needed.

serialMeasuredCallsPerSecond is the number of sequential measured calls divided by the sum of their FFI wall time. This is not server throughput: checks, request preparation, and stand pauses are not in the denominator. firstObservedCallsMs is the first observed call of the scenario on a shared handle; previous scenarios may already have warmed it. peakProcessRssBytes includes Python and the checker; it does not measure the package’s own allocations. Missing CPU/RAM under environment limits is recorded as null, not zero.

The pilot

The registry’s CI runs a pilot over a fixed set of packages: it builds their releases, attaches the reports, and checks the resulting artefacts before the index is published. The output is a directory with releases/, observations/reports/, and passports.json. The pilot packages and the reasons for choosing them are pinned with the pilot: Dahl’s proverbs, an archive with two dependencies, the Land Code. Scenarios fix the exact suite and testIndex; extraFacts=10/100 variants clone facts about new entities and re-check the original expectations. That is synthetic load of the chosen case, not a promise about the complexity of any query.

Registry and MCP

The passport index is built from the releases and the report store. The index itself does not rewrite releases and does not run checks. A new release moves the passport with it, keeping the version immutable; reports are exported separately as hash-addressed JSON, and their hashes are re-checked on the next index build.

The showcase reads that index. Pages: /passports/, /ru/passports/, and /ru/passports/<name>/<version>/. Passport JSON, full source bytes of reports, sample queries, signatures, dependencies, and sources are available.

MCP uses the same index. law_packages adds passportReleases: addresses of individual releases, which may differ from the current corpus world. The tool law_passport requires name, version, contentHash; sections selects sections, limit and offset page JSON Pointer records. The next field holds continuation arguments. Long strings are split explicitly through stringOffset/stringLength, so information is not lost and page size is bounded. The reports section holds history, including failures.

Updates and compatibility

A new standalone release has build/0.3 and requires a passport. Build/0.1 and build/0.2 continue to be read; files are not added to them after the fact. A build/0.1 release does not support frozen replay.

Changing the author’s description while CLIR stays the same changes sourceHash. A report with a different sourceHash/buildHash/replayHash is not attached to the previous release. A generator change incompatible with the passport format requires a new format version and keeping the old reader.

A successful build confirms only the recorded expectations and checks. A fragment measure is not coverage of the whole statute text. Article-by- article span and rule coverage by tests currently have explicit states not_run/unsupported; they must not be read as 0% or 100%.

The registry’s CI runs the contracts, the pilot, and a UI build on affected changes, and daily stores observations as a CI artefact. A change gets a short smoke measurement; the regular run measures in full. History between CI runs lives in artefacts; merging them into the public registry is a separate export. The workflow does not publish the site.