Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

docs: the re-clone remedy did not move the rewritten tag (#98)

Matthew Kissingere2a41ed039be
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4609062a..8569dd1c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,31 @@
Changes to `@kiln/engine`. Source and installable packages are distributed through
GitHub. The package is not published on the npm registry.
+## The documented way to convert an old clone did not work — 2026-09-12
+
+- The 2026-09-10 rewrite moved `refs/tags/oss-2026-09-05` as well as `main`, and a tag
+ is the one ref `git fetch` will not update on its own. So the README's remedy
+ — `git fetch origin && git reset --hard origin/main` — left the old tag in place,
+ holding every removed file reachable. Measured on the clone this was found in:
+ `.git` at 228 MB where a fresh clone is 26 MB, with identical content.
+- Reproduced by running the documented commands verbatim in a throwaway copy. The two
+ obvious next guesses are not merely ineffective, they are **refused**: plain
+ `git fetch --tags` and even `--prune-tags` both report `would clobber existing tag`,
+ so a reader has no route to the answer without already knowing `--force`.
+- The instructions now force the tag and then reclaim. Verified end to end on the real
+ stale clone: 228 MB to 23 MB, `fsck` clean, `HEAD` and the working tree hash
+ byte-identical before and after. The plan document already recorded that "the tag was
+ the whole rewrite" for the *push* side; this is the same fact on the clone side, which
+ is the side a reader is on.
+- `scripts/reliability.test.mjs` pins it, and asserts the **absence** of the broken form
+ as well as the presence of the working one — the short version is what a later
+ simplification reaches for.
+- Clone figures re-measured: 60 MB full and 49 MB with `--filter=blob:none`, where the
+ README said 52 MB and 48 MB. `.git` grew from 18 MB to 26 MB when the runtime bundles
+ were re-added after the rewrite; the checkout is unchanged at 34 MB. The timing claims
+ are removed rather than restated — they are network-bound and cannot be honestly
+ re-verified from a different link.
+
## Skill bytes are canonical, and the SEP-2640 record is corrected — 2026-09-12
- Re-read SEP-2640 from the spec text on its PR branch and the working group's own
diff --git a/README.md b/README.md
index d1b1eefb..8f523585 100644
--- a/README.md
+++ b/README.md
@@ -80,19 +80,35 @@ bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png
file contents on the server, fetching them only if you ask for an old revision.
A plain `git clone` also works and gives you the whole history up front.
-History was rewritten on 2026-09-10 to drop 288 MB of gallery renders and launch
-video that no tool reads, taking a clone from 440 MB and 79 seconds to 52 MB and
-8 seconds, or 48 MB with `--filter=blob:none`. Every commit survived and the tree
-is unchanged apart from those files, but every commit hash changed, so a clone
-made before that date cannot fast-forward. Re-clone, or discard local history
-with `git fetch origin && git reset --hard origin/main`. The gallery images are
-served from `assets.kilnstudio.tools`; the 83 poster receipts that attest their
-bytes stayed in `examples/renders/`.
-
This writes a GLB and a six-view image of an existing program. It makes no model call.
Rendering uses the CPU unless a compatible local GPU service is available.
Use `--render cpu` to select the CPU explicitly.
+History was rewritten on 2026-09-10 to drop 288 MB of gallery renders and launch
+video that no tool reads, taking a clone from 440 MB to 60 MB, or 49 MB with
+`--filter=blob:none`; measured 2026-09-12. Every commit survived and the tree is
+unchanged apart from those files, but every commit hash changed, so a clone made
+before that date cannot fast-forward.
+
+Re-cloning is simplest. To convert a clone you already have, move the **tag** as
+well as the branch:
+
+```sh
+git fetch --tags --force origin
+git reset --hard origin/main
+git reflog expire --expire=now --all
+git gc --prune=now
+```
+
+`--force` is the load-bearing flag. `oss-2026-09-05` was rewritten too, and git
+will not move a tag that already exists without it: plain `git fetch --tags`, and
+even `--prune-tags`, both report `would clobber existing tag` and leave the old
+one in place, holding every removed file reachable. Omit it and `.git` stays at
+228 MB where a fresh clone is 26 MB; run it and the same clone packs to 23 MB.
+
+The gallery images are served from `assets.kilnstudio.tools`; the 83 poster
+receipts that attest their bytes stayed in `examples/renders/`.
+
## Connect your agent
The [agent reading guide](site/public/llms.txt) links to setup, tool schemas and the
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.md
index a1e49bec..ff04a05a 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
@@ -2065,3 +2065,73 @@ supplied by an arbitrary connected server -- but if archives ever come back to M
the SEP names the conditions: no symlinks, no non-regular entries, a declared
uncompressed size, never the sole retrieval form, and unpacking to exactly the file
set the entry enumerates.
+
+
+## Phase 15 -- What an audit of the audit found
+
+Opened 2026-09-12, after Phase 14 closed with every row done or blocked upstream. The
+starting question was whether "nothing open" was true, and the way to answer it was to
+measure the repository rather than re-read the record. Every gate passes offline --
+`check:toolchain`, `check:skills`, `typecheck`, `lint` over 481 files, 1858 pass / 2
+skip / 0 fail across 215 files, render-service 37 pass, coverage 95.39% functions /
+92.59% lines with 46 functions and 222 lines of slack. `bun outdated` across all three
+manifests returns only the upstream-blocked `ai` 7 family plus one `webgpu` patch.
+
+So the ledger was accurate. Four things it does not cover came out of measuring anyway,
+and three of them are the same shape: a claim this repository publishes that nobody had
+re-measured since the day it was written.
+
+| ID | Task | State |
+| --- | --- | --- |
+| 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 | Queued; the repository half and the GitHub setting |
+| 15.3 | The documented offline gate does not run render-service's 37 tests, or `check:skills` | Queued |
+| 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.1 -- the tag is the whole rewrite, on the clone side too
+
+Phase 3 already learned this in one direction. `git push --force origin main` looked
+complete while a fresh clone still measured 57 MiB, because `refs/tags/oss-2026-09-05`
+still pointed at the original `d941f15` and held every removed blob reachable; pushing
+the tag took the clone from 92 MB to 52 MB, and the note written then says *"anyone
+repeating this work should push every ref."*
+
+The same fact applies to a reader converting an old clone, and the README did not say
+so. Its remedy was `git fetch origin && git reset --hard origin/main`, which moves the
+branch and leaves the tag. **This working copy was the evidence**: `.git` at 228 MB,
+`HEAD` in sync with `origin/main`, the local tag still at `d941f15` with 66 removed
+PNGs, against a fresh clone's 26 MB of identical content.
+
+Reproduced in a throwaway copy by running the documented commands verbatim -- 59 MB
+afterwards, and only because a `git gc` the README never mentions was added; without it,
+228 MB. The two obvious next guesses are worse than ineffective, they are **refused**:
+
+| Command | Result |
+| --- | --- |
+| `git fetch origin && git reset --hard origin/main` (documented) | tag unchanged at `d941f15` |
+| `git fetch --tags origin` | `! [rejected] ... would clobber existing tag` |
+| `git fetch --prune-tags --tags origin` | same rejection |
+| `git fetch --tags --force origin` | `t [tag update]`, then 23 MB after `gc --prune=now` |
+
+A reader therefore cannot discover `--force` by trying the obvious things first, which
+is what makes this a documentation defect rather than a shortcut anybody would find.
+
+Fixed, pinned in `scripts/reliability.test.mjs`, and verified the way the ratchet's own
+tests are: the assertion fails on the old README text for the stated reason before it
+passes on the new one. It asserts the **absence** of the broken form as well as the
+presence of the working one, because the short version is the one a later simplification
+reaches for.
+
+Applied to this clone as well, backup first: a `git bundle` of the pre-rewrite lineage
+(`dd9d5f7`, 177 commits, 235 MB) was written outside the tree and *verified by restoring
+it* -- 119 removed files present at the tip, and all 83 posters recovered with sha256
+matching the `imageHash` in their `examples/renders/*.json` receipts, which is invariant
+I1 from Phase 1 run against the backup instead of the bucket. Only then the tag was
+forced and the objects pruned: 228 MB to 23 MB, `fsck` clean, `HEAD` and tree hash
+byte-identical.
+
+**The clone figures had also drifted**, which is the second instance of the same shape.
+60 MB full and 49 MB filtered, where the README said 52 MB and 48 MB: `.git` grew 18 MB
+to 26 MB when the runtime bundles were re-added after the rewrite, and the checkout is
+unchanged at 34 MB. The timing claims came out rather than being restated, because they
+are network-bound and cannot be honestly re-measured from a different link.
diff --git a/scripts/reliability.test.mjs b/scripts/reliability.test.mjs
index f51cf023..ad0cce25 100644
--- a/scripts/reliability.test.mjs
+++ b/scripts/reliability.test.mjs
@@ -154,6 +154,27 @@ describe('repository reliability contracts', () => {
expect(workflow).toContain('Report the native dependency inventory');
});
+ // The 2026-09-10 rewrite moved `refs/tags/oss-2026-09-05` as well as `main`, and a
+ // tag is the one ref `git fetch` will not update on its own. That makes the stale
+ // tag, not the branch, what keeps 288 MB of removed files reachable in an old clone
+ // -- so the documented remedy has to force it. This is not hypothetical tidying: the
+ // instructions here really did omit it, and a clone that had run them still measured
+ // 228 MB against a fresh clone's 26 MB.
+ //
+ // Asserting the absence matters more than asserting the presence. The broken form is
+ // the shorter, more obvious one, so it is what a later edit reaches for.
+ test('the re-clone remedy moves the rewritten tag, not just the branch', async () => {
+ const readme = await readText('README.md');
+
+ expect(readme).toContain('git fetch --tags --force origin');
+ // Both near-misses are *refused* by git rather than silently ineffective, which is
+ // why a reader cannot discover `--force` by trying the obvious things first.
+ expect(readme).not.toContain('git fetch origin && git reset --hard origin/main');
+ expect(readme).toContain('oss-2026-09-05');
+ // Forcing the tag frees nothing until the objects it pinned are actually dropped.
+ expect(readme).toContain('git gc --prune=now');
+ });
+
test('standalone agent context stays concise and names the safety-critical paths', async () => {
const agents = await readText('AGENTS.md');