A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(contract): enumerate the runtime contract facts, and what would notice
yhh381b60033860
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 24625f6df..e45e267ee 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,39 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **An inventory of what the engine's runtime contract facts actually are.** The+ `EsEventOut` hole above was not thin test coverage — the ABI compatibility+ system did not know a fact lived there. Those are different severities and+ nothing could tell them apart, because nothing enumerated the facts.++ `tools/contract-inventory.mjs` enumerates them: fourteen, each declaring who+ AUTHORS it, what is PROJECTED from it, what independently VERIFIES it, and+ whether a digest covers it. It is deliberately descriptive — no authority+ moves and nothing is generated from it. What exists comes first; which+ authorities are worth merging is a decision that needs this list to make.++ Two kinds of finding, and the second is what keeps it from becoming a list+ somebody remembers. A CLAIM that no longer holds: every citation carries a+ probe, so an entry pointing at a fact that has moved is red rather than stale+ documentation. And GROUND with no claim over it: a generated artifact no fact+ projects, or a `C++ contract:` pin no fact names, is a fact nobody wrote down.++ The three roles are kept apart, and the checker refuses to let them merge — a+ file cited as both a projection and the verification of the same fact is a+ generator being asked whether it generated correctly. That rule caught one on+ its first run: `es_check_sysctx` proves the emitted C struct matches the+ emitted constant, which is the generator agreeing with itself; the independent+ verification is the sabotage suite.++ Five facts carry a declared gap, so the list reads as work rather than as+ permission — `entityRepresentation` and `mathPolicy` are in no digest at all,+ and three hand-copied constants are pinned by a test rather than a handshake.+ Two authors is not automatically a defect: `mathPolicy` is two independent+ implementations held together by a bit-exact differential, which proves more+ than generating one from the other would.+### Fixed- **A fourth ABI struct was outside the compatibility system entirely.** Three ofdiff --git a/tools/contract-inventory.mjs b/tools/contract-inventory.mjsnew file mode 100644index 000000000..1bb7a87bb--- /dev/null+++ b/tools/contract-inventory.mjs@@ -0,0 +1,219 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file contract-inventory.mjs — what Estella's runtime contract facts are,+ * who authors each, and what would notice if one changed.+ *+ * `EsEventOut` shipped for as long as it existed with no word count of its own,+ * no compile-time check and no term in any digest. That was not thin test+ * coverage — the ABI compatibility system did not know a fact lived there. The+ * two are different severities and nothing could tell them apart, because+ * nothing enumerated the facts.+ *+ * This enumerates them. It is DESCRIPTIVE on purpose: no authority moves, no+ * artifact is generated from here. First answer what exists, then decide what is+ * worth canonicalising — the reverse builds a central schema and then goes+ * looking for things to put in it.+ *+ * Two kinds of finding, and the second is the one that keeps this honest:+ *+ * - A CLAIM that no longer holds. Every citation carries a probe, so an entry+ * pointing at a fact that has moved is red rather than stale documentation.+ * - GROUND with no claim over it. A generated artifact no fact projects, or a+ * `C++ contract:` pin no fact names, is a fact nobody wrote down. This is+ * the same comparison `check-verification-authority` makes, and it is why a+ * longer list would not have done.+ *+ * Sabotaged in four directions before it was trusted, each red on its own line+ * and nothing else: a probe pointed at a moved fact, a verification that was+ * also a projection, an unattributed `*.generated.*`, and a `C++ contract:` pin+ * no fact named.+ *+ * node tools/contract-inventory.mjs [--json]+ */+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { execFileSync } from 'node:child_process';+import { FACTS, NOT_CONTRACT } from './lib/contractFacts.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const JSON_OUT = process.argv.includes('--json');+const findings = [];+const notes = [];++const read = (p) => readFileSync(path.join(ROOT, p), 'utf8');++/** Every file under a directory, so a directory author can be probed. */+function walk(dir, out = []) {+ for (const name of readdirSync(path.join(ROOT, dir))) {+ const child = `${dir}/${name}`;+ if (statSync(path.join(ROOT, child)).isDirectory()) walk(child, out);+ else out.push(child);+ }+ return out;+}++/**+ * Does the fact still live where the entry says? A citation is only worth+ * having if it fails when the thing it points at moves.+ */+function probeHolds(cite) {+ const at = path.join(ROOT, cite.path);+ if (!existsSync(at)) return 'no such path';+ if (cite.dir) {+ const files = walk(cite.path);+ if (!files.length) return 'directory is empty';+ for (const f of files) {+ try {+ if (cite.probe.test(read(f))) return null;+ } catch { /* binary or unreadable; the next file may match */ }+ }+ return `no file under it matches ${cite.probe}`;+ }+ return cite.probe.test(read(cite.path)) ? null : `does not match ${cite.probe}`;+}++/**+ * Authority, projection and verification are three roles, and the third has to+ * be INDEPENDENT of the first two or the green means nothing. A file that is+ * both a projection and the verification of the same fact is a generator being+ * asked whether it generated correctly.+ */+function checkRoleSeparation(fact) {+ const projected = new Set(fact.projections);+ for (const v of fact.verification) {+ if (projected.has(v.path)) {+ findings.push(`${fact.id}: ${v.path} is cited as BOTH a projection and a`+ + ' verification. A derivation cannot verify itself.');+ }+ }+}++/** Computed, never declared: the status is what the citations add up to. */+function statusOf(fact) {+ const semantic = fact.authors.filter((a) => a.kind === 'semantic');+ const impl = fact.authors.filter((a) => a.kind === 'implementation');+ const verified = fact.verification.length > 0;+ if (impl.length > 1) {+ return verified ? 'multi-implementation-differential' : 'multi-implementation-unbound';+ }+ if (semantic.length > 1) {+ return verified ? 'multi-author-machine-verified' : 'multi-author-unbound';+ }+ if (fact.digest) return 'single-author-covered';+ return verified ? 'single-author-verified' : 'single-author-unverified';+}++const RED_STATUS = new Set(['multi-author-unbound', 'multi-implementation-unbound', 'single-author-unverified']);++const report = [];+for (const fact of FACTS) {+ for (const [role, cites] of [['author', fact.authors], ['verification', fact.verification]]) {+ for (const cite of cites) {+ const why = probeHolds(cite);+ if (why) findings.push(`${fact.id}: ${role} ${cite.path} — ${why}`);+ }+ }+ for (const p of fact.projections) {+ if (!existsSync(path.join(ROOT, p))) findings.push(`${fact.id}: projection ${p} — no such path`);+ }+ if (fact.digest) {+ const why = probeHolds(fact.digest);+ if (why) findings.push(`${fact.id}: digest ${fact.digest.name} at ${fact.digest.path} — ${why}`);+ }+ checkRoleSeparation(fact);++ const status = statusOf(fact);+ if (RED_STATUS.has(status) && !fact.owed) {+ findings.push(`${fact.id}: ${status} — more than one author and nothing compares them,`+ + ' and no `owed` says why that is accepted.');+ }+ // The debt is paid the day the gate says so, not the day someone remembers.+ if (fact.owed && fact.digest && /no digest covers it/.test(fact.owed)) {+ findings.push(`${fact.id}: owes "no digest covers it" but now HAS one (${fact.digest.name}).`+ + ' Delete the `owed` line — a gap that reads as open after it closed is worse than none.');+ }+ report.push({ ...fact, status });+}++// ── Ground: every generated artifact belongs to a fact ────────────────────────+const tracked = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8' })+ .split('\n').filter(Boolean)+ .filter((f) => !/^(third_party|build)\//.test(f));++const GENERATED_NAME = /\.generated\.|\/generated\//;+const DECLARES_GENERATED = /auto-generated|GENERATED by|@generated|generatedBy|DO NOT EDIT|do not edit/i;+const generated = tracked.filter((f) => {+ if (!/\.(ts|tsx|js|mjs|c|h|hpp|cpp|json|d\.ts)$/.test(f)) return false;+ if (GENERATED_NAME.test(f)) return true;+ try {+ return DECLARES_GENERATED.test(read(f).slice(0, 400));+ } catch {+ return false;+ }+});++const projected = new Set(FACTS.flatMap((f) => f.projections));+for (const g of generated) {+ if (projected.has(g) || NOT_CONTRACT[g]) continue;+ findings.push(`GROUND: ${g} is generated, and no fact projects it. Either it derives`+ + ' from an authority (add it) or it is not a contract (say so in NOT_CONTRACT).');+}+for (const [p, why] of Object.entries(NOT_CONTRACT)) {+ if (!existsSync(path.join(ROOT, p))) findings.push(`NOT_CONTRACT names ${p}, which is gone — ${why}`);+}++// ── Ground: every hand-copied cross-language pin belongs to a fact ────────────+const PIN_FILE = 'sdk/tests/cpp-contract.test.ts';+if (existsSync(path.join(ROOT, PIN_FILE))) {+ const src = read(PIN_FILE);+ const titles = [...src.matchAll(/describe\('C\+\+ contract: ([^']*?) \(([^)]*)\)'/g)].map((m) => m[1]);+ const probes = FACTS.flatMap((f) => f.verification.filter((v) => v.path === PIN_FILE).map((v) => v.probe));+ for (const title of titles) {+ if (!probes.some((p) => p.test(title))) {+ findings.push(`GROUND: "${PIN_FILE}" pins "${title}", and no fact names that pin.`+ + ' A constant hand-copied across the boundary is a fact whether or not it is written down.');+ }+ }+ notes.push(`${titles.length} cross-language pin(s) in ${PIN_FILE}, each claimed by a fact.`);+} else {+ findings.push(`GROUND: ${PIN_FILE} is gone; the cross-language pins it held are now unclaimed.`);+}++// ── Say it ───────────────────────────────────────────────────────────────────+if (JSON_OUT) {+ const shape = report.map((f) => ({+ id: f.id,+ what: f.what,+ surface: f.surface,+ status: f.status,+ authors: f.authors.map((a) => ({ path: a.path, kind: a.kind })),+ projections: f.projections,+ verification: f.verification.map((v) => ({ path: v.path, how: v.how })),+ digest: f.digest ? f.digest.name : null,+ owed: f.owed ?? null,+ }));+ console.log(JSON.stringify({ facts: shape, findings }, null, 2));+} else {+ const width = Math.max(...report.map((f) => f.id.length));+ for (const f of report) {+ const digest = f.digest ? f.digest.name : '—';+ console.log(` ${f.id.padEnd(width)} ${f.status.padEnd(33)} digest: ${digest}`);+ }+ const owed = report.filter((f) => f.owed);+ if (owed.length) {+ console.log(`\n${owed.length} declared gap(s) — work, not permission:`);+ for (const f of owed) console.log(` ${f.id}: ${f.owed}`);+ }+ for (const n of notes) console.log(`\n${n}`);+ console.log(`\n${generated.length} generated artifact(s), each attributed.`);+}++if (findings.length) {+ console.error(`\ncontract-inventory: ${findings.length} finding(s).`);+ for (const f of findings) console.error(` ${f}`);+ process.exit(1);+}+if (!JSON_OUT) console.log(`\ncontract-inventory: ${FACTS.length} fact(s), every claim held against the tree.`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 30a097706..9a03105c5 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -221,6 +221,10 @@ export const GATES = [// error, it is a picture that is merely wrong. cpp-contract pins the ones// somebody remembered; this says which ones nobody did.{ id: 'enum-twins', run: 'node tools/check-enum-twins.mjs' },+ // …and this says which facts nobody wrote down at all. A generated artifact no+ // authority claims, or a cross-language pin no fact names, is a compatibility+ // fact outside the compatibility system — the state EsEventOut was in.+ { id: 'contract-inventory', run: 'node tools/contract-inventory.mjs' },{ id: 'examples', run: 'node build-tools/cli.js check-examples' },{ id: 'documents', run: 'node build-tools/cli.js validate-documents' },];diff --git a/tools/lib/contractFacts.mjs b/tools/lib/contractFacts.mjsnew file mode 100644index 000000000..ccfaf1d81--- /dev/null+++ b/tools/lib/contractFacts.mjs@@ -0,0 +1,270 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file contractFacts.mjs — the runtime contract facts, declared.+ *+ * A fact is something the engine and something else must agree about or one of+ * them reads the wrong bytes. This file says, for each: who AUTHORS it, what is+ * PROJECTED from it, what independently VERIFIES it, and whether a digest+ * covers it. `contract-inventory.mjs` holds every claim here against the tree.+ *+ * The three roles are kept apart on purpose. An authority owns the fact; a+ * projection derives it into another representation; a verification decides+ * INDEPENDENTLY whether the two agree. Folding verification into the authority+ * graph is how a green build stops meaning anything — a schema asking a+ * generator whether it generated the schema. So a verification may never name a+ * file that is also a projection of the same fact, and the checker refuses one.+ *+ * `probe` is what makes this different from a list somebody remembers: the fact+ * has to still be findable where the entry says it is, or the entry is a+ * finding rather than documentation.+ *+ * An author's `kind` is `semantic` (owns what the fact IS — more than one is+ * drift waiting) or `implementation` (a second realisation of a fact specified+ * elsewhere). Two implementations plus a differential is STRONGER than+ * generating one from the other: same-source generation proves both inherited+ * one implementation, an independent pair proves both satisfy the contract.+ *+ * A verification's `how` is `compiler` (the build fails), `handshake` (the two+ * sides compare at run time and refuse), `test` (a suite parses the other side+ * and asserts), or `independent-source` (a list written from the spec, not+ * derived from the thing it checks — never collapse one of those into an+ * authority).+ */++export const FACTS = [+ {+ id: 'componentShapes',+ what: 'Every field of every engine component, and the offset its C++ struct puts it at.',+ surface: 'runtime-wasm-abi',+ authors: [+ { path: 'src/esengine/ecs/components', dir: true, probe: /ES_COMPONENT/, kind: 'semantic' },+ ],+ projections: [+ 'sdk/src/wasm/ptrLayouts.generated.ts',+ 'sdk/src/wasm/wasm.generated.ts',+ 'sdk/src/ecs/component.generated.ts',+ 'sdk/src/ecs/bridge/ptrAccessors.generated.ts',+ 'sdk/src/ecs/bridge/nativeEngineApi.generated.ts',+ 'sdk/esengine.d.ts',+ 'src/esengine/bindings/WebBindings.generated.cpp',+ 'src/esengine/bindings/EditorAPI.generated.cpp',+ 'src/esengine/aot/AotComponents.generated.hpp',+ 'src/esengine/aot/AotComponents.generated.cpp',+ 'docs/astro/src/data/components.generated.json',+ ],+ verification: [+ { path: 'sdk/src/ecs/bridge/BuiltinBridge.ts', how: 'handshake', probe: /ABI_LAYOUT_HASH/ },+ { path: 'tools/check-native-components.mjs', how: 'test', probe: /PTR_ACCESSORS/ },+ { path: 'tools/check-component-fields.mjs', how: 'test', probe: /a declared field has a reader/ },+ ],+ digest: { name: 'eht-abi-layout-hash', path: 'sdk/src/ecs/component.generated.ts', probe: /ABI_LAYOUT_HASH/ },+ },+ {+ id: 'abiStructs',+ what: 'The word width of every struct a compiled system is handed by address.',+ surface: 'runtime-aot-abi',+ authors: [+ { path: 'sdk/src/ecs/aot/abiDigest.ts', probe: /export const SYSCTX_WORDS/, kind: 'semantic' },+ ],+ projections: [+ 'src/esengine/aot/estella_abi.h',+ 'src/esengine/aot/EngineDigest.generated.h',+ ],+ verification: [+ { path: 'compiler/tests/abi-structs.test.ts', how: 'test', probe: /refuses a field appended/ },+ ],+ digest: { name: 'engine-abi', path: 'sdk/src/ecs/aot/abiDigest.ts', probe: /sysctx=/ },+ },+ {+ id: 'commandRecords',+ what: 'What a compiled system may ask the host to do, as a kind number in a four-word record.',+ surface: 'runtime-aot-abi',+ authors: [+ { path: 'sdk/src/ecs/aot/abiDigest.ts', probe: /export const CMD_DESPAWN/, kind: 'semantic' },+ ],+ projections: ['src/esengine/aot/estella_abi.h'],+ verification: [+ { path: 'compiler/tests/abi-structs.test.ts', how: 'test', probe: /es_check_cmd/ },+ ],+ digest: { name: 'engine-abi', path: 'sdk/src/ecs/aot/abiDigest.ts', probe: /cmdkinds=/ },+ },+ {+ id: 'resourceShapes',+ what: 'The built-in resources a compiled system can read: their members, and which method reads which bit set.',+ surface: 'runtime-aot-abi',+ authors: [+ { path: 'sdk/src/ecs/resourceShapes.ts', probe: /export const RESOURCE_SHAPES/, kind: 'semantic' },+ ],+ projections: [],+ verification: [+ { path: 'sdk/tests/resource-shape.test.ts', how: 'test', probe: /engineAbiParts/ },+ ],+ digest: { name: 'engine-abi', path: 'sdk/src/ecs/aot/abiDigest.ts', probe: /RESOURCE_NAMES/ },+ },+ {+ id: 'aotFixtureModule',+ what: 'One compiled system, checked in so the C++ harness builds without running the compiler.',+ surface: 'internal',+ authors: [+ { path: 'compiler/src/codegen.ts', probe: /export function emitC/, kind: 'semantic' },+ ],+ projections: [+ 'tests/aot/generated/estella_offsets.h',+ 'tests/aot/generated/move_system.c',+ 'tests/aot/generated/move_system_decl.c',+ 'tests/aot/generated/move_system_hash.h',+ ],+ verification: [+ { path: 'compiler/tests/generated.test.ts', how: 'test', probe: /ESTELLA_AOT_WRITE/ },+ ],+ digest: { name: 'engine-abi', path: 'tests/aot/generated/move_system_hash.h', probe: /ES_EXPECTED_CONTRACT_HASH/ },+ },+ {+ id: 'entityRepresentation',+ what: 'How an entity handle packs an index and a generation into one u32.',+ surface: 'runtime-wasm-abi',+ authors: [+ { path: 'sdk/src/types.ts', probe: /export const ENTITY_INDEX_BITS/, kind: 'semantic' },+ { path: 'src/esengine/core/Types.hpp', probe: /using Layout = PackedId</, kind: 'semantic' },+ ],+ projections: [],+ verification: [+ { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /packed Entity bit split/ },+ ],+ digest: null,+ owed: 'no digest covers it: the split crosses as a bare u32, so a mismatch is a decoded'+ + ' handle pointing at another entity rather than a refusal. The test parses the'+ + ' header, which is a binding but not a handshake.',+ },+ {+ id: 'mathPolicy',+ what: 'The numeric subset a compiled system may use, specified to the bit because ECMAScript does not specify trigonometry.',+ surface: 'runtime-aot-abi',+ authors: [+ { path: 'sdk/src/math/exact.ts', probe: /function kernelSin/, kind: 'implementation' },+ { path: 'compiler/src/codegen.ts', probe: /es_kernel_sin/, kind: 'implementation' },+ ],+ projections: ['src/esengine/aot/estella_abi.h'],+ verification: [+ { path: 'compiler/tests/exact-trig.test.ts', how: 'test', probe: /bit for bit/i },+ ],+ digest: null,+ owed: 'no digest covers it: a module built against a different polynomial loads and'+ + ' answers different pixels. The differential is bit-exact but needs a host C'+ + ' compiler, so a checkout without one verifies nothing here.',+ },+ {+ id: 'tweenWireEnums',+ what: 'The tween easing/state/loop/target enums, which cross the boundary as bare numbers.',+ surface: 'runtime-wasm-abi',+ authors: [+ { path: 'src/esengine/animation/TweenData.hpp', probe: /enum class/, kind: 'semantic' },+ { path: 'sdk/src/animation/TweenTypes.ts', probe: /TweenState/, kind: 'semantic' },+ ],+ projections: [],+ verification: [+ { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /animation tween enums/ },+ { path: 'tools/check-enum-twins.mjs', how: 'test', probe: /owes a pin/ },+ ],+ digest: null,+ owed: 'hand-copied, outside the directory EHT parses. The pin is a test, not a'+ + ' handshake: a drift ships if the suite is not run.',+ },+ {+ id: 'particleColorLut',+ what: 'How many entries the particle colour lookup table has, which is its stride on both sides.',+ surface: 'runtime-wasm-abi',+ authors: [+ { path: 'src/esengine/particle/ParticleSystem.hpp', probe: /LUT/, kind: 'semantic' },+ { path: 'sdk/src/particle/gradient.ts', probe: /GRADIENT_LUT_SIZE/, kind: 'semantic' },+ ],+ projections: [],+ verification: [+ { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /particle color LUT/ },+ ],+ digest: null,+ owed: 'hand-copied; the pin is a test, not a handshake.',+ },+ {+ id: 'tilemapCellEncoding',+ what: 'Which bits of a tile word are the id and which are the three flip flags.',+ surface: 'project-asset-format',+ authors: [+ { path: 'src/esengine/tilemap/TilemapSystem.hpp', probe: /FLIP/, kind: 'semantic' },+ { path: 'sdk/src/tilemap/tileBits.ts', probe: /TILE_ID_MASK/, kind: 'semantic' },+ ],+ projections: [],+ verification: [+ { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /tilemap cell encoding/ },+ ],+ digest: null,+ owed: 'hand-copied; and it is a FILE format, so a drift mis-renders every saved map'+ + ' rather than failing to load.',+ },+ {+ id: 'uiBaseLayer',+ what: 'The layer number UI elements draw from, which orders them against the world.',+ surface: 'runtime-wasm-abi',+ authors: [+ { path: 'src/esengine/renderer/plugins/UIElementPlugin.hpp', probe: /Layer/i, kind: 'semantic' },+ ],+ projections: [],+ verification: [+ { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /UI base layer/ },+ ],+ digest: null,+ },+ {+ id: 'shaderSources',+ what: 'The engine shaders, and the WGSL twin each one needs to reach the second backend.',+ surface: 'internal',+ authors: [+ { path: 'src/esengine/data/shaders', dir: true, probe: /#pragma shader/, kind: 'semantic' },+ ],+ projections: ['src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp'],+ verification: [+ { path: 'tools/check-wgsl-twin.mjs', how: 'test', probe: /fragment stage/ },+ { path: 'tools/check-shader-blocks.mjs', how: 'test', probe: /shader/i },+ ],+ digest: null,+ },+ {+ id: 'apiTiers',+ what: 'The stability tier every exported SDK symbol carries, and what that tier promises.',+ surface: 'sdk-api',+ authors: [+ { path: 'sdk/src', dir: true, probe: /@public/, kind: 'semantic' },+ ],+ projections: ['docs/astro/src/data/apiStability.generated.json'],+ verification: [+ { path: 'tools/api-surface.mjs', how: 'test', probe: /check-baseline/ },+ { path: 'tools/check-freeze-bar.mjs', how: 'test', probe: /public/i },+ ],+ digest: null,+ },+ {+ id: 'uiWidgetPrefabs',+ what: 'The built-in UI widgets, as prefab data the SDK ships rather than reads from disk.',+ surface: 'sdk-api',+ authors: [+ { path: 'sdk/src/ui/widgets/prefabs', dir: true, probe: /"version"/, kind: 'semantic' },+ ],+ projections: ['sdk/src/ui/widgets/prefabs/generated.ts'],+ verification: [+ { path: 'sdk/tests/ui-widget-prefabs.gen.test.ts', how: 'test', probe: /prefab/i },+ ],+ digest: null,+ },+];++/**+ * Generated artifacts that are NOT a projection of a contract fact, and why.+ * Being generated is not the same as being derived from a contract: a measured+ * baseline records what a machine did, and pinning it to an authority would+ * claim a fact the number does not carry.+ */+export const NOT_CONTRACT = {+ 'sdk/etc/perf.snapshot.json':+ 'a measured baseline, not a derivation — accepted with `perf-guard --update`.',+};