Economics and cost model

AWC is an agent workspace cache. Its bet is that the physical bill can track new bytes and cold reads, not the workspace count. This page explains why the design is shaped that way, what the three flattening mechanisms buy you, and where the measured evidence stops.

For the hand-held version, read see the economics. That tutorial fans out many forks and shows the remote-fetch count collapsing. This page is the why behind it.

Why fork count is free

A conventional fleet gives each agent its own clone, volume, or sandbox snapshot. The bill then scales with the agent count, because each workspace is priced as a full physical copy. AWC rejects that model. The design holds that charging each branch as a full volume contradicts the economic thesis. Fork operations should be free or nearly free.

Fork can be free because a fork creates only metadata. A workspace begins as a reference to an existing immutable snapshot and an empty private delta. The base bytes already live in the tenant content store, keyed by digest. A new fork points at them. It does not copy them. Fork work stays independent of snapshot size. Any work proportional to file count is import, mount, or checkpoint work, not fork work.

The bill tracks new content and cold reads, not how many workspaces exist. Branch count is reporting only, not a primary charge. That is the central design choice. The rest of this page is about what makes it true, and what it costs.

The three mechanisms that flatten the bill

Three mechanisms turn "many workspaces, one base" into "about one remote fetch, not N". Each has an honest limit.

Tenant-scoped content addressing. Each distinct object lives once per tenant. Identical bytes share one object, whether they appear in one fork or in a hundred. All forks of one base under one tenant resolve a shared file to the same object. The limit is the tenant boundary. Cross-tenant deduplication is prohibited, to avoid content-presence side channels. The dedup ceiling is per-tenant commonality, not global. For how content identity works, read content addressing.

The cache hierarchy. A read walks the Linux page cache and the host-local object cache before it touches object storage. Once an object is cached, repeated reads cost zero remote bytes. The limit is that the cache is per host and disposable. A second cold host pays again. Loss of the host cache affects performance only, never correctness.

Singleflight. The daemon keeps an in-memory map of active fetches keyed by cache key. When several readers miss the same object at the same instant, one becomes the leader and fetches. The rest become followers and share the result. The read path routes through the fetch coordinator. The leader and follower counters publish at /metrics (awc_singleflight_leader_fetches_total, awc_singleflight_follower_requests_total). The limit is timing. Singleflight only helps when concurrent readers contend on one digest while the leader is still in flight. On one loopback host the leader tends to install the cache entry before the other readers arrive. They then take the cache fast path, and the follower path stays idle. Singleflight's value is the cross-host regime, where network round trips widen the contention window. That regime is not yet measured. For the design choices behind this path, read overlay, cache, and singleflight.

The measured shape

The evidence comes from two places. The regression gates are deterministic checks over the software data path. The pilot run is one end-to-end measurement on a single loopback host.

On the pilot, a fan-out of many agents over a common base reads about the same remote bytes as one agent. Local FUSE and CPU work scale with concurrency. Remote bytes do not. The fan-out property holds on loopback.

For storage, physical unique bytes come out at the base plus the sum of unique deltas, not forks times base. Storage amplification (logical retained divided by physical unique) is greater than one. The economic meaning is direct. Forking a large snapshot many times costs the base plus the unique deltas, not one full copy per fork.

For reads, the cache effect is the cold-versus-warm gap. A cold read costs one remote fetch plus verify-and-install. The same read warm is a pure local-cache read. On a real object store the cold cost widens by the store round trip, while the warm cost stays local. So the gap, and the egress savings, grows.

What it costs you

The same measurements expose the local cost. AWC is slower than a plain OverlayFS or ext4 view for local storage and for cold access. This is the price of routing reads through a FUSE content cache.

Cold reads are taxed. A cold build costs more than a warm one, because each first-touch file pays a remote fetch plus verify-and-install. The per-file cold-fetch cost dominates when the working set is small. Workloads that read or transform many files cold pay the most.

Editing a base file pays copy-up. Editing a file that lives in the lower overlay triggers a full data copy-up through FUSE. The first cold edit of each base file is the expensive one.

Publishing a snapshot costs bandwidth. Ingest does more byte work than a bare checksum pass, because it verifies and installs each object. This is a one-time cost per snapshot, not a per-read cost.

These are local taxes. The economic bet is that cross-host byte reuse pays them back.

Where the evidence stops

The pilot is one loopback host with a local object store. The flat-bytes result is real, but on loopback it is explained by the object cache plus the Linux page cache. The singleflight follower path is idle there. So the pilot proves the byte-amplification property, not the singleflight mechanism. The regression gates prove the coalescing property directly in the software data path, with no page cache in the loop.

The cross-host regime is where the economic case has to hold. A cross-host run needs a second host, a real network, the fetch coordinator on the read path, and its counters published. That run is not yet measured.

Until that cross-host run exists, the cross-host economic edge stays an open thesis. That edge is the whole reason the local tax is worth paying. It is not a proven result.

Read this before you reuse a claim

The pilot fan-out result is a local loopback measurement, not a cross-host proof. The cross-host economic edge is unmeasured. Singleflight's follower path is idle on loopback; the loopback win is the caches. Locally, AWC is slower than plain OverlayFS for cold reads and for editing base files.

For the boundary that keeps the write side cheap, read the durability model. For how shared bytes survive the deletion of one fork, read run garbage collection.