Architecture: Global Dataset Contract Registry rollout in fork

[lspassos1]

Summary

Track the fork-first rollout of the Global Dataset Contract Registry in lspassos1/worldmonitor before any upstream proposal. This issue owns the problem statement, rollout slices, invariants, validation bar, and upstream-readiness criteria.

Why one issue

This work is one architectural problem with a phased implementation. The issue should stay consolidated so the problem, success criteria, and rollout order live in one place. The implementation can still land as multiple focused PRs.

Problem

Bootstrap keys, health keys, seed metadata, and tier definitions drifted across manual maps in api/bootstrap.js, api/health.js, server/_shared/cache-keys.ts, and tests. That makes parity fixes and new dataset additions depend on synchronized edits across unrelated files.

Goals

• move dataset identity, bootstrap registration, health registration, and seed freshness expectations into a single authored source of truth
• generate deterministic edge/server artifacts from that source
• eliminate manual registry drift across runtime files and tests
• keep this phase compile-time and test-time only; no coordinator or runtime locking yet

Constraints

• fork-first only; no upstream proposal until the fork proves parity
• api/*.js must stay edge-safe and self-contained
• generated artifacts are read-only and deterministic
• behavioral parity comes before stricter enforcement

PR plan

1. chore(registry): stabilize dataset contract foundation and bootstrap parity
2. refactor(health): load generated health registry in fork
3. ci(registry): enforce generated registry freshness in fork
4. docs(registry): document full dataset workflow

Implementation checklist

• add registry/datasets.ts as the authored source of truth
• generate bootstrap artifacts for edge and server
• restore missing bootstrap aliases and parity with the pre-registry bootstrap set
• generate health artifacts and switch api/health.js to imports
• preserve health semantics for bootstrap/standalone grouping, seed freshness, on-demand keys, empty-ok keys, and cascade groups
• enforce npm run registry:check in pre-push and CI
• update docs for registry-first dataset additions
• update tests to assert against generated registries instead of deleted inline maps

Validation

• npm run registry:check
• node --test tests/bootstrap.test.mjs
• node --test tests/edge-functions.test.mjs
• npm run test:data
• npm run typecheck
• npm run typecheck:api

Upstream readiness

• generated artifacts are stable and deterministic
• no unresolved parity regressions remain in bootstrap, health, or seed freshness handling
• the rollout can be replayed upstream as a series of smaller focused PRs

[lspassos1]

Split the registry rollout into smaller fork-side PRs linked from this tracking issue:

• chore(registry): stabilize dataset contract foundation and bootstrap parity #10 chore(registry): stabilize dataset contract foundation and bootstrap parity
• refactor(health): load generated health registry in fork #11 refactor(health): load generated health registry in fork
• ci(registry): enforce generated registry freshness in fork #12 ci(registry): enforce generated registry freshness in fork
• docs(registry): document the full dataset workflow #13 docs(registry): document the full dataset workflow

The earlier combined PR #4 is being superseded so review can happen slice-by-slice.

[lspassos1]

Registry phase is complete in the fork.

Merged PR sequence:

• chore(registry): stabilize dataset contract foundation and bootstrap parity #10 chore(registry): stabilize dataset contract foundation and bootstrap parity
• refactor(health): load generated health registry in fork #11 refactor(health): load generated health registry in fork
• ci(registry): enforce generated registry freshness in fork #12 ci(registry): enforce generated registry freshness in fork
• docs(registry): document the full dataset workflow #13 docs(registry): document the full dataset workflow

Validation executed for the registry phase:

• npm run registry:check
• node --test tests/bootstrap.test.mjs
• node --test tests/edge-functions.test.mjs
• npm run test:data
• npm run typecheck
• npm run typecheck:api

Phase two is now tracked separately in:

• Architecture: distributed cache-fill coordinator rollout in fork #14 Architecture: distributed cache-fill coordinator rollout in fork
• C1: cache-fill coordinator foundation in fork #15 C1: cache-fill coordinator foundation in fork
• C2: enable coordinator for service statuses and risk scores #16 C2: enable coordinator for service statuses and risk scores
• C3: measure and tune cache-fill coordinator outcomes #17 C3: measure and tune cache-fill coordinator outcomes
• C4: migrate temporal anomalies off ad hoc Redis lock #18 C4: migrate temporal anomalies off ad hoc Redis lock