clio-schemas 0.2.1__tar.gz

clio_schemas-0.2.1/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Node
+tools/ts-gen/node_modules/
+
+# Generated TS output (regenerated in CI; committed goldens live in tests/golden)
+generated-ts/
+.ts-fresh/
+
+# Consumer copy-out target for the committed schemas (repo-local temp).
+# NOTE: the CANONICAL committed schemas live at src/clio_schemas/schemas/ and
+# are tracked — do NOT ignore that path.
+/schemas/

clio_schemas-0.2.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: clio-schemas
+Version: 0.2.1
+Summary: Canonical shared record schemas (pydantic v2) for clio-agent, clio-relay, and gact-tui.
+Project-URL: Homepage, https://github.com/iowarp/clio-schemas
+Project-URL: Repository, https://github.com/iowarp/clio-schemas
+Author: IOWarp
+License: MIT
+Keywords: clio,json-schema,pydantic,schemas
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.370; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clio-schemas
+
+**The single source of truth for the record shapes shared across the CLIO
+system.** `clio-agent`, `clio-relay`, and `gact-tui` all speak the same wire
+records — artifact versions/chains and transform provenance records. Historically
+each service hand-wrote its own copy of these types and
+they drifted. This package makes the shapes canonical: they are defined once as
+[pydantic](https://docs.pydantic.dev/) v2 models here and exported to JSON
+Schema. Python consumers import the models; TypeScript consumers **generate**
+types from the JSON Schema shipped inside the package. Nobody hand-writes a
+shared shape again.
+
+> **Status: P2.1 records landed (version 0.2.0 / issue #1120).** The bootstrap
+> placeholders are gone. `ArtifactVersion`, `ArtifactRecord`, `ProvEdge`,
+> `TransformRecord`, their nested value models, and their enums are canonical.
+
+---
+
+## Why the schemas are immutable package resources (design decision)
+
+An exact `clio-schemas` pin, on its own, does **not** guarantee two services see
+the same schema *bytes*: if each consumer *regenerated* JSON Schema from the
+pydantic models under its own resolved pydantic version, a pydantic point release
+could subtly change the output and drift would return through the back door.
+
+So the canonical JSON Schemas are **built once, committed, and shipped as
+immutable package resources** inside the wheel (`clio_schemas/schemas/*.json`),
+alongside a canonical hash manifest (`HASHES.json`). Consumers **copy** those
+committed bytes — they never regenerate. An exact pin therefore *does* determine
+the bytes. Regenerating from the models is a repo-local developer command
+(`--regenerate`), gated to the single **locked pydantic version**, so the
+committed artifacts can only change deliberately, in this repo.
+
+## What's in the box
+
+```
+clio-schemas/
+├── pyproject.toml                     # uv-compatible, py>=3.12, pydantic v2, hatchling
+├── src/clio_schemas/
+│   ├── __init__.py                    # public exports + __version__
+│   ├── constants.py                   # LOCKED_PYDANTIC_VERSION, file names
+│   ├── models.py                      # canonical models + ClioSchemaBase + registry
+│   ├── export.py                      # copy / check / regenerate / verify
+│   ├── py.typed                       # ships type information
+│   └── schemas/                       # COMMITTED immutable artifacts (in the wheel)
+│       ├── artifact_version.json      #   per-model, self-contained
+│       ├── artifact_record.json       #   per-model, self-contained
+│       ├── transform_record.json      #   plus provenance/value model schemas
+│       ├── index.json                 #   aggregate: shared $defs emitted once
+│       └── HASHES.json                #   canonical sha256 manifest
+├── tools/ts-gen/
+│   ├── schemas-to-ts.mjs              # JSON Schema dir -> TS module graph (deterministic)
+│   ├── tsconfig.check.json            # isolated strict typecheck of generated TS
+│   └── package.json / package-lock.json
+├── scripts/check_version_bump.py      # CI: schema change ⇒ version bump
+├── tests/
+│   ├── test_roundtrip.py              # JSON/TS golden anti-drift tests
+│   ├── test_legacy_parity.py          # original clio-agent byte fixtures
+│   ├── test_version_bump.py           # unit tests for the bump-enforcement core
+│   └── golden/                        # committed golden TS directory
+│       ├── _models.ts index.ts artifact_version.ts transform_record.ts ...
+└── ci-drafts/                         # workflow drafts for this repo + both consumers
+```
+
+## The pipeline
+
+```
+pydantic models ──render (locked pydantic)──▶ committed *.json + HASHES.json ──ship in wheel──▶
+    consumer copies bytes ──schemas-to-ts.mjs──▶ TypeScript module graph
+```
+
+Every hop is **deterministic**: JSON is emitted with sorted keys and a stable
+`$defs` order; the TypeScript generator uses a fixed banner (no timestamp),
+sorted file order, and pinned formatting. The aggregate `index.json` carries all
+models under a single shared `$defs`, so the generator emits each shared
+definition (e.g. the `ArtifactKind` enum and nested `IdentityEvidence`) **exactly
+once** — the generated module graph has no duplicate declarations.
+
+## Export command modes
+
+```bash
+# Consumer: copy the immutable committed schemas into ./schemas
+uv run python -m clio_schemas.export --out schemas
+
+# Consumer CI: verify a directory matches the committed bytes exactly
+# (rejects stale, missing, AND unexpected/orphaned files)
+uv run python -m clio_schemas.export --out schemas --check
+
+# DEV: re-render the committed package resources from the models
+# (refuses unless the installed pydantic == LOCKED_PYDANTIC_VERSION)
+uv run python -m clio_schemas.export --regenerate
+
+# REPO CI: assert committed artifacts are canonical (match models + hashes)
+uv run python -m clio_schemas.export --verify
+```
+
+## Quick start
+
+```bash
+uv sync --extra dev                                   # install (locked pydantic)
+uv run python -m clio_schemas.export --verify         # artifacts are canonical
+uv run pytest                                          # golden round-trip + conformance
+
+cd tools/ts-gen && npm ci && npm run check            # generate TS + strict typecheck
+```
+
+## Legacy extraction compatibility
+
+The P2.1 artifact/provenance records use `LegacyToleranceBase` so their
+clio-agent behavior remains byte- and validation-compatible: unknown keys are
+ignored, ordinary Pydantic coercion remains enabled, immutable records stay
+frozen, and `ArtifactRecord` stays mutable. Moving existing records to the
+strict `ClioSchemaBase` contract would be a wire change; that coordinated
+convergence is tracked in iowarp/clio-agent#1121.
+
+## How to add a model
+
+1. Define the pydantic v2 model in `src/clio_schemas/models.py`, inheriting
+   `ClioSchemaBase` (strict wire semantics: `extra="forbid"`, `strict=True`,
+   `frozen=True`). Give every field a `Field(description=...)` — descriptions flow
+   into the JSON Schema and the generated TS doc comments.
+2. Append the class to the `EXPORTED_MODELS` tuple in the same file.
+3. Regenerate the committed artifacts and the golden TS, then bump the version:
+   ```bash
+   uv run python -m clio_schemas.export --regenerate            # updates schemas/ + HASHES.json
+   cd tools/ts-gen && node schemas-to-ts.mjs \
+       --in ../../src/clio_schemas/schemas --out ../../tests/golden
+   ```
+4. Bump `__version__` in `src/clio_schemas/__init__.py` **and** `version` in
+   `pyproject.toml` in lockstep (CI enforces a bump whenever `HASHES.json`
+   changes), then `uv run pytest`.
+
+## Versioning policy — exact-pin lockstep
+
+Consumers pin an **exact** version (`clio-schemas==X.Y.Z`, not `>=`). A schema is
+a contract between multiple services; a range would let two services resolve
+different shapes and reintroduce drift. Therefore:
+
+- **Any** change to a committed schema (detected via `HASHES.json`) requires a
+  `clio-schemas` version bump — enforced mechanically in CI by
+  `scripts/check_version_bump.py`, which compares the hash manifest against the
+  merge base and fails if the version was not incremented.
+- All consumers (`clio-agent`, `clio-relay`, `gact-tui`) update their pin to the
+  new exact version **in lockstep**, in the same coordinated change.
+- The version lives in exactly two places that must agree: `pyproject.toml`
+  `version` and `clio_schemas.__version__`; CI verifies they match.
+
+### Wire evolution
+
+Exact-pin lockstep is the bootstrap rule. As the real records land and the
+system runs mixed versions during rollouts, the intended evolution discipline
+is:
+
+- **Additive, reader-first staging.** Additive changes (new optional field, new
+  enum member) ship to *readers* before *writers*: deploy the version that can
+  *accept* the new shape everywhere first, then deploy the writers that *emit*
+  it. Readers must ignore-or-tolerate unknown-but-optional additions during the
+  transition. Extracted P2.1 records preserve their legacy reader-tolerant
+  behavior through `LegacyToleranceBase`; new records use `ClioSchemaBase`.
+- **N / N-1 compatibility.** Once real schemas exist, adjacent versions are
+  expected to interoperate: a service on version *N* and one on *N-1* must be
+  able to exchange the records they share for the duration of a rollout.
+  Breaking (non-additive) changes require a two-step migration across at least
+  one intermediate version, never a flag-day.
+- **Rollback ordering.** Roll back in the reverse of deploy order: retire the
+  *writers* of a new shape before the *readers* that understand it, so a rolled
+  -back writer never emits a shape an already-rolled-back reader would reject.
+
+Convergence of the extracted records on stricter validation is tracked by
+iowarp/clio-agent#1121 and requires a coordinated consumer migration.
+
+## How consumers regenerate
+
+- **clio-agent (Python):** pin `clio-schemas==X.Y.Z`, `import clio_schemas`. Its
+  CI copies the committed schemas out of the installed package and `--check`s any
+  vendored copy for exact-byte + file-set equality (see
+  `ci-drafts/clio-agent-schema-check.yml`).
+- **clio-relay (Python):** same as clio-agent — import the models, pin exact.
+- **gact-tui (TypeScript):** pin `clio-schemas==X.Y.Z`, copy the shipped JSON
+  Schema out of the package, and run the in-repo generator (`tools/ts-gen`,
+  pinned via its lockfile) to produce `.ts`. Its CI regenerates into a clean dir
+  and compares exact file *sets* + bytes so untracked/orphaned files are caught
+  (see `ci-drafts/gact-tui-ts-gen.yml`).

clio_schemas-0.2.1/README.md

@@ -0,0 +1,183 @@
+# clio-schemas
+
+**The single source of truth for the record shapes shared across the CLIO
+system.** `clio-agent`, `clio-relay`, and `gact-tui` all speak the same wire
+records — artifact versions/chains and transform provenance records. Historically
+each service hand-wrote its own copy of these types and
+they drifted. This package makes the shapes canonical: they are defined once as
+[pydantic](https://docs.pydantic.dev/) v2 models here and exported to JSON
+Schema. Python consumers import the models; TypeScript consumers **generate**
+types from the JSON Schema shipped inside the package. Nobody hand-writes a
+shared shape again.
+
+> **Status: P2.1 records landed (version 0.2.0 / issue #1120).** The bootstrap
+> placeholders are gone. `ArtifactVersion`, `ArtifactRecord`, `ProvEdge`,
+> `TransformRecord`, their nested value models, and their enums are canonical.
+
+---
+
+## Why the schemas are immutable package resources (design decision)
+
+An exact `clio-schemas` pin, on its own, does **not** guarantee two services see
+the same schema *bytes*: if each consumer *regenerated* JSON Schema from the
+pydantic models under its own resolved pydantic version, a pydantic point release
+could subtly change the output and drift would return through the back door.
+
+So the canonical JSON Schemas are **built once, committed, and shipped as
+immutable package resources** inside the wheel (`clio_schemas/schemas/*.json`),
+alongside a canonical hash manifest (`HASHES.json`). Consumers **copy** those
+committed bytes — they never regenerate. An exact pin therefore *does* determine
+the bytes. Regenerating from the models is a repo-local developer command
+(`--regenerate`), gated to the single **locked pydantic version**, so the
+committed artifacts can only change deliberately, in this repo.
+
+## What's in the box
+
+```
+clio-schemas/
+├── pyproject.toml                     # uv-compatible, py>=3.12, pydantic v2, hatchling
+├── src/clio_schemas/
+│   ├── __init__.py                    # public exports + __version__
+│   ├── constants.py                   # LOCKED_PYDANTIC_VERSION, file names
+│   ├── models.py                      # canonical models + ClioSchemaBase + registry
+│   ├── export.py                      # copy / check / regenerate / verify
+│   ├── py.typed                       # ships type information
+│   └── schemas/                       # COMMITTED immutable artifacts (in the wheel)
+│       ├── artifact_version.json      #   per-model, self-contained
+│       ├── artifact_record.json       #   per-model, self-contained
+│       ├── transform_record.json      #   plus provenance/value model schemas
+│       ├── index.json                 #   aggregate: shared $defs emitted once
+│       └── HASHES.json                #   canonical sha256 manifest
+├── tools/ts-gen/
+│   ├── schemas-to-ts.mjs              # JSON Schema dir -> TS module graph (deterministic)
+│   ├── tsconfig.check.json            # isolated strict typecheck of generated TS
+│   └── package.json / package-lock.json
+├── scripts/check_version_bump.py      # CI: schema change ⇒ version bump
+├── tests/
+│   ├── test_roundtrip.py              # JSON/TS golden anti-drift tests
+│   ├── test_legacy_parity.py          # original clio-agent byte fixtures
+│   ├── test_version_bump.py           # unit tests for the bump-enforcement core
+│   └── golden/                        # committed golden TS directory
+│       ├── _models.ts index.ts artifact_version.ts transform_record.ts ...
+└── ci-drafts/                         # workflow drafts for this repo + both consumers
+```
+
+## The pipeline
+
+```
+pydantic models ──render (locked pydantic)──▶ committed *.json + HASHES.json ──ship in wheel──▶
+    consumer copies bytes ──schemas-to-ts.mjs──▶ TypeScript module graph
+```
+
+Every hop is **deterministic**: JSON is emitted with sorted keys and a stable
+`$defs` order; the TypeScript generator uses a fixed banner (no timestamp),
+sorted file order, and pinned formatting. The aggregate `index.json` carries all
+models under a single shared `$defs`, so the generator emits each shared
+definition (e.g. the `ArtifactKind` enum and nested `IdentityEvidence`) **exactly
+once** — the generated module graph has no duplicate declarations.
+
+## Export command modes
+
+```bash
+# Consumer: copy the immutable committed schemas into ./schemas
+uv run python -m clio_schemas.export --out schemas
+
+# Consumer CI: verify a directory matches the committed bytes exactly
+# (rejects stale, missing, AND unexpected/orphaned files)
+uv run python -m clio_schemas.export --out schemas --check
+
+# DEV: re-render the committed package resources from the models
+# (refuses unless the installed pydantic == LOCKED_PYDANTIC_VERSION)
+uv run python -m clio_schemas.export --regenerate
+
+# REPO CI: assert committed artifacts are canonical (match models + hashes)
+uv run python -m clio_schemas.export --verify
+```
+
+## Quick start
+
+```bash
+uv sync --extra dev                                   # install (locked pydantic)
+uv run python -m clio_schemas.export --verify         # artifacts are canonical
+uv run pytest                                          # golden round-trip + conformance
+
+cd tools/ts-gen && npm ci && npm run check            # generate TS + strict typecheck
+```
+
+## Legacy extraction compatibility
+
+The P2.1 artifact/provenance records use `LegacyToleranceBase` so their
+clio-agent behavior remains byte- and validation-compatible: unknown keys are
+ignored, ordinary Pydantic coercion remains enabled, immutable records stay
+frozen, and `ArtifactRecord` stays mutable. Moving existing records to the
+strict `ClioSchemaBase` contract would be a wire change; that coordinated
+convergence is tracked in iowarp/clio-agent#1121.
+
+## How to add a model
+
+1. Define the pydantic v2 model in `src/clio_schemas/models.py`, inheriting
+   `ClioSchemaBase` (strict wire semantics: `extra="forbid"`, `strict=True`,
+   `frozen=True`). Give every field a `Field(description=...)` — descriptions flow
+   into the JSON Schema and the generated TS doc comments.
+2. Append the class to the `EXPORTED_MODELS` tuple in the same file.
+3. Regenerate the committed artifacts and the golden TS, then bump the version:
+   ```bash
+   uv run python -m clio_schemas.export --regenerate            # updates schemas/ + HASHES.json
+   cd tools/ts-gen && node schemas-to-ts.mjs \
+       --in ../../src/clio_schemas/schemas --out ../../tests/golden
+   ```
+4. Bump `__version__` in `src/clio_schemas/__init__.py` **and** `version` in
+   `pyproject.toml` in lockstep (CI enforces a bump whenever `HASHES.json`
+   changes), then `uv run pytest`.
+
+## Versioning policy — exact-pin lockstep
+
+Consumers pin an **exact** version (`clio-schemas==X.Y.Z`, not `>=`). A schema is
+a contract between multiple services; a range would let two services resolve
+different shapes and reintroduce drift. Therefore:
+
+- **Any** change to a committed schema (detected via `HASHES.json`) requires a
+  `clio-schemas` version bump — enforced mechanically in CI by
+  `scripts/check_version_bump.py`, which compares the hash manifest against the
+  merge base and fails if the version was not incremented.
+- All consumers (`clio-agent`, `clio-relay`, `gact-tui`) update their pin to the
+  new exact version **in lockstep**, in the same coordinated change.
+- The version lives in exactly two places that must agree: `pyproject.toml`
+  `version` and `clio_schemas.__version__`; CI verifies they match.
+
+### Wire evolution
+
+Exact-pin lockstep is the bootstrap rule. As the real records land and the
+system runs mixed versions during rollouts, the intended evolution discipline
+is:
+
+- **Additive, reader-first staging.** Additive changes (new optional field, new
+  enum member) ship to *readers* before *writers*: deploy the version that can
+  *accept* the new shape everywhere first, then deploy the writers that *emit*
+  it. Readers must ignore-or-tolerate unknown-but-optional additions during the
+  transition. Extracted P2.1 records preserve their legacy reader-tolerant
+  behavior through `LegacyToleranceBase`; new records use `ClioSchemaBase`.
+- **N / N-1 compatibility.** Once real schemas exist, adjacent versions are
+  expected to interoperate: a service on version *N* and one on *N-1* must be
+  able to exchange the records they share for the duration of a rollout.
+  Breaking (non-additive) changes require a two-step migration across at least
+  one intermediate version, never a flag-day.
+- **Rollback ordering.** Roll back in the reverse of deploy order: retire the
+  *writers* of a new shape before the *readers* that understand it, so a rolled
+  -back writer never emits a shape an already-rolled-back reader would reject.
+
+Convergence of the extracted records on stricter validation is tracked by
+iowarp/clio-agent#1121 and requires a coordinated consumer migration.
+
+## How consumers regenerate
+
+- **clio-agent (Python):** pin `clio-schemas==X.Y.Z`, `import clio_schemas`. Its
+  CI copies the committed schemas out of the installed package and `--check`s any
+  vendored copy for exact-byte + file-set equality (see
+  `ci-drafts/clio-agent-schema-check.yml`).
+- **clio-relay (Python):** same as clio-agent — import the models, pin exact.
+- **gact-tui (TypeScript):** pin `clio-schemas==X.Y.Z`, copy the shipped JSON
+  Schema out of the package, and run the in-repo generator (`tools/ts-gen`,
+  pinned via its lockfile) to produce `.ts`. Its CI regenerates into a clean dir
+  and compares exact file *sets* + bytes so untracked/orphaned files are caught
+  (see `ci-drafts/gact-tui-ts-gen.yml`).

clio_schemas-0.2.1/SCAFFOLD_REPORT.md

@@ -0,0 +1,167 @@
+# clio-schemas scaffold — build report (issue #1110, P0.6)
+
+Pipeline-only bootstrap of the `iowarp/clio-schemas` package: a pydantic v2 ->
+JSON Schema -> TypeScript loop, with the canonical schemas shipped as immutable
+package resources, a golden anti-drift test, strict wire conformance, and CI
+drafts for this repo and both consumers. This directory is intended to become
+the real repo verbatim after review.
+
+## CHANGES AFTER REVIEW (Codex verdict: no-ship — findings accepted)
+
+Each accepted finding, the fix, and the proof it works.
+
+1. **Design correction — immutable package resources, not consumer-side
+   regeneration.** An exact pin does not fix schema *bytes* if consumers
+   regenerate under their own pydantic.
+   - *Fix:* canonical JSON Schemas are rendered once (under the locked pydantic)
+     and committed as package resources in `src/clio_schemas/schemas/*.json`,
+     shipped inside the wheel; a canonical `HASHES.json` (sha256) is committed
+     alongside. `export.py` now has consumer modes that **copy** those bytes
+     (`--out DIR`) or **verify** a copy (`--out DIR --check`), and dev/CI modes
+     that render from the models (`--regenerate`, `--verify`) gated to
+     `LOCKED_PYDANTIC_VERSION = 2.13.4`.
+   - *Proof:* `uv run python -m clio_schemas.export --verify` → "OK: 4 committed
+     schema file(s) are canonical"; wheel listing shows `clio_schemas/schemas/{schema_probe,probe_batch,index,HASHES}.json`
+     + `py.typed`; `--regenerate`/`--verify` raise a clear error under any other
+     pydantic (guard `_require_locked_pydantic`).
+
+2. **Golden covers EVERY model + full-directory set equality.**
+   - *Fix:* `test_golden_directory_set_and_bytes` compares the complete generated
+     dir vs the complete golden dir (filename-set equality + byte content);
+     `test_every_model_has_a_committed_schema` and
+     `test_every_model_has_a_golden_ts_module` are parameterised over
+     `EXPORTED_MODELS`.
+   - *Proof:* 22 tests pass; `diff -rN tests/golden generated-ts` → "GOLDEN
+     MATCHES FRESH GENERATION".
+
+3. **Stale-artifact detection via clean temp dir + exact file SETS.**
+   - *Fix:* the TS generator wipes its `--out` dir first (orphans cannot
+     survive); the round-trip test generates into a fresh `tmp_path`; `export
+     --check` rejects unexpected `.json` (`unexpected:` / `missing:` / `stale:`).
+     The gact-tui CI draft now regenerates into a clean dir and uses `diff -rN`
+     (not `git diff`, which misses untracked/orphans).
+   - *Proof:* injecting `rogue.json` → `--check` exits 1 with "unexpected:
+     rogue.json"; corrupting a file → exit 1 "stale: schema_probe.json".
+
+4. **CI enforces version bump on schema change.**
+   - *Fix:* `scripts/check_version_bump.py` compares `HASHES.json` against the
+     merge base and fails if it changed without an `__version__` increment; pure
+     core (`requires_bump`, `is_increment`) is unit-tested in
+     `tests/test_version_bump.py`. Wired into `ci-drafts/clio-schemas-ci.yml`.
+   - *Proof:* `check_version_bump.py` runs clean; 6 unit tests cover
+     unchanged/changed/bumped/downgrade cases.
+
+5. **Strict wire validation + negative conformance tests.**
+   - *Fix:* `ClioSchemaBase(ConfigDict(extra="forbid", strict=True,
+     frozen=True))`; both models inherit it. Tests assert `sequence="7"` (str
+     for int) is rejected, unknown keys are rejected, and records are frozen.
+   - *Proof:* `test_string_for_int_is_rejected`, `test_unknown_key_is_rejected`,
+     `test_records_are_frozen` all pass.
+
+6. **Multi-root readiness — shared definitions emitted once.**
+   - *Fix:* second model `ProbeBatch` references `SchemaProbe` (nested) and reuses
+     `ProbeKind` (shared enum). The exporter builds an aggregate `index.json` via
+     pydantic `models_json_schema` (single shared `$defs`); the TS generator
+     compiles that once into `_models.ts` (declarations), emits thin per-model
+     re-export modules, and an `index.ts` barrel. A `$ref`-sibling flattening
+     pass in the generator prevents json-schema-to-typescript from duplicating a
+     ref'd type (it had produced `ProbeKind` + `ProbeKind1`).
+   - *Proof:* declaration scan across `generated-ts` shows every type exactly
+     once (`ProbeKind` count 1); `test_no_duplicate_declarations_in_barrel`
+     passes.
+
+7. **Packaging ships the schemas; documented consumption path.**
+   - *Fix:* `[tool.hatch.build.targets.wheel].artifacts` force-includes
+     `schemas/*.json` + `py.typed`; sdist includes `scripts`/`ci-drafts`. README
+     documents that gact-tui copies the committed schemas from the installed
+     package (pin ⇒ bytes) and runs the in-repo generator pinned by its lockfile.
+   - *Proof:* wheel zip listing (see item 1) contains all four JSON files +
+     `py.typed`; `uv build` produces wheel + sdist.
+
+8. **README wire-evolution paragraph.**
+   - *Fix:* added "Wire evolution" subsection: additive-reader-first staging,
+     N/N-1 compatibility once real schemas land (P2.1 designs the full protocol),
+     and rollback-in-reverse-of-deploy ordering. Exact-pin lockstep retained for
+     the bootstrap.
+
+## File inventory
+
+| File | Purpose |
+| --- | --- |
+| `pyproject.toml` | hatchling build, `requires-python>=3.12`, `pydantic>=2.7,<3`; wheel force-includes `schemas/*.json` + `py.typed`; ruff/pytest/pyright config; `dev` extra. |
+| `src/clio_schemas/__init__.py` | Public exports (models, `ClioSchemaBase`, `EXPORTED_MODELS`, `LOCKED_PYDANTIC_VERSION`) + `__version__`. |
+| `src/clio_schemas/constants.py` | `LOCKED_PYDANTIC_VERSION`, aggregate/hash file names (import-cheap, avoids a `runpy` warning). |
+| `src/clio_schemas/models.py` | `ClioSchemaBase` (strict/forbid/frozen), `ProbeKind` (shared enum), `SchemaProbe`, `ProbeBatch` (references SchemaProbe), `EXPORTED_MODELS`. |
+| `src/clio_schemas/export.py` | Deterministic render + `copy` / `check` / `regenerate` / `verify` modes; aggregate schema; hash manifest; pydantic-lock guard; dir-diff (missing/unexpected/stale). |
+| `src/clio_schemas/py.typed` | PEP 561 marker. |
+| `src/clio_schemas/schemas/*.json` | **Committed immutable artifacts:** `schema_probe.json`, `probe_batch.json`, `index.json` (aggregate), `HASHES.json`. |
+| `scripts/check_version_bump.py` | CI: schema-hash change ⇒ version-bump enforcement (pure, unit-tested core). |
+| `tools/ts-gen/schemas-to-ts.mjs` | Aggregate -> `_models.ts` (once) + per-model re-export modules + `index.ts` barrel; `$ref`-sibling flattening; deterministic (fixed banner, sorted, LF). |
+| `tools/ts-gen/package.json` + `package-lock.json` | Pins `json-schema-to-typescript@15.0.4` + `typescript@5.6.3`; `generate`/`check` scripts. |
+| `tools/ts-gen/tsconfig.check.json` | Isolated strict typecheck (`types: []`, `lib: es2020`). |
+| `tests/test_roundtrip.py` | Committed-canonical, per-model coverage, golden dir set+bytes, no-dup-declarations, strict conformance (negative) tests. |
+| `tests/test_version_bump.py` | Unit tests for the version-bump core. |
+| `tests/golden/*.ts` | Committed golden TS module graph (`_models.ts`, `index.ts`, `probe_batch.ts`, `schema_probe.ts`). |
+| `ci-drafts/clio-schemas-ci.yml` | Own repo: ruff/pyright, `--verify`, version-pin agreement, version-bump script, golden round-trip, TS typecheck. |
+| `ci-drafts/clio-agent-schema-check.yml` | Consumer: exact pin + `--out schemas --check` byte/set equality. |
+| `ci-drafts/gact-tui-ts-gen.yml` | Consumer: copy shipped schemas, generate TS into clean dir, typecheck, `diff -rN` set+byte equality. |
+| `README.md` | Purpose, immutable-resource design rationale, pipeline, export modes, add-a-model, exact-pin lockstep + wire-evolution, consumer regeneration. |
+| `.gitignore` | Ignores venv/caches/dist/node_modules/`generated-ts`/`.ts-fresh`/top-level `schemas/`; keeps `src/clio_schemas/schemas/` tracked. |
+| `uv.lock` | Resolved lock (pins pydantic 2.13.4 = LOCKED_PYDANTIC_VERSION). |
+
+## Verify locally
+
+```bash
+cd clio-schemas-scaffold
+
+uv sync --extra dev
+uv run python -m clio_schemas.export --verify            # committed artifacts canonical
+uv run python -m clio_schemas.export --out /tmp/s        # consumer copy
+uv run python -m clio_schemas.export --out /tmp/s --check  # exit 0 = matches
+uv run --extra dev ruff check src tests scripts
+uv run --extra dev ruff format --check src tests scripts
+uv run --extra dev pyright src tests scripts
+uv run --extra dev pytest                                # 22 passed
+uv run python scripts/check_version_bump.py --base origin/main
+uv build                                                 # wheel + sdist (schemas inside)
+
+cd tools/ts-gen && npm ci && npm run check               # generate TS + strict typecheck
+```
+
+## Verified in this session (all green)
+
+- `--verify`: 4 committed schema files canonical (match models + HASHES under
+  locked pydantic 2.13.4).
+- `pytest`: **22 passed** — committed-canonical, per-model coverage (×2), golden
+  dir set+bytes, no-duplicate-declarations, negative conformance (str-for-int,
+  unknown-key, frozen), version-bump unit tests.
+- Consumer copy + `--check` pass; injected unexpected file and corrupted file
+  each fail `--check` with a typed reason.
+- `ruff check` + `ruff format --check` + `pyright` (src/tests/scripts) clean.
+- TS generation: `_models.ts` declares every type exactly once (`ProbeKind`
+  shared enum once); per-model re-export modules + barrel; strict `tsc` passes;
+  `diff -rN tests/golden generated-ts` identical.
+- `uv build`: wheel + sdist; wheel contains `schemas/*.json` + `py.typed`.
+- `check_version_bump.py` runs clean.
+
+## Not verified / caveats
+
+- **CI YAML files are drafts, not executed** in a real Actions runner. Step
+  logic mirrors commands verified locally, but action versions
+  (`astral-sh/setup-uv@v5`, `actions/setup-node@v4`) and consumer-repo paths
+  (e.g. gact-tui `src/generated/schemas`) must be reconciled on adoption.
+- **Consumer snippets assume a published/installable `clio-schemas==0.1.0`.**
+  Until the repo is published (PyPI or git pin), `uv pip install
+  "clio-schemas==0.1.0"` / dependency-pin steps will not resolve. Locally it
+  installs from source (`uv sync`, `uv build`).
+- **`LOCKED_PYDANTIC_VERSION` is hardcoded to 2.13.4** (matching `uv.lock`).
+  Bumping pydantic is a deliberate action: update the constant, `--regenerate`,
+  and version-bump. `--verify`/`--regenerate` correctly refuse under any other
+  installed pydantic — this is by design, not a bug.
+- **`json-schema-to-typescript` determinism is pinned by version** (15.0.4), not
+  proven across versions; the golden guards it and a bump requires regenerating
+  the golden.
+- **`check_version_bump.py` merge-base logic** is exercised only via its pure
+  unit-tested core here (the scaffold dir is not a git repo with an `origin/main`
+  history); in a real repo it diffs against the base ref.
+- Windows note: the generator normalises CRLF->LF; verified on win32.

clio_schemas-0.2.1/ci-drafts/clio-agent-schema-check.yml

@@ -0,0 +1,47 @@
+# DRAFT — job snippet to add to clio-agent's CI (e.g. a new job in
+# `.github/workflows/ci.yml`, or a standalone workflow).
+#
+# Purpose (acceptance criterion #2 of #1110): clio-agent resolves the
+# clio-schemas dependency (exact pin) and verifies that any schemas it vendors
+# match the IMMUTABLE bytes shipped inside the installed clio-schemas package.
+# Because consumers *copy* the committed artifacts rather than regenerate them,
+# the exact pin fully determines the bytes — this job proves that holds.
+#
+# Prerequisite in clio-agent: add an exact pin to pyproject.toml, e.g.
+#   dependencies = [ ..., "clio-schemas==0.1.0" ]
+# If clio-agent vendors the schemas for offline use, commit them under a known
+# dir (e.g. `schemas/`); otherwise it can consume them straight from the package.
+
+jobs:
+  clio-schemas-export-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync deps (resolves the exact clio-schemas pin)
+        run: uv sync --extra dev
+
+      - name: Confirm exact-pin lockstep is installed
+        run: |
+          uv run python - <<'PY'
+          import clio_schemas
+          print("clio-schemas", clio_schemas.__version__)
+          PY
+
+      # Option A — clio-agent vendors the schemas under ./schemas:
+      # verify the vendored copy is byte-identical to the installed package
+      # (rejects stale, missing, AND unexpected/orphaned files).
+      - name: Vendored schemas match the installed package (exact bytes + set)
+        run: uv run python -m clio_schemas.export --out schemas --check
+
+      # Option B — CI refreshes the vendored copy into a CLEAN dir and fails on
+      # any drift, including untracked/orphaned files that `git diff` alone
+      # would miss:
+      #   rm -rf schemas
+      #   uv run python -m clio_schemas.export --out schemas
+      #   git add -A schemas && git diff --cached --exit-code -- schemas