Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
release: 0.7.0, and a gate that notices when the version moves (#101)
Matthew Kissinger2c5f30baa92d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 964f36ba..26580ca5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -3,6 +3,27 @@Changes to `@kiln/engine`. Source and installable packages are distributed throughGitHub. The package is not published on the npm registry.+## 0.7.0 — the version moves with what ships — 2026-09-12++- `version` sat at `0.6.0` from the OSS release through **21 shipped changes**, while CI+ named every tarball from it. Two people could hold `kiln-engine-0.6.0.tgz` and have+ materially different software — across a three.js major, a history rewrite and a `dist/`+ re-add. It moves per shipped change now: patch for a fix, minor for changed or added+ capability, which is the normal case pre-1.0.+- **0.7.0 rather than a patch.** What accumulated is behaviour: three.js r186, the+ CommonJS removal it exposed, 128 lines of previously understated tool schema in+ `docs/tools.md`, and a `shadows.type` contract that now selects a filter from+ `basic`/`pcf`/`vsm` instead of naming one that no longer exists.+- A bump has to be rebuilt, because `runtimeBuildIdentity` hashes the version into each+ entry's `identity` in `dist/build.json` — the value a build receipt cites. A test now+ asserts `package.json` and every `dist/build.json` entry agree.+- **Nothing caught that drift before, and this was verified rather than assumed.** With+ the version at 0.7.0 and `dist/` still recording 0.6.0, the full suite passed — 1860+ tests, zero failures. `mcp-bundle.test.ts` rebuilds `dist/mcp-server.mjs` and compares+ bytes, but the version is read from `package.json` at runtime rather than inlined, so+ the bytes are identical and the stale record is invisible to it. Confirmed by the+ rebuild: `dist/build.json` was the only file that changed.+## The documented offline gate did not run two of the repository's checks — 2026-09-12- `bun run test` is `bun test src scripts`, so it never reached `render-service/`. Its 37diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5cfe8980..07e4ef29 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -39,6 +39,20 @@ nothing outside that list, which is how `scripts/` went unlinted while the coverrun measured it. Note that `biome` prints at most 20 diagnostics by default, so acount read off the output is a floor.+### Version++`version` in `package.json` moves with every change that ships. It sat at `0.6.0`+through 21 shipped changes while CI named every tarball from it, so two people could+hold `kiln-engine-0.6.0.tgz` and have materially different software. Patch for a fix,+minor for changed or added capability; this package is pre-1.0 and unpublished, so a+minor is the normal case.++Bumping it means rebuilding: `runtimeBuildIdentity` hashes the version into each+entry's `identity` in `dist/build.json`, which is the value a build receipt cites. Run+`bun run build:runtime` and commit `dist/`. A test asserts the two agree -- nothing else+does, because the version is read from `package.json` at runtime rather than inlined, so+the bundle bytes are identical either way and a byte comparison cannot see the drift.+For behavior changes, first add a focused failing test, then make the smallest fixand run the relevant checks. Keep the coverage thresholds. Ordinary tests use CPUrendering and make no model calls. Live provider tests are optional and can spenddiff --git a/dist/build.json b/dist/build.jsonindex 46e1f691..06af63ab 100644--- a/dist/build.json+++ b/dist/build.json@@ -2,8 +2,8 @@"schemaVersion": 1,"entries": {"mcp": {- "identity": "sha256:20067475685459d0c4b30d1ca041536c6a4d0d2902ee6cd8ba13d45126283676",- "engineVersion": "0.6.0",+ "identity": "sha256:39a3d2c85bfc1bcf872996972abc3e79487d18d22a6a65b572658fda94728b0b",+ "engineVersion": "0.7.0","toolchain": "[email protected]","sourceHash": "8b119c3d8a847dc055b984ce299376e691ae8da52f262a014410c64e19e7ffa2","dependencyHash": "e7aeb48fd1c91bd7719fecea4ae771f611a1271c139c342634d7bf337608a20c",@@ -30,8 +30,8 @@"bundleHash": "sha256:230a45f97a246aba269162fe1b05e3064fa152336ddab2476602a060135fa271"},"cli": {- "identity": "sha256:20067475685459d0c4b30d1ca041536c6a4d0d2902ee6cd8ba13d45126283676",- "engineVersion": "0.6.0",+ "identity": "sha256:39a3d2c85bfc1bcf872996972abc3e79487d18d22a6a65b572658fda94728b0b",+ "engineVersion": "0.7.0","toolchain": "[email protected]","sourceHash": "8b119c3d8a847dc055b984ce299376e691ae8da52f262a014410c64e19e7ffa2","dependencyHash": "e7aeb48fd1c91bd7719fecea4ae771f611a1271c139c342634d7bf337608a20c",@@ -58,8 +58,8 @@"bundleHash": "sha256:00dbff6138a98d8cbe7510c433fc0466683fc317864464b820a963f8f0d21b9d"},"worker": {- "identity": "sha256:20067475685459d0c4b30d1ca041536c6a4d0d2902ee6cd8ba13d45126283676",- "engineVersion": "0.6.0",+ "identity": "sha256:39a3d2c85bfc1bcf872996972abc3e79487d18d22a6a65b572658fda94728b0b",+ "engineVersion": "0.7.0","toolchain": "[email protected]","sourceHash": "8b119c3d8a847dc055b984ce299376e691ae8da52f262a014410c64e19e7ffa2","dependencyHash": "e7aeb48fd1c91bd7719fecea4ae771f611a1271c139c342634d7bf337608a20c",@@ -86,8 +86,8 @@"bundleHash": "sha256:9237ea47c698a012f24762a27f44bb69fbecee8f5f25cc2317595b8d26bfd010"},"agent-run": {- "identity": "sha256:20067475685459d0c4b30d1ca041536c6a4d0d2902ee6cd8ba13d45126283676",- "engineVersion": "0.6.0",+ "identity": "sha256:39a3d2c85bfc1bcf872996972abc3e79487d18d22a6a65b572658fda94728b0b",+ "engineVersion": "0.7.0","toolchain": "[email protected]","sourceHash": "8b119c3d8a847dc055b984ce299376e691ae8da52f262a014410c64e19e7ffa2","dependencyHash": "e7aeb48fd1c91bd7719fecea4ae771f611a1271c139c342634d7bf337608a20c",@@ -114,8 +114,8 @@"bundleHash": "sha256:1aa43d4128308a4e720081b3f9e0903bc971e543273529ff3f1338d9ff2bceb0"},"agent-providers": {- "identity": "sha256:20067475685459d0c4b30d1ca041536c6a4d0d2902ee6cd8ba13d45126283676",- "engineVersion": "0.6.0",+ "identity": "sha256:39a3d2c85bfc1bcf872996972abc3e79487d18d22a6a65b572658fda94728b0b",+ "engineVersion": "0.7.0","toolchain": "[email protected]","sourceHash": "8b119c3d8a847dc055b984ce299376e691ae8da52f262a014410c64e19e7ffa2","dependencyHash": "e7aeb48fd1c91bd7719fecea4ae771f611a1271c139c342634d7bf337608a20c",diff --git a/docs/plans/repo-size-and-r2-migration-2026-09-10.md b/docs/plans/repo-size-and-r2-migration-2026-09-10.mdindex f8a58720..61424728 100644--- a/docs/plans/repo-size-and-r2-migration-2026-09-10.md+++ b/docs/plans/repo-size-and-r2-migration-2026-09-10.md@@ -2086,7 +2086,7 @@ re-measured since the day it was written.| 15.1 | The README's remedy for converting a pre-rewrite clone does not work | **Done 2026-09-12.** See below || 15.2 | Three CI jobs report on every PR and block nothing | **Done 2026-09-12.** Both halves. See below || 15.3 | The documented offline gate does not run render-service's 37 tests, or `check:skills` | **Done 2026-09-12.** See below |-| 15.4 | `version` has been `0.6.0` for 21 shipped changes, and the tarball is named from it | Queued; owner chose to bump per shipped change |+| 15.4 | `version` has been `0.6.0` for 21 shipped changes, and the tarball is named from it | **Done 2026-09-12.** 0.7.0, gated. See below |### 15.1 -- the tag is the whole rewrite, on the clone side too@@ -2217,3 +2217,32 @@ That is three for three in this phase: every fix wired the check into `bun test`than adding a CI job, for the reason Phase 14 gave -- a job is the thing somebody forgetsto add. 15.2 is the exception that proves it, since half of it could only ever be aGitHub setting, and the repository half is what makes that half's absence loud.+++### 15.4 -- a version that did not move, and a gate that could not see it++`version` was set to `0.6.0` at the OSS release and stayed there through 21 shipped+changes, while `package-candidate` named every tarball from it on every push. Two people+holding `kiln-engine-0.6.0.tgz` could have materially different software: the three.js+r186 major, the CommonJS removal, 128 lines of understated tool schema and a changed+`shadows.type` contract all landed under that one filename. That is why 0.7.0 rather+than a patch -- what accumulated is behaviour, not fixes.++The interesting half is the gate. `runtimeBuildIdentity` hashes `engineVersion` into each+entry's `identity` in `dist/build.json`, so a bump that is not rebuilt leaves the+committed bundle claiming a version it was not built at -- and `identity` is the value a+build receipt cites.++**Nothing caught that, and it was measured rather than reasoned.** With `version` at+0.7.0 and `dist/build.json` still recording 0.6.0, the full suite passed: 1860 tests,+zero failures. The obvious candidate to catch it cannot. `mcp-bundle.test.ts` rebuilds+`dist/mcp-server.mjs` and compares sha256 against the committed bytes, but the engine+version is read from `package.json` at module load rather than inlined by the bundler, so+the bytes are byte-identical at any version. The rebuild confirmed it from the other+side: `dist/build.json` was the *only* file that changed, all five `.mjs` bundles+untouched.++So the sequence was the repository's own TDD rule applied to a release step: bump, watch+1860 tests pass on a mismatch, add the assertion, watch it name `mcp 0.6.0` against+`mcp 0.7.0`, rebuild, watch it pass. A byte comparison is not a version check, and the+difference only shows up when the version is the one thing that moved.diff --git a/package.json b/package.jsonindex e6caec24..b03bf1dc 100644--- a/package.json+++ b/package.json@@ -1,7 +1,7 @@{"name": "@kiln/engine","private": true,- "version": "0.6.0",+ "version": "0.7.0","description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.","license": "MIT","author": "Matthew Kissinger",diff --git a/scripts/reliability.test.mjs b/scripts/reliability.test.mjsindex 9c2cb6ed..2f7b6e28 100644--- a/scripts/reliability.test.mjs+++ b/scripts/reliability.test.mjs@@ -252,6 +252,29 @@ describe('repository reliability contracts', () => {expect(scripts.test).not.toContain('render-service');});+ // `version` sat at 0.6.0 through 21 shipped changes while CI named every tarball from+ // it, so two people could hold `kiln-engine-0.6.0.tgz` and have materially different+ // software -- across a three.js major, a history rewrite and a `dist/` re-add. The+ // version moves per shipped change now, which only means anything if the committed+ // bundle agrees with it.+ //+ // Nothing caught the disagreement before. `mcp-bundle.test.ts` rebuilds+ // `dist/mcp-server.mjs` and compares bytes, but the engine version is read from+ // package.json at runtime rather than inlined, so the bytes are identical and the+ // stale `engineVersion` in `dist/build.json` passed unnoticed. `runtimeBuildIdentity`+ // hashes that version into `identity`, which is the value a receipt cites.+ test('the committed runtime bundle records the version it ships as', async () => {+ const { version } = await readJson('package.json');+ const build = await readJson('dist/build.json');++ expect(typeof version).toBe('string');+ const entries = Object.entries(build.entries ?? {});+ expect(entries.length).toBeGreaterThan(0);+ for (const [name, entry] of entries) {+ expect(`${name} ${entry.engineVersion}`).toBe(`${name} ${version}`);+ }+ });+test('standalone agent context stays concise and names the safety-critical paths', async () => {const agents = await readText('AGENTS.md');