docs← Back to article

Markdown for LLMs

Editions and updates

The source Markdown for this article. Copy it into your assistant or download it as a text file.

Download this articlePlain text ↗
# Editions and updates

A package never quotes "the law" in the abstract. It quotes a specific
revision of a specific act in a specific language, taken from specific
bytes — and it records how that revision changes over time. This page
describes the model for those records and the checks that keep
them accurate.

Environment: the commands on this page are **available in the public
release** (**S**), except the `./law engine --help` listing from a source
checkout; the consolidation example reads the lab fixture
`fixtures/consolidation-mini/edition.law`. Marks follow the
[topic legend](/corpus/#how-this-topic-marks-confidence).

## Source, edition, publication, fragment

Four levels identify quoted text (**S**, compiler-enforced):

- **source** — the Work: the act as an abstract norm-giver
  ("the constitution", "the parcel registry rules");
- **edition** — the Expression: one language plus one revision;
- **publication** — the Manifestation: the concrete bytes the text
  was taken from, content-hashed;
- **fragment** — the article-level pinned text with its language and
  status.

The central rule: **one revision in two languages is two
editions**, linked by a correspondence declaration that is metadata
only. No shared meaning is assumed between language versions; each
edition stands on its own bytes, and any claim that two editions say
the same thing must be written down explicitly to be inspected.

The companion [pinning page](/corpus/sources/pinning/) explains how fragments are pinned to bytes.

## Materialization and timeless texts

Every source record carries a materialization status (**S**): pinned
states for texts backed by local bytes, plus `dynamic`, `abstract`,
and `unavailable` for texts that cannot or should not be pinned. The
stricter canon profiles require pinned states before a package may
enter them.

Scripture and doctrine use a `timeless` applicability marker instead
of a legal lifetime; mixing timeless texts with lifecycle events is
rejected with a diagnostic (`LDC-E5308`).

## `law amend` repairs code, not law

This heading states the single most confused name in the toolchain,
so it is said once, prominently: the amendment search in the engine is
a minimal **code-repair** search over scenarios. It proposes small
edits that make failing scenarios pass. It knows nothing about legal
amendments, revision operations, or consolidation.

The name does not even exist at the top level of the user command
line. This transcript is real:

```console
$ law amend
law: unknown command amend
```

The repair search lives one level down in the checkout composition,
takes compiled input plus scenarios, and is budgeted explicitly:

```console
$ ./law engine --help
...
amend <ir.json> (--target <file>… | --goals <goals.lawtest> --cases <worlds>…) [--scenarios <file-or-dir>…] [--max-edits N] [--budget N] [--apply <file>] [--json]
```

Legal change — a new revision superseding an old one — is expressed
with the edition machinery on this page, never with the repair
search.

## The edition lifetime machine

Whether an edition applies at a given legal date is computed by an
applicability machine (**I**, with a full-profile check **G**).
Editions move on dated events:

- **opening** — `in_force`, `restored`;
- **suspending** — `suspended`;
- **closing** — `repealed`, `expired`, `invalidated` (closing is
  irreversible and takes effect forward in time only);
- **neutral** — `adopted`, `published` (recorded, but they open
  nothing by themselves).

The full-profile check replays these events per edition, including a
compatibility pass over older data that predates the current event
vocabulary.

## Consolidation: four operations

A revision is a committed edge from a previous edition state to a
next one, and every edge must be reproducible: applying the edge's
operations to the previous state must yield the next state exactly
(**G**). The operation vocabulary is closed at exactly four
operations — `replace`, `repeal`, `renumber`, `insert` — and any
change that cannot be expressed with them cannot be committed as a
consolidation edge.

Most of the corpus records consolidation edges as annotations; a
smaller number is executable, meaning the check replays the operations
and compares the result byte for byte.

A three-article worked example ships in the lab fixtures. The
`Prev` edition says five coins in `article/1`, keeps a temporary
clause in `article/2`, and a kept clause in `article/3`; the `Next`
edition says seven coins, drops the temporary clause, renumbers the
kept one to `article/4`, and adds `article/5`:

```law fixture="consolidation-mini/edition.law"
language "law.core" version "0.2";
package lab.consolidation version "0.1.0";
namespace "urn:law:lab:consolidation";
source Charter { kind policy; }
edition Prev of Charter { language en; officiality unofficial; materialization_status ABSTRACT_ONLY; in_force [@2026-01-01, infinity); }
edition Next of Charter { language en; officiality unofficial; materialization_status ABSTRACT_ONLY; in_force [@2026-01-01, infinity); }
fragment Old1 in Prev { kind article; locator "article/1"; text en unofficial """The fee is five coins."""; }
fragment Old2 in Prev { kind article; locator "article/2"; text en unofficial """A temporary clause."""; }
fragment Old3 in Prev { kind article; locator "article/3"; text en unofficial """A kept clause."""; }
fragment New1 in Next { kind article; locator "article/1"; text en unofficial """The fee is seven coins."""; }
fragment New3 in Next { kind article; locator "article/4"; text en unofficial """A kept clause."""; }
fragment New5 in Next { kind article; locator "article/5"; text en unofficial """A new clause."""; }
revision Change { previous Prev; next Next; relation amends; effective @2026-07-01;
 op replace { locator "article/1"; language en; text """The fee is seven coins."""; }
 op repeal { locator "article/2"; }
 op renumber { locator "article/3"; to_locator "article/4"; }
 op insert { locator "article/5"; language en; text """A new clause."""; }
}
```

Lower the fixture, then run the consolidation check over the edge —
it replays the four operations against `Prev` and compares the result
with the declared `Next` texts:

```text
$ law engine lower fixtures/consolidation-mini/edition.law 2>/dev/null > /tmp/lab-work/consolidation/program.json
$ law engine consolidate /tmp/lab-work/consolidation/program.json 'urn:law:lab:consolidation#Change' 2>/dev/null; echo "exit=$?"
article/1 (en)
article/4 (en)
article/5 (en)
exit=0
```

Exit 0 with the three surviving locators means the edge is
reproducible: its operations turn `Prev` into `Next` exactly. The repeal removed
`article/2`, the renumber moved the kept clause to `article/4`, and
the computed texts match `Next` byte for byte — seven coins in
`article/1`, the kept clause, the new clause. (**S** — `law engine`
ships in the public composition; the same replay runs as an
automated check (**G**) where the corpus marks the edge executable.)

The comparison is real, not ceremonial. Rewrite the `replace`
operation as an instruction instead of the resulting text —
`"Replace the word five with seven."` — and the same command
refuses, naming the divergent locator:

```text
$ law engine consolidate /tmp/lab-work/consolidation/bad-program.json 'urn:law:lab:consolidation#Change' 2>&1 | grep LDC
LDC-E5401: edge urn:law:lab:consolidation#Change: applying operations to urn:law:lab:consolidation#Prev does not yield urn:law:lab:consolidation#Next — article/1 (en) diverges; neither the computed consolidation nor the declared one is accepted as true automatically (§32.2)
```

## Divergence between authentic editions

When two language editions are both authentic, neither is the
translation of the other, and their readings can diverge. A
full-profile check (**G**) compares the formalized readings of paired
editions and reports divergence, so that a bilingual act cannot
silently mean one thing in one language and another thing in the
other.

## What the toolchain does not answer yet

The runtime lifecycle of a single norm — "is this norm in force for
this case at this legal time" — needs both a case and a legal time,
and no producer computes it yet (**O**). The schema for that answer
exists and declares its own status as unavailable in the current
tool release. Until a producer lands, lifetime questions are answered
at edition level with the machine above, not at norm level.

## Reproduction details

<details>
<summary>Toolchain, hashes, and full transcripts</summary>

Commands on this page were run against `law 0.1.1`, semantics `law.core/0.2`,
standard library `0.2.0` (full `law version` blocks under [Reproduction details on the pinning page](/corpus/sources/pinning/#reproduction-details)).

</details>

## Further reading

- [A real article: source and anchor](/tutorials/real-article-source/)
- [Sources: source, edition, publication, fragment](/constructs/sources/)
- [Sources and text](/recipes/i-sources/)
- [Pin the act, edition, and publication](/recipes/i-sources/pin-publication/)