# Core schema generation

Edit the four v1 core sources and their named `fragments/` definitions in
`packages/contracts/schemas/src/`. Native v2 public schemas and
`native-execution.v2.schema.json` are also authored in that source directory.
Then run from the workspace root:

```bash
uv run --no-sync python scripts/bundle_schemas.py
uv run --no-sync python scripts/bundle_schemas.py --check
uv run --no-sync python -m pytest tests/schema_bundler
```

Nine generated files are checked in under `src/robotics_runtime_contracts/schemas/`:
four v1 cores, four native v2 public schemas and their shared internal definitions.
Historical v1 wrappers, common definitions and the pre-existing dataset v2 schema
retain their authored locations and bytes. New v2 source/resource inventory and
every generated byte are checked strictly by the assembler.
Source fragments are build inputs, not new public schema resources. Consumers
still load the packaged schemas offline through the existing registry.

The assembler uses the existing [referencing API](https://referencing.readthedocs.io/en/stable/api/)
for URI, anchor and JSON Pointer lookup. Its narrow source format materializes imports at
`$defs` entries; it does not implement reference resolution or flatten arbitrary
schemas. Fragment bodies use final resource IDs, which are shortened to local
fragments only when they refer to the assembled resource itself. Ordinary
references and their sibling constraints remain intact. The Draft 2020-12 resource
walker distinguishes schemas from instance data in `const` and `examples`.

Build-only imports must contain only `$ref` and resolve to schema objects. Nested
resource IDs and dynamic references are outside this source format and fail the
generation check. Source and packaged roots must explicitly declare
`https://json-schema.org/draft/2020-12/schema`; nested `$schema` declarations
are unsupported, even if they repeat that dialect. Instance data in `const` and
`examples` is not subject to these schema-location restrictions.
Unregistered references fail offline. All packaged schemas and every resolved
reference target are metaschema-checked before any generated file is written:
a pointer into a string, array or malformed schema object fails even when the
generated bytes already match. Every object target must also be a known schema
location in the registry, as identified by the Draft 2020-12 walker. Objects
under `const`, `examples`, or other instance-data locations are rejected as
reference targets, even if metaschema-valid or equal to a real schema elsewhere.
This restriction applies to both ordinary references and build-only imports;
it prevents hidden reference chains and scope keywords from escaping the checks.
Ordinary refs may target boolean schemas without this object-location restriction.
Pre-commit checks for stale bytes; CI also requires an empty resource
diff. Output has authored key order, two-space indentation, UTF-8 and LF, with
one trailing newline. An unchanged generation does not rewrite files.

## Historical reproduction before the refactor

The restored sources first reproduced all four cores at workspace commit
`3109ff5af523d371e81a1f45e036fc6f3c73a811` byte for byte: **84,269 bytes**.
`tests/schema_bundler/fixtures/baseline.json.gz` preserves those eight source
files and all 30 original packaged resources, including the catalog, independently
of git history depth. `baseline-manifest.json` records the archive, source and
resource hashes. The historical reproduction test assembles those sources with
the same current bundler and compares every resulting byte with the baseline.

| Core | Historical SHA-256 |
| --- | --- |
| acceptance-result | `a18f42957e58267affeda0c0a71aaa7dcfae9dc3b6112912edd11bceccc99417` |
| acceptance-scenario | `fedd2e92a250c732956d1ff45ead255f6391399bd283dff1a35005ac138ceb04` |
| runtime-manifest | `72e3fdd0afff10f17fda9aaab5226761dee9ad18549fbb6a5ccdaa3d7497da2f` |
| transport-qualification-result | `62cbcea3af6642362ddf495a31c0ef0e950d45c24c7bfc5e3f86d829809a556e` |

To inspect the compressed fixture with ordinary Python:

```python
import gzip
import json
from pathlib import Path

path = Path("tests/schema_bundler/fixtures/baseline.json.gz")
snapshot = json.loads(gzip.decompress(path.read_bytes()))
print(snapshot["resources"]["acceptance-scenario-core.v1.schema.json"])
```

## Named definitions and compatibility

Twenty conditional rules now live under descriptive `$defs` names. Public
wrappers reference those names instead of `#/allOf/N`, so source ordering no
longer selects a rule accidentally. Core `allOf` lists still apply the same rules.
Named scalar primitives are owned by `common.v1`; existing definition aliases and
inline uses refer there. Similar-looking historical constraints remain distinct:
transport ROS names/types retain their stricter patterns and length limits;
`runSha256` retains the acceptance-run pattern spelling. This refactor does not
normalize or widen those constraints.

The original refactor proof compared every resolved assertion tree for all 29
schemas, IDs, catalog bytes and fixture diagnostics. The forward gate now uses
the [bounded D10 compatibility rules](schema-compatibility.md) against actual
released Git blobs, so new roles and permitted additions do not fail an obsolete
equality test. Historical source-to-byte reproduction remains unchanged.
Comparison uses JSON tokens to distinguish booleans from
numbers. A resolved `$ref` with sibling assertions remains a distinct token
containing both in the same scope; it is not converted into an `allOf` branch,
which could change `unevaluatedProperties` behavior. It fails on recursive
reference graphs, and the refactor regression tests verify that changed
constraints are detected. Previously schema-valid registered fixtures from both
packages must remain valid. Previously invalid fixtures may become valid under
permitted additions; their error messages are not a frozen schema interface. Malformed
serialization and unknown schema declarations cannot supply an instance for
this comparison; existing parser and schema-selection tests remain responsible
for those cases. Resource hashes are updated consciously only after these checks.

The refactor remains evidence for a constraint-preserving reorganization under
D10. The release gate adds bounded structural checks and public API semantic
regressions; it does not claim general implication between arbitrary schemas.
Future assertion changes require the compatibility or new-major path in ADR 0007.
