Size the Scanner and OfflineKit storage budgets

These two optional budgets bound a service’s measured logical bytes. Leave the variables empty until you have allocated capacity to that state. Setting a positive integer enables the existing pre-write capacity check; it does not reserve disk space or make concurrent writes an atomic global quota.

Use decimal integers in bytes, without a unit suffix or thousands separators. One GiB is 1,073,741,824 bytes. Empty means unbudgeted; zero, a negative number, or invalid text is not a way to disable a declared budget.

Scanner: allocate a share of the object store

1. Obtain the object store’s usable logical capacity after its replication or erasure-coding overhead. Raw device capacity is not this number.
2. Subtract the allocation for every other bucket sharing the backing volumes, plus the operator’s allowance for metadata, versions, maintenance and free space.
3. Allocate the remaining logical capacity to scanner-artifacts. Compare the measured bucket size plus the largest expected incoming write with that allocation. If it does not fit, add capacity or follow the custody-aware cleanup procedure before enabling the budget.

For example, an estate can allocate 200 GiB of usable logical capacity to this bucket and reserve 60 GiB of that allocation for its unmeasured overhead and growth margin. Its budget would then be 140 GiB, or 150323855360 bytes. This example is valid only for that allocation; it is not a default for a shared object store. Object versioning and backend overhead can consume physical space beyond the logical sizes returned by ListObjectsV2.

See the Scanner capacity procedure for driver capability, measurement failures and recovery.

OfflineKit: retain working space outside the CAS

Read the capacity of the filesystem actually mounted at OfflineKit:Import:StorageRoot. Subtract existing unrelated use, an operating free-space margin, and capacity for the largest permitted concurrent imports in quarantine/ and multipart-buffer/. Those working directories share the filesystem but are excluded from the CAS measurement. Account for every concurrent upload, not just one carrier’s final size.

For example, a dedicated 100 GiB filesystem with 20 GiB allocated to quarantine, 10 GiB to multipart buffering and 10 GiB to filesystem overhead/free-space margin leaves 60 GiB for CAS files: OFFLINEKIT_IMPORT_CAS_BUDGET_BYTES=64424509440. Verify those workspace allocations against the estate’s upload limits and concurrency. File lengths are logical bytes, so filesystem allocation overhead still needs its reserve.

See the OfflineKit capacity procedure for the promotion guard, quarantine retention after refusal and recovery.

Apply and verify

Put the chosen values in the estate’s private environment file. Keep the Compose ${VAR:-} defaults empty. Recreate the affected service roles through the normal deployment procedure so that the processes receive the changed environment. Use an ops.health token to read the relevant /doctor/{service}/checks endpoint, or Platform’s /api/v1/platform/doctor/aggregate surface.

Verify the state ID, measured bytes and configured budget together. A measurement failure must not be read as zero usage. A budget below current use pauses new guarded writes; it does not delete retained content. Check capacity after changes to the volume allocation, replication, import concurrency or other buckets’ allocations.

Verified against source 9583485f184a3311e1bf5b73b807c14f203ef9c6: ScannerArtifactCapacityContract, CapacityGuardedArtifactObjectStore, ScannerArtifactOwnedStateMeasurer, OfflineKitPartsCapacityContract, OfflineKitPartsOwnedStateMeasurer and OfflineKitImportCasWritePause. Re-verify the deployment defaults with:

pwsh tools/scripts/test-targeted-xunit.ps1 -Project src/__Tests/architecture/StellaOps.Architecture.Contracts.Tests/StellaOps.Architecture.Contracts.Tests.csproj -Class '*ScannerConsolidationConformanceTests' -BuildProjectReferences

The linked owner procedures describe the behavior checks for each guard.