Skip to content

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.

feat(contract): enumerate the runtime contract facts, and what would notice

yhh381b60033860
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 of
diff --git a/tools/contract-inventory.mjs b/tools/contract-inventory.mjs
new file mode 100644
index 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.mjs
index 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.mjs
new file mode 100644
index 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`.',
+};