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 only identifiers with status: active in the pinned source catalog.
• Remove identifiers that leave the source catalog. Removed paths return 404.
• 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

Deploy locally with:

npm run build
npx wrangler deploy

GitHub Actions deployment

The .github/workflows/deploy-cloudflare-workers.yml workflow deploys public/ to Cloudflare Workers on pushes to main and on manual dispatch. 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 runs npm run smoke:problem-routes, which fetches every active problem identifier from the same vendored catalog against the live host and fails the deployment if any of them does not return HTTP 200.

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.

The scheduled smoke-live.yml workflow checks representative active problem, schema, and vocabulary identifiers, plus the absence of one removed namespace. Availability is monitored after publication and is not a Registry Stack source-build gate. The post-deploy smoke:problem-routes step in deploy-cloudflare-workers.yml is narrower and exhaustive rather than representative: it checks every active problem identifier, every time.