Repository navigation
feat(api)!: reset /v1 to the chora model before its first deploy - #122
Conversation
Owner ruling of 2026-11-14 (ADR 0004 amendment). /v1 was never deployed (every Worker Deploy run skipped the deploy step: no CLOUDFLARE_API_TOKEN) and nothing in the estate calls it, so it changes in place: - uuid is the ADR-008 profile C UUIDv8 of the birth path; minted_in names its domain (V9). No UUIDv5 is served; uuid_v8 is dropped. - clade and secondary become placements [{scheme, category, primary|rank}] in the scheme clade-12 (A7 W10). - prefixed is dropped; /c/{ref} resolves a canonical name or a uuid. - /v1/llm reports registry chora-registry and each result's uuid and placements. sync/export-json.sh writes the new shape; archive.json keeps each moved repo's v8 id, and a retired path's v5 only as uuid_v5 (record). The gate checks uuid against the seed and the derivation in minted_in, refuses any retired /v1 field, and follows a pre-reset base by its uuid_v8. Worker: placements.js (primaryClade, cladeCodes) replaces repo.clade everywhere; tests cover the resolver and the new invariants. openapi.yaml 2.0.0 (redocly: same 7 warnings as main), USER-API-GUIDE, verification README, CHANGELOG. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0136P7ZoUeC49fDEvSwDNvuS
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1d87a5aca7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| description: >- | ||
| Deterministic UUIDv5 over `github.com/<owner>/<name>` at the repository's birth path, in the @url namespace. Minted once and never changed (ADR 0008, which supersedes ADR 0007): a move or rename changes `github` only, and a clade change never touches it. The birth path is not served. An id the registry once served and withdrew is never minted again. | ||
| UuidV8: | ||
| ADR-008 profile C UUIDv8 (version 8, variant 10) of `github.com/<owner>/<name>` at the repository's birth path, in the domain that minted it (`minted_in`; owner ruling V9). Minted once and never changed (ADR 0008): a move or rename changes `github` only, and a placement change never touches it. The birth path is not served. An id the registry once derived and withdrew is never minted again. No UUIDv5 is served: `/v1` was reset to this shape before its first deploy (ADR 0004 amendment, 2026-11-14). |
There was a problem hiding this comment.
Update the remaining identity documentation
The new contract says /v1 serves only a UUIDv8 in uuid, but the primary README still tells consumers that uuid is UUIDv5, uuid_v8 is served alongside it, and /v2 will perform this migration (README.adoc:103-110); docs/wikis/Core-Concepts.adoc:29-32 and docs/governance/RELEASE-RUNBOOK.adoc:94-96 repeat the obsolete shape. Anyone using those entry-point documents will build against fields this commit removes, so they should be updated as part of the reset.
Useful? React with 👍 / 👎.
| description: >- | ||
| ADR-008 profile C UUIDv8 of `github.com/<owner>/<name>` at the birth path, in the `gv-clade-index` domain (owner ruling D320). Added beside `uuid` under the additive-only `/v1` rule (ADR 0004); `/v2` makes it the `uuid`. Like `uuid`, it is minted once and never changed (ADR 0008). A deed carries it as an opaque value, not as the path it was derived from. | ||
| Where the repo sits in one of the registry's classification schemes (A7 W10). An identity fact, never the id and never an edict. Exactly one placement per scheme is primary; the others carry a rank 1..n. | ||
| required: [scheme, category] |
There was a problem hiding this comment.
Encode the placement discriminator in the schema
Although the description requires each placement to be either the primary entry or a ranked entry, the schema requires only scheme and category, so OpenAPI validators and generated clients accept {scheme, category} as well as objects containing both primary and rank. Those values cannot reliably represent the model and the former is silently ignored by primaryClade(). Model the two alternatives with a oneOf that requires exactly primary or rank so the authoritative contract detects malformed responses.
Useful? React with 👍 / 👎.
| # Placements in the classification schemes of the seed (A7 W10). Today it | ||
| # declares one scheme, clade-12: the primary placement first, then the | ||
| # ranked ones in rank order. | ||
| placements = sprintf("{\"scheme\":\"clade-12\",\"category\":\"%s\",\"primary\":true}", primary) |
There was a problem hiding this comment.
Preserve placements from every declared scheme
When the seed declares a second classification scheme, its placements pass scheme/category validation but are discarded by sync/parse-repos.js:157, and this exporter then reconstructs only hard-coded clade-12 entries. The new generic placements API therefore silently omits every valid non-clade placement even though the schema describes placements across the registry's schemes. Export the structured placement clauses rather than rebuilding them from the legacy primary/secondary columns.
Useful? React with 👍 / 👎.
| command -v uuidgen >/dev/null 2>&1 \ | ||
| || { echo "export-json: uuidgen is required (package uuid-runtime / util-linux) for uuid" >&2; exit 1; } | ||
| if ! paste "$PARSED" "$BIRTH" "$IDS" | awk -F'\t' ' | ||
| if ! paste "$PARSED" "$BIRTH" "$IDS" "$DOMAINS" | awk -F'\t' ' |
There was a problem hiding this comment.
Preflight uuidgen before writing output files
On a machine without uuidgen, this script now writes repos.json before failing later at the still-present retired-ID derivation on line 156. Because the exporter writes directly into worker/data, a failed run leaves the generated files partially updated or truncated; previously the removed command -v uuidgen check stopped before any output was touched. Restore the preflight (or stage all outputs atomically) while archived retired UUIDv5 values still require this command.
Useful? React with 👍 / 👎.
… types (#125) ## Summary This registers `hyperpolymath/affinescript` in the registry seed under the owner's rulings of 2026-11-19. The patch was prepared by the kyX CLADE thread, whose push was refused; this PR reapplies it on `main` `24625ff` and re-checks it. kyx#9 (the translator) and affinescript#800 (its chora) depend on it landing. The rulings, each made by selector: - **Id:** the profile C v8 of `chora-registry:github.com/hyperpolymath/affinescript`, which is `0858724e-265e-81d0-909b-05cf7e1b4b2d`, with `:minted-in chora-registry`. The owner also ruled in the A1 thread the same day that `gv-clade-index` "should not exist as it was renamed to chora-registry", so no new or late id is minted in the old domain. - **Lineage:** `satellite`, parent `nextgen-languages`. - **Placement:** `clade-12` `nl`, primary. It is provisional until the chora and CLADE data formats are fully mapped. ## Changes - `verisim/seed/chora-registry_praxis.deed`: adds the `(repo :name "affinescript" …)` record and raises `:total-repos` from 327 to 328. - `sync/parse-repos.js`: `LINEAGE` gains `hub` and `satellite`, the #122 lineage types named in standards `clade-to-repo-deed.adoc` §3. - `README.adoc`, `docs/developer/REPO-ONBOARDING.adoc`, `docs/wikis/Core-Concepts.adoc` and `docs/wikis/Glossary.adoc` list the two new lineage types. - `worker/data/index.json` and `worker/data/repos.json` are regenerated by `sync/export-json.sh`. ## RSR Quality Checklist ### Required - [x] Tests pass: `scripts/check-registry.sh` - [x] Code is formatted - [x] Linter is clean - [x] No banned language patterns - [x] No `unsafe` blocks without `// SAFETY:` comments (none) - [x] No banned functions - [x] SPDX license headers present on all new/modified source files (no new files; existing headers untouched) - [x] No secrets, credentials, or `.env` files included ### As Applicable - [x] Documentation updated for user-facing changes (the lineage lists) ## Testing - `printf 'hyperpolymath\taffinescript\tchora-registry\n' | bash sync/uuid-v8.sh` gives `0858724e-265e-81d0-909b-05cf7e1b4b2d`. - `sync/export-json.sh` regenerated `worker/data`. The output matches the kyX thread's patch line for line, apart from the `generated` timestamp. - `GV_BASE_REPOS_JSON=<main's repos.json> bash scripts/check-registry.sh` passes. Ids are unique. The archive holds 20 moved repos and 19 retired ids. All 327 repos of the base are still registered, followed by id, and their ids are unchanged. ## Follow-up (standards, A1) CHORA-SPEC L1 still says late pre-V9 registrations use `gv-clade-index`. The A1 thread reconciles L1 with the 2026-11-19 ruling in standards. The commit is unsigned: the platform's signing shim did not sign it. Per standards CLAUDE.md that does not block anything, and merging through the GitHub UI signs the merge commit. This PR is a draft for the owner to merge. --- _Generated by [Claude Code](https://claude.ai/code/session_0136P7ZoUeC49fDEvSwDNvuS)_ --------- Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>



Summary
The owner ruled by selector in the A1 thread on 2026-11-14 to reset
/v1before its first deploy (item d). This PR records that ruling as an amendment to ADR 0004.The Worker API has never been deployed. Every Worker Deploy run skipped the deploy step because there is no
CLOUDFLARE_API_TOKEN(run 24 at 57607d3 shows "Deploy (wrangler): skipped"). An estate code search found no caller of/v1outside this repo. ADR 0004's additive-only rule and 90-day window exist to protect published consumers, and there are none yet. So/v1changes in place, once, instead of being frozen in the clade model and replaced by/v2.Changes
Served shape (
repos.json,index.json,/v1/*)uuidis now the ADR-008 profile C UUIDv8 of the birth path. The newminted_infield names its domain:gv-clade-indexorchora-registry(V9).uuid_v8is dropped.cladeandsecondarybecomeplacements:[{scheme, category, primary: true} | {scheme, category, rank}], in the schemeclade-12(A7 W10).prefixed(the<clade>-<name>binomial) is dropped. A clade is a placement, never part of a name./c/{ref}resolves a canonical name or a uuid. TheCLADE-<binomial>form returns 404, and a test covers that./v1/llmreportsregistry: chora-registryand gives each result's name, uuid and placements./v1/repoand/cderiveclade_nameandclade_colourfrom the primary clade-12 placement.archive.jsonis internal and never served. Each moved repo now carries its v8uuid. A retired path keeps its v8 asuuid, and its v5 asuuid_v5, kept as a record only.Gate (
scripts/check-registry.sh)uuidmust equal the id the seed stores, and the derivation of the birth path inminted_in./v1.uuid_v8. So this PR passes against main'srepos.json: all 327 repos, ids unchanged.Planted tests
prefixed).uuid.Worker
worker/src/placements.js(primaryClade,cladeCodes) replaces everyrepo.cladeandrepo.secondary.Contract and docs
docs/api/openapi.yamlgoes to 2.0.0, with new schemasMintingDomainandPlacement.USER-API-GUIDE.adoc,verification/README.adocandCHANGELOG.adocare updated.Testing
bash scripts/check-registry.sh: PASS. WithGV_BASE_REPOS_JSONset to main'srepos.jsonit also passes (327 repos, followed by id).bash tests/check-registry-test.sh: PASS. 19 planted failures fire, and the positive cases pass.cd worker && bunx vitest run: 39/39.eslintandprettier --checkare clean.shellcheck -S warning: clean.redocly lint docs/api/openapi.yaml: valid, with the same 7 warnings as main.Not changed
These are recorded here, out of scope for this PR:
docs/SPEC-clade-verisim-portal.adocandverisim/schema/repo.vclstill describeprefixed-name. They are historical spec and schema.worker-deploy.ymlsets up Node.js. Bun is the estate's tier-1 runtime.chora-registry_chora.deedstill carries:prefixed-name, whichclade-to-repo-deed.adocmaps. That belongs to the standards mapping, not to this API.This PR is a draft for the owner.
Generated by Claude Code