From bc7c46b2d5411432606b01f050eaa29183d71b3a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:14:11 +0900 Subject: [PATCH] fix(features): check declared needs and show the IndexedDB capability assembly (09-05) A missing capability reached the feature factory as an anonymous TypeError. The composer now names the feature and the capability, and the IndexedDB provider example moves from a browser spec into an opt-in recipe with a test. Co-Authored-By: Claude Opus 5.5 --- .../frontend-application-foundation.md | 11 ++ .../indexeddb-feature-capability.ts | 137 ++++++++++++++++++ ...st-browser-file-storage-runtime-removal.ts | 2 + src/bootstrap/runtime-adapters.ts | 5 + src/features/feature-adapter-contribution.ts | 14 ++ .../feature-adapter-composition.test.ts | 23 +++ .../indexeddb-feature-capability.test.ts | 54 +++++++ 7 files changed, 246 insertions(+) create mode 100644 recipes/frontend-capabilities/indexeddb-feature-capability.ts create mode 100644 tests/recipes/indexeddb-feature-capability.test.ts diff --git a/docs/architecture/frontend-application-foundation.md b/docs/architecture/frontend-application-foundation.md index 6cb3ca28..d820018e 100644 --- a/docs/architecture/frontend-application-foundation.md +++ b/docs/architecture/frontend-application-foundation.md @@ -138,6 +138,17 @@ browser-capability test composes the feature over the real `createIndexedDbRuntime` and native IndexedDB, proving that this seam is not limited to an in-memory contract fixture. +The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference +runtime (`productionComposition: false` in +`config/recipes/frontend-capability-recipes.json`). The composition example is +`recipes/frontend-capabilities/indexeddb-feature-capability.ts` +(`createLocalDraftIndexedDbCapability`, exercised by +`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a +feature with `needs: ["indexedDb"]` copies it and adds `indexedDb` to the feature +capabilities in `src/bootstrap/runtime-adapters.ts`. Until it does, that object +fails the app typecheck, and `composeFeatureAdapterInputs()` rejects the +composition with `feature needs indexedDb, which the host did not provide`. + ## Presentation consumer surface `ApplicationProvider` remains the composition root for presentation, but new diff --git a/recipes/frontend-capabilities/indexeddb-feature-capability.ts b/recipes/frontend-capabilities/indexeddb-feature-capability.ts new file mode 100644 index 00000000..c5b7aeb7 --- /dev/null +++ b/recipes/frontend-capabilities/indexeddb-feature-capability.ts @@ -0,0 +1,137 @@ +import { + createIndexedDbRuntime, + type IndexedDbRuntimeDependencies, +} from "../../src/adapters/storage/indexeddb/index.ts"; +import type { IndexedDbDatasetScope } from "../../src/application/ports/browser-file-storage/index.ts"; +import { + createIndexedDbRepositoryProvider, + type IndexedDbRepositoryProvider, +} from "../../src/features/feature-adapter-contribution.ts"; +import type {} from "../../src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts"; +import type { LocalDraft } from "../../src/features/local-draft-feature/domain/local-draft.ts"; + +type LocalDraftRuntimeDependencies = IndexedDbRuntimeDependencies< + LocalDraft, + LocalDraft, + never +>; +type LocalDraftRuntime = ReturnType< + typeof createIndexedDbRuntime +>; + +/** + * 09-05. How a host builds the `indexedDb` feature capability, shown for the + * local-draft sample. IndexedDB is an opt-in reference runtime + * (`offline-indexeddb` in config/recipes/frontend-capability-recipes.json, + * `productionComposition: false`), so `src/bootstrap/runtime-adapters.ts` does + * not build it. A product that installs a feature with `needs: ["indexedDb"]` + * copies this into its composition, replaces the codec, migrations and storage + * policy with its own decisions, and adds `indexedDb` to the feature + * capabilities there; until it does, that object fails the app typecheck and + * `composeFeatureAdapterInputs` names the missing capability. + * + * The scope tokens come from the product's storage registry and the lifecycle + * authority from its composition root; neither is invented here. + */ +export function createLocalDraftIndexedDbCapability( + options: Readonly<{ + // The sample keeps drafts across sign-out, so its dataset is origin-shared. + scope: IndexedDbDatasetScope & Readonly<{ accountScope: "ORIGIN_SHARED" }>; + authorizeLifecycle: LocalDraftRuntimeDependencies["authorizeLifecycle"]; + /** Defaults to the browser's `indexedDB`; tests pass an in-memory one. */ + factory?: IDBFactory; + }>, +): Readonly<{ + indexedDb: IndexedDbRepositoryProvider; + /** Opens (and migrates) the database; repository calls fail until it has. */ + open(signal?: AbortSignal): ReturnType; + close(): void; +}> { + const runtime = createIndexedDbRuntime({ + ...(options.factory === undefined ? {} : { factory: options.factory }), + scope: options.scope, + storagePolicy: Object.freeze({ + owner: "local-draft-feature", + namespace: "local-draft", + classification: "INTERNAL", + authority: "LOCAL_FIRST", + accountScope: "ORIGIN_SHARED", + retention: Object.freeze({ kind: "EXPLICIT_DELETE" }), + softBudgetBytes: 1_000_000, + hardBudgetBytes: 2_000_000, + evictionPriority: "USER_AUTHORED", + logoutAction: "KEEP_ORIGIN_SHARED", + accountDeletionAction: "KEEP_ORIGIN_SHARED", + pressureAction: "RETAIN", + unavailableFallback: "READ_ONLY", + }), + schemaVersion: 1, + recordStore: "records", + governanceStore: "governance", + retentionStore: "retention", + retentionEligibilityIndex: "by-eligibility", + lifecycleMetadataStores: [], + idempotencyStore: "receipts", + idempotencyExpiryIndex: "by-expiry", + receiptRetentionMs: 60_000, + maxIdempotencyReceipts: 100, + migrations: [ + { + id: "local-draft-schema-v1", + fromVersion: 0, + toVersion: 1, + operations: [ + { kind: "CREATE_STORE", name: "governance", keyPath: "bindingKey" }, + { + kind: "CREATE_STORE", + name: "retention", + keyPath: "recordKey", + indexes: [{ name: "by-eligibility", keyPath: "eligibleAtEpochMs" }], + }, + { kind: "CREATE_STORE", name: "records", keyPath: "key" }, + { + kind: "CREATE_STORE", + name: "receipts", + keyPath: "idempotencyKey", + indexes: [{ name: "by-expiry", keyPath: "expiresAtEpochMs" }], + }, + ], + }, + ], + codec: { + currentVersion: 1, + encode: (value) => ({ ok: true, value }), + measureStoredBytes: (value) => + new TextEncoder().encode(JSON.stringify(value)).byteLength, + decode: (version, value) => { + if (version !== 1 || value === null || typeof value !== "object") { + return { ok: false }; + } + const candidate = value as Partial; + return typeof candidate.draftId === "string" && + typeof candidate.title === "string" && + typeof candidate.body === "string" + ? { ok: true, value: candidate as LocalDraft } + : { ok: false }; + }, + fingerprint: async (value) => { + const bytes = new TextEncoder().encode( + JSON.stringify([value.draftId, value.title, value.body]), + ); + const digest = await crypto.subtle.digest("SHA-256", bytes); + return Array.from(new Uint8Array(digest), (byte) => + byte.toString(16).padStart(2, "0"), + ).join(""); + }, + }, + queryPolicy: { plan: () => ({ limit: 1 }) }, + authorizeLifecycle: options.authorizeLifecycle, + }); + return Object.freeze({ + indexedDb: createIndexedDbRepositoryProvider( + Object.freeze({ "local-draft": runtime }), + ), + open: (signal?: AbortSignal) => runtime.open(signal), + close: () => runtime.close(), + }); +} diff --git a/scripts/test-browser-file-storage-runtime-removal.ts b/scripts/test-browser-file-storage-runtime-removal.ts index d042b892..1d23bdc2 100644 --- a/scripts/test-browser-file-storage-runtime-removal.ts +++ b/scripts/test-browser-file-storage-runtime-removal.ts @@ -31,6 +31,8 @@ const runtimePaths = [ "src/adapters/storage/opfs", "tests/browser-capabilities", "tests/fixtures/browser-file-storage-boundaries", + // The composition example of this runtime goes with it. + "recipes/frontend-capabilities/indexeddb-feature-capability.ts", ] as const; const runtimeSourceRoots = runtimePaths.filter((entry) => entry.startsWith("src/"), diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 2025e0ed..1a32eacd 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -557,6 +557,11 @@ export async function createRuntimeAdapters( ...(telemetryCollector === undefined ? {} : { collector: telemetryCollector }), }); // Each installed contribution receives only the capabilities it declares. + // 09-05. `indexedDb` is not built here: IndexedDB is an opt-in reference + // runtime (`productionComposition: false`). Installing a feature that needs + // it makes this object fail the app typecheck until the product adds + // `indexedDb`, built as in recipes/frontend-capabilities/ + // indexeddb-feature-capability.ts. const featureCapabilities = Object.freeze({ http: contractOperations, telemetry: featureTelemetry, diff --git a/src/features/feature-adapter-contribution.ts b/src/features/feature-adapter-contribution.ts index d58eee8e..087a482a 100644 --- a/src/features/feature-adapter-contribution.ts +++ b/src/features/feature-adapter-contribution.ts @@ -174,6 +174,20 @@ export function composeFeatureAdapterInputs< } seen.add(contribution.featureId); if (!enabled.has(contribution.featureId)) continue; + // 09-05. The context type already asks for every declared need, but a + // host that widens it (or JavaScript) used to reach the feature's factory + // and fail there as an anonymous TypeError. + const provided = context as Readonly< + Partial> + >; + const missing = contribution.needs.find( + (need) => provided[need] === undefined, + ); + if (missing !== undefined) { + throw new TypeError( + `feature ${contribution.featureId} needs ${missing}, which the host did not provide`, + ); + } const installed = invokeContribution( contribution as unknown as FeatureAdapterContribution< diff --git a/tests/contract/reusable-capability/feature-adapter-composition.test.ts b/tests/contract/reusable-capability/feature-adapter-composition.test.ts index 945d8194..8eeaaeb0 100644 --- a/tests/contract/reusable-capability/feature-adapter-composition.test.ts +++ b/tests/contract/reusable-capability/feature-adapter-composition.test.ts @@ -140,6 +140,29 @@ describe("feature adapter composition", () => { ).toThrow(/duplicate.*test-http-feature/u); }); + it("names the feature and the capability the host did not provide (09-05)", () => { + const withoutIndexedDb = Object.freeze({ http }) as unknown as Parameters< + typeof composeFeatureAdapterInputs< + readonly [typeof LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION] + > + >[2]; + expect(() => + composeFeatureAdapterInputs( + Object.freeze([LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION] as const), + Object.freeze(["local-draft"]), + withoutIndexedDb, + ), + ).toThrow("feature local-draft needs indexedDb, which the host did not provide"); + // A feature switched off gets no input, so its needs are not asked for. + expect( + composeFeatureAdapterInputs( + Object.freeze([LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION] as const), + Object.freeze([]), + withoutIndexedDb, + ), + ).toEqual({}); + }); + it("rejects an input installed under another feature's id (Q-6.9-6)", () => { const wrongId = defineFeatureAdapterContribution({ featureId: "test-http-feature", diff --git a/tests/recipes/indexeddb-feature-capability.test.ts b/tests/recipes/indexeddb-feature-capability.test.ts new file mode 100644 index 00000000..c386dd6b --- /dev/null +++ b/tests/recipes/indexeddb-feature-capability.test.ts @@ -0,0 +1,54 @@ +import { describe, expect, it } from "vitest"; + +import { composeFeatureAdapterInputs } from "../../src/features/feature-adapter-contribution.ts"; +import { LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION } from "../../src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts"; +import { createLocalDraftIndexedDbCapability } from "../../recipes/frontend-capabilities/indexeddb-feature-capability.ts"; +import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; + +describe("IndexedDB feature capability recipe (09-05)", () => { + it("composes local-draft over the recipe's IndexedDB capability", async () => { + const memory = new MemoryIndexedDbFactory(); + const capability = createLocalDraftIndexedDbCapability({ + scope: Object.freeze({ + authorityToken: "a1b2c3d4e5f60718293a4b5c6d7e8f90", + namespaceToken: "n1b2c3d4e5f60718293a4b5c6d7e8f90", + partitionToken: "p1b2c3d4e5f60718293a4b5c6d7e8f90", + accountScope: "ORIGIN_SHARED" as const, + }), + authorizeLifecycle: () => ({ authorized: false }), + factory: memory.factory, + }); + try { + await expect(capability.open()).resolves.toEqual({ + ok: true, + value: undefined, + }); + const inputs = composeFeatureAdapterInputs( + Object.freeze([LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION] as const), + Object.freeze(["local-draft"]), + Object.freeze({ indexedDb: capability.indexedDb }), + ); + const localDraft = inputs["local-draft"]; + if (!localDraft) throw new Error("local-draft input was not composed"); + const draft = Object.freeze({ + draftId: "draft-1", + title: "Architecture notes", + body: "Stored through the recipe capability.", + }); + + await expect( + localDraft.saveDraft({ + draft, + expectedRevision: null, + idempotencyKey: "local-draft-create-1", + }), + ).resolves.toEqual({ ok: true, value: { revision: 1 } }); + await expect(localDraft.findDraft("draft-1")).resolves.toEqual({ + ok: true, + value: { draft, revision: 1 }, + }); + } finally { + capability.close(); + } + }); +});