Corpus guide: what lives here

The corpus is the collection of packages kept in the repository. A package is a versioned folder of source files with a manifest. Some packages formalize an act, some hold a shared vocabulary, some are supporting libraries. A case package holds one worked example: the facts of a case and the results expected from them.

Every package records the exact versions of the packages it uses. This topic calls that record a pin. The package together with everything it uses, at those exact versions, is its world: the complete set of packages that answers a question. Because the world is fixed, the same question gives the same answer on every machine.

What you will do here

This topic shows how to organize packages in the corpus, how to keep their text tied to the official sources, how to measure and review coverage, how to release and upgrade packages, and how several authors work in one tree without disturbing each other.

Choose a route

• Understand the architecture. Read Packages, cases, and worlds first, then continue down the reading order.

• Walk through an example. The lab tour runs five small fictional packages end to end, with every command and its recorded output. The worked solutions keep the full transcripts.

• Solve a specific task. Go straight to the page for it:

  • add or update a dependency — Dependencies, locks, and registries;
  • tie package text to an official source — Pinning source text;
  • follow a new edition of an act — Editions and updates;
  • measure how much of an act is formalized — Coverage: measure, depth, clauses;
  • see what a change breaks — Change impact and dossiers;
  • publish a release — Publishing a release;
  • find a package or a predicate — Catalogs and discovery;
  • pick the right check run in a shared tree — Team workflow: conventions and check profiles.

  Readers who learn by doing can also start with the hands-on A package in the corpus and return here for the map.

What each route needs

• Public release: the installed law 0.1.1 binary and the lab bundle. This covers the lab tour and most commands on these pages.
• Source checkout: the repository’s ./law launcher. Only four commands need it — gen, query, answers, and ingest; the public binary answers each with unknown command.

The exact toolchain behind every transcript is listed under Reproduction details at the end of this page.

Reading order

Start here: index and architecture

• Packages, cases, and worlds — the three nouns that carry the architecture, and the manifest-to-lock-to-link pipeline.
• Package boundaries: what the corpus answers — the import surface and the questions the corpus cannot answer.
• Dependencies, locks, and registries — exact pins, lockfiles, directory registries, and offline transfer.
• Team workflow: conventions and check profiles — explicit imports, per-package repair, and which check run to use when.

Vocabulary

• Modeling vocabulary: entities, relations, enums, constants
• Local and shared vocabulary
• Vocabulary contracts: kinds, keys, and templates
• Stable identity
• Languages: labels, forms, and editions
• Bridges between vocabularies
• Vocabulary migrations
• Audit surface: relations, functions, questions, lints

Sources and quality

• Pinning source text
• Editions and updates
• Coverage: measure, depth, clauses
• Reviews, approvals, and records

Changes, releases, import, alignment, discovery

• Change impact and dossiers
• Compatibility: versions and language lines
• Publishing a release
• Upgrades and replay
• Importing external knowledge
• Alignment and concept bridges
• Catalogs and discovery

The lab

The lab is a fictional parcel-registry domain used for runnable examples that must never be mistaken for real law. Its fixtures are cited by package id throughout this topic: labparcels.iface (shared vocabulary, no rules), labparcels.registry (the fictional source act plus rules), labparcels.fees and labparcels.appeals (consumers of the registry world), and labparcels.case1 (the worked case over the locked world). Two further lab fixtures carry the worked examples on the import and impact pages. The guided tour runs these fixtures end to end, and the worked solutions record every command with its output; the lab templates ship blank beside filled on the same fixtures; the exercises in A package in the corpus cover the same moves on a real package.

Where this topic reuses existing guides

The corpus topic summarizes and links; it does not fork. The pages below remain the primary reference for their subjects:

• Packages and cases — the command surface for packages and cases.
• Several packages and a world — the world idea, worked by hand.
• A package in the corpus — manifest, scenarios, provenance, and checks for one package.
• N. Package, context, snapshots, case, result, and test — the full case-work recipe book.
• Package passports — the published identity card of a package.
• Versions — version grammar and selection rules.
• Schema catalog — one page per format, generated from the schema sources.

How this topic marks confidence

Pages in this topic tag capabilities with a short letter. The words are the primary meaning; the letter is a compact mark for the same thing.

Mark	In words	What it tells you
S	Available in the public release	The command or behaviour ships in the installed law release.
I	Requires a source checkout	Internal tooling: only the repository’s ./law launcher has it.
X	Experimental	An experimental profile; it may change.
O	Schema only	The format is published as a schema.
T	Team convention	A rule the team keeps; the tools do not enforce it.
U	Unconfirmed	The guide promises nothing about the item.
G	Full-profile CI check	The full-profile continuous-integration run checks it.

The letters mix several properties — availability, maturity, team convention, and which check covers an item — so they are not a confidence scale: S is not “more certain” than T. Absence of a mark is never a promise either.

Conventions used across these pages

• Fixtures are cited by package id, never by location.
• Fenced commands were run; fenced outputs are verbatim results.
• Anything marked unconfirmed, or not marked at all, is something these pages deliberately refuse to promise.

Reproduction details

Toolchain, hashes, and full transcripts

Pinned toolchain. These pages run on two routes. The public route is the installed law-v0.1.1 release against the lab bundle; the checkout route is the repository’s ./law launcher for the tools the public composition omits. Every fenced command was run on the route its section names, and every fenced output is verbatim. The public toolchain behind the tour:

Output

$ law version
law 0.1.1
semantics: law.core/0.2
std for language 0.2: 0.2.0
lawql: lawql/1 (queryResult 0.1)
binary hash: sha256:cfa7c17232f2dc594e665dbbf2ad3c154675797ef4be07ef7d758c9abfb80a28

(macOS arm64; Linux x64 reports sha256:be8b4fbbaac81a58e2e70ad5f9e1c9d5a3b0e7d6dd16209d30221f13b34e9c4d.) The release archives live at https://github.com/arxohq/law-releases/releases/tag/law-v0.1.1; the bundle’s PINNED.md repeats the archive and binary hashes.

Build warnings on the error stream are omitted from fenced output throughout; where output below comes from the error stream or is an excerpt, the fence says so.

Composition boundary. The boundary splits the command surface in two: gen, query, answers, and ingest are absent from the public composition — the installed binary answers each with unknown command — while every other command these pages use ships in it. Marks follow that split on every page: the missing four are I, never S; S covers the public command surface and observed engine behavior. (./law help --json in a checkout reports the same four as internal.) Each transcript below repeats its own law version footer. When two runs disagree, compare the first line for the tool and the last line for the exact bytes — the hash differs per platform.