ref-pool

The pointer table for large content — slugs frozen on registration, folded without ever touching the prefix bytes.

The ref-pool is the “pointer table” for all large chunks of content. Oversized system items, <file> blocks, and big documents are moved into the pool and referenced by a stable slug, so that folding them later never disturbs the cached prefix.

Slugs are frozen on registration

register validates the slug against the regex ^[A-Za-z0-9_\-./]+$, requires the block to be band=FOLD, and requires ref_slug to equal the slug. Duplicate registration raises an error — a slug, once frozen, is immutable.

• register_or_skip — idempotent registration. Used when sharing a RefPool across turns: the harness produces a ref_pool with the full payload every round, and this method prevents the second round from overwriting an entry that the first round already folded into a placeholder.

Folding without breaking the prefix

fold(slug, summary=...)   # swaps an entry for a short placeholder

The slug is not touched, and the bytes of every [ref:slug] reference point in the text stay unchanged → subsequent breakpoints can still hit. This is how “references fold naturally” is realized: you replace the content a slug points to, never the pointer itself.

Folding swaps payload only, not the slug. Because the reference bytes are identical before and after, the prefix hash up to that point is preserved — the cache survives the fold.

Rendering and linting

• render_blocks — renders entries in lexicographic slug order, guaranteeing byte stability across emits.
• lint_text / lint_blocks — before emit, scan all [ref:slug] references; on finding an unregistered slug, immediately fail-fast.

The bridge’s _sync_refpool_into_system renders the ref-pool into the system segment in the order pin* + ref-pool fold* + drop*, keeping the §5 invariant intact.

How content enters the pool

Source	Behavior
system text > 2048 chars	the oversized system item goes into the pool, slug system-doc-{i}, with a PIN reference stub left in place
Hermes <file path=…> block	dotted slug, band=FOLD
Telos large doc	dash slug

The threshold is _REFPOOL_THRESHOLD = 2048.

Three-color bands

Why ref-pool entries are FOLD and where the PIN stub goes.

Architecture reference

The full ref-pool section, with the invariants table.