Pin the edition

ActionsArtifactVerification

Task and place

Pinning turns acquired bytes into a verifiable source base. The formalization declares what the bytes are, which reading they represent, and which extracts it relies on; the tool then re-verifies that bond on every check. Acquisition preserves the bytes, pinning makes the claim about them checkable, and only then can inventory read them with confidence.

Inputs

• The preserved bytes and the source card from acquisition.
• A chosen fragment granularity: whole articles, headed extracts with locators, or both.
• The honesty label decided at acquisition, carried over unchanged.

Actions

• Declare the act itself: its kind, jurisdiction, and number.
• Declare the edition: a dated reading of the act in one language, with the materialization claim stating what is presented alongside.
• Declare the publication: the concrete bytes, with media type, origin address, retrieval moment, a hash of the whole document, and the local file inside the package.
• Declare one fragment per relied-upon extract: kind, locator, exact text, and its own hash.
• Keep local files inside the package directory. The source is part of the package, not a link into whatever machine the package happens to land on.
• When several language versions exist, pin each as its own edition and record which one the rules were read from.
• Link each extract to the original: the fragment text must occur byte-for-byte in the pinned document, without normalization.

Decisions

• Which materialization status the edition claims. The claim obliges: a pinned copy stays labeled as a copy, and the checks below hold the formalizer to the label.
• How coarse or fine fragments are. Coarse fragments are cheap and vague; fine fragments pin exactly what each rule relies on.

Artifact

The artifact is a verifiable source base: declarations plus local files plus hashes, in a state where the tool re-checks the whole bond. The running example pins its edition under the literal label PINNED_UNOFFICIAL_COPY. Non-runnable excerpt, showing the shape of the edition and publication declarations:

Arxo Law

edition EAI_EDITION of EAI_LAW_30 {
    language ru-KZ; officiality official; adopted @2005-02-07;
    materialization_status PINNED_UNOFFICIAL_COPY;
}
publication EAI_RU_TEXT of EAI_EDITION {
    media_type "text/plain; charset=utf-8";
    retrieved_at @2026-09-13T13:00:00+03:00;
    content_hash "sha256:4cd311a9a3316f3255992116108755f2073aaaaf12b3d41e3c7a1c598c2d3cdb";
    local_path "sources/employee-accident-insurance/ru.txt";
}

One of its four fragments, likewise a non-runnable excerpt:

Arxo Law

fragment EAI_ART17 in EAI_EDITION {
    kind article; locator "article/17";
    content_hash "sha256:e2cfec0fd003d70724d68b09f22314604080cb00deada3b246b050882c6f7f36";
}

Worked example

The example edition pins the full-document hash shown above; its four fragments carry locators and short heading texts that occur in the document. All runs below were observed with tool version law 0.1.0 and semantics law.core/0.2. Two runs name a local build explicitly: the published 0.1.0 has no gen command, so the pinning check below comes from the local 0.1.0 whose version line is quoted first.

Output

law 0.1.0
семантика: law.core/0.2
std для языка 0.2: 0.2.0
хэш бинаря: sha256:78dea06ce928547e87bd9875a2556cc663def37cbb78c8b04aa0da57839c95d7

[translation] The output reads: law 0.1.0, semantics law.core/0.2, std for language 0.2 is 0.2.0, binary hash sha256:78de…c95d7. This is the local 0.1.0 build, not the published one pinned in the bundle (binary hash sha256:c56e…210d) — the Russian output language is the visible tell.

The recomputed hash of the local text equals the pinned document hash:

Output

4cd311a9a3316f3255992116108755f2073aaaaf12b3d41e3c7a1c598c2d3cdb  corpus/laws/kz/laws/employee-accident-insurance/sources/employee-accident-insurance/ru.txt

The pinning check passes silently on the local build named above (the published build has no gen command, so bundle readers verify the fragment hashes through the package check instead), and the package check confirms the bond:

Output

$ law gen pinning corpus/laws/kz/laws/employee-accident-insurance --check; echo "exit=$?"
exit=0

Output

check OK: corpus/laws/kz/laws/employee-accident-insurance

From provision to check: the article 19 chain

Pinning the document is the start of a chain, not its end. The reference dossier continues provision by provision: source passage → inventory unit → decision → rule → check. The employer branch of article 19 — the finding EAI-R1 closed in the candidate — is the worked chain, quoted here in full because it is the page’s answer to “where exactly did this number come from”:

1. Provision. Article 19, paragraph 1, line 363 of the pinned bytes (sources/employee-accident-insurance/ru.txt, document hash sha256:4cd3…d3cdb as recomputed above): «Возмещение вреда … при установлении ему степени утраты профессиональной трудоспособности от пяти до двадцати девяти процентов включительно, осуществляется страхователем согласно трудовому законодательству Республики Казахстан.» [translation] Harm connected with established capacity loss from five through twenty-nine percent inclusive is reimbursed by the policyholder under labour legislation.
2. Inventory unit. The current inventory splits the article instead of filing it whole (as did v2 before it): the row “Article 19.1, line 363” names the employer reimbursement branch for loss five through twenty-nine as its own content unit with fate “formalize”, while the neighboring rows exclude the Civil Code reference, the caps, the annuity mechanics, and paragraphs 2–6 by name.
3. Decision. The semantic review records the missing branch as finding EAI-R1 and closes it by adding the branch — the review row, not a silent edit.
4. Rule. Candidate file 02-r1-fix.law carries LowLossEmployerReimburses: loss percent between 5 and 29 inclusive derives low_loss_employer_reimbursement_due, with a rule label restating the article, paragraph, and range.
5. Checks. tests/r1.lawtest pins both sides of the branch: loss twenty reimburses, loss four stays silent.

One honest limit: the fragment EAI_ART19 pins only the article heading, so the line-363 link above lives in the inventory row and the rule label — quoted text with a line number — not in a fragment hash. A finer fragment per relied-upon paragraph would move that link into hashed text; that refinement is open, and until it lands the chain’s first step is a quotation, not a checksum.

Pitfall

The expensive failure is claiming official bytes over a downloaded copy: the checks turn green and the system starts asserting about the source what nobody answers for, convincingly, with hashes. The cheap failure is editing a fragment text without updating its hash, which the tool refuses with LDC-E5201. A close cousin is confusing the two hashes: the publication hash covers the whole document, each fragment hash covers only its extract.

Verification

The stage is done when each of the following holds:

• The recomputed document hash equals the pinned publication hash.
• The pinning check exits clean, and the package check passes with the fragments in place.
• Every fragment of a pinned edition carries its own hash, and each fragment text occurs in the pinned document.

Limits

Pinning proves that the extracts come from the presented bytes, not that those bytes are the authentic official publication. A pinned unofficial copy stays one; the edition label says so, and no green check upgrades it.

Next step

Continue with Inventory the act, which reads the pinned bytes article by article before any rule is written.

Sources

• Reconciliation with the pinned edition — the four checks and what each of them claims.
• Source and anchor — addresses in the act versus links to its bytes.