Skip to content

Refresh Discipline

Jump to bottom
hyperpolymath edited this page Jun 1, 2026 · 1 revision

Schema mirror refresh discipline

This page is the wiki-form restatement of the in-tree binding authority at schemas/SCHEMA-MIRROR.md. If the two disagree, the in-tree file wins — but they should never disagree; both restate the same discipline.

What's mirrored

schemas/cartridge-v1.json in this repo is a SHA-pinned mirror of:

Why mirror at all

  1. Offline validation. Hosts (boj-server, panll) and cartridge authors must validate cartridge.json without round-tripping to a network resource.
  2. Reproducibility. A given commit of this repository must validate against a deterministic schema version. CI / fetchers read the bundled copy, not the canonical URL.

PINNED-SHA file format

schemas/PINNED-SHA is a small TOML-flavoured key=value record. The current file:

# SPDX-License-Identifier: MPL-2.0
# Pinning record for schemas/cartridge-v1.json against the canonical upstream
# at hyperpolymath/standards/cartridges/cartridge-v1.json.
#
# Updated when the local mirror is synced with the canonical schema.
# See SCHEMA-MIRROR.md for the refresh discipline.

canonical_repo = "hyperpolymath/standards"
canonical_path = "cartridges/cartridge-v1.json"
canonical_commit = "<40-char SHA>"
canonical_blob_sha = "<40-char blob SHA>"
content_sha256 = "<64-hex content hash>"
pinned_at = "<YYYY-MM-DD>"
pinned_by_pr = "<org/repo#N>"

All seven fields are updated on every bump. The CI gate (cartridge-schema.yml) parses content_sha256 with awk -F'"' '/content_sha256/ {print $2}' and fails the job if sha256sum schemas/cartridge-v1.json disagrees.

Refresh procedure

When the canonical schema in hyperpolymath/standards advances:

1. Get the new canonical commit SHA

gh api repos/hyperpolymath/standards/commits?path=cartridges/cartridge-v1.json \
  --jq '.[0] | {sha, date: .commit.committer.date, message: .commit.message}'

The top entry is the most recent commit that touched cartridges/cartridge-v1.json. That's your new canonical_commit.

If you want the commit's blob SHA for the file too:

gh api repos/hyperpolymath/standards/contents/cartridges/cartridge-v1.json?ref=<commit-sha> \
  --jq '.sha'

That's your new canonical_blob_sha.

2. Replace the mirror file

gh api repos/hyperpolymath/standards/contents/cartridges/cartridge-v1.json?ref=<commit-sha> \
  --jq '.content' | base64 -d > schemas/cartridge-v1.json

3. Compute the new content SHA-256

sha256sum schemas/cartridge-v1.json
# → <64-hex>  schemas/cartridge-v1.json

That's your new content_sha256.

4. Update PINNED-SHA

Edit schemas/PINNED-SHA and set:

  • canonical_commit → step 1's SHA
  • canonical_blob_sha → step 1's blob SHA
  • content_sha256 → step 3's hash
  • pinned_at → today's date (YYYY-MM-DD)
  • pinned_by_pr → the standards PR / commit that introduced the change (e.g. hyperpolymath/standards#NNN)

5. Open the bump PR

The PR description references the upstream standards PR/commit that motivated the bump. CI will:

  1. Verify sha256sum schemas/cartridge-v1.json equals the new content_sha256 (catches editor-introduced newline drift, etc.).
  2. Run validator unit tests.
  3. Run deno task audit over all 139 cartridge manifests.

In audit mode today, step 3 is informational only — a schema bump that introduces new required fields will not block the PR, but the audit report will flood with the new violations, which is your signal that the inventory needs to grow.

6. Auto-merge

Auto-merge once CI is green. The pinned mirror is now advanced.

Conflict resolution: standards wins

If the local mirror diverges from hyperpolymath/standards and they disagree, standards is the source of truth. The local mirror is always advancing toward standards. Cartridges authored against an older mirror remain valid as long as the schema change is backwards-compatible; breaking changes ship as a new file (cartridge-v2.json) rather than a mutation of the v1 file, so a manifest pinned to v1 never silently loses validation.

Related

Clone this wiki locally