Skip to content

feat(api)!: reset /v1 to the chora model before its first deploy - #122

Merged
hyperpolymath merged 2 commits into
mainfrom
a1/v1-chora-shape
Nov 15, 2026
Merged

hyperpolymath merged 2 commits into
mainfrom
a1/v1-chora-shape

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

Summary

The owner ruled by selector in the A1 thread on 2026-11-14 to reset /v1 before 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 /v1 outside this repo. ADR 0004's additive-only rule and 90-day window exist to protect published consumers, and there are none yet. So /v1 changes in place, once, instead of being frozen in the clade model and replaced by /v2.

Changes

Served shape (repos.json, index.json, /v1/*)

  • uuid is now the ADR-008 profile C UUIDv8 of the birth path. The new minted_in field names its domain: gv-clade-index or chora-registry (V9).
    • No UUIDv5 is served, and uuid_v8 is dropped.
  • clade and secondary become placements: [{scheme, category, primary: true} | {scheme, category, rank}], in the scheme clade-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. The CLADE-<binomial> form returns 404, and a test covers that.
  • /v1/llm reports registry: chora-registry and gives each result's name, uuid and placements.
  • /v1/repo and /c derive clade_name and clade_colour from the primary clade-12 placement.

archive.json is internal and never served. Each moved repo now carries its v8 uuid. A retired path keeps its v8 as uuid, and its v5 as uuid_v5, kept as a record only.

Gate (scripts/check-registry.sh)

  • uuid must equal the id the seed stores, and the derivation of the birth path in minted_in.
  • It refuses any field retired from /v1.
  • The never-removed check (section 7) follows a base from before the reset by its uuid_v8. So this PR passes against main's repos.json: all 327 repos, ids unchanged.

Planted tests

  • Case 5 now plants a retired field (prefixed).
  • The birth-id and remint cases use v8.
  • The V9 case reads uuid.

Worker

  • The new worker/src/placements.js (primaryClade, cladeCodes) replaces every repo.clade and repo.secondary.
  • Data tests now check: one primary clade-12 placement; ranked, distinct, valid others; no retired field; v8 ids with a known domain.
  • New resolver tests cover name and uuid lookup, and the 404 for a binomial.

Contract and docs

  • docs/api/openapi.yaml goes to 2.0.0, with new schemas MintingDomain and Placement.
  • ADR 0004 gains the amendment.
  • USER-API-GUIDE.adoc, verification/README.adoc and CHANGELOG.adoc are updated.

Testing

  • bash scripts/check-registry.sh: PASS. With GV_BASE_REPOS_JSON set to main's repos.json it 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. eslint and prettier --check are 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.adoc and verisim/schema/repo.vcl still describe prefixed-name. They are historical spec and schema.
  • worker-deploy.yml sets up Node.js. Bun is the estate's tier-1 runtime.
  • chora-registry_chora.deed still carries :prefixed-name, which clade-to-repo-deed.adoc maps. That belongs to the standards mapping, not to this API.

This PR is a draft for the owner.


Generated by Claude Code

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
@hyperpolymath
hyperpolymath marked this pull request as ready for review November 15, 2026 00:13
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T00:19:39.181377Z 1d87a5a Draft marked ready
🔒 Security Review ✅ Completed 2026-11-15T00:17:26.040031Z 1d87a5a Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@sonarqubecloud

Copy link
Copy Markdown

Repository owner deleted a comment from coderabbitai Bot Nov 15, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/api/openapi.yaml
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).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread docs/api/openapi.yaml
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]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread sync/export-json.sh
# 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)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread sync/export-json.sh
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' '

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

@hyperpolymath
hyperpolymath merged commit 09ef283 into main Nov 15, 2026
16 checks passed
@hyperpolymath
hyperpolymath deleted the a1/v1-chora-shape branch November 15, 2026 00:22
hyperpolymath added a commit that referenced this pull request Nov 19, 2026
… 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants