Markdown for LLMs

Arxo registry publication descriptor 0.2

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

# Arxo registry publication descriptor 0.2

Descriptor of a RELEASE in the registry. The previous record `p/<name>/<version>.json` carried only a locked package and said nothing about what the release pulls in: a graph edge could be learned only by downloading the whole compiled file. Here dependencies and required resources are declared, so the graph and pin conflicts are visible BEFORE downloading. This is the publication contract, not the source of lockfile fields: only a subset flows into the closed locked-package form of the lockfile, and `dependencies`/`resources`/`languageSemantics` are not carried over there.

## Versions

Accepted `descriptorFormat`: `law.package-descriptor/0.2`.

## Top-level fields

| name | type-or-$ref | required | description |
|---|---|---|---|
| `descriptorFormat` | `"law.package-descriptor/0.2"` | yes | Format version. Its absence means an old registry record (specVersion 0.1): it can still be read, but the new add/install/update orchestration rejects it because it does not declare exact dependencies. |
| `name` | [`#/$defs/PackageName`](#packagename) | yes | — |
| `version` | [`#/$defs/Version`](#version) | yes | — |
| `namespace` | `string` | yes | — |
| `contentHash` | [`#/$defs/Sha256`](#sha256) | yes | sha256 of the canonical compiled (CLIR) bytes. Deliberately narrower than the general digest form: the bytes can only be checked with the algorithm they were computed with. |
| `worldHash` | [`#/$defs/Sha256`](#sha256) | no | Optional sha256 of the canonical bytes of the linked world of this release (root plus its pinned closure), published as p/<name>/<version>/world.lawir.json. The world is built by the engine link step only; SDKs verify these bytes and execute them, they never link. Absent on releases published before the field existed. |
| `editorSourceMapHash` | [`#/$defs/Sha256`](#sha256) | no | Optional sha256 of the raw editor source-map sidecar. A resolver copies it to the locked package, so the resolution hash covers the authored-location pin without changing the CLIR. |
| `questionCatalogHash` | [`#/$defs/Sha256`](#sha256) | no | Optional sha256 of the published questions catalog sidecar, installed as deps/<package>.questions.json from the immutable registry version. It does not affect CLIR or evaluation semantics. |
| `taskGuideCatalogHash` | [`#/$defs/Sha256`](#sha256) | no | Optional sha256 of the published task-guides catalog sidecar, installed as deps/<package>.task-guides.json from the immutable registry version. Task guides are metadata: they do not affect CLIR or evaluation semantics. |
| `signature` | `object` | no | Ed25519 signature over the canonical locked-package projection excluding the signature, domain-separated by application/vnd.arxo.locked-package+json. |
| `registryId` | [`#/$defs/RegistryId`](#registryid) | yes | — |
| `resolverUri` | `string` | yes | Identity of the release, not a URL. The registry address lives in the consumer's settings and changes with the mirror; identity does not. |
| `features` | `array` | yes | — |
| `languageSemantics` | `string` | no | Semantics line of the release. A linked world is assembled from packages of ONE line; incompatibility is detected while preparing the operation, not by editing the semanticVersion of a downloaded file. |
| `dependencies` | `array` | yes | EXACT direct dependencies of the release. Must match the actual `imports` of the published CLIR — this is checked after download, because the descriptor is the publisher's promise, and it is proved by the bytes. |
| `resources` | `array` | no | Required resources of the release, delivered as a blob keyed by contentHash. The first release supports only calendar datasets; an unknown kind is rejected rather than being placed "somewhere". |

## Enumerations

| location | values |
|---|---|
| `properties/descriptorFormat` | `"law.package-descriptor/0.2"` |
| `properties/signature/properties/algorithm` | `"ed25519"` |
| `$defs/DescriptorResource/properties/kind` | `"calendar-dataset"` |
| `$defs/DescriptorResource/properties/capability` | `"law.calendar/0.1"` |
| `$defs/PackageVersions/properties/format` | `"law.package-versions/0.1"` |

## Raw schema

[`https://law.arxo.io/schema/package-descriptor.schema.json`](https://law.arxo.io/schema/package-descriptor.schema.json)

## `PackageName`

Type: `string`.

## `Version`

Type: `string`.

## `Sha256`

Type: `string`.

## `RegistryId`

Type: `string`.

## `DescriptorDependency`

Type: `object`.
Required: `name`, `version`, `namespace`, `registryId`, `contentHash`.

| name | type-or-$ref | description |
|---|---|---|
| `name` | [`#/$defs/PackageName`](#packagename) | — |
| `version` | [`#/$defs/Version`](#version) | — |
| `namespace` | `string` | — |
| `registryId` | [`#/$defs/RegistryId`](#registryid) | — |
| `contentHash` | [`#/$defs/Sha256`](#sha256) | — |

## `DescriptorResource`

Type: `object`.
Required: `id`, `kind`, `capability`, `contentHash`, `file`.

| name | type-or-$ref | description |
|---|---|---|
| `id` | `string` | Logical resource identifier — the same one as the calendar snapshot node and the law.lock entry. Two incompatible datasets under one id are a rejection citing both sources. |
| `kind` | `"calendar-dataset"` | — |
| `capability` | `"law.calendar/0.1"` | — |
| `contentHash` | [`#/$defs/Sha256`](#sha256) | — |
| `file` | `string` | File name as A SINGLE segment: the in-project address is built by the consumer (resources/calendars/<package>/<file>). The publisher's path does not become a requirement on the user's machine. |

## `PackageVersions`

Index `p/<name>/versions.json`: without it the remote registry cannot name the latest stable version, and `add NAME` without a version would be unrunnable.

Type: `object`.
Required: `format`, `name`, `versions`.

| name | type-or-$ref | description |
|---|---|---|
| `format` | `"law.package-versions/0.1"` | — |
| `name` | [`#/$defs/PackageName`](#packagename) | — |
| `versions` | `array` | — |