diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 787fa916..99d56352 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -129,6 +129,9 @@ 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). + 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. 3. Create `src/features//context-routes.ts` exporting `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 31e1333f..0d2d96c2 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -695,6 +695,7 @@ export function composeContractContributions( const packagesById = new Map(); const contributionIds = new Set(); const installedContributions: InstalledContractContribution[] = []; + let fixtureInstalled = false; for (const raw of rows) { if (!raw || typeof raw !== "object") { @@ -794,6 +795,28 @@ export function composeContractContributions( ) { fail(`${featureId}: template fixture identity`); } + // §4.8, §24.5 (07-04). The fixture is the sample vertical's test data, + // not a product contract: it never joins the contract set, so a fixture + // copied into a product feature would drop that API from the release + // check without a word. Only the feature the fixture is named after may + // install it; every other feature pins an EXTERNAL_PACKAGE. + // The owner is derived from the fixture id (upper snake case feature id + // plus `_V`) instead of being written out, because + // test:sample-removal rejects the sample feature's id anywhere in src/ + // once the sample is gone. + const fixtureOwner = fixture.fixtureId + .slice(0, -`_V${fixture.revision}`.length) + .toLowerCase() + .replaceAll("_", "-"); + if (featureId !== fixtureOwner) { + fail( + `${featureId}: TEMPLATE_FIXTURE ${fixture.fixtureId} belongs to ${fixtureOwner} only; pin an EXTERNAL_PACKAGE`, + ); + } + if (fixtureInstalled) { + fail(`${featureId}: only one TEMPLATE_FIXTURE contribution is allowed`); + } + fixtureInstalled = true; if (eventRows.length !== 0) { fail(`${featureId}: template fixture must not contribute events`); } diff --git a/tests/features/reference-feature/reference-fixture-provenance.test.ts b/tests/features/reference-feature/reference-fixture-provenance.test.ts new file mode 100644 index 00000000..c02f1caa --- /dev/null +++ b/tests/features/reference-feature/reference-fixture-provenance.test.ts @@ -0,0 +1,37 @@ +import { describe, expect, it } from "vitest"; + +import { + ContractContributionError, + composeContractContributions, +} from "../../../src/contracts/external-contract-runtime.ts"; +import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts"; + +// 07-04 (§4.8). The product-feature rejection is in +// tests/unit/external-contract-runtime.test.ts. +describe("reference template fixture provenance", () => { + it("installs the fixture outside the release contract set", () => { + const composed = composeContractContributions([ + REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, + ]); + expect(composed.contributions).toHaveLength(1); + expect(composed.externalPackages).toHaveLength(0); + }); + + it("rejects a second fixture contribution from the same feature", () => { + const second = Object.freeze({ + ...REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, + contributionId: "reference-feature-http-v2", + http: Object.freeze([]), + }); + let reason: string | undefined; + try { + composeContractContributions([REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, second]); + } catch (error) { + expect(error).toBeInstanceOf(ContractContributionError); + reason = (error as ContractContributionError).reason; + } + expect(reason).toBe( + "reference-feature: only one TEMPLATE_FIXTURE contribution is allowed", + ); + }); +}); diff --git a/tests/unit/contract-snapshot-bypass.test.ts b/tests/unit/contract-snapshot-bypass.test.ts index cbc3825c..79304b44 100644 --- a/tests/unit/contract-snapshot-bypass.test.ts +++ b/tests/unit/contract-snapshot-bypass.test.ts @@ -65,13 +65,12 @@ describe("external contract composition", () => { try { composed = composeContractContributions([ { - contributionId: "fixture-v1", + contributionId: "smuggled-events-v1", featureId: "test-feature", - source: { - kind: "TEMPLATE_FIXTURE", - fixtureId: "REFERENCE_FEATURE_V1", - revision: 1, - }, + // 07-04. A package source accepts events, so a hidden event that was + // read would be installed and fail the assertion below. A fixture + // source throws on any event, which hid whether it was read. + source: TEST_CONTRACT_CONTRIBUTION.source, http: [], events: iteratorSmuggling([], [smuggled]), }, diff --git a/tests/unit/external-contract-runtime.test.ts b/tests/unit/external-contract-runtime.test.ts index 421dfe87..c98b1348 100644 --- a/tests/unit/external-contract-runtime.test.ts +++ b/tests/unit/external-contract-runtime.test.ts @@ -86,6 +86,28 @@ describe("external contract contribution composition", () => { }); }); +// The sample feature's own cases (its fixture composes, a second one does not) +// live in tests/features so they leave with the sample. +describe("template fixture provenance (07-04, §4.8)", () => { + it("rejects a fixture copied into a product feature, which would leave the contract set silently", () => { + const copied = Object.freeze({ + ...contribution("order-http-v1", TEST_CONTRACT_CONTRIBUTION.http), + featureId: "order", + source: Object.freeze({ + kind: "TEMPLATE_FIXTURE" as const, + fixtureId: "REFERENCE_FEATURE_V1" as const, + revision: 1 as const, + }), + }); + const error = captureContributionError(() => + composeContractContributions([copied]), + ); + expect(error.reason).toMatch( + /^order: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to .+ only; pin an EXTERNAL_PACKAGE$/u, + ); + }); +}); + describe("validator invocation (07-06)", () => { const returning = (result: unknown): RuntimeValidator => ({ schemaId: "Malformed",