Markdown for LLMs

Arxo normative change set 0.1

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

# Arxo normative change set 0.1

A normative change as an object for the Arxo Change Protocol: pairs of states of packages or case releases (before/after), the dependency world, the commencement regime, the declared intent, and the producer artifacts a change dossier is assembled from. Host-level composition over existing producer runs (impact, impact-editions, goals, comparison, measure); it carries no semantics and is not executed. The same schema reads a reform over corpus packages and a change package of a case project.

## Versions

Accepted `schemaVersion`: `law.change-set/0.1`.

## Top-level fields

| name | type-or-$ref | required | description |
|---|---|---|---|
| `schemaVersion` | `"law.change-set/0.1"` | yes | — |
| `id` | `string` | yes | Stable identifier of the change set (URN). |
| `kind` | enum (3) | yes | draft-amendment: pinned edition against a draft model; edition-change: two dated editions of the same act; case-release: two releases of a case package (change package of a project). |
| `title` | [`#/$defs/LocalizedText`](#localizedtext) | yes | — |
| `jurisdiction` | `string` | no | — |
| `legalStatus` | [`#/$defs/LegalStatus`](#legalstatus) | yes | Legal status of the AFTER state, not of the model: a draft is not law. |
| `units` | `array` | yes | — |
| `world` | [`#/$defs/World`](#world) | yes | — |
| `commencement` | [`#/$defs/Commencement`](#commencement) | no | — |
| `intent` | [`#/$defs/Intent`](#intent) | no | — |
| `goalsDeclared` | `array` | no | Goals evaluated on both sides, by StableId. |
| `producers` | `array` | yes | Artifacts of existing tools the dossier is assembled from. The dossier builder reads them and never re-executes anything. |
| `composition` | [`#/$defs/Composition`](#composition) | no | — |
| `coverageProfile` | [`#/$defs/CoverageProfile`](#coverageprofile) | no | — |
| `readings` | [`#/$defs/Readings`](#readings) | no | — |
| `objections` | `array` | no | — |
| `notes` | `array` | no | — |

## Enumerations

| location | values |
|---|---|
| `properties/schemaVersion` | `"law.change-set/0.1"` |
| `properties/kind` | `"draft-amendment"`, `"edition-change"`, `"case-release"` |
| `$defs/LegalStatus` | `"draft"`, `"adopted"`, `"in-force"`, `"superseded"` |
| `$defs/StateKind` | `"edition"`, `"draft"`, `"case-release"` |
| `$defs/ChangeUnit/properties/subject` | `"package"`, `"case"` |
| `$defs/Intent/properties/protectedScope/items/properties/kind` | `"predicate"`, `"subject"`, `"stage"`, `"article"` |
| `$defs/ObjectionClass` | `"expert"`, `"approved-criterion"`, `"binding-decision"` |
| `$defs/Objection/properties/status` | `"open"`, `"accepted"`, `"rejected"`, `"superseded"` |
| `$defs/ProducerTool` | `"impact"`, `"impact-editions"`, `"goals"`, `"differential"`, `"measure"`, `"population-impact"`, `"sources"`, `"scenarios"`, `"package-info"`, `"lockfile"`, `"institutional-dependencies"`, `"delivery-channels"`, `"computations-index"`, `"bank-health"`, `"other"` |
| `$defs/ProducerRole` | `"root"`, `"consumer"`, `"step"`, `"end-to-end"`, `"reading"`, `"objections"` |

## Raw schema

[`https://law.arxo.io/schema/change-set.schema.json`](https://law.arxo.io/schema/change-set.schema.json)

## `Digest`

Type: `string`.

## `Date`

Type: `string`.

## `LocalizedText`

Language tag → text.

Type: `object`.

## `LegalStatus`

Values: `"draft"`, `"adopted"`, `"in-force"`, `"superseded"`.

## `StateKind`

Values: `"edition"`, `"draft"`, `"case-release"`.

## `SourceRef`

A pinned publication or document: bytes named by hash.

Type: `object`.
Required: `file`, `sha256`.

| name | type-or-$ref | description |
|---|---|---|
| `file` | `string` | — |
| `label` | `string` | — |
| `url` | `string` | — |
| `sha256` | `string` | — |
| `sizeBytes` | `integer` | — |

## `State`

One side of a unit: a dated edition of a package, a draft model over it, or a case release.

Type: `object`.
Required: `kind`, `label`.

| name | type-or-$ref | description |
|---|---|---|
| `kind` | [`#/$defs/StateKind`](#statekind) | — |
| `label` | `string` | — |
| `edition` | `string` | Edition identifier inside the package (e.g. TAX_CODE_2025). |
| `editionDate` | [`#/$defs/Date`](#date) | — |
| `programHash` | [`#/$defs/Digest`](#digest) | programHash of the executed program, as recorded by the producer. |
| `artifactHash` | [`#/$defs/Digest`](#digest) | artifactHash of the committed CLIR file, when the state is a corpus package. |
| `lockfileHash` | [`#/$defs/Digest`](#digest) | — |
| `sources` | `array` | — |
| `draftUnits` | `array` | Draft files applied over the base package (kind = draft). |
| `caseRelease` | `string` | Release label of the case package (kind = case-release). |

## `ChangeUnit`

Type: `object`.
Required: `subject`, `before`, `after`.

| name | type-or-$ref | description |
|---|---|---|
| `subject` | enum (2) | — |
| `package` | `string` | Package name (subject = package) or case package name (subject = case). |
| `before` | [`#/$defs/State`](#state) | — |
| `after` | [`#/$defs/State`](#state) | — |

## `PackageRef`

Type: `object`.
Required: `name`, `version`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | `string` | — |
| `version` | `string` | — |
| `contentHash` | [`#/$defs/Digest`](#digest) | — |

## `World`

Dependency world of the change: the import closure of the root. Anything outside the closure is outside the dossier by construction.

Type: `object`.
Required: `closure`, `boundary`.

| name | type-or-$ref | description |
|---|---|---|
| `root` | `string` | — |
| `closure` | `array` | — |
| `lockfileHash` | [`#/$defs/Digest`](#digest) | — |
| `resolutionHash` | [`#/$defs/Digest`](#digest) | — |
| `boundary` | `string` | Human-readable statement of what the world does not contain. |

## `Commencement`

Transition regime as read from the act: general date and closed exceptions. Transitional provisions themselves are rules of the package, not host logic.

Type: `object`.
Required: `general`.

| name | type-or-$ref | description |
|---|---|---|
| `general` | [`#/$defs/Date`](#date) | — |
| `exceptions` | `array` | — |
| `readingDecision` | `string` | Decision that fixed the reading of the dates and its status. |

## `Outcome`

Scenario outcome as printed by impact (NEITHER, TRUE_ONLY, FALSE_ONLY, BOTH, or a calc outcome).

Type: `string`.

## `Intent`

Declared boundary of the reform: expected outcome changes, goals that must hold, and the area that must not change. Absent in a dossier built without a declaration; then every observed difference is classified observed, never expected.

Type: `object`.
Required: `expectedChanges`, `protectedGoals`, `protectedScope`.

| name | type-or-$ref | description |
|---|---|---|
| `declaredBy` | `string` | — |
| `declaredOn` | [`#/$defs/Date`](#date) | — |
| `expectedChanges` | `array` | — |
| `protectedGoals` | `array` | — |
| `protectedScope` | `array` | — |

## `Readings`

Two readings of the same source: the adopted one (the AFTER state of the units) and an alternative built from the same draft; the producer is an impact report between the two AFTER worlds, and the dossier names the scenario classes on which they diverge.

Type: `object`.
Required: `adopted`, `alternative`, `producer`.

| name | type-or-$ref | description |
|---|---|---|
| `adopted` | `string` | — |
| `alternative` | `string` | — |
| `basis` | `string` | — |
| `producer` | `string` | Path of the impact artifact adopted → alternative, as listed in producers (role reading). |
| `objectionsProducer` | `string` | Path of the impact artifact adopted → alternative over the objection scenarios only. |

## `ObjectionClass`

expert: a scenario by an expert or a party, no legal force; approved-criterion: adopted by the owner of the formalization as a check; binding-decision: grounded in a court decision or an official clarification. Entering the bank gives a scenario no legal force.

Values: `"expert"`, `"approved-criterion"`, `"binding-decision"`.

## `Objection`

Type: `object`.
Required: `id`, `scenario`, `class`, `claim`, `source`, `filedOn`, `status`, `history`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | `string` | — |
| `scenario` | `string` | Scenario name in the objections bank (file stem--NNN). |
| `class` | [`#/$defs/ObjectionClass`](#objectionclass) | — |
| `claim` | `string` | — |
| `source` | `string` | — |
| `filedOn` | [`#/$defs/Date`](#date) | — |
| `status` | enum (4) | — |
| `history` | `array` | — |

## `ProducerTool`

Values: `"impact"`, `"impact-editions"`, `"goals"`, `"differential"`, `"measure"`, `"population-impact"`, `"sources"`, `"scenarios"`, `"package-info"`, `"lockfile"`, `"institutional-dependencies"`, `"delivery-channels"`, `"computations-index"`, `"bank-health"`, `"other"`.

## `ProducerRole`

root: the report about the changed package itself; consumer: the same pair re-run over a package that imports it (section 8); step / end-to-end: legs of a composition of successive changes (section 3, composition).

Values: `"root"`, `"consumer"`, `"step"`, `"end-to-end"`, `"reading"`, `"objections"`.

## `CompositionLeg`

Type: `object`.
Required: `label`, `from`, `to`, `producer`.

| name | type-or-$ref | description |
|---|---|---|
| `label` | `string` | — |
| `from` | [`#/$defs/Date`](#date) | — |
| `to` | [`#/$defs/Date`](#date) | — |
| `producer` | `string` | Path of the impact-editions artifact of this leg, as listed in producers. |

## `Composition`

A chain of successive changes of the same root: every step and the end-to-end pair are separate producers; the dossier reports transient changes (present in a step, absent end-to-end) and interactions.

Type: `object`.
Required: `steps`, `endToEnd`.

| name | type-or-$ref | description |
|---|---|---|
| `steps` | `array` | — |
| `endToEnd` | [`#/$defs/CompositionLeg`](#compositionleg) | — |

## `CoverageAxis`

Type: `object`.
Required: `name`, `predicate`, `argIndex`, `values`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | `string` | — |
| `predicate` | `string` | Local name of the case-input predicate that fixes this axis. |
| `argIndex` | `integer` | — |
| `values` | `array` | — |
| `cap` | `integer` | Integer axes: values at or above this bound fold into the last declared value. |

## `CoverageProfile`

Finite product of axes read from the scenario bank: which cells of the product at least one scenario fixes. A coverage statement about the bank, not a legal answer.

Type: `object`.
Required: `axes`.

| name | type-or-$ref | description |
|---|---|---|
| `axes` | `array` | — |
| `note` | `string` | — |

## `Producer`

Type: `object`.
Required: `tool`, `path`, `sha256`.

| name | type-or-$ref | description |
|---|---|---|
| `tool` | [`#/$defs/ProducerTool`](#producertool) | — |
| `path` | `string` | Path of the artifact relative to the repository root. |
| `sha256` | [`#/$defs/Digest`](#digest) | sha256 of the artifact bytes as read by the builder. |
| `schemaVersion` | `string` | — |
| `role` | [`#/$defs/ProducerRole`](#producerrole) | — |
| `package` | `string` | For role = consumer: the importing package the artifact is about. |
| `concat` | `array` | Packages added to the world beyond the import closure, as the package's own test families do (`concat` in law.toml): a replay, not a dependency world. |
| `label` | `string` | — |
| `note` | `string` | — |