✨ feat(build): decisions D1-D15, plus cacheable agentic and long-tail rules

[roninjin10]

Fifteen decisions (D1–D15) from a side-by-side comparison of this repository wired with Nx (#226), Turborepo (#225), and Bazel (#227), plus the first two waves of the follow-on work that makes agentic and long-tail tasks expressible as targets.

27 lanes, 47 commits, 142 files, +20,325 / −963.

The number that motivated it

smthrs ci "//..." planned 278 targets, of which 232 (83%) could not replay. DocsParity was the only rule that cached across the workspace; TsBuild, Typecheck, and Vitest declared no cache key at all and fell through to a false default.

Flipping that default alone would have been worse than leaving it. The cache stored a JSON success envelope — {key, target, label, exitOk, output, storedAt} — and captureOutputs digested declared outputs rather than storing them. A hit on a clean tree would have marked TsBuild successful with no dist/ on disk. So the content-addressed store landed first, and the flip came after.

What changed

Configuration split. WORKSPACE.ts declares what exists; BUILD.ts declares targets — the MODULE.bazel / BUILD.bazel shape. The toolchain registers once, so no rule threads packageManager as an attr and no package BUILD.ts imports ../../BUILD.ts.

Execution is confined. Actions run against a projected copy of their declared inputs, with one shared environment allowlist. sandbox: false and --dangerously-no-sandbox are the escape hatches, and neither disables caching — an un-sandboxed target's input list becomes a promise rather than a guarantee, which is how Bazel treats no-sandbox too.

Caching is on by default, opt out by exception. The exceptions keep their stated reasons; the wasm reproducibility gate stays uncached because the rebuild is the check.

Visibility is enforced at plan time, at package and folder level, with tiers derived from the existing smthrs.group manifest field rather than restated.

Outputs are content-addressed. A cache hit restores declared outputs from the store, confined to the workspace, and a missing blob is a miss rather than a hit.

npm packages are targets derived from pnpm-lock.yaml, so an action's inputs name the packages it uses instead of an ambient node_modules.

Consumers key on producer output bytes (Input.Produced), not on the producer's target key. Without this an uncached producer emitting different bytes leaves its consumer replaying a verdict about an artifact that no longer exists.

New rules for the surface both repos actually have: BunTest, BunTestCoverage, NodeTest, ScriptCheck, GeneratedArtifact. ScriptCheck is structurally load-bearing — ToolBuild is kinds: ["build"] and requires declared outputs to exist, so before this there was no way to declare a lint- or test-kind arbitrary command at all.

Bugs found by running the code, not reading it

A mapping pass verified every premise before implementation and found 16 wrong and 15 unbuildable as written (docs/architecture/build-system/corrections.md). Three mattered:

• Nested BUILD.ts silently pruned its parent's inputs. Adding pkg/src/internal/BUILD.ts removed pkg/src/internal/b.ts from //pkg:lib's declared inputs while the parent's tsc -b still compiled that subtree. Harmless while nothing cached; a stale-green generator the moment D5 flipped.
• The baseline was already red. GeneratedRootFiles.test.ts hand-copies root BUILD.ts attrs and had drifted.
• //:ci never ran in CI. GithubCiGen kinds were [build, lint] while ci.yml ran the docs verb and ci //packages/....

Deliberately not done

• Changesets — there is no .changeset/ and no @changesets/* dependency to build on. Internal range retargeting on bump landed, which is the part that carries the value; adopting the package did not.
• GithubCiGen write mode — the renderer models no needs, permissions, matrix, or step-level if, and would drop 60+ explanatory comments from ci.yml. Contract mode stays and now covers the full gate surface instead.

Both are recorded in docs/architecture/build-system/corrections.md rather than left as silent omissions.

Measured

smthrs build "//packages/..." --jobs 4, 90 targets:

	wall	detail
cold, cache cleared, every dist/ removed	58.25s	391s user across 4 jobs
warm, nothing changed	2.19s	90/90 cache hits, 0 re-runs

Per-target digests are byte-identical between the two runs, so the key is stable across processes — the property that makes the cache shareable rather than merely local.

Verification

• pnpm run check across every workspace: clean.
• Design record in docs/architecture/build-system/ — the decisions, the corrections, and eight open design questions (six ruled on, two left to the maintainer).

🤖 Generated with Claude Code