diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 99d56352..cfa84ace 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -129,6 +129,10 @@ selected app. Every build and check script runs it first; run it yourself with entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). + An HTTP API is written twice: its API contract operation (V2) is what + `check:registries` governs, and its contract contribution descriptor (V3) + is what executes. `tests/unit/http-operation-v2-v3-parity.test.ts` fails + when one exists without the other or when they disagree. A product feature's contract contribution uses an `EXTERNAL_PACKAGE` source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never joins the release contract set; the composer rejects it anywhere else. diff --git a/src/contracts/api-operations.ts b/src/contracts/api-operations.ts index 692021e6..c333f26b 100644 --- a/src/contracts/api-operations.ts +++ b/src/contracts/api-operations.ts @@ -27,6 +27,15 @@ export type ApiOperation = Readonly<{ maxEncodedSearchBytes?: number; }>; +/** + * 07-02. A V2 row is the declaration `check:registries` (FE-REG-API) governs; + * it is not what executes. The executed copy of the same HTTP API is the V3 + * descriptor (`InstalledHttpContract`) in the feature's contract contribution. + * A feature writes both, and `tests/unit/http-operation-v2-v3-parity.test.ts` + * checks they name the same operations, method, path, statuses, limits, auth + * profile, replay and write semantics, request body and schema ids. The + * deadline is not compared: V2 `timeoutMs` is `null` while V3 always has one. + */ export type RestOperationV2 = ApiOperation & Readonly<{ contractVersion: 2; diff --git a/tests/unit/http-operation-v2-v3-parity.test.ts b/tests/unit/http-operation-v2-v3-parity.test.ts index 340c0372..287a747f 100644 --- a/tests/unit/http-operation-v2-v3-parity.test.ts +++ b/tests/unit/http-operation-v2-v3-parity.test.ts @@ -9,8 +9,8 @@ import { INSTALLED_CONTRACT_CONTRIBUTIONS, } from "../../src/features/loaded-feature-runtimes.ts"; -// 07-03 (D-7). FE-REG-API governs the V2 rows while the V3 descriptors are -// what executes. Until V2 is generated from V3, both copies must agree. +// 07-03 (D-7), 07-02. FE-REG-API governs the V2 rows while the V3 descriptors +// are what executes. Until V2 is generated from V3, both copies must agree. const RETRY_SEMANTICS_FOR_REPLAY_POLICY = Object.freeze({ SAFE: "SAFE", IDEMPOTENT: "IDEMPOTENT", @@ -29,8 +29,35 @@ const v2Rows = (Object.values(API_OPERATIONS) as readonly ApiOperation[]).filter (operation): operation is RestOperationV2 => operation.contractVersion === 2, ); +// V3 validates the whole canonical input with one schema; V2 splits it into a +// path schema and a request (search or body) schema, "NoRequest" when absent. +// An operation that needs both has no rule yet and fails here until one is +// written down. +const NO_REQUEST = "NoRequest"; + +function v2InputSchema(row: RestOperationV2): string { + const declared = [row.pathSchema, row.requestSchema].filter( + (schemaId) => schemaId !== NO_REQUEST, + ); + expect( + declared.length, + `${row.operationId}: V2 declares both a path and a request schema; decide which V3 input schema matches them`, + ).toBeLessThanOrEqual(1); + return declared[0] ?? NO_REQUEST; +} + describe("HTTP operation V2 rows and V3 descriptors", () => { - it("declare the same method, path, statuses, limit, auth profile and replay policy", () => { + // 07-02. Both directions: a V3-only operation executes outside the + // FE-REG-API gate, a V2-only one is governed but never executes. With the + // sample feature removed both sets are empty, which is why there is no + // "at least one row" assertion (test:sample-removal runs this file). + it("cover the same operations", () => { + expect([...v3ByOperationId.keys()].sort(), "V3 descriptors").toEqual( + v2Rows.map((row) => row.operationId).sort(), + ); + }); + + it("declare the same method, path, statuses, limit, auth profile, replay policy, write semantics, request body and schema ids", () => { for (const row of v2Rows) { const descriptor = v3ByOperationId.get(row.operationId); expect(descriptor, `${row.operationId} has no V3 descriptor`).toBeDefined(); @@ -43,6 +70,12 @@ describe("HTTP operation V2 rows and V3 descriptors", () => { maxResponseBytes: descriptor.frontend.responseByteLimit, authProfileId: descriptor.frontend.authProfileId, retrySemantics: descriptor.contract.retrySemantics, + // The executor treats an operation as a write by its effect + // descriptor, not by its method. + semantics: descriptor.contract.commandEffect === null ? "QUERY" : "COMMAND", + requestBody: descriptor.contract.requestBody, + inputSchema: descriptor.contract.inputValidator.schemaId, + responseSchema: descriptor.contract.outputValidator.schemaId, }, row.operationId, ).toEqual({ @@ -52,6 +85,10 @@ describe("HTTP operation V2 rows and V3 descriptors", () => { maxResponseBytes: row.maxResponseBytes, authProfileId: row.authProfileId, retrySemantics: RETRY_SEMANTICS_FOR_REPLAY_POLICY[row.replayPolicy], + semantics: row.semantics, + requestBody: row.requestSource === "body" ? "JSON" : "NONE", + inputSchema: v2InputSchema(row), + responseSchema: row.responseSchema, }); } });