Give the snapshot bridge and fold helper one Apple native-build owner
Deletion-first acceptance
This is part of #2803's simplify-and-shrink initiative. Before production simplification, name the production mechanism, duplicated decision, state, fallback, forwarding layer, or public/internal interface this change removes. Compare deletion and inlining against extraction. Moving the same state into another file is not a deletion case.
Every PR reports baseline/final SHAs; added, deleted and net production lines; test/fixture/documentation changes separately; and the exact mechanisms removed. Use a rename-aware diff (git diff --numstat -M BASE...HEAD) and account for all affected production paths, including destination packages. Moving tests out of production files, generated output, formatting churn, and moving code elsewhere are not production-code deletion. Preserve readable code; no compressed formatting to hit a number.
Default for simplification work: net production reduction. A required behavior-preserving size split may be line-neutral. Growth needs an explicit, quantified explanation of the correctness or type guarantee it buys, why deletion/inlining cannot achieve it, and what old mechanism is removed; it is not automatically acceptable because ownership looks cleaner. If the only benefit is relocating fields or adding a wrapper, defer the change. Required regression tests and a minimal correctness fix are allowed to grow without inventing unrelated deletion to offset them.
Priority and scope gate
Early cleanup candidate, alongside #2972/#2974 where edit ownership is disjoint. The native cache is already shared: moving it is not itself a reduction. Inventory and delete the fold helper's broad snapshot-host construction, snapshot-specific plumbing and superseded adaptation. Preserve a single cache implementation, cache keys and error semantics. If a narrow build port adds more machinery than it removes, propose the smaller seam or report the quantified tradeoff before calling this simplification complete.
Problem and evidence
The snapshot bridge and fold helper correctly share compilation and cache behavior, but the shared implementation still belongs to snapshot-source. The fold helper consequently imports snapshot deadlines, errors, host construction, toolchain identity, cache mechanics, and host types. Its host factory constructs the full snapshot host and overrides run, although compilation does not need bridge sockets or target-process inspection.
Verified against origin/main at 5712a3552e209c9c853bc1f42cb3e007f1213139: packages/platform-apple/src/foldable/fold-helper-cache.ts:6–18,85–92, snapshot-source/native-build-cache.ts:20–31, and snapshot-source/types.ts:81–125. The earlier consolidation in #2858 should be retained; this change finishes its ownership boundary.
Intended design
Move the existing shared implementation into a domain-named module group within packages/platform-apple/src, such as native-build/. Keep the snapshot-specific recipe, bridge identity, preparation lifecycle, and acquisition errors under snapshot-source; keep fold compilation arguments and public fold failure mapping under foldable.
The small product interface remains recognizable:
ensureNativeBuildCacheEntry({ host, deadline, cacheRoot, binaryFilename,
lockDescription, keyInputs, build }): Promise<{ path: string; cacheKey: string }>NativeBuildHost contains only the actual build/cache requirements: file access, command execution, lock acquisition, process identity, and required path/toolchain reads. Inventory accesses before defining it. It must not expose bridge start/connect or target-process inspection. Reuse existing host-kit implementations. Domain-neutral build failures carry typed cancellation/timeout/build facts; each consumer maps them to its existing public errors and diagnostic fields. No shared build module imports SnapshotSourceError or emits bridge-specific error fields.
Implementation and acceptance
- Characterize current cache identity and both consumer error mappings. Run
pnpm depgraph affected packages/platform-apple/src/snapshot-source/native-build-cache.ts and scope moves to these two consumers.
- Move shared cache, source fingerprinting, and the reusable toolchain-identity portion with their existing tests. Separate bridge-specific identity from shared toolchain identity without introducing a compatibility re-export.
- Replace the fold helper's whole-snapshot-host construction with the narrow build host. Retain its Apple tool-provider execution scope; retain the bridge's current execution behavior.
- Move path-keyed Fallow entries only for renamed files and stage new modules before checking layering.
Before/after measures: one cache implementation remains one; foldable imports from snapshot-source fall to zero; shared build imports of snapshot protocol/error types fall to zero; the build port loses socket/process-target capabilities. For identical source and toolchain inputs, cache identity, hit/miss behavior, compilation argv, binary verification, lock ownership, cancellation, atomic publication, and public failure details remain unchanged. Record the exact modules moved and any unavoidable identity difference; a gratuitous cache invalidation is not success.
Validation
Run the moved equivalents of native-build-cache.test.ts, cache-identity.test.ts, cache.test.ts, preparation.test.ts, and foldable/fold-helper-cache.test.ts using pnpm exec vitest run --project unit-core <paths>. Preserve positive and negative cases for corruption, toolchain changes, timeout, cancellation, and partial publication. Run the existing Darwin native-build/argv conformance cases selected by the affected gates. Finish with repository-wide pnpm format and pnpm check:affected --run on the implementation head; retain any CI-only obligations it reports.
Scope and readiness
Ready for implementation after a fresh main rebase. No dependency on runner-state extraction or presentation redesign. This belongs under architecture umbrella #2803. Do not generalize into a plugin framework, move it into host-kit, add another cache, change bridge recovery, or alter simulator allocation/scoping. Expected effort: M; risk: low to medium, concentrated in cache identity and error preservation.
For a fresh worktree run pnpm install --frozen-lockfile && pnpm build first. Read docs/agents/testing.md; do not weaken an eager-closure or layering gate to accommodate new module paths.
Give the snapshot bridge and fold helper one Apple native-build owner
Deletion-first acceptance
This is part of #2803's simplify-and-shrink initiative. Before production simplification, name the production mechanism, duplicated decision, state, fallback, forwarding layer, or public/internal interface this change removes. Compare deletion and inlining against extraction. Moving the same state into another file is not a deletion case.
Every PR reports baseline/final SHAs; added, deleted and net production lines; test/fixture/documentation changes separately; and the exact mechanisms removed. Use a rename-aware diff (
git diff --numstat -M BASE...HEAD) and account for all affected production paths, including destination packages. Moving tests out of production files, generated output, formatting churn, and moving code elsewhere are not production-code deletion. Preserve readable code; no compressed formatting to hit a number.Default for simplification work: net production reduction. A required behavior-preserving size split may be line-neutral. Growth needs an explicit, quantified explanation of the correctness or type guarantee it buys, why deletion/inlining cannot achieve it, and what old mechanism is removed; it is not automatically acceptable because ownership looks cleaner. If the only benefit is relocating fields or adding a wrapper, defer the change. Required regression tests and a minimal correctness fix are allowed to grow without inventing unrelated deletion to offset them.
Priority and scope gate
Early cleanup candidate, alongside #2972/#2974 where edit ownership is disjoint. The native cache is already shared: moving it is not itself a reduction. Inventory and delete the fold helper's broad snapshot-host construction, snapshot-specific plumbing and superseded adaptation. Preserve a single cache implementation, cache keys and error semantics. If a narrow build port adds more machinery than it removes, propose the smaller seam or report the quantified tradeoff before calling this simplification complete.
Problem and evidence
The snapshot bridge and fold helper correctly share compilation and cache behavior, but the shared implementation still belongs to
snapshot-source. The fold helper consequently imports snapshot deadlines, errors, host construction, toolchain identity, cache mechanics, and host types. Its host factory constructs the full snapshot host and overridesrun, although compilation does not need bridge sockets or target-process inspection.Verified against
origin/mainat5712a3552e209c9c853bc1f42cb3e007f1213139:packages/platform-apple/src/foldable/fold-helper-cache.ts:6–18,85–92,snapshot-source/native-build-cache.ts:20–31, andsnapshot-source/types.ts:81–125. The earlier consolidation in #2858 should be retained; this change finishes its ownership boundary.Intended design
Move the existing shared implementation into a domain-named module group within
packages/platform-apple/src, such asnative-build/. Keep the snapshot-specific recipe, bridge identity, preparation lifecycle, and acquisition errors undersnapshot-source; keep fold compilation arguments and public fold failure mapping underfoldable.The small product interface remains recognizable:
NativeBuildHostcontains only the actual build/cache requirements: file access, command execution, lock acquisition, process identity, and required path/toolchain reads. Inventory accesses before defining it. It must not expose bridge start/connect or target-process inspection. Reuse existing host-kit implementations. Domain-neutral build failures carry typed cancellation/timeout/build facts; each consumer maps them to its existing public errors and diagnostic fields. No shared build module importsSnapshotSourceErroror emits bridge-specific error fields.Implementation and acceptance
pnpm depgraph affected packages/platform-apple/src/snapshot-source/native-build-cache.tsand scope moves to these two consumers.Before/after measures: one cache implementation remains one; foldable imports from
snapshot-sourcefall to zero; shared build imports of snapshot protocol/error types fall to zero; the build port loses socket/process-target capabilities. For identical source and toolchain inputs, cache identity, hit/miss behavior, compilation argv, binary verification, lock ownership, cancellation, atomic publication, and public failure details remain unchanged. Record the exact modules moved and any unavoidable identity difference; a gratuitous cache invalidation is not success.Validation
Run the moved equivalents of
native-build-cache.test.ts,cache-identity.test.ts,cache.test.ts,preparation.test.ts, andfoldable/fold-helper-cache.test.tsusingpnpm exec vitest run --project unit-core <paths>. Preserve positive and negative cases for corruption, toolchain changes, timeout, cancellation, and partial publication. Run the existing Darwin native-build/argv conformance cases selected by the affected gates. Finish with repository-widepnpm formatandpnpm check:affected --runon the implementation head; retain any CI-only obligations it reports.Scope and readiness
Ready for implementation after a fresh main rebase. No dependency on runner-state extraction or presentation redesign. This belongs under architecture umbrella #2803. Do not generalize into a plugin framework, move it into host-kit, add another cache, change bridge recovery, or alter simulator allocation/scoping. Expected effort: M; risk: low to medium, concentrated in cache identity and error preservation.
For a fresh worktree run
pnpm install --frozen-lockfile && pnpm buildfirst. Readdocs/agents/testing.md; do not weaken an eager-closure or layering gate to accommodate new module paths.