Use snapshots as fanout parents

[sjmiller609]

Summary

• record snapshot ids on instances forked from snapshots
• expose ref_count on snapshot API responses
• refuse explicit snapshot deletion while direct snapshot forks still exist
• hardlink raw snapshot memory files into snapshot forks and assert the shared inode path in tests
• skip referenced snapshots during scheduled snapshot cleanup

Tests

• go test ./lib/forkvm/
• go test ./lib/instances/ -run 'Test(StoppedSnapshotLifecycleAndForkAfterSourceDeletion|DeleteSnapshotFailsWhenForkMetadataUnreadable|ForkSnapshotHardlinksRawMemoryFile|ForkSnapshotFromCompressedSourceCopiesRawMemory|RunSnapshotSchedules|SnapshotSchedule)'\n- go test ./lib/snapshot ./cmd/api/api -run 'TestNonexistent'\n\nNote: a full go test ./lib/instances/ run was stopped after it entered slower runtime-adjacent coverage; the targeted snapshot/fork/schedule coverage above passed.

---

Note

Medium Risk
Changes snapshot lifecycle semantics and the public API schema (new required ref_count and 409 on delete), which may affect clients and cleanup behavior. Forking now hardlinks snapshot memory files, so filesystem/linking edge cases could impact fork reliability.

Overview
Snapshots now act as fanout parents. Instances created via ForkSnapshot persist the source snapshot ID in metadata (ForkOfSnapshot), and snapshot GET/LIST responses expose a new required ref_count field.

Deletion semantics tighten. Explicit snapshot deletion now fails with 409 Conflict when any direct forks still exist (and scheduled cleanup silently skips those snapshots), and the OpenAPI/client code is updated accordingly.

Fork performance/space change. Snapshot forks avoid copying the raw memory file by skipping it during directory copy and then hardlinking it into the forked instance; tests add coverage for ref counting, unreadable metadata, and inode sharing.

^{Reviewed by Cursor Bugbot for commit 05e4a11. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

✱ Stainless preview builds for hypeman

This PR will update the hypeman SDKs with the following commit message.

feat: Use snapshots as fanout parents

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ hypeman-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/bb4646f6fb4110bb5e59a0806051a2b767e4eba9/dist.tar.gz

✅ hypeman-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@bef4cf9f4e62ccc985c10bbe5a6ef2e4d39de4b3

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-18 15:22:05 UTC

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR modifies snapshot and fork lifecycle logic in packages/api/lib/ but does not appear to change API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal) that the filter specifically targets.

To monitor this PR anyway, reply with @firetiger monitor this.