foundation-fix-gap-4-db-split

Status: PROPOSED
Spec deltas:
- ./specs/api-host/spec.md
- ./specs/api-types/spec.md

What & why

The post-Stage-4 foundation-coherence audit (Gap #4) flagged that HostAdapters.db was shaped for the narrow LedgerDb interface (bun:sqlite-style prepare(sql) / run(sql)) consumed by the host-internal PluginLedger, while @suaveplan/api-db-adapter produces a multi-engine AdminDatabaseLike façade plugins consume. The two surfaces are type-incompatible — there is no safe way to share a single adapters.db slot. The E2E foundation-stack server documented the gap explicitly (@suaveplan/api-db-adapter was swapped out for a raw bun:sqlite handle to satisfy the ledger).

This change splits the slot:

HostAdapters.ledgerDb: LedgerDb — host-private, narrow SQLite handle the PluginLedger keeps using. Renamed from the former HostAdapters.db.
HostAdapters.db?: AdminDatabaseLike — optional, consumer-facing. Populated by createDbAdapter(...).admin from @suaveplan/api-db-adapter. The host threads it onto PluginContext.db (admin-scoped) and applies createTenantScopedWrapper(admin, tenantId) per request to expose it on RequestContext.db (tenant-scoped).
PluginContext.db: AdminDatabaseLike | null + RequestContext.db: TenantScopedDatabaseLike | null added as top-level fields. null when (a) the host was booted without adapters.db configured, or (b) for RequestContext only, the tenant resolver chain returned null on this request.
E2E foundation-stack restores createDbAdapter({ engine: "sqlite", url: ":memory:" }) as adapters.db and adds a GET /api/db-ping route exercising ctx.db?.execute + ctx.db?.query through the tenant-scoped wrapper. A companion test asserts 200 + non-empty rows.

Impact

Affected dependents

@suaveplan/api-types — PluginContext / RequestContext / JobContext / ConnectionContext each gain a db field. Source- incompatible for any consumer constructing a PluginContext literal — but the only in-tree literal consumer is the host's own test harness ({} as never mock), which already type-erases.
@suaveplan/api-host —
- HostAdapters.db renamed to ledgerDb; new optional HostAdapters.db: AdminDatabaseLike.
- Host config Zod schema updated.
- RequestPipelineOptions gains optional db: AdminDatabaseLike.
- buildRequestContext accepts + propagates db.
- Request-pipeline driver applies createTenantScopedWrapper when both adapters.db is set AND a tenant is resolved.
- New runtime dep @suaveplan/api-db-adapter.
@suaveplan/e2e-foundation-stack — wires createDbAdapter + registers an inline bun:sqlite engine factory; adds the /api/db-ping route + an E2E test.

Blast radius (atomic update list in this commit):

packages/api-stack/api/api-types/src/plugin-context/plugin-context.types.ts
packages/api-stack/api/api-host/src/host/host.types.ts
packages/api-stack/api/api-host/src/host/host.ts
packages/api-stack/api/api-host/src/host/host.test.ts
packages/api-stack/api/api-host/src/request-pipeline/request-pipeline.types.ts
packages/api-stack/api/api-host/src/request-pipeline/request-pipeline-driver.ts
packages/api-stack/api/api-host/src/request-pipeline/request-pipeline-helpers.ts
packages/api-stack/api/api-host/package.json
e2e/foundation-stack/src/server.ts
e2e/foundation-stack/src/fixture-plugin.ts
e2e/foundation-stack/tests/foundation.spec.ts
e2e/foundation-stack/package.json

Backward compatibility

The HostAdapters.db → HostAdapters.ledgerDb rename is a hard rename (no compatibility shim) because the genesis branch has no shipped consumers outside the in-tree atomic update list above.

PluginContext.db / RequestContext.db are NEW fields, additive at the type level for any future consumer.

Parity Checklist

This is a genesis-original fix; no upstream parity table required.

Verification

bunx turbo lint typecheck test build --filter=@suaveplan/api-host --filter=@suaveplan/api-types --filter=@suaveplan/api-db-adapter --filter=@suaveplan/e2e-foundation-stack → green on api-host / api-types / api-db-adapter. (The e2e package's typecheck error is a pre-existing module-resolution issue unrelated to this change — confirmed via git-stash baseline.)

bunx turbo test:coverage --filter=@suaveplan/api-host --filter=@suaveplan/api-types → 100% lines on touched modules (statements/branches/functions unchanged at baseline).

E2E suite: bun test:e2e → 11/11 pass, including the new db adapter — ctx.db wired through tenant-scoped wrapper test.

4.6 KiB Raw Blame History