Memory and ownership
====================

A budget is an accounting contract. It has meaning only when the lifetime
of a charge matches the lifetime of the storage it pays for.

A charge follows storage
------------------------

Reserve bytes before allocating. Release the charge after freeing the storage.
When replacing a buffer, the old and new buffers can coexist.
Charge the full new allocation during that overlap.
Charging only the increase would understate the peak.

.. math::

   \text{replacement peak} = \text{other live storage}
     + \text{old buffer} + \text{new buffer}.

Session-owned input is reclaimed by the session.
Caller-owned input remains the caller's responsibility.
The names ``read_owned`` and ``read_kept`` make that distinction explicit.
A shorter read does not shrink the allocation already made for it.

Known zero is not unknown
-------------------------

A memory probe can know that no headroom remains.
It can also fail to discover headroom. Those are different states.
The policy carries a separate knowledge flag rather than using zero for both.
On Linux, readable cgroup limits apply through the visible ancestor hierarchy.
A container's host-wide free-memory number alone can be misleading.

Reports outlive workspaces
--------------------------

A report shown after a session ends must own its title, source, and repair text.
It must not borrow a buffer that the session has freed.
Source spans use byte offsets internally. User-facing columns count Unicode scalars.
Terminal markers account for display width separately.

The remaining boundary
----------------------

Guidedog meters its managed working storage.
The Typst compiler and native dependencies manage their own allocations.
Large PDF books can consume much more memory than the host budget.
The remote CPython validation measured about 14.5 GiB peak RSS including Typst.
Treat that measurement as workload evidence, not a universal upper bound.
See :doc:`../errors` for the user's choices when a managed budget is reached.