문제
FeatureRuntime은 featureId·schemas·adapters·contractContributions인데, 네 곳이
지워진 V2 모양을 적었다. feature-module.ts 머리 주석("API contracts with their
runtime schemas and mappers"), installed-feature-contracts.ts("The V2 API
registries"), frontend-application-foundation.md("composes the V2 API
registries"), starter-experience.md 기능 추가 2단계("the API contract
(operations, schema metadata, runtime schemas, mappers)"). 기능 작성자가 없는
칸을 찾게 된다. 07-05(starter-experience 같은 문장)를 함께 닫는다.
고른 방법
네 문장을 지금 모양으로 고친다: schemas는 FE-REG-SCHEMA 행, 어댑터 기여는
application input, 계약 기여는 HTTP operation이고 FE-REG-API 행은 거기서
투영한다(installed-feature-runtime-registries.ts와 같다).
위험·한계
verify:documentation은 문장 내용을 보지 않으므로 다시 낡아도 게이트가 모른다.
검증
- git grep "V2 API registr|runtime schemas, mappers|runtime schemas and
mappers" -- src docs/architecture → 0건.
- verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-10
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-05
143 lines
4.9 KiB
TypeScript
143 lines
4.9 KiB
TypeScript
export type FeatureContractIdentity = Readonly<{ featureId: string }>;
|
|
|
|
type EmptyRecord = Readonly<Record<never, never>>;
|
|
|
|
/**
|
|
* 15-01. A feature has two halves. The declaration (`FeatureModule`) is what
|
|
* the shell needs before any of the feature's routes is entered: its route
|
|
* table, its messages, its cache invalidation identities and the external
|
|
* contract packages the release manifest is checked against at boot. It is
|
|
* imported statically and lands in the initial chunk, so it stays data.
|
|
*
|
|
* Everything executable (the FE-REG-SCHEMA schema definitions, the adapter
|
|
* contributions that build the application input, and the HTTP contract
|
|
* contributions whose descriptors FE-REG-API rows are projected from) is the
|
|
* runtime half (`FeatureRuntime`). `loadRuntime` imports it dynamically when
|
|
* one of the feature's routes is entered. Before 15-01 both halves loaded at
|
|
* boot and each feature added about 3.9 KB gzip to the initial chunk.
|
|
*/
|
|
|
|
/**
|
|
* Zero-feature products are a supported topology. The fallback contract keeps
|
|
* every composer's property access valid without pretending that any feature
|
|
* route, invalidation edge or contract package exists.
|
|
*/
|
|
export type EmptyFeatureContract = FeatureContractIdentity &
|
|
Readonly<{
|
|
routes: EmptyRecord;
|
|
routeRuntimeContracts: EmptyRecord;
|
|
invalidation: Readonly<{
|
|
topics: readonly [];
|
|
namespaces: readonly [];
|
|
edges: readonly [];
|
|
}>;
|
|
topicVersions: readonly [];
|
|
contractPackages: readonly [];
|
|
}>;
|
|
|
|
export type FeatureMessageCatalogs = Readonly<
|
|
Record<string, Readonly<Record<string, string>>>
|
|
>;
|
|
|
|
type EmptyFeatureMessageCatalogs = Readonly<
|
|
Record<string, Readonly<Record<never, never>>>
|
|
>;
|
|
|
|
|
|
/**
|
|
* The executable half. `featureId` must equal the declaring module's id; the
|
|
* loader checks it, and checks that every adapter and contract contribution in
|
|
* it belongs to that feature.
|
|
*/
|
|
export type FeatureRuntime<
|
|
Schemas = EmptyRecord,
|
|
Adapter = never,
|
|
ContractContribution = never,
|
|
> = Readonly<{
|
|
featureId: string;
|
|
/**
|
|
* FE-REG-SCHEMA rows (`SchemaDefinition`) for the feature's route and API
|
|
* schemas. The HTTP operations themselves are the V3 descriptors in
|
|
* `contractContributions`; FE-REG-API rows are projected from them.
|
|
*/
|
|
schemas: Schemas;
|
|
adapters: readonly Adapter[];
|
|
contractContributions: readonly ContractContribution[];
|
|
}>;
|
|
|
|
export type AnyFeatureRuntime = FeatureRuntime<unknown, unknown, unknown>;
|
|
|
|
/**
|
|
* The default parameters deliberately describe the empty-product fallback.
|
|
* Concrete generated modules retain their literal types; only an empty
|
|
* generated tuple resolves to this default shape.
|
|
*/
|
|
export type FeatureModule<
|
|
Contract extends FeatureContractIdentity = EmptyFeatureContract,
|
|
Routes extends Readonly<Record<string, unknown>> = EmptyRecord,
|
|
Messages extends FeatureMessageCatalogs = EmptyFeatureMessageCatalogs,
|
|
Runtime extends AnyFeatureRuntime = FeatureRuntime,
|
|
> = Readonly<{
|
|
id: string;
|
|
contracts: Contract;
|
|
routes: Routes;
|
|
messages: Messages;
|
|
/**
|
|
* Must dynamically import the feature's `feature-runtime.ts`: a static
|
|
* import here would put the runtime half back into the initial chunk
|
|
* (tests/unit/feature-shape-growth.test.ts measures it).
|
|
*/
|
|
loadRuntime(): Promise<Runtime>;
|
|
}>;
|
|
|
|
/** Structural supertype used when accepting any concrete feature descriptor. */
|
|
export type AnyFeatureModule = FeatureModule<
|
|
FeatureContractIdentity,
|
|
Readonly<Record<string, unknown>>,
|
|
FeatureMessageCatalogs,
|
|
AnyFeatureRuntime
|
|
>;
|
|
|
|
/** The runtime half a module's `loadRuntime` resolves to. */
|
|
export type FeatureModuleRuntime<Module extends AnyFeatureModule> = Awaited<
|
|
ReturnType<Module["loadRuntime"]>
|
|
>;
|
|
|
|
export function defineFeatureModule<const Module extends AnyFeatureModule>(
|
|
module: Module,
|
|
): Readonly<Module> {
|
|
if (module.id !== module.contracts.featureId) {
|
|
throw new TypeError(
|
|
`Feature module id ${module.id} does not match contract featureId ${module.contracts.featureId}`,
|
|
);
|
|
}
|
|
return Object.freeze({ ...module }) as unknown as Readonly<Module>;
|
|
}
|
|
|
|
export function defineFeatureRuntime<const Runtime extends AnyFeatureRuntime>(
|
|
runtime: Runtime,
|
|
): Readonly<Runtime> {
|
|
return Object.freeze({
|
|
...runtime,
|
|
adapters: Object.freeze([...runtime.adapters]),
|
|
contractContributions: Object.freeze([...runtime.contractContributions]),
|
|
}) as unknown as Readonly<Runtime>;
|
|
}
|
|
|
|
/**
|
|
* Loads a module's runtime half and refuses one that belongs to another
|
|
* feature. Composers call this instead of `module.loadRuntime()` directly.
|
|
*/
|
|
export async function loadFeatureRuntime<const Module extends AnyFeatureModule>(
|
|
module: Module,
|
|
): Promise<FeatureModuleRuntime<Module>> {
|
|
const runtime = (await module.loadRuntime()) as FeatureModuleRuntime<Module>;
|
|
const owner = (runtime as AnyFeatureRuntime).featureId;
|
|
if (owner !== module.id) {
|
|
throw new TypeError(
|
|
`Feature module ${module.id} loaded the runtime of ${String(owner)}`,
|
|
);
|
|
}
|
|
return runtime;
|
|
}
|