Skip to content

Commit 1376eb6

Browse files
docs(cartridges): add Reference implementations subsection (#333)
## Summary Adds a short `== Reference implementations` subsection at the end of `cartridges/CARTRIDGE-FORMAT.adoc` pointing implementers at the live downstream consumer of this format. The cartridge format here is now consumed by `hyperpolymath/boj-server-cartridges`, which serves as the canonical registry (already referenced in `<<Registry and on-demand fetch>>`) and exercises the schema across every shipped cartridge. New section gives implementers a worked example to read. ## Rationale Downstream landed three pieces of machinery worth pointing at from the spec: - A SHA-pinned mirror of `cartridge-v1.json` at `schemas/` with `PINNED-SHA` + `SCHEMA-MIRROR.md` documenting the refresh discipline. - A zero-dep Deno validator at `tools/validate-cartridges/` (only `jsr:@std/fs` + `jsr:@std/path` + `jsr:@std/assert`) with `audit` / `audit-verbose` / `strict` / `test` tasks. - A blocking CI gate at `.github/workflows/cartridge-schema.yml`; strict mode went live 2026-06-01 after 139/139 manifests passed. Subsection is ~28 lines, doesn't restate the spec, and clarifies that downstreams pin by SHA rather than tracking `main` — bumps follow the procedure in downstream's `schemas/SCHEMA-MIRROR.md`. ## Test plan - [ ] AsciiDoc renders cleanly (manual review of the new subsection). - [ ] No other content modified — diff is a pure append at end-of-file. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 2894681 commit 1376eb6

1 file changed

Lines changed: 27 additions & 0 deletions

File tree

cartridges/CARTRIDGE-FORMAT.adoc

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,3 +156,30 @@ The `tray` UI exposes "Add cartridge source" with optional verification against
156156
This document is v1. Backwards-incompatible changes will be published as
157157
`cartridge-v2.json` with a migration ADR. v1 manifests remain consumable
158158
indefinitely; hosts implementing v2 must accept both.
159+
160+
== Reference implementations
161+
162+
The live downstream consumer of this format is
163+
`hyperpolymath/boj-server-cartridges`, which serves as the canonical registry
164+
(see <<Registry and on-demand fetch>>) and exercises the schema across every
165+
shipped cartridge. Implementers building a new host or validator can read it as
166+
a worked example.
167+
168+
Key files in that repository:
169+
170+
* `schemas/cartridge-v1.json` — SHA-pinned mirror of `cartridges/cartridge-v1.json`
171+
from this repo.
172+
* `schemas/PINNED-SHA` — exact upstream commit the mirror tracks.
173+
* `schemas/SCHEMA-MIRROR.md` — in-tree authority documenting the refresh
174+
discipline.
175+
* `tools/validate-cartridges/` — zero-dep Deno validator (only
176+
`jsr:@std/fs`, `jsr:@std/path`, `jsr:@std/assert`) with `audit`,
177+
`audit-verbose`, `strict`, and `test` tasks.
178+
* `.github/workflows/cartridge-schema.yml` — CI gate running the validator;
179+
strict mode went live 2026-06-01 after 139/139 manifests passed.
180+
181+
Refresh discipline: downstream pins the schema by SHA rather than tracking
182+
`main`. To consume a new revision of `cartridge-v1.json`, follow the procedure
183+
in the downstream's `schemas/SCHEMA-MIRROR.md` — bump `PINNED-SHA`, refresh
184+
the mirrored copy, re-run the validator against every manifest, and only then
185+
land the bump.

0 commit comments

Comments
 (0)