refactor(catalog): compose and inject validated definitions

[lloydrichards]

Goals/Scope

Close #249 by composing validated catalog fragments and supplying one catalog to the scaffold services. Review duplicate and reference failures, plus catalog propagation through preview and Finalize.

Description

composeCatalog validates each fragment, rejects duplicate IDs and broken references, and returns the catalog used by Blueprint, Plan, Apply, and Finalize. For example, yield* composeCatalog([officialFragment, trustedFragment]) validates the combined graph before planning. CLI and Recipe Builder keep a temporary bundled adapter until #273 and #274 replace it.

How to Test

Run bun format, bun lint, bun run type-check, and bun run okf:check. Run scoped catalog, scaffold, CLI, and docs tests, then build the CLI and docs site. Use a temporary repository for the CLI smoke test.

Comments

Closes #249. The HTTP loader and deployed source belong to later PRs in #275.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
stack-effect-docs	Ready	Preview	Sep 27, 2026 6:51pm UTC

[changeset-bot]

⚠️ No Changeset found

Latest commit: a433a85

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

✅ No new issues found.

Reviewed changes in PR #278 against feat/catalog-distribution, including catalog composition, service injection, application wiring, tests, and authoring guidance.

• Validated composition: Added a fragment schema, typed validation errors, duplicate and graph-reference checks, and a trusted exception for the bundled catalog's Finalize scripts.
• Catalog propagation: Supplied one catalog through Blueprint, Plan, preview workspaces, and Finalize, with an injected-definition test covering catalog projections and generated output.
• Composition roots: Kept explicit bundled adapters for the CLI and Recipe Builder and moved root catalog authoring scripts to a repository entrypoint.

Local @repo/catalog, @repo/scaffold, and stack-effect tests, bun run type-check, and bun run format:check passed.

  ^{｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}