From a8c5eabcd93e8512359d1593759de982ee772860 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:42:54 +0900 Subject: [PATCH] fix(contracts): stop quiet passes in release checks and guard contracts imports (Q-6.7-12) - release-tokens.ts: compareReleaseToRuntime filled the runtime-side assetManifestHash with the release's own value, so the field always compared equal and read as a pass. The result now also carries `unverified: ["assetManifestHash"]` (additive field; compatible and mismatches are unchanged). - contract-set.ts: a duplicated package in `expected` without expectedSetDigest made the digest helper throw, so verifyContractSet rejected. It now returns CONTRACT_SET_DUPLICATE_PACKAGE, and any other throw from the expected-digest computation returns CONTRACT_SET_DIGEST_INVALID. - query-keys.ts: the identity registry copied and sorted every row on each new intern; it now does so only when an eviction is needed. - .dependency-cruiser.json: new rule contracts-do-not-know-presentation-or-bootstrap. No current violations; a temporary src/contracts probe importing presentation and bootstrap was reported by check:architecture and then removed. Verified: tests/unit/contract-release-checks.test.ts (release-tokens and contract-set cases RED before; eviction-order and matching-set cases are characterization and passed before and after); gates green except the known removal-fixture test. Co-Authored-By: Claude Opus 5.5 --- .dependency-cruiser.json | 11 +++ src/contracts/contract-set.ts | 15 +++- src/contracts/query-keys.ts | 12 ++-- src/contracts/release-tokens.ts | 14 +++- tests/unit/contract-release-checks.test.ts | 83 ++++++++++++++++++++++ 5 files changed, 125 insertions(+), 10 deletions(-) create mode 100644 tests/unit/contract-release-checks.test.ts diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index b3c60795..1e022fd6 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -167,6 +167,17 @@ "path": "^src/(application|features)" } }, + { + "name": "contracts-do-not-know-presentation-or-bootstrap", + "comment": "Q-6.7-12. `src/contracts` is shared vocabulary read by every layer, including the service worker and web worker builds. Importing presentation or the composition root from it would pull React and the whole app into those builds. There is no such import today; this keeps it that way.", + "severity": "error", + "from": { + "path": "^src/contracts" + }, + "to": { + "path": "^src/(presentation|bootstrap)" + } + }, { "name": "generic-presentation-does-not-compose-the-product", "comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.", diff --git a/src/contracts/contract-set.ts b/src/contracts/contract-set.ts index caf39568..5f36455c 100644 --- a/src/contracts/contract-set.ts +++ b/src/contracts/contract-set.ts @@ -82,6 +82,11 @@ export async function verifyContractSet( const expectedById = new Map( input.expected.map((entry) => [entry.packageId, entry] as const), ); + // Q-6.7-12. A duplicated expectation is a failure code, not a rejection + // from the digest computation further down. + if (expectedById.size !== input.expected.length) { + return failure("CONTRACT_SET_DUPLICATE_PACKAGE"); + } for (const entry of input.manifest.packages) { if (!expectedById.has(entry.packageId)) { return failure("CONTRACT_SET_PACKAGE_UNEXPECTED"); @@ -115,8 +120,14 @@ export async function verifyContractSet( return failure("CONTRACT_SET_DIGEST_MISMATCH"); } - const expectedDigest = - input.expectedSetDigest ?? (await computeContractSetDigest(input.expected)); + let expectedDigest: `sha256:${string}`; + try { + expectedDigest = + input.expectedSetDigest ?? + (await computeContractSetDigest(input.expected)); + } catch { + return failure("CONTRACT_SET_DIGEST_INVALID"); + } if (expectedDigest !== input.manifest.setDigest) { return failure("CONTRACT_SET_DIGEST_MISMATCH"); } diff --git a/src/contracts/query-keys.ts b/src/contracts/query-keys.ts index 2a0f23fc..8de078e3 100644 --- a/src/contracts/query-keys.ts +++ b/src/contracts/query-keys.ts @@ -215,16 +215,16 @@ export function createRuntimeIdentityRegistry( let closed = false; function evictAvailable(requiredBytes: number): void { + const fits = () => + byCanonical.size < maxEntries && + totalCanonicalBytes + requiredBytes <= maxCanonicalBytes; + // Q-6.7-12. Copy and sort the rows only when something must be evicted. + if (fits()) return; const candidates = [...byCanonical.values()] .filter((row) => row.refCount === 0) .sort((left, right) => left.touched - right.touched); for (const row of candidates) { - if ( - byCanonical.size < maxEntries && - totalCanonicalBytes + requiredBytes <= maxCanonicalBytes - ) { - return; - } + if (fits()) return; byCanonical.delete(row.canonical); byToken.delete(row.token); totalCanonicalBytes -= row.canonicalBytes; diff --git a/src/contracts/release-tokens.ts b/src/contracts/release-tokens.ts index 1c4135ef..e9d5a6d0 100644 --- a/src/contracts/release-tokens.ts +++ b/src/contracts/release-tokens.ts @@ -32,11 +32,19 @@ function token(name: string, source: string, compatibilityRole: string) { return Object.freeze({ token: name, source, compatibilityRole }); } +/** + * Q-6.7-12. Runtime configuration carries no asset manifest hash, so that + * field is never compared. It used to be filled from the release itself and + * therefore read as a pass; it is reported as unverified instead. + */ +const UNVERIFIED_BY_RUNTIME_CONFIG = Object.freeze([ + "assetManifestHash", +] as const); + /** * Compare a release manifest and runtime configuration structurally. Version * fields are delegated to the numeric compatibility policy, never compared * lexically. - * */ export function compareReleaseToRuntime( release: Readonly<{ @@ -53,14 +61,16 @@ export function compareReleaseToRuntime( RELEASE_ID: string; }>, ) { - return verifyCompatibilityTuple({ + const result = verifyCompatibilityTuple({ frontend: release, runtime: { buildId: runtimeConfig.BUILD_ID, configSchemaVersion: runtimeConfig.CONFIG_SCHEMA_VERSION, apiContractVersion: runtimeConfig.API_CONTRACT_VERSION, + // Placeholder only; see UNVERIFIED_BY_RUNTIME_CONFIG. assetManifestHash: release.assetManifestHash, releaseId: runtimeConfig.RELEASE_ID, }, }); + return Object.freeze({ ...result, unverified: UNVERIFIED_BY_RUNTIME_CONFIG }); } diff --git a/tests/unit/contract-release-checks.test.ts b/tests/unit/contract-release-checks.test.ts new file mode 100644 index 00000000..e309dcba --- /dev/null +++ b/tests/unit/contract-release-checks.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, it } from "vitest"; + +import { + CONTRACT_SET_ALGORITHM, + computeContractSetDigest, +} from "../../src/contracts/contract-set-canonical.ts"; +import { verifyContractSet } from "../../src/contracts/contract-set.ts"; +import { createRuntimeIdentityRegistry } from "../../src/contracts/query-keys.ts"; +import { compareReleaseToRuntime } from "../../src/contracts/release-tokens.ts"; + +/** Q-6.7-12. Quiet passes and small defects in the release contracts. */ + +describe("release to runtime comparison", () => { + it("reports the asset manifest hash as unverified, not as compared", () => { + const result = compareReleaseToRuntime( + { + buildId: "build-a", + configSchemaVersion: "1.0", + apiContractVersion: "1.0", + assetManifestHash: "assets-a", + releaseId: "release-a", + }, + { + BUILD_ID: "build-a", + CONFIG_SCHEMA_VERSION: "1.0", + API_CONTRACT_VERSION: "1.0", + RELEASE_ID: "release-a", + }, + ); + expect(result).toMatchObject({ compatible: true, mismatches: [] }); + expect(result.unverified).toEqual(["assetManifestHash"]); + }); +}); + +describe("contract set verification", () => { + const accounts = Object.freeze({ + packageId: "@example/accounts", + version: "1.2.3", + digest: `sha256:${"1".repeat(64)}` as const, + runtimeProtocolVersion: 1 as const, + sourceRevision: "a".repeat(40), + }); + + it("returns a failure code for a duplicated expected package", async () => { + const manifest = { + setAlgorithm: CONTRACT_SET_ALGORITHM, + setDigest: await computeContractSetDigest([accounts]), + packages: [accounts], + }; + await expect( + verifyContractSet({ expected: [accounts, accounts], manifest }), + ).resolves.toEqual({ ok: false, code: "CONTRACT_SET_DUPLICATE_PACKAGE" }); + }); + + it("still admits a matching set", async () => { + const manifest = { + setAlgorithm: CONTRACT_SET_ALGORITHM, + setDigest: await computeContractSetDigest([accounts]), + packages: [accounts], + }; + await expect( + verifyContractSet({ expected: [accounts], manifest }), + ).resolves.toEqual({ ok: true }); + }); +}); + +describe("runtime identity registry eviction", () => { + it("evicts the least recently touched released row first", () => { + let sequence = 0; + const registry = createRuntimeIdentityRegistry({ + maxEntries: 2, + tokenFactory: () => `identity-token-${String(sequence++).padStart(4, "0")}`, + }); + const first = registry.intern({ resource: "first" }).token; + const second = registry.intern({ resource: "second" }).token; + // Touch "first" again so "second" becomes the eviction candidate. + expect(registry.intern({ resource: "first" }).token).toBe(first); + registry.intern({ resource: "third" }); + expect(registry.inspect().entries).toBe(2); + expect(registry.intern({ resource: "first" }).token).toBe(first); + expect(registry.intern({ resource: "second" }).token).not.toBe(second); + }); +});