Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 27 additions & 11 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,32 @@ name: ci
# Before this layout (run 44460876935, 2026-11-19): 9 minutes wall, 26 jobs, 87.5 runner-minutes;
# gate shard 1 took 8 minutes (all 474 test files plus a recipe slice) and shots shards up to
# 8.3 minutes (four `t3d` processes per folder, each re-importing and recompiling the recipe).
# Now: 16 shards (T3D_SHARD=k/16, CI_SHARDS in scripts/lib/shard.ts). Each runs its `bun test --shard`
# slice (balanced by scripts/lib/test-timings.json) and its units of recipe work, split by
# measured cost (scripts/lib/recipe-costs.json; greedy longest-first, scripts/lib/shard.ts): one
# folder's gate and its renders are separate units, renders take one process per folder
# Now: 18 shards (T3D_SHARD=k/18, CI_SHARDS in scripts/lib/shard.ts; with `site` that is 19 jobs,
# under the 20 a free account runs at once). Each runs its `bun test --shard` slice (balanced by
# scripts/lib/test-timings.json) and its units of recipe work, split by measured cost
# (scripts/lib/recipe-costs.json; greedy longest-first, scripts/lib/shard.ts): one folder's gate
# and its renders are separate units, renders take one process per folder
# (scripts/shots-folder.ts); shard 1 also runs lint, types, build and pack.
# Measured 2026-11-19 (run 44474402275): 6.6 minutes push → green, shards 2.6-6.4 minutes,
# 76 runner-minutes. The floor is one unit: human_head's renders, because each of shot / hero /
# blueprint / icon compiles its LOD0 again (about 55 s each). Under 5 minutes needs the four
# renders to share one compile (a src/cli change; docs/maintenance.md "CI time"). When shards
# drift: `bun run scripts/recipe-costs.ts --tests`, then `--plan` to pick the shard count.
# Measured 2026-11-19 with 16 shards (run 44474402275): 6.6 minutes push → green, shards
# 2.6-6.4 minutes, 76 runner-minutes; the floor was human_head's renders, where each of shot /
# hero / blueprint / icon compiled LOD0 again. Since then the four renders share one compile
# (src/cli/compile-cache.ts).
# Measured 2026-11-19 with 18 shards (run 44492321426): 5.5 minutes push → green, 18 gate jobs of
# 155-299 s (mean 222 s), about 67 runner-minutes. The work was already small enough; the split
# was off by up to 35%, because the costs were dev-machine seconds with one guessed factor for
# renders (real factors: 0.9 to 2.3 per folder). Slowest shard 299 s: shard 8, whose rts_barracks
# renders took 153 s against 94 s in the costs.
# The costs are now that run's own GitHub seconds (`bun run scripts/recipe-costs.ts --from-run
# 44492321426`; scripts/recipe-costs-run.ts says what is measured and what is derived), with
# 16 s of overhead per job (checkout, setup, the stale check) and 26 s of shard 1's own steps.
# Measured after rebalancing (run 44494826233, 2026-11-19): 4.6 minutes push → green, slowest job 269 s.
# The plan it ran on: still 18 shards (the fewest whose worst job fits 240 s), every job
# about 222 s (`--plan`: 221-223 s; up to 237 s where the heaviest recipe shard also draws the
# 30 s test file src/kinds/creature-family.test.ts), about 4.3 minutes push → green (the slowest
# job plus about 30 s of queueing and the `verify` job), the same 67 runner-minutes. No single
# unit is the floor: the largest are face_demo's renders (171 s) and gate (166 s). Replace this
# paragraph with the next measured run. When shards drift: `--from-run <id>` on the commit a
# green run built, then `--plan` to pick the shard count (★).
# Docs-only changes (scripts/ci-changes.ts: Markdown / docs/ outside recipes/) skip the recipe
# gate and the renders; lint, types and every test still run, and `verify` still reports.

Expand All @@ -43,9 +59,9 @@ jobs:
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
env:
T3D_SHARD: ${{ matrix.shard }}/16
T3D_SHARD: ${{ matrix.shard }}/18
steps:
# Full history without old file contents (blob:none): enough for `git diff --name-only`.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Expand Down
8 changes: 7 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,15 @@ Several agents can share one machine through a resource queue, CI is balanced by
- `build`, `shot`, `hero`, `review`, `critique`, `blueprint`, `icon`, `gaps`, `tune`, `finish`, `concept` and `neural run` take one CPU token; `hero --quality path` takes 8 and traces on the threads granted (same bytes). `blender review` and `blender session start|run|finish` take `blender`; Blender adapter jobs and jobs sent to a loopback model URL take `blender` / `gpu` while they run. A waiting command prints one `t3d queue: waiting …` line on stderr.
- `bun run verify` holds one place in the queue for the whole gate; tests run with the queue off.
- CI: `gate` and `shots` are one 16-shard `gate` job (26 jobs → 18) balanced by measured cost (`scripts/lib/recipe-costs.json`, `scripts/lib/test-timings.json`); `bun test` is split across the shards; docs-only changes skip the recipe gate and the renders. `verify` stays the single required check.
- `bun run shots` renders each folder's sheet, hero, blueprint and icon in one process, byte-identical to the four separate commands.
- `bun run shots` renders each folder's sheet, hero, blueprint and icon in one process and from one compile per asset and LOD (`human_head` renders 242 s → 88 s locally), byte-identical to the four separate commands. The shared compile is off everywhere else, so `t3d mcp` never serves an old compile.
- `bear_hybrid`, `wolf_hybrid` and `dragon_hybrid` are model-first with no CPU build: `t3d build` with a model output missing stops with one `T3D_NEURAL_MISSING` instead of building a code creature that fails QA. `modelChain` takes `required: true` and `ctx.neural` asks take `{ required: true }`; `ranger` and `human_head` keep their CPU fallback.
- CI: 18 gate shards with costs calibrated from a real run: `bun run scripts/recipe-costs.ts --from-run <run id>` reads a green `ci` run's logs and rewrites the cost files in GitHub seconds; `--plan` marks the shard count to pick. Measured 5.5 min and 67 runner-minutes before rebalancing (jobs 155–299 s); measured 4.6 min push → green after (slowest job 269 s), under the 5-minute target for the first time since it was set.

### Fixed
- The npm package is 4.2 MB instead of 40.6 MB: model recipes' generated outputs (`recipes/*/neural/`) stay in git. 0.13.0 shipped them without the concept images they need, so they never built from the package. The `pack` gate step now fails when the tarball goes over 5.3 MB packed or 16 MB unpacked, holds a file over 1 MB, or holds anything under `recipes/*/neural/`.
- `T3D_NEURAL_MISSING` for a recipe inside the installed package says the package ships no model outputs and to clone the repo or copy the recipe folder; a `--require-neural` miss no longer says "using the CPU path".
- Model creatures: a rigger's terminal stub bone on a leg (UniRig, 6 mm past the toe) no longer shifts hip, stifle, hock and paw one joint down and gets the rig refused (`T3D_MODEL_SKELETON`).
- Critiques: every committed asset has a well-formed critique bound to its current renders, re-judged from the images, with a fix note under every score below 10. Malformed critiques had been hiding their scores from the gate.
- CI's "committed renders match a fresh render" check never failed: its pathspec `recipes/*/out` matches no file under `out/`. It now uses `:(glob)recipes/*/out/**`, and a test proves the pathspec lists the committed outputs (D286).
- `rts_faction`: committed renders refreshed; they still showed the tank's old belt weathering, which the broken check let through.

Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Human names a thing → research specs + real photos into `recipes/<name>/README
## Coordination and CI
- **Finish the job:** fix, test, document, run the gate. Decide and state decisions rather than asking what code/docs answer. Ask only before irreversible/outward-facing acts.
- **Hive** (big tasks: `/feature`): one checkout, never git worktrees; only the top-level agent spawns; exclusive file sets, no git for agents; max 4 parallel; coordinator runs the full gate once at the end. Heavy commands take turns through the machine queue (ADR 017): a `t3d queue: waiting …` line is not a failure, `T3D_QUEUE_BUSY` / `T3D_QUEUE_TIMEOUT` mean a busy machine, not wrong code; never write `sleep`/`pgrep` wait loops, use `t3d queue status`.
- **CI:** free GitHub runners; target < 5 min (As of 2026-11: 9 min before cost-balanced shards; measured 6.6 min and 76 runner-minutes after, floor = `human_head`'s four renders each recompiling, see `docs/maintenance.md`). `ci.yml`: `gate` (16 shards, `T3D_SHARD=k/16`: each runs `bun run verify` — its `bun test --shard` slice plus its recipe units balanced by `scripts/lib/recipe-costs.json`; shard 1 also lint, types, build, pack — then `bun run shots` on its render units, failing on any change under `recipes/*/out` and uploading contact sheets when it fails; docs-only changes skip recipes and shots), `site`, and the aggregate `verify`, the one required check. `pages.yml`: gallery to developerz-ai.github.io/ts23d. `release-tag.yml` (idempotent) + `release.yml` (runs the full gate; refuses a tag not on a green `main` commit): release PR merge → tag → npm via OIDC (no tokens). Every action SHA-pinned; Dependabot moves pins.
- **CI:** free GitHub runners; target < 5 min (As of 2026-11: measured 5.5 min and 67 runner-minutes on 18 shards, slowest job 299 s; since then the costs are that run's GitHub seconds (`bun run scripts/recipe-costs.ts --from-run <id>`), then measured 4.6 min with the slowest job at 269 s, see `docs/maintenance.md`). `ci.yml`: `gate` (18 shards, `T3D_SHARD=k/18`: each runs `bun run verify` — its `bun test --shard` slice plus its recipe units balanced by `scripts/lib/recipe-costs.json`; shard 1 also lint, types, build, pack — then `bun run shots` on its render units, failing on any change under `recipes/*/out` and uploading contact sheets when it fails; docs-only changes skip recipes and shots), `site`, and the aggregate `verify`, the one required check. `pages.yml`: gallery to developerz-ai.github.io/ts23d. `release-tag.yml` (idempotent) + `release.yml` (runs the full gate; refuses a tag not on a green `main` commit): release PR merge → tag → npm via OIDC (no tokens). Every action SHA-pinned; Dependabot moves pins.
- **AI-maintained, for years untouched:** `.dz/maintainer/maintainer.yml` sets the developerz.ai lanes (review + merge on green for every author, triage, daily `health` and `security-release`, weekly `release-due` which cuts releases, monthly `improve` and `cleanup` which also moves the Bun pin and runs a January yearly review). [`docs/maintenance.md`](docs/maintenance.md) maps what decays over a decade to the lane that catches it; keep it true when a lane changes. Only owner settings (rulesets, npm trusted publisher, 1.0.0) stay human.

## Using the library in another project
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ bun run verify --json # for agents: { ok, failed, results, output
| `test` | The `test` script in `package.json` (`src`, `scripts`, `examples`, `apps/site/src`; one 120 s per-test timeout) | `bun run test` |
| `recipes` | Every recipe compiles at 3 LODs, passes QA, builds byte-identically twice, has `hero.png` + `sheet.png` + `manifest.json`; also runs each recipe's own `*.test.ts` | `bun run recipes` |
| `build` | `dist/` JS + `.d.ts` | `bun run build` |
| `pack` | Packs the tarball, installs it in an empty project, imports every `exports` subpath under Bun and Node, runs `t3d build` | `bun run scripts/pack-smoke.ts` |
| `pack` | Packs the tarball, installs it in an empty project, imports every `exports` subpath under Bun and Node, runs `t3d build`, holds the tarball to the size budget in `scripts/pack-budget.ts` | `bun run scripts/pack-smoke.ts` |

11 steps, in this order (`STEPS` in `scripts/verify.ts`). An unknown `--only` name exits 2. In CI every shard runs its slice of `test` and `recipes`; the other steps run once, on shard 1.

Expand Down
8 changes: 5 additions & 3 deletions PUBLISHING.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ bun run release x.y.z ─► PR "chore: release x.y.z" ─► merge to main ─
| 1. Stamp | You / an agent | `bun run release x.y.z` sets `package.json` `version` (and `src/export/version.ts`), turns `## [Unreleased]` in `CHANGELOG.md` into `## [x.y.z] - <date>` (a fresh empty `[Unreleased]` stays on top), moves the link index at the bottom (`[Unreleased]` compares from `vx.y.z`, `[x.y.z]` compares from the previous tag) and regenerates `docs/changelog/` (a page per version plus the `README.md` index). `RELEASE_DATE=YYYY-MM-DD` overrides the date. Refused (`T3D_RELEASE`) when `x.y.z` is not above the current version, when `[Unreleased]` has no entries or no summary sentence, when `[x.y.z]` already exists, or when the `[Unreleased]` link does not compare from the latest version (`bun run changelog` rebuilds the index). Links and pages are generated, never hand-edited; the `conventions` gate step fails on drift |
| 2. PR | You / an agent | `git switch -c release/x.y.z && git add -A CHANGELOG.md docs/changelog && git commit -am 'chore: release x.y.z' && gh pr create --fill`. Title **exactly** `chore: release x.y.z` |
| 3. Merge | Reviewer | Merge to `main` with the title as the commit message (squash keeps it) |
| 4. `ci` | GitHub Actions | On the merge commit: `gate` (16 shards: `bun run verify`, then `bun run shots`, which fails if committed `recipes/*/out` are stale), `site` (`bun run site:build`). The `verify` job passes only when both succeeded; it is the one required check |
| 4. `ci` | GitHub Actions | On the merge commit: `gate` (18 shards: `bun run verify`, then `bun run shots`, which fails if committed `recipes/*/out` are stale), `site` (`bun run site:build`). The `verify` job passes only when both succeeded; it is the one required check |
| 5. `release-tag.yml` | GitHub Actions | Runs when `ci` succeeds on a push to `main` whose head commit message starts with `chore: release `. Reads the version from `package.json`, checks the stamp, then, each step skipped when already done: annotated tag `vX.Y.Z` on that commit (a tag on another commit fails) → GitHub Release with that CHANGELOG section → `gh workflow run release.yml --ref vX.Y.Z -f version=X.Y.Z` unless npm already serves `X.Y.Z`. Re-running it finishes a half-done release |
| 6. `release.yml` `check` | GitHub Actions | Refuses any ref but `refs/tags/vX.Y.Z`, a tag commit that is not on `origin/main`, and a commit with no successful `ci` push run (`gh run list --commit`); re-checks the stamp; runs the whole gate, `bun run verify`, unsharded (every step, recipes included) |
| 7. `release.yml` `publish` | GitHub Actions, environment `npm-publish` | npm ≥ 11.5.1, `npm publish --access public --provenance` (its `prepack` script runs `bun run build`). Only this job holds `id-token: write`; it restores no cache |
Expand All @@ -38,7 +38,9 @@ The dispatch in step 5 is needed because a tag pushed with `GITHUB_TOKEN` trigge

## What ships

`package.json` `files` and `exports` decide it; `bun run scripts/pack-smoke.ts` proves it. It packs the tarball (`prepack` builds `dist/`), installs it into an empty project and, as a consumer: builds a two-box recipe with `bunx -p @developerz.ai/ts23d t3d build` to QA PASS, imports every `exports` subpath under Bun and Node, type-checks them with `tsc` (`skipLibCheck: false`, no DOM lib), and fails if the tarball carries `*.test.ts`, `recipes/**/*.png` or `dist/**/*.map`, lacks `CLAUDE.md`, or misses an `exports` target. `exports` is an explicit list: the root, one subpath per module in `scripts/lib/tiers.ts` except `cli`, and `./package.json`. The library imports under Node ≥ 22 (the `default` condition, `dist/`); the `t3d` CLI and the examples need Bun. `AGENTS.md` is a symlink to `CLAUDE.md` and npm skips symlinks, so the package ships `CLAUDE.md` only.
`package.json` `files` and `exports` decide it; `bun run scripts/pack-smoke.ts` proves it. It packs the tarball (`prepack` builds `dist/`), installs it into an empty project and, as a consumer: builds a two-box recipe with `bunx -p @developerz.ai/ts23d t3d build` to QA PASS, imports every `exports` subpath under Bun and Node, type-checks them with `tsc` (`skipLibCheck: false`, no DOM lib), and fails if the tarball carries `*.test.ts`, `recipes/**/*.png`, `dist/**/*.map` or anything under `recipes/*/neural/`, lacks `CLAUDE.md`, misses an `exports` target, or breaks the size budget in `scripts/pack-budget.ts` (as of 2026-11: 5.3 MB packed, 16 MB unpacked, 1 MB per file; measured 4.2 MB / 12.7 MB, about 2,300 files). The failure names the largest files and the fix: exclude what a consumer does not need in `files`, or raise `PACK_BUDGET` with a reason in the diff.

The model-built recipes' outputs (`recipes/*/neural/`: concept PNGs, image-to-3D GLBs, `record.json`; about 40 MB) stay in git, not in the tarball. From `node_modules`, `ranger` and `human_head` build their CPU tier (QA PASS) with a `T3D_NEURAL_MISSING` notice; `bear_hybrid`, `wolf_hybrid` and `dragon_hybrid` have no CPU build that passes QA, so `t3d build` stops with one `T3D_NEURAL_MISSING` error. In both cases the `fix:` says the package ships no model outputs: clone the repo to build the model tier, or copy the recipe folder and run `t3d neural run` on it. `exports` is an explicit list: the root, one subpath per module in `scripts/lib/tiers.ts` except `cli`, and `./package.json`. The library imports under Node ≥ 22 (the `default` condition, `dist/`); the `t3d` CLI and the examples need Bun. `AGENTS.md` is a symlink to `CLAUDE.md` and npm skips symlinks, so the package ships `CLAUDE.md` only.

## Versioning

Expand Down Expand Up @@ -68,7 +70,7 @@ Repository → Settings → Environments → **New environment** `npm-publish`.

### 2b. Repository rules

- Ruleset on `main`: require a pull request and the `verify` status check (the `ci` aggregate job; one check, not the 25 shard jobs).
- Ruleset on `main`: require a pull request and the `verify` status check (the `ci` aggregate job; one check, not one per job: 18 `gate` shards and `site`).
- Tag ruleset on `v*`: restrict creation to maintainers and the release workflow, so nobody else can mint a release tag.

### 3. Trusted publisher on npmjs.com
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,7 @@ Runnable copy: [`examples/build-with-bun.ts`](examples/build-with-bun.ts) — ex

## Use it with any agent

**The docs ship inside the package, versioned with the code, readable offline.** After `bun add`, everything an agent needs is at `node_modules/@developerz.ai/ts23d/`: `CLAUDE.md` (the agent brain; the repo's `AGENTS.md` is a symlink to it and is not in the tarball), `llms.txt`, `docs/`, `recipes/` (worked examples), `CHANGELOG.md` and `.claude/{skills,agents,commands}`.
**The docs ship inside the package, versioned with the code, readable offline.** After `bun add`, everything an agent needs is at `node_modules/@developerz.ai/ts23d/`: `CLAUDE.md` (the agent brain; the repo's `AGENTS.md` is a symlink to it and is not in the tarball), `llms.txt`, `docs/`, `recipes/` (worked examples; the model recipes' `neural/` outputs stay in git: from the package `ranger` and `human_head` build their CPU tier, and `bear_hybrid`, `wolf_hybrid` and `dragon_hybrid`, which have no CPU build, stop with `T3D_NEURAL_MISSING` and a `fix:` that says to clone the repo), `CHANGELOG.md` and `.claude/{skills,agents,commands}`.

Point your agent at them. Add to your project's `CLAUDE.md` or `AGENTS.md`:

Expand Down
Loading