Registry Stack identifiers

This repository prepares the static site for https://id.registrystack.org/. It hosts stable machine identifiers owned by Registry Stack: problem type URIs, JSON-LD namespaces and vocabularies, JSON Schemas, JSON-LD contexts, and response profiles.

The authoritative current-source catalog lives in the registry-stack repository under products/identifiers/. This repository is the exact-source publisher. src/upstream/source.json pins the exact Registry Stack commit and catalog SHA-256 digest that supplied every published record. Deployment also requires that commit to be an ancestor of Registry Stack main, so a pull-request branch commit is never accepted as final provenance.

Deployment is configured for Cloudflare Workers Static Assets with:

• Worker name: registrystack-id
• Build command: npm run build
• Asset directory: public
• Route: id.registrystack.org/*

Identifier policy

Published identifiers are stable contracts.

• Do not repurpose an identifier after publication.
• Publish identifiers in the pinned source catalog as active.
• Preserve a previously published identifier that leaves the active source catalog and mark its last reviewed record deprecated. Never reuse its URI for another kind or meaning.
• Do not change an identifier's kind.
• Use lowercase product scopes in paths.
• Use code for programmatic branching in client code. Problem type URLs are identifiers and documentation pointers, not a parsing interface.
• Keep generated static files in sync with src/catalogs/.
• Publish imported schema, context, and profile bytes at their canonical URI and at an immutable SHA-256 artifact URI, each served with the content type its kind defines.
• Resolve Relay V2's authored vocab/core/<field> predicates to the governed core vocabulary record. The record states that child terms are adopter-owned and that resolution does not register or review a child term.

Content quality rules

This site is an identifier resolver, not a replacement for the product docs. Generated pages may summarize existing public facts and link to documentation, but they must not introduce new runtime guarantees unless those guarantees are backed by source code, tests, schemas, or published product documentation.

Problem pages separate:

• Defined facts: canonical URI, product, code, category when known, and source.
• Documentation links: public Registry Stack docs that remain authoritative for operational behavior.
• Guidance: explicitly marked as not_published unless it has been curated.

Problem records deliberately leave http_statuses, retryable, caller_action, and operator_action as null when the resolver has no curated value. Clients should use the RFC 9457 response body, especially code, status, and detail, for request-specific behavior.

Site design

Human pages share one stylesheet and self-hosted font subsets (Public Sans, IBM Plex Mono) kept in src/assets/, following the registrystack.org design system. They are publisher-owned presentational machinery, not identifiers: npm run import:catalog never touches them, the build copies them to public/assets/, and the stylesheet is served under a content-hashed filename so it can cache safely. The OFL font licenses are kept beside the fonts in src/assets/fonts/.

HTML pages carry noindex: the resolver is reached by following identifiers from responses and documentation, not by search, and human explanations stay with the product docs. Machine artifacts, catalogs, and llms.txt are unaffected.

Local workflow

Import the catalog and artifacts from an exact Registry Stack commit:

npm run import:catalog -- ../registry-stack --source-revision <full-commit>

Verify the vendored catalog against a checkout of that same commit:

npm run check:upstream -- ../registry-stack

Regenerate public/, run the exact-catalog import tests, and compare every generated byte:

npm run build
npm test

npm test also runs npm run check:problem-routes, which reads every kind: "problem" entry from the vendored src/upstream/catalog.v1.json and asserts that its canonical URI has a matching route under public/, with no live network dependency. It checks every other entry that publishes bytes the same way: the artifact at its canonical URI, the page beside it, and the immutable copy under artifacts/sha256/. That vendored copy is the one npm run import:catalog refreshes; there is no other check step here that talks to Registry Stack directly.

npm run report:catalog -- <base-ref> renders the added, removed, metadata- updated, and artifact-updated identifier sets for review.

Cloudflare Workers preparation

The repository includes wrangler.jsonc so Wrangler deploys public/ as Workers static assets on the registrystack-id service. The compatibility date is pinned because Wrangler does not store the dashboard's Latest compatibility-date setting in source control.

The generated public/_headers file sets content types, CORS for machine artifacts, immutable caching for SHA-256 artifact paths, and conservative cache headers for canonical identifiers. The generated public/_redirects file reserves compatibility routes that can be expanded later without changing the identifier policy.

Cloudflare setup

The Cloudflare account is configured with:

• Worker name: registrystack-id
• Static assets source: public/
• Worker preview URL: https://registrystack-id.jeremi-ccf.workers.dev/
• DNS record: proxied AAAA id -> 100::
• Worker route: id.registrystack.org/* in the registrystack.org zone

Build a local deployment candidate with:

npm run build
npx wrangler deploy

Do not use that command to publish a Registry Stack release. Production publication is owned by the release workflow described below.

GitHub Actions deployment

The .github/workflows/deploy-cloudflare-workers.yml workflow deploys the reviewed bundle committed to main only when Registry Stack release publication dispatches it with an exact annotated release tag, source commit, catalog SHA-256, and correlation ID. The committed src/upstream/source.json must match those inputs. The workflow verifies that bundle against the tagged source before it builds or deploys. It does not deploy on a publisher repository push, and it does not import unreviewed source during deployment. Configure these repository secrets before enabling it:

• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_API_TOKEN scoped to deploy the registrystack-id Worker and its existing route. The workflow does not edit DNS.

The initial deployment, DNS record, and Worker route were created manually from the Cloudflare dashboard.

After each deployment, the workflow fetches every active and deprecated identifier in the reviewed publisher catalogs plus every retained immutable artifact. It compares the live response with the generated bytes and expected media type, then checks representative compatibility routes.

Registry Stack needs one fine-grained IDENTIFIER_PUBLISHER_TOKEN repository secret with Actions read/write access only to registrystack/registrystack-id. Its release workflow uses the token to dispatch this workflow and wait for the correlated run. The Cloudflare credentials remain only in this repository.

To recover an interrupted publication, rerun the failed Registry Stack release workflow. An already-public exact release takes its read-only closeout path and dispatches the same tag, source commit, and catalog digest again. Alternatively, dispatch this workflow from main with all four recorded inputs. Never change the source commit or digest for a released tag; fix forward with a new release if immutable public bytes conflict.

The ci.yml workflow checks every pull request against the exact pinned Registry Stack commit, rebuilds the site, runs a local availability smoke, and lints the workflows.

The sync-registry-stack.yml workflow checks Registry Stack main each day and on manual dispatch. Enable Allow GitHub Actions to create and approve pull requests in this repository's Actions workflow permissions. The sync job uses GitHub's temporary repository token with Contents, Pull requests, and Actions write permissions; no separate synchronization secret is required. It imports the exact merged commit, verifies it, and opens or updates a draft synchronization pull request. Because token-created pushes do not trigger CI and pull-request runs may require approval, it explicitly dispatches publisher CI on the synchronization branch. The job does not approve or merge its pull request and grants no Cloudflare or DNS authority. The synchronization branch is automation-owned; human changes must go to Registry Stack source or a separate publisher branch.

Before tagging a Registry Stack release, merge a reviewed synchronization pull request whose pinned commit and catalog digest are the exact release source. The later release dispatch will fail closed if main contains another bundle.

The scheduled smoke-live.yml workflow repeats the exact-catalog smoke plus representative compatibility checks. Availability is monitored after publication and is not a Registry Stack source-build gate.