Add .acb storage budget policy and budget command

Author: omoshola-o

README.md

@@ -293,6 +293,7 @@ If `.acb/.amem/.avis` files are on another machine, sync them to the server firs
 | Autonomic profile | Conservative local-first posture | `ACB_AUTONOMIC_PROFILE=desktop|cloud|aggressive` |
 | Rolling backup | Compile writes checkpointed backups for existing outputs | `ACB_AUTO_BACKUP`, `ACB_AUTO_BACKUP_RETENTION`, `ACB_AUTO_BACKUP_DIR` |
 | Storage migration | Policy-gated with checkpointed auto-safe path | `ACB_STORAGE_MIGRATION_POLICY=auto-safe|strict|off` |
+| Storage budget policy | 20-year projection + backup rollup when budget pressure appears | `ACB_STORAGE_BUDGET_MODE=auto-rollup|warn|off`, `ACB_STORAGE_BUDGET_BYTES`, `ACB_STORAGE_BUDGET_HORIZON_YEARS`, `ACB_STORAGE_BUDGET_TARGET_FRACTION` |
 | Collective cache maintenance | Periodic expiry cleanup of collective cache entries | `ACB_COLLECTIVE_CACHE_MAINTENANCE_SECS` |
 | Maintenance throttling | SLA-aware under sustained registry load | `ACB_SLA_MAX_REGISTRY_OPS_PER_MIN` |
 | Health ledger | Periodic operational snapshots (default: `~/.agentra/health-ledger`) | `ACB_HEALTH_LEDGER_DIR`, `AGENTRA_HEALTH_LEDGER_DIR`, `ACB_HEALTH_LEDGER_EMIT_SECS` |

docs/public/command-surface.md

@@ -17,6 +17,7 @@ acb get
 acb completions
 acb health
 acb gate
+acb budget
 ```
 
 ## `acb compile`
@@ -69,6 +70,25 @@ acb gate <file.acb> --unit-id 42 --max-risk 0.55 --depth 4 --require-tests
 
 Fails with non-zero exit if risk/test criteria are not met (CI-friendly).
 
+## `acb budget`
+
+```bash
+acb budget <file.acb>
+acb budget <file.acb> --horizon-years 20 --max-bytes 2147483648
+acb budget <file.acb> --format json
+```
+
+Estimates long-horizon growth and reports whether the graph is on track for a fixed storage budget.
+
+Runtime policy env:
+
+```bash
+export ACB_STORAGE_BUDGET_MODE=auto-rollup
+export ACB_STORAGE_BUDGET_BYTES=2147483648
+export ACB_STORAGE_BUDGET_HORIZON_YEARS=20
+export ACB_STORAGE_BUDGET_TARGET_FRACTION=0.85
+```
+
 ## `acb-mcp`
 
 ```bash

docs/public/implementation-2026-02-22.md

@@ -17,6 +17,14 @@ This page records the codebase-system upgrades implemented in this cycle.
      - `test-gap`
      - `hotspots`
      - `dead-code`
+5. Long-horizon storage budget policy:
+   - Added `acb budget` command for projection and budget guidance.
+   - Added compile-time storage policy:
+     - `ACB_STORAGE_BUDGET_MODE=auto-rollup|warn|off`
+     - `ACB_STORAGE_BUDGET_BYTES`
+     - `ACB_STORAGE_BUDGET_HORIZON_YEARS`
+     - `ACB_STORAGE_BUDGET_TARGET_FRACTION`
+   - `auto-rollup` mode trims oldest `.acb` backup lineage when budget pressure is detected.
 
 ## Why this matters
 
@@ -33,6 +41,7 @@ acb query repo.acb hotspots
 acb query repo.acb dead-code
 acb health repo.acb
 acb gate repo.acb --unit-id 42 --max-risk 0.60 --require-tests
+acb budget repo.acb --horizon-years 20 --max-bytes 2147483648
 ```
 
 ## Files changed
@@ -42,4 +51,3 @@ acb gate repo.acb --unit-id 42 --max-risk 0.60 --require-tests
 - `docs/public/command-surface.md`
 - `docs/public/quickstart.md`
 - `README.md`
-

docs/public/quickstart.md

@@ -31,6 +31,7 @@ acb query project.acb dead-code
 ```bash
 acb health project.acb
 acb gate project.acb --unit-id 1 --max-risk 0.60 --require-tests
+acb budget project.acb --horizon-years 20 --max-bytes 2147483648
 ```
 
 ## 5. Start MCP server

docs/public/runtime-install-sync.md

@@ -43,3 +43,20 @@ export AGENTIC_TOKEN="$(openssl rand -hex 32)"
 ```
 
 Server deployments must sync `.acb/.amem/.avis` artifacts to server storage before runtime.
+
+## Long-horizon storage budget policy
+
+To target ~1-2 GB over long horizons (for example 20 years), configure:
+
+```bash
+export ACB_STORAGE_BUDGET_MODE=auto-rollup
+export ACB_STORAGE_BUDGET_BYTES=2147483648
+export ACB_STORAGE_BUDGET_HORIZON_YEARS=20
+export ACB_STORAGE_BUDGET_TARGET_FRACTION=0.85
+```
+
+Modes:
+
+- `auto-rollup`: trims oldest `.acb` backup lineage when budget pressure is detected.
+- `warn`: emit warnings only.
+- `off`: disable policy.