suaveplan/openspec/archive/2026-05-18-extend-api-foundation-host-services/tasks.md

Tasks — extend-api-foundation-host-services

Two-package patch. Order matters: api-plugin first (gates the api side). The two test/gate sweeps run separately per package; no umbrella.

1. Patch @suaveplan/api-plugin

• 1.1 Add PLUGIN_INVALID_STATE to src/error-codes.ts (preserves the existing 10 codes — total 11)
• 1.2 Add src/registry/seed-services.ts (or extend src/registry/registry.ts) with seedServices(map) method on PluginRegistry. Internal seededServices: Map<string, unknown>. Idempotent re-seed.
• 1.3 Modify createPluginContext (or wherever the per-plugin context is built) to pre-populate the shared services map from the registry's seeded entries before onRegister runs
• 1.4 Tests:
  • 1.4.1 src/registry/seed-services.test.ts — covers the 3 scenarios in the spec delta (seed → resolve, later seed overrides, post-init throws)
  • 1.4.2 Update src/api-plugin.spec-conformance.test.ts — asserts PLUGIN_INVALID_STATE present + thrown from a real production path (seedServices after init)
• 1.5 Update sibling .md for registry + error-codes
• 1.6 Gates:
  • 1.6.1 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin --force green
  • 1.6.2 bunx turbo test:coverage --filter=@suaveplan/api-plugin --force — still 100/100/100/100
  • 1.6.3 bun scripts/openspec-conformance.ts @suaveplan/api-plugin exit 0
  • 1.6.4 bunx turbo build --filter=@suaveplan/api-plugin --force green
  • 1.6.5 Dependent sweep bunx turbo test --filter=...@suaveplan/api-plugin --force still green (verifies no regression in tenant/openapi/migrations/api)

2. Patch @suaveplan/api

• 2.1 Add src/services/registry-augmentation.{ts,md,index.ts} declaring the canonical ServiceRegistry slots. Root barrel side-effect imports it.
• 2.2 Add subpath export ./services/registry-augmentation in package.json
• 2.3 Modify src/app/app.ts SuaveApp.initialize() to call this._registry.seedServices(...) before this._registry.initialize()
• 2.4 Add db?: SurrealAdapter to SuaveAppOptions (in src/types/api.ts or wherever the options type lives); store on this._db. Update AppBuilder.database(...) to also store the adapter when provided as a constructed object.
• 2.5 Add @suaveplan/surrealdb as an optional peer dep so the db slot type is resolvable (peerDependencyMeta.optional: true to avoid forcing the dep on api consumers who don't use SurrealDB)
• 2.6 Tests:
  • 2.6.1 src/app/seed-services.test.ts — covers the 3 scenarios in the spec delta (plugin resolves app, slots seeded, missing migrationRunner)
  • 2.6.2 src/services/registry-augmentation.test.ts — covers the side-effect import + type augmentation
  • 2.6.3 src/services/registry-augmentation.spec-conformance.test.ts — expectTypeOf every slot
  • 2.6.4 src/app/options.test.ts — db option seeded / missing
• 2.7 Sibling .md for registry-augmentation module
• 2.8 Gates: same 5 as §1.6 but filtered for @suaveplan/api

3. Archive

• 3.1 Fold specs/api-plugin/spec.md into canonical openspec/specs/api-plugin/spec.md (append the new requirement; preserve existing)
• 3.2 Fold specs/api/spec.md into canonical openspec/specs/api/spec.md (append the new requirements; preserve existing)
• 3.3 Move openspec/changes/extend-api-foundation-host-services/ → openspec/archive/<date>-extend-api-foundation-host-services/
• 3.4 DO NOT refresh MANIFEST or STATUS — orchestrator consolidates after the full chain ships