suaveplan/openspec/changes/schema-registry-completion/tasks.md

Tasks — Schema-registry completion

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Spec authoring

• 1.1 Read legacy packages/universal/schema-registry/src end-to-end at ../suaveplan/
• 1.2 Read genesis packages/core/schema-registry/src end-to-end and openspec/specs/ (no canonical schema-registry spec exists yet — this proposal seeds it)
• 1.3 Read openspec/AGENTS.md Sections 13 (spec-conformance audit), 14 (source mapping for migrations); §14a (proposal must list affected dependents); §0a (parity checklist)
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill ## Source mapping in proposal.md — every requirement cites a line range OR appears in the "no source line" table with justification
• 1.6 Draft specs/schema-registry/spec.md from openspec/templates/spec-delta.md — seven ADDED requirements (transitive, diff, store interface, memory store, database store, canonical utilities, subject config)
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles
• 1.8 Draft ## Migration section listing the CompatibilityLevel union widening and the new async constructor option
• 1.9 bunx openspec change validate schema-registry-completion exits with no errors

2. Implementation — types

• 2.1 Extend CompatibilityLevel in src/types/schema-registry.types.ts to include BACKWARD_TRANSITIVE, FORWARD_TRANSITIVE, FULL_TRANSITIVE
• 2.2 Add SchemaField interface in src/types/schema-registry.types.ts (legacy L15-L26); used by diff and canonical utilities
• 2.3 Add DiffChangeType union ("added" | "removed" | "modified")
• 2.4 Add SchemaDiffChange and SchemaDiffResult interfaces
• 2.5 Add TransitiveReport and TransitiveVersionResult interfaces
• 2.6 Add SubjectConfig interface (compatibility, maxVersions?, metadata?)
• 2.7 Add SchemaStoreAdapter interface (8 async methods per legacy L82-L105)
• 2.8 Add optional fingerprint?: string to SchemaDefinition

3. Implementation — utilities

• 3.1 Create src/utils/canonical/canonical.ts exporting canonicalizeSchema, computeFingerprint, djb2Hash, flattenFields, isOptionalOrHasDefault (legacy src/utils/utils.ts L1-L70 verbatim)
• 3.2 Sibling canonical.md ≥200 words with basic + advanced examples

4. Implementation — transitive compatibility

• 4.1 Create src/core/transitive/transitive.ts exporting checkTransitiveCompatibility(history, candidate, mode), buildTransitiveReport(history, candidate, mode), isTransitiveMode(mode), stripTransitive(mode)
• 4.2 Use the genesis checkCompatibility directly (do not duplicate the rules); transitive entry points iterate history and aggregate errors with [v<n>] prefixes (legacy convention, L31)
• 4.3 Sibling transitive.md ≥200 words

5. Implementation — diff

• 5.1 Create src/core/diff/diff.ts exporting diffSchemas(oldSchema, newSchema) and formatDiffReport(result) (legacy src/diff/schema-differ.ts L1-L175 verbatim)
• 5.2 Use flattenFields from canonical utilities; never duplicate the field-walking logic
• 5.3 Sibling diff.md ≥200 words

6. Implementation — stores

• 6.1 Create src/store/memory/memory.ts exporting MemorySchemaStore implementing SchemaStoreAdapter against an in-memory Map<string, SchemaDefinition[]> for versions and Map<string, SubjectConfig> for configs
• 6.2 Create src/store/database/database.ts exporting DatabaseSchemaStore<TAdapter extends DatabaseAdapter> (legacy src/store/database-store.ts L1-L147)
• 6.3 Add @suaveplan/db to packages/core/schema-registry/package.json dependencies (workspace:^); verify STATUS.md lists @suaveplan/db as completed (it is — db-sqlite is shipped)
• 6.4 Re-target the DatabaseAdapter import in the database store to @suaveplan/db (legacy used an inline interface)
• 6.5 Sibling memory.md and database.md ≥200 words each

7. Implementation — registry async surface

• 7.1 Extend SchemaRegistry constructor to accept store?: SchemaStoreAdapter in RegistryOptions
• 7.2 When store is supplied, route persistence through the store; gate sync method calls with SchemaRegistryError(SCHEMA_REGISTRY.STORE_FAILURE, ..., { context: { reason: "sync_call_on_async_store" } })
• 7.3 Add async siblings: registerAsync, getLatestAsync, getVersionAsync, getAllAsync, listSubjectsAsync, deleteSubjectAsync, checkCompatibilityAsync
• 7.4 In register / registerAsync, compute fingerprint = computeFingerprint(schema as SchemaDefinition) when format === "json-schema" and the schema matches SchemaDefinition shape; stamp it onto the resulting SchemaDefinition
• 7.5 De-dup: if the latest version's fingerprint equals the candidate's fingerprint, return the existing version (no new version assigned)
• 7.6 Wire the new *_TRANSITIVE modes into the existing register flow: when state.compatibility ends with _TRANSITIVE, call checkTransitiveCompatibility(state.versions, schema, state.compatibility) instead of checkCompatibility(schema, latest, ...)
• 7.7 Validate setCompatibility(subject, level) against the seven-mode union; throw SchemaRegistryError(SCHEMA_REGISTRY.UNKNOWN_COMPATIBILITY_MODE, ...) on invalid input

8. Errors

• 8.1 Add STORE_FAILURE and UNKNOWN_COMPATIBILITY_MODE to SCHEMA_REGISTRY_CODES in src/errors/schema-registry-error.ts
• 8.2 Update sibling schema-registry-error.md to document the two new codes

9. Wiring

• 9.1 Update packages/core/schema-registry/src/index.ts to re-export every new symbol (transitive helpers, diff, stores, canonical utilities, types)
• 9.2 Update packages/core/schema-registry/package.json exports map: add ./transitive, ./diff, ./store/memory, ./store/database, ./utils/canonical subpath entries
• 9.3 Update root README.md ## Modules section to link the new co-located .md files
• 9.4 Update the package description in package.json to mention transitive compatibility, diff, and pluggable stores

10. Tests

• 10.1 src/core/transitive/transitive.test.ts — multi-version history; BACKWARD_TRANSITIVE rejects when ANY old version disagrees; FORWARD_TRANSITIVE and FULL_TRANSITIVE analogous; per-version error prefixes [v1], [v2], ...
• 10.2 src/core/transitive/transitive.spec-conformance.test.ts — exhaustive isTransitiveMode / stripTransitive over all seven CompatibilityLevel values
• 10.3 src/core/diff/diff.test.ts — added / removed / modified / type-changed; nested-field diff; formatDiffReport rendering with [BREAKING] annotation
• 10.4 src/core/diff/diff.spec-conformance.test.ts — fast-check property diffSchemas(a, a).changes === []; formatDiffReport empty result text
• 10.5 src/store/memory/memory.test.ts — round-trip every method of SchemaStoreAdapter; deleteSubject returns false when subject absent
• 10.6 src/store/memory/memory.spec-conformance.test.ts — pins the contract (every method present, every method async)
• 10.7 src/store/database/database.test.ts — against a fake DatabaseAdapter that records SQL; verifies INSERT / SELECT / DELETE issued correctly with positional params
• 10.8 src/store/database/database.spec-conformance.test.ts — error path: db.query rejects → STORE_FAILURE raised with cause-chain preserving the original error
• 10.9 src/utils/canonical/canonical.test.ts — canonicalizeSchema sorts at every level; computeFingerprint deterministic; djb2Hash matches known vectors; flattenFields produces dot-paths; isOptionalOrHasDefault truthy/falsy
• 10.10 src/utils/canonical/canonical.spec-conformance.test.ts — fast-check property canonicalizeSchema(a) === canonicalizeSchema(shuffleFields(a)) (canonicalisation is field-order independent)
• 10.11 Extend src/core/registry/schema-registry.test.ts — async surface end-to-end with MemorySchemaStore; verify register de-dup based on fingerprint; verify transitive mode triggers transitive checker
• 10.12 Extend src/core/registry/schema-registry.spec-conformance.test.ts — UNKNOWN_COMPATIBILITY_MODE thrown for invalid setCompatibility; STORE_FAILURE thrown when sync method called on store-backed registry
• 10.13 Every it(...) in 10.1-10.12 carries { timeout: 5000 }

11. Documentation

• 11.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 11.2 README links every co-located .md under ## Modules
• 11.3 README ## Features enumerates the seven new capabilities (transitive, diff, store interface, memory store, database store, canonical utilities, subject config)
• 11.4 Update CLAUDE.md package listing for @suaveplan/schema-registry to include the new exports

12. Pre-archive verification (the 5-gate triple)

• 12.1 bun run check — Biome 0 errors / 0 warnings / 0 info across the whole monorepo
• 12.2 bunx turbo lint typecheck test --filter=@suaveplan/schema-registry — green
• 12.3 bunx turbo test:coverage --filter=@suaveplan/schema-registry — 100/100/100/100
• 12.4 bun scripts/openspec-conformance.ts @suaveplan/schema-registry — exit 0, no error findings
• 12.5 bunx turbo build --filter=@suaveplan/schema-registry — green

13. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 13.1 Generics threaded; expectTypeOf assertions on every literal-type claim (CompatibilityLevel widened, SCHEMA_REGISTRY_CODES keys, DiffChangeType literals)
• 13.2 Zod schemas wired at every declared boundary (SchemaDefinition, SubjectConfig, SchemaField, RegistryOptions extended)
• 13.3 Every error code in SCHEMA_REGISTRY_CODES thrown by at least one production path (STORE_FAILURE and UNKNOWN_COMPATIBILITY_MODE covered above; existing four codes remain in place)
• 13.4 Strict-mode behaviors tested on and off (transitive vs. non-transitive, store-backed vs. in-memory)
• 13.5 OTel instruments emitted from production paths and asserted with InMemorySpanExporter from @suaveplan/opentelemetry (the register.total counter and check.duration_ms histogram are already in place; new transitive/store paths should record to the same instruments)
• 13.6 Lifecycle dedup tested where claimed (re-register identical schema → fingerprint match → same SchemaDefinition returned, no version increment)
• 13.7 No retroactive tick — every box above reflects work done in this change

14. Dependent sweep

• 14.1 bunx turbo test --filter=...@suaveplan/schema-registry — green; @suaveplan/events-schema continues to pass
• 14.2 Search dependents for exhaustive switch over CompatibilityLevel: grep -rln "CompatibilityLevel" packages/ src/. For each hit, verify the switch handles the three new transitive arms (or falls through to the corresponding non-transitive arm)
• 14.3 Search dependents for SchemaRegistry constructor: grep -rln "new SchemaRegistry\|createRegistry" packages/ src/. None should require code changes — the new option is additive

15. Archive

• 15.1 Fold specs/schema-registry/spec.md into openspec/specs/schema-registry/spec.md (this seeds the canonical capability spec, since one does not yet exist)
• 15.2 Move openspec/changes/schema-registry-completion/ → openspec/archive/<yyyy-mm-dd>-schema-registry-completion/
• 15.3 Refresh MANIFEST.md (this change adds @suaveplan/db as a dep)

Audit Note (2026-05-02)

Audit verdict: DEFERRED — 0/78 tasks evidenced in code.

Evidence reviewed:

• packages/core/schema-registry/src/ has only core/{registry,compatibility}, errors/, types/, constants/. No core/transitive/, no core/diff/, no store/, no utils/canonical/.
• types/schema-registry.types.ts CompatibilityLevel does not include *_TRANSITIVE arms (verified by absence of any matching directory or test).
• No @suaveplan/db dependency in package.json (DatabaseSchemaStore depends on it).

Missing pieces:

1. Transitive compatibility (core/transitive/) and the seven-mode CompatibilityLevel widening.
2. Schema diff engine (core/diff/) + formatDiffReport.
3. Canonical schema utilities (utils/canonical/), SchemaStoreAdapter interface, MemorySchemaStore, DatabaseSchemaStore<TAdapter> (requires adding @suaveplan/db dep), the async surface on SchemaRegistry, and the two new error codes.

Decision: leave change open. New canonical spec file + dep graph change + async API surface require focused implementation work.