[PR #220] [MERGED] fix(snapshot): increase overlaybd compaction threshold with dynamic calculated value

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/220 **Author:** [@huajq](https://github.com/huajq) **Created:** 8/26/2026 **Status:** ✅ Merged **Merged:** 8/27/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `fix/runtime-owned-layer-compaction` --- ### 📝 Commits (1) - [`d0a84d8`](https://github.com/kvcache-ai/AgentENV/commit/d0a84d879d6b70a9a5bf27c8708fe7f77b4c7489) fix(snapshot): increase overlaybd compaction threshold with dynamic calculated value ### 📊 Changes **1 file changed** (+140 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `src/sandbox/firecracker/overlaybd_snapshot.rs` (+140 -7) </details> ### 📄 Description ## What Change the overlaybd snapshot layer compaction trigger in `rewrite_lowers_with_runtime_roots` from "total lowers > 32" to a dynamic budget on the runtime-owned suffix only: `max(32 - stable_prefix/4, 1)`. Adds regression tests for both sides of the trigger. ## Why The old trigger counted the stable base prefix. On a deep base (e.g. a 32-layer rootfs), every pause compacted the entire runtime-owned suffix into a new cumulative file: the layer count pinned at 33 while each compaction rewrote (and on publish re-uploaded) all deltas since the base. Two snapshots branching from the same parent each re-upload their shared ancestry. ## Related issue N/A ## Scope and non-goals Included: trigger semantics + unit tests. Excluded (known follow-ups, unchanged by this PR): distributed snapshot chains resumed from the repository still grow one layer per generation (a single-layer suffix is never compacted); no managed-layer GC; no streaming compaction of remote (OSS/registry) lowers. ## Design and behavior changes Compaction now fires only when the runtime-owned suffix plus the appended layer exceeds a budget that shrinks as the stable prefix grows (32 with an empty prefix, 24 with a 32-layer prefix, clamped to 1). Stable base lowers never trigger compaction on their own; total stack depth stays well below overlaybd's 255-layer hard limit. What gets compacted is unchanged: the runtime-owned suffix only, never remote lowers. ## Compatibility and operations - Public API or generated protocol: N/A - Configuration or defaults: N/A (threshold remains a private constant) - Snapshot manifest, artifact layout, or storage format: N/A — only *when* compaction fires changes - Upgrade and rollback: N/A - Host requirements, permissions, ports, or dependencies: N/A ## Validation - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [ ] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text cargo fmt --all -- --check # clean cargo clippy -p agentenv --all-targets -- -D warnings # clean cargo test -p agentenv --lib overlaybd_snapshot # 11 passed, incl. 2 new regression tests cargo test -p agentenv --lib # 774 passed; 1 pre-existing env failure ``` Skipped checks and reasons: integration tests not run (Linux sandbox run; the trigger logic is covered by the added unit tests). The one full-suite failure is `privileges::tests::scoped_spawn_clears_child_capabilities_without_mutating_caller`, a pre-existing capability assertion that fails when tests run as root; it is unrelated to this change. ## Risks and reviewer notes Single file: `src/sandbox/firecracker/overlaybd_snapshot.rs`. Main risk is behavioral: deep-base snapshots now reach higher layer counts (up to base + budget) before compacting — bounded well under the 255 hard limit by the shrinking budget. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi commented

2026-10-29 14:21:35 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/220
Author: @huajq
Created: 8/26/2026
Status: ✅ Merged
Merged: 8/27/2026
Merged by: @yingdi-shan

Base: main ← Head: fix/runtime-owned-layer-compaction

📝 Commits (1)

d0a84d8 fix(snapshot): increase overlaybd compaction threshold with dynamic calculated value

📊 Changes

1 file changed (+140 additions, -7 deletions)

View changed files

📝 src/sandbox/firecracker/overlaybd_snapshot.rs (+140 -7)

📄 Description

What

Change the overlaybd snapshot layer compaction trigger in rewrite_lowers_with_runtime_roots from "total lowers > 32" to a dynamic budget on the runtime-owned suffix only: max(32 - stable_prefix/4, 1). Adds regression tests for both sides of the trigger.

Why

The old trigger counted the stable base prefix. On a deep base (e.g. a 32-layer rootfs), every pause compacted the entire runtime-owned suffix into a new cumulative file: the layer count pinned at 33 while each compaction rewrote (and on publish re-uploaded) all deltas since the base. Two snapshots branching from the same parent each re-upload their shared ancestry.

N/A

Scope and non-goals

Included: trigger semantics + unit tests. Excluded (known follow-ups, unchanged by this PR): distributed snapshot chains resumed from the repository still grow one layer per generation (a single-layer suffix is never compacted); no managed-layer GC; no streaming compaction of remote (OSS/registry) lowers.

Design and behavior changes

Compaction now fires only when the runtime-owned suffix plus the appended layer exceeds a budget that shrinks as the stable prefix grows (32 with an empty prefix, 24 with a 32-layer prefix, clamped to 1). Stable base lowers never trigger compaction on their own; total stack depth stays well below overlaybd's 255-layer hard limit. What gets compacted is unchanged: the runtime-owned suffix only, never remote lowers.

Compatibility and operations

Public API or generated protocol: N/A
Configuration or defaults: N/A (threshold remains a private constant)
Snapshot manifest, artifact layout, or storage format: N/A — only when compaction fires changes
Upgrade and rollback: N/A
Host requirements, permissions, ports, or dependencies: N/A

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

cargo fmt --all -- --check                      # clean
cargo clippy -p agentenv --all-targets -- -D warnings   # clean
cargo test -p agentenv --lib overlaybd_snapshot # 11 passed, incl. 2 new regression tests
cargo test -p agentenv --lib                    # 774 passed; 1 pre-existing env failure

Skipped checks and reasons: integration tests not run (Linux sandbox run; the trigger logic is covered by the added unit tests). The one full-suite failure is privileges::tests::scoped_spawn_clears_child_capabilities_without_mutating_caller, a pre-existing capability assertion that fails when tests run as root; it is unrelated to this change.

Risks and reviewer notes

Single file: src/sandbox/firecracker/overlaybd_snapshot.rs. Main risk is behavioral: deep-base snapshots now reach higher layer counts (up to base + budget) before compacting — bounded well under the 255 hard limit by the shrinking budget.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

bsakaguchi

closed this issue
added the
pull-request
label

Rows
Columns

[PR #220] [MERGED] fix(snapshot): increase overlaybd compaction threshold with dynamic calculated value #262