WFT-6: Registry Snapshot Version 2

[stevekinney]

What / Why

Implements WFT-6: advances GET /v1/registry (weft.system.registry) from registryVersion: 1 to 2. workflows becomes a sorted array of WorkflowRevisionManifest (WFT-5's canonical contract vocabulary, PR #943) instead of a flat Record<name, entry>, and a new activeRevisions: Record<name, revision> map points each workflow name at its currently active manifest. A new generatedAt field reports an informational ISO-8601 timestamp. activities is unchanged. Weft is pre-release, so registryVersion: 1 is rejected outright — producers and consumers are updated together in this one PR, with no v1 compatibility layer.

Acceptance criteria (WFT-6)

• Registry snapshot returns v2 shape — REGISTRY_VERSION = 2; RegistrySnapshot.workflows is readonly WorkflowRevisionManifest[], activeRevisions: Readonly<Record<string,string>>, generatedAt: string. Proven by packages/weft/src/core/registry-snapshot.test.ts ("returns registryVersion 2", "includes workflows with their schema, description, and tags", "generatedAt reflects the injected clock") and packages/weft/src/server/operations/get-registry.test.ts ("returns the snapshot for a populated engine").
• Snapshot output is deterministic across repeated generation — generatedAt excluded from determinism; two calls with the same injected clock produce byte-identical output. Proven by registry-snapshot.test.ts ("two consecutive buildRegistrySnapshot calls produce identical output apart from generatedAt") and packages/weft/src/cli/codegen.test.ts ("codegen output is identical for two snapshots differing only in generatedAt").
• Ordering is deterministic by workflow name and revision — workflows sorted by (name, revision) via the new exported compareWorkflowManifests. Proven by registry-snapshot.test.ts ("orders workflow manifests alphabetically by name") and a direct unit test of the comparator's tiebreak ("compareWorkflowManifests breaks ties on revision when names are equal" — unreachable through the engine itself, since one workflow name has exactly one registration).
• Console and clients consume the same registry snapshot version — packages/weft-ui's registry-view.ts, codegen-preview-source.ts, registry-types.ts, and schedule-queries.ts (an additional real consumer found while implementing, reading activeRevisions for its workflow picker) all resolve activeRevisions[name] === manifest.revision the same way engine-side registry-contract-builder.ts and the new codegen-validate.ts do. Proven by the corresponding *.test.ts/*.svelte test files, and by bunx turbo run typecheck test --filter=@lostgradient/weft-ui passing (1434 pass / 0 fail).
• weft codegen keeps working on the v2 snapshot — validation split into a new codegen-validate.ts module (codegen.ts was already 460/500 lines): every workflows[] element is validated via WFT-5's parseWorkflowRevisionManifest (hostile-input bounds included), then projected to the active set. Proven by codegen.test.ts's full suite plus the new codegen-validate.test.ts (direct coverage of the activeRevisions-not-an-object and no-matching-manifest branches, which the CLI's own --from/--server paths can't reach on their own).
• No new failure mode silently masked — a registered workflow whose contract exceeds a WFT-5 hostile-input limit (which nothing in engine registration enforces) now throws the new RegistryManifestLimitError, logged with workflowType before the operation pipeline masks it as a generic 500. Proven by registry-snapshot.test.ts ("throws RegistryManifestLimitError...") and get-registry.test.ts's new masked-500 test asserting the log line via a console.error spy.
• Async-lifecycle correctness — buildRegistrySnapshot is now async (contract hashing is crypto.subtle-backed); the GET /v1/registry invoke path now awaits it, fixing a latent bug where the prior synchronous try/catch would have silently missed a rejected promise once the function became async. No torn/partial-manifest race is possible: engine.listWorkflowDefinitions()/listActivityDefinitions() are read synchronously in one eager pass before any await.

Deliberate behavior changes (documented in CHANGELOG.md / migration.md)

• A workflow's tags now come back alphabetically sorted on the wire (normalizeWorkflowContract sorts them), not in registration order.
• A hand-vendored weft codegen --from workflow entry with a boolean root schema is now rejected with a clear diagnostic instead of silently coarsened (activities keep that tolerance; their shape is unchanged).

Persisted-data schema decision

No change, no bump. GET /v1/registry is a derived, non-persisted introspection snapshot — no storage codec, WorkflowState, checkpoint, or effect-log shape is touched. Stated explicitly per the batch instructions so reviewers don't go looking for a migration.

Gates run (all green)

• bun run typecheck
• bun run lint (oxlint + check-lint-disables, check-implementation-file-sizes, check-import-cycles, check-internal-imports, check-engine-internals-field-access, check-definition-vocabulary, check-catalog-completeness, check-catalog-drift, check-type-ergonomics)
• bun run build
• bun test — 9916 pass / 0 fail / 55 skip (628 → 629 files, includes new codegen-validate.test.ts)
• bun run scripts/check-coverage.ts — 100.00% lines, 100.00% functions
• bun run verify:documentation
• bun run verify:jsdoc:full (audit-jsdoc-manifest, jsdoc doctests, jsdoc declarations, markdown doctests)
• bun run prepack — 9/9 gates, including validate-package-consumers.ts's packed-install regression suite
• packages/weft-ui: bun run typecheck && bun run lint && bun test — 1434 pass / 0 fail

Docs touched

• documentation/reference/api-server.md — new "Registry Snapshot" section (route, v2 shape, example JSON)
• documentation/reference/cli.md — rewrote the weft codegen paragraph describing the source snapshot shape
• documentation/guides/workflow-versioning.md — new "Discovering revisions at runtime" section linking activeRevisions/manifests to the existing Revision Identity guide
• CHANGELOG.md — [Unreleased] > Changed entry
• documentation/guides/migration.md — new "Unreleased" entry (see note below)

One deviation from the approved plan, with reason

The plan's RECOMMENDED ASSUMPTION was CHANGELOG-only, no migration.md entry, citing "WFT-5's own precedent." That premise turned out to be factually wrong: migration.md's ## Unreleased section already carries two WFT-5 entries (the buildWorkerManifestFromRegistry() digest-value change and the unversioned-workflow-default change) that I found while implementing. I followed the actual precedent instead of the stated one and added a WFT-6 entry to migration.md alongside the CHANGELOG entry.

Two small, honest fixes to shared gate scripts along the way, not scope creep — both required to get gates green and are called out here rather than buried:

• scripts/check-coverage.ts: the src/cli/codegen.ts coverage allowance's line numbers were stale after the file shrank (~460 → ~315 lines) from the codegen-validate.ts extraction; realigned to the current line numbers for the same underlying (OS/process-boundary-only) untestable branches, plus one new one this batch introduces (the emitter's CodegenEmitError catch is now provably unreachable through --from/--server, since codegen-validate.ts's manifest depth bound always fires first).
• scripts/check-package-contents.ts: bumped maximumEntryCount to the actual measured npm pack --dry-run count (1489) rather than the unverified "+2 per new file" formula's prediction (1487) — verified codegen-validate.ts itself contributes exactly the expected 2 dist entries; the remaining +2 is pre-existing drift from before this batch.

Finishing rounds (post-implementation review cycle)

Four additional commits landed after the initial implementation, closing out review threads across five rounds of the fetch → CI → threads → conflicts loop:

• 3b2a0886 — Fixed four Codex threads that had carried unbacked "Fixed" replies from a prior review pass (unbounded workflows/activeRevisions collections, silent duplicate-identity resolution via .find()), plus the two coordinator-mandated items: folded a workflow's .activities({...})-scoped registrations into its manifest's contractHash/revision via a new Engine.listWorkflowActivityDefinitions(), and root-caused the CI-only ui-coverage failure to a genuine timing race in schedule-form-drawer.test.ts (the registry query settling from undefined to [] after this PR made snapshot-building async flips a Select-vs-Input DOM branch depending on runner speed) — fixed at the source in schedule-form-fields.svelte, not with a CI workaround.
• fb4a7b15 — Aligned weft codegen's consumer-side 512-workflow ceiling with a matching producer-side check in buildRegistrySnapshot, sharing one constant (core/registry-limits.ts) so the two can never drift apart.
• 12bda02d — An incomplete first attempt at exempting buildWorkerManifestFromRegistry() from that new ceiling (an enforceWorkflowCountLimit escape hatch); superseded the same round by 3f88357e below once review caught that it only skipped the aggregate check, not the underlying full-snapshot build.
• 3f88357e — The actual fix: extracted per-workflow manifest building into core/registry-workflow-manifest.ts (buildWorkflowManifestForType) so buildWorkerManifestFromRegistry resolves only the workflows it's asked for, never touching an unrelated registration's contract or count at all. Also escaped a terminal-injection vector in parseWorkflowRevisionManifest's name-validation diagnostics, and split schedule-form-fields.svelte's free-text fallback message so a still-loading/unauthorized registry lookup is never described as "no registered workflows."

A weft-ui coverage-ratchet regression surfaced mid-way (adding a second free-text branch grew the file's line/function count faster than tests could cover it): resolved by collapsing the two Input branches into one with a conditional description, not by adjusting scripts/coverage-baseline.ts — the "add tests, never lower baselines" constraint held throughout.

All four finishing commits, all four resolved-thread batches (9 + 4 + 1 + 4 = 18 threads), and the full gate suite (typecheck, lint, test, 100% coverage, bun run validate, bun run prepack — both packages) are captured in the squash-merge commit body.

https://claude.ai/code/session_012pnZWYhy4bZehK8iHTZQMN

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-02T17:41:06.681177Z	3f88357	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 833a539259

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🔵 Needs a closer look

It is a breaking wire-shape change spanning the engine, generated clients, hostile-input validation, and a sibling package, so final human review is warranted despite the thorough tests and no functional bugs found.

Pull request overview

This PR implements WFT-6, advancing GET /v1/registry (weft.system.registry) from registryVersion: 1 to 2. The workflows field changes from a flat Record<name, entry> into a sorted array of WorkflowRevisionManifest (WFT-5's canonical contract vocabulary), paired with a new activeRevisions: Record<name, revision> pointer map and an informational generatedAt ISO-8601 timestamp. buildRegistrySnapshot becomes async (manifest hashing is crypto.subtle-backed), producers and consumers are updated together with no v1 compatibility layer, and a new RegistryManifestLimitError surfaces WFT-5 hostile-input limit violations that engine registration itself does not enforce.

Changes:

• Reshape the registry snapshot to v2 (manifest array + activeRevisions + generatedAt) and make buildRegistrySnapshot async with a new masked-500 limit error.
• Split weft codegen validation into a new codegen-validate.ts that parses each workflow manifest via parseWorkflowRevisionManifest and projects only the active revision.
• Update all consumers (server op, worker manifest builder, weft-ui registry/preview/schedule/start-wizard views) plus docs, CHANGELOG, migration guide, and gate scripts.

File summaries

File	Description
core/registry-snapshot.ts	Async builder, activeRevisions/generatedAt, RegistryManifestLimitError, compareWorkflowManifests, manifest projection
worker/manifest/registry-contract-builder.ts	Resolves active manifest from snapshot; drops the old workflowVersionsByType map
server/operations/get-registry.ts	v2 output schema, awaits the async builder, logs the new limit error before masking
cli/codegen.ts / codegen-validate.ts / codegen-emit.ts	Extracted manifest-aware validation; emitter now takes the active workflow projection
cli/generated/*, __fixtures__/codegen/registry.json	Regenerated client/catalog and v2 fixture
core/registry-snapshot.test.ts, get-registry.test.ts, codegen*.test.ts	Updated/added coverage incl. limit error and active-manifest resolution
weft-ui/** (registry-view, registry-types, codegen-preview-source, schedule-queries, start-wizard + tests)	Consume v2 manifest array via activeRevisions resolution
docs (api-server.md, cli.md, workflow-versioning.md, migration.md, CHANGELOG.md)	Document the v2 shape and deliberate behavior changes
scripts/check-coverage.ts, check-package-contents.ts, markdown-doctest-skip-counts.json	Realigned gate allowances

Review details

• Files reviewed: 33/35 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2ac2e27e32

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🔵 Needs a closer look

It is a breaking wire-contract change spanning the public registry snapshot, worker-manifest hashing, CLI codegen, and the UI, which warrants final human review despite only minor documentation nits being found.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

packages/weft/src/core/registry-snapshot.ts:310

• This comment justifies the null-prototype activeRevisions map by pointing to "the same rationale as workflows/activities below", but workflows is no longer a null-prototype Record — it is now the sortedManifests array, where a __proto__ workflow name is safe because it lives in each manifest's name field rather than as an object key. Only activities below still relies on the null-prototype technique. Consider dropping the stale workflows reference so the comment matches the v2 shape.

packages/weft/src/cli/codegen-validate.ts:169

• The detailed multi-paragraph JSDoc block here describes projecting each activeRevisions entry into an emitter-ready shape and the boolean-root-schema narrowing — behavior that belongs to resolveActiveWorkflowEntries (below), not parseAllManifests, which only parses manifests. As written, parseAllManifests carries two stacked JSDoc comments (this block plus the accurate one-line summary on the next line), so editors/tooling surface this inaccurate description for it, while resolveActiveWorkflowEntries has no doc comment at all. Consider moving this block to resolveActiveWorkflowEntries and keeping only the one-line summary on parseAllManifests.

/**
 * Parse every raw `workflows` array element as a {@link WorkflowRevisionManifest}
 * (hostile-input validated: bounded identifiers/entry counts/schema depth,
 * `contractHash` recomputed and compared — see `core/contract/manifest-parse.ts`),
 * then project the manifest named by each `activeRevisions` entry into the
 * `{ inputSchema?, outputSchema? }` shape {@link emitRegistryDeclaration}
 * consumes.
 *
 * A manifest in `workflows` with no matching `activeRevisions` entry
 * (a future installed-but-inactive revision) is silently excluded, not an
 * error — only the currently active manifest per name feeds codegen.
 *
 * Workflow schemas lose the boolean-root tolerance `RegistryActivityEntry`
 * keeps: `parseWorkflowRevisionManifest`'s schema-fragment parser requires a
 * JSON object at every `inputSchema`/`outputSchema` position, matching what
 * a real registry snapshot always produces (`definitionSchemaToJsonSchema`
 * never emits a boolean root). A hand-vendored `--from` file using a
 * boolean root schema is rejected with a clear diagnostic rather than
 * silently coarsened, a deliberate narrowing from v1 — see CHANGELOG.md.
 */
/** Parse every raw `workflows` array element, short-circuiting with an indexed diagnostic on the first hostile-input rejection. */

• Files reviewed: 33/35 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[stevekinney]

REQUEST CHANGES

Summary

This PR's actual code changes for the v2 registry snapshot shape (workflows-as-manifest-array, activeRevisions, generatedAt, RegistryManifestLimitError, deterministic ordering via compareWorkflowManifests, the async buildRegistrySnapshot lifecycle, and the four updated weft-ui consumers) are well-executed and well-tested where they exist — the async-lifecycle reasoning (definitions read synchronously before any await) is sound, the documentation updates (CHANGELOG.md, migration.md, api-server.md) are accurate against the code, and the __proto__-safety null-prototype pattern is applied consistently across every new map.

But this PR cannot merge as-is, for two independent reasons:

1. Both coordinator-flagged open items are still open. The ui-coverage CI check is still failing against the current head commit. I traced it by diffing the LCOV artifacts from this run against the main@9df859dc baseline run: the regression is not in any file this PR touches — it's a one-function drop in schedule-form-fields.svelte (untouched by this diff), which reads as inter-test flakiness rather than a gap this PR introduced. See the inline comment for the full trace; either way it needs to be run down, not routed around. Separately, the scoped-activity contractHash gap in registry-snapshot.ts — which the coordinator's batch guidance explicitly rejects deferring — has not been fixed; only a reply proposing to defer it exists.

2. Four of the five Codex/Copilot review threads on this PR carry replies from the implementer's account claiming a fix was made, when the described fix does not exist anywhere in the current diff or history. codegen-validate.ts's unbounded workflows array, unbounded activeRevisions map, and silent-first-match duplicate-identity handling were each replied to with a specific, detailed "Fixed" description (new constants, new functions, new imports) — none of which is present in the file. The branch's last commit (2ac2e27) is timestamped roughly 30 minutes before these replies, so nothing was pushed after them either. This matches the coordinator's note that the implementer died on a usage limit after pushing — it appears that happened mid-reply, after composing the "Fixed" text but before actually writing and committing the fixes. Every one of those threads needs the real fix landed (or the claim corrected) before this can be trusted as reviewed.

Blocking

• registry-snapshot.ts: workflow-scoped activities excluded from contractHash/revision — coordinator-mandated fix, not implemented.
• codegen-validate.ts:70: unbounded workflows array before parse/hash — claimed fixed, not implemented.
• codegen-validate.ts:138: unbounded activeRevisions map, no per-entry byte bound — claimed fixed, not implemented.
• codegen-validate.ts:216: silent first-match on duplicate (name, revision) identity, inconsistent with the other two updated consumers — claimed fixed, not implemented.
• ui-coverage CI job failing on the current head commit — root cause not yet identified (traced to schedule-form-fields.svelte, a file this PR does not touch; see inline comment).

Non-blocking

• codegen-validate.ts:169: stacked/misattributed JSDoc — claimed fixed, not implemented, but doc-only.
• registry-snapshot.ts:317: sequential await in the manifest-build loop could be parallelized.

Once the two coordinator items and the four falsely-resolved threads are actually fixed (or the threads corrected with an honest scope call, same as was done for the fifth thread), the underlying WFT-6 implementation looks close to mergeable.

(Note on review state: GitHub does not allow a PR's own author to submit a formal Request-Changes/Approve review on their own PR, and this session is authenticated as the PR author. Posting as COMMENT instead — treat this as REQUEST CHANGES given the blocking items above.)

[Copilot]

🔵 Needs a closer look

It changes a public wire contract (registry v2), contract hashing, hostile-input validation, CLI, and multiple UI consumers together, so it warrants final human review despite passing gates.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

packages/weft/scripts/check-package-contents.ts:31

• The numbers here don't match the PR description. The description's "Two small, honest fixes" section states this was "bumped maximumEntryCount to the actual measured npm pack --dry-run count (1489) ... rather than the unverified '+2 per new file' formula's prediction (1487)", but the code (and this comment) use a measured count of 1493 and a formula prediction of 1491. The code comment appears authoritative (it accounts for the two extra core/ extraction files added after the earlier codegen-validate.ts-only revision), so the PR description looks stale and should be updated to 1493/1491 to avoid confusing reviewers verifying this gate bump.

• Files reviewed: 41/43 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3b2a08860f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fb4a7b15d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🔵 Needs a closer look

It is a breaking change to a public wire contract (registryVersion 1→2) spanning the core engine, CLI, server, and UI, which warrants final human review despite being well-tested and gated.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

packages/weft/documentation/guides/migration.md:14

• This migration note describes the operator UI as "the bundled Console," but documentation/guides/server.md:196 states that "Weft no longer bundles a dashboard, and the CLI starts a headless API server." The Console is the separate @lostgradient/weft-ui package (not yet published, per AGENTS.md), so calling it "bundled" here contradicts the documented headless-by-default contract and could mislead a reader into expecting a UI shipped with @lostgradient/weft. Consider dropping "bundled."

• Files reviewed: 42/44 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

It makes a breaking change to a public wire contract with regenerated catalog artifacts, coverage-allowlist edits, and many cross-package consumers, and it contains a user-facing documentation inaccuracy ("bundled Console") that warrants human review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

packages/weft/documentation/guides/migration.md:14

• This says the endpoint is consumed "through weft codegen or the bundled Console," but Weft ships no bundled Console/dashboard — it is headless by default (see documentation/guides/server.md: "Weft no longer bundles a dashboard, and the CLI starts a headless API server"), and the operator console is the separate @lostgradient/weft-ui package. Calling it "bundled" is inaccurate and may mislead readers into expecting a UI to ship with @lostgradient/weft. Consider referring to it as the external operator console.

• Files reviewed: 42/44 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 12bda02d8f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🔵 Needs a closer look

It is a breaking public wire-API change (v1→v2 with no compat layer) that also alters contract-hash/identity inputs and coordinates changes across the engine, server, CLI, and the weft-ui package, warranting final human review.

Review details

• Files reviewed: 47/49 changed files
• Comments generated: 0 new
• Review effort level: Balanced