Markdown for LLMs
Pin the edition
The source Markdown for this article. Copy it into your assistant or download it as a text file.
# Pin the edition
## 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:
```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:
```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.
```text
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:
```text
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:
```text
$ law gen pinning corpus/laws/kz/laws/employee-accident-insurance --check; echo "exit=$?"
exit=0
```
```text
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](/handbook/files/filled/eai-source-inventory-v3.md) splits the article instead of filing it whole (as did [v2](/handbook/files/filled/eai-source-inventory-v2.md) 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](/handbook/inventory/), which reads the pinned bytes article by article before any rule is written.
## Sources
- [Reconciliation with the pinned edition](/tutorials/pinned-edition/) — the four checks and what each of them claims.
- [Source and anchor](/tutorials/real-article-source/) — addresses in the act versus links to its bytes.