Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,20 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning].

=== [Unreleased]

==== Changed (breaking, before the first deploy)

* *`/v1` reset to the chora model* (ADR 0004 amendment, owner ruling of
2026-11-14). `/v1` was never deployed, so it changes in place:
** `uuid` is the UUIDv8 of the birth path; `minted_in` names its domain
(`gv-clade-index` or `chora-registry`). No UUIDv5 is served and
`uuid_v8` is gone.
** `clade` and `secondary` become `placements`
(`[{scheme, category, primary|rank}]`, scheme `clade-12`).
** `prefixed` is gone; `/c/{ref}` resolves a canonical name or a uuid, not
a `CLADE-<binomial>`.
** `/v1/llm` reports `registry: chora-registry`.
** `docs/api/openapi.yaml` 2.0.0.

==== Added

* *`uuid_v8` on every registry entry* (standards ADR-008, owner ruling
Expand Down
10 changes: 5 additions & 5 deletions docs/USER-API-GUIDE.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,8 @@ policy and its rationale are ADR 0004.
|Repos matching a tag/keyword (VeriSimDB-backed)
|yes

|`GET /c/{binomial}`
|Resolve a `CLADE-<binomial>` autolink — 302 to the portal; `?format=json` for data
|`GET /c/{ref}`
|Resolve a repo by canonical name or uuid — 302 to the portal; `?format=json` for data
|no
|===

Expand All @@ -100,7 +100,7 @@ List everything filed under Formal Verification & Proofs:

[source,bash]
----
curl -s "$BASE/v1/repos?clade=fv&limit=200" | jq '.total, (.repos[] | .prefixed)'
curl -s "$BASE/v1/repos?clade=fv&limit=200" | jq '.total, (.repos[] | .name)'
----

Find repos by substance:
Expand All @@ -117,11 +117,11 @@ The LLM-friendly shape (what you want when feeding another model):
curl -s "$BASE/v1/llm?q=reversible%20file%20operations" | jq '.results[].repo'
----

Resolve a `CLADE-` autolink the way GitHub issues do:
Resolve a repo by name or uuid:

[source,bash]
----
curl -s "$BASE/c/fv-haec?format=json" | jq '{name, clade, github_url}'
curl -s "$BASE/c/haec?format=json" | jq '{name, uuid, placements, github_url}'
----

== Responses & errors
Expand Down
95 changes: 57 additions & 38 deletions docs/api/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema

info:
title: Clade Registry API
version: 1.3.0
version: 2.0.0
summary: >-
Read-only registry mapping the hyperpolymath ecosystem's repositories to
clade groupings. Map and territory — this is the map.
Expand Down Expand Up @@ -102,7 +102,7 @@ tags:
- name: query
description: VeriSimDB-backed attribute queries (rate-limited)
- name: resolver
description: CLADE-<binomial> autolink resolution
description: Repo resolution by canonical name or uuid

security: [] # PUBLIC tier today; per-operation overrides below when tiers land

Expand Down Expand Up @@ -241,10 +241,11 @@ paths:
get:
tags: [registry]
operationId: getRepo
summary: Single repo detail (canonical name or prefixed binomial)
summary: Single repo detail (canonical name)
description: |
Resolves by canonical name (`haec`) — the prefixed binomial
(`fv-haec`) is accepted by `/c/{binomial}`, not here. Adds
Resolves by canonical name (`haec`); `/c/{ref}` also accepts the
repo's uuid. `clade_name` and `clade_colour` describe the primary
clade-12 placement. Adds
`clade_name`, `clade_colour`, `github_url` and `portal_url` to the
base repo record.
parameters:
Expand Down Expand Up @@ -364,8 +365,8 @@ paths:
operationId: llmSearch
summary: Structured output optimised for LLM consumption (rate-limited)
description: |
Top 10 matches, each reduced to the fields an LLM needs (binomial,
summary, clade, canonical URLs), plus inferred `relationships` between
Top 10 matches, each reduced to the fields an LLM needs (name, uuid,
summary, placements, canonical URLs), plus inferred `relationships` between
result rows (currently `same-clade` groupings when ≥2 results share a
clade). This is the endpoint the LLM tier will upgrade in Phase 5
(API-key auth + higher limits); today it is public.
Expand Down Expand Up @@ -461,21 +462,22 @@ paths:
schema: { $ref: '#/components/schemas/Error' }
default: { $ref: '#/components/responses/ApiError' }

/c/{binomial}:
/c/{ref}:
get:
tags: [resolver]
operationId: resolveCladeRef
summary: Resolve a CLADE-<binomial> autolink
operationId: resolveRepoRef
summary: Resolve a repo by canonical name or uuid
description: |
Resolves the estate's `CLADE-<binomial>` custom autolinks (e.g. an
issue mentioning `CLADE-fv-haec` links here). Looks up by prefixed
binomial first, then canonical name. Humans get a `302` to the portal
page; bots pass `?format=json` for the data inline.
Looks up by canonical name (`haec`), then by uuid. The prefixed
binomial (`fv-haec`) is retired with the old clade model (ADR 0004
amendment of 2026-11-14): a clade is a placement, never part of a
name. Humans get a `302` to the portal page; bots pass
`?format=json` for the data inline.
parameters:
- name: binomial
- name: ref
in: path
required: true
description: Prefixed binomial (`fv-haec`) or canonical repo name (`haec`)
description: Canonical repo name (`haec`) or the repo's uuid
schema:
type: string
minLength: 1
Expand Down Expand Up @@ -588,20 +590,40 @@ components:
CladeCode:
type: string
description: |
Two-letter clade code from the closed 12-code taxonomy: fv, nl, rm,
gv, db, ap, ix, dx, pt, ax, gm, sc. The letters abbreviate the clade
NAME (never the repo name) — see verisim/seed/clades.a2ml.
Two-letter category code of the clade-12 scheme: fv, nl, rm, gv, db,
ap, ix, dx, pt, ax, gm, sc. The letters abbreviate the category NAME
(never the repo name). The scheme is declared in
verisim/seed/chora-registry_praxis.deed.
enum: [fv, nl, rm, gv, db, ap, ix, dx, pt, ax, gm, sc]
Uuid:
type: string
format: uuid
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 👍 / 👎.

MintingDomain:
type: string
format: uuid
description: ADR-008 profile C domain that minted the id (V9). `gv-clade-index` for a repo born before V9 or registered late under L1; `chora-registry` for one born after V9.
enum: [gv-clade-index, chora-registry]
Placement:
type: object
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 👍 / 👎.

properties:
scheme:
type: string
description: Scheme id (today `clade-12`)
example: clade-12
category:
type: string
description: Category id in that scheme (for clade-12, a CladeCode)
example: fv
primary:
type: boolean
const: true
rank:
type: integer
minimum: 1
Iso8601:
type: string
format: date-time
Expand All @@ -613,29 +635,24 @@ components:
# ── core objects ──────────────────────────────────────────────────────
Repo:
type: object
required: [name, uuid, clade, secondary, lineage, prefixed, github]
required: [name, uuid, minted_in, placements, lineage, github]
properties:
name:
type: string
description: Canonical name — the registry's primary key
uuid: { $ref: '#/components/schemas/Uuid' }
uuid_v8: { $ref: '#/components/schemas/UuidV8' }
clade: { $ref: '#/components/schemas/CladeCode' }
secondary:
minted_in: { $ref: '#/components/schemas/MintingDomain' }
placements:
type: array
items: { $ref: '#/components/schemas/CladeCode' }
description: Zero or more secondary clade codes
items: { $ref: '#/components/schemas/Placement' }
description: The repo's placements, primary first, then by rank
lineage: { $ref: '#/components/schemas/RepoLineage' }
parent:
type: string
description: Parent repo name (empty when lineage is standalone)
description:
type: string
description: One-line substance description (may be empty)
prefixed:
type: string
description: '<clade>-<name> binomial used by CLADE- autolinks'
example: fv-haec
github:
type: string
description: '<owner>/<name> on GitHub'
Expand Down Expand Up @@ -810,22 +827,24 @@ components:
enum: [hyperpolymath]
registry:
type: string
enum: [gv-clade-index]
enum: [chora-registry]
results:
type: array
maxItems: 10
items:
type: object
required: [repo, canonical_name, summary, clade, lineage, github_url, portal_url]
required: [repo, uuid, summary, placements, lineage, github_url, portal_url]
properties:
repo:
type: string
description: Prefixed binomial (what CLADE- autolinks use)
canonical_name: { type: string }
description: Canonical repo name
uuid: { $ref: '#/components/schemas/Uuid' }
summary:
type: string
description: Repo description (may be empty)
clade: { $ref: '#/components/schemas/CladeCode' }
placements:
type: array
items: { $ref: '#/components/schemas/Placement' }
lineage: { $ref: '#/components/schemas/RepoLineage' }
github_url: { type: string, format: uri }
portal_url: { type: string, format: uri }
Expand Down
25 changes: 25 additions & 0 deletions docs/decisions/0004-api-versioning.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,28 @@ Evolution policy within the major version:
frozen.
* When Phase 5+ adds authenticated endpoints, they join `/v1` (additive);
auth-tier changes are governed by the same additive-only rule.

== Amendment 2026-11-14: `/v1` reset before its first deploy

Owner ruling of 2026-11-14, by selector in the standards A1 thread.

The additive-only rule exists to protect published consumers. `/v1` has never
been published: every Worker Deploy run skipped the deploy step for want of
`CLOUDFLARE_API_TOKEN`, and no code in the estate calls the API. So `/v1` is
reset to the chora model once, before its first deploy, rather than frozen in
the clade model and replaced by `/v2`:

* `uuid` is the ADR-008 profile C UUIDv8 of the birth path, in the domain
that minted it, served as `minted_in` (standards CHORA-SPEC V9). No UUIDv5
is served; `uuid_v8` is dropped, because `uuid` now is that id.
* `clade` and `secondary` become `placements`: the repo's placements in the
registry's classification schemes (A7 W10), today the scheme `clade-12`.
* `prefixed` (the `<clade>-<name>` binomial) is dropped: a clade is a
placement, never part of a repo's name. `/c/{ref}` resolves a canonical
name or a uuid; the `CLADE-<binomial>` autolink form is retired.
* `/v1/llm` reports `registry: chora-registry` and gives each result's name,
uuid and placements.
* `docs/api/openapi.yaml` goes to 2.0.0.

From the first deploy on, the rules above hold unchanged: `/v1` is
additive-only and a breaking change ships as `/v2`.
Loading
Loading