@hviana/sema 0.9.4 → 0.9.5

package/docs/architecture/factored-machinery.md

@@ -1,29 +1,43 @@
 # Factored Machinery — One Definition, Many Consumers
 
-Every shared operation is defined once and imported many times. Duplicating it
-forks the corpus contract; moving it hides who owns the gate.
+> **Law:** every operation that more than one layer relies on is defined once
+> and imported everywhere. A second copy is a write/read drift waiting to
+> happen. A copy moved into a consumer hides who owns the gate.
 
-Siblings: `match-project.md`, `commonality.md`, `meter.md`.
+Each row is a contract that broke at least once when it existed twice:
+
+- `contentBoundaries` carried its own hash loop;
+- the ingest cache re-implemented deposit;
+- recall spelled its own fragment test.
 
 ## Single-definition contracts
 
-| Symbol                                                        | Defined in                                              | One fact                                                                                                                                                                                      |
-| ------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `contentLevels`                                               | `src/geometry.ts`                                       | Single boundary rule: cuts + levels from one rolling hash pass; every segmentation reads it.                                                                                                  |
-| `canonicalWindows` / `chainReach` / `leafIdRun` / `windowIds` | `src/mind/canonical.ts`                                 | Write/read contract: training interns `W-1,W` windows, reading chains to `W²` and probes `W`-windows — drift silences recognition.                                                            |
-| `junction.ts` + `WalkCache`                                   | `src/mind/junction.ts`                                  | Shared junction ascent (parents + containers) with bounded `√N·W` walk; `WalkCache` memoizes capped reads/parents/containers per response; bridge and attention share it.                     |
-| `joinWithBridge`                                              | `src/mind/resonance.ts`                                 | One out-of-search assembly: `bridge(left,right)` or bare concat with `bridgeMiss` trace.                                                                                                      |
-| `dismissedKnownContent`                                       | `src/mind/bridge.ts`                                    | Pure attestation: any unaccounted `W`-window that resolves as known content — shared gap guard for substitution and CAST.                                                                     |
-| `sharedReachMemo`                                             | `src/mind/traverse.ts`                                  | One response-scoped `AncestorReach` memo (cleared on write and for traces); every `reachOf`/`edgeAncestors` consumer shares it.                                                               |
-| `guidedFirst`                                                 | `src/mind/traverse.ts`                                  | Guided-or-first answer bytes: `guidedNext` else first-inserted edge (`LIMIT 1`).                                                                                                              |
-| `leadsSomewhere`                                              | `src/store.ts` (raw), `src/mind/traverse.ts` (memoised) | Admission predicate: `hasNext` or `hasHalo`, defined once on the store; traverse memoises the edge tier per response.                                                                         |
-| `isChunk`                                                     | `src/sema.ts`                                           | `kids !== null && kids.every(k=>k.kids===null)` — smallest grouped unit; governs regions, seams, indexing.                                                                                    |
-| `twoEndedSeat`                                                | `src/sema.ts`                                           | One seat algebra: first half low seats, second half high seats; shared by perception, `fold`, and canonical folds.                                                                            |
-| `closed`/`admissible`/`advance`/`closeOver`                   | `src/mind/derivation.ts`                                | One admission for every derivation step, the readings every tier asks, and the engine that walks the post-grounding layers.                                                                   |
-| `exactNode`                                                   | `src/mind/primitives.ts`                                | The exact content-addressed lookup (`resolve`, `canonResolve`): the identity fold (`contentIdentity`, geometry.ts) — a miss decided by the segment filter, a hit named bottom-up, no vectors. |
+| Symbol                                                                 | Home                                  | The one fact it owns                                                                                                                   |
+| ---------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `contentLevels`                                                        | `geometry.ts`                         | the boundary rule: cuts and levels from one rolling hash (`fold-contract.md`)                                                          |
+| `groupByLevel` / `foldSlice`                                           | `geometry.ts`                         | the tree's shape, written once over two algebras (vector and identity)                                                                 |
+| `twoEndedSeat`                                                         | `sema.ts`                             | the seat algebra: low seats for the first half, high seats for the second                                                              |
+| `isChunk`                                                              | `sema.ts`                             | the smallest grouped unit, a node whose children are all leaves                                                                        |
+| `exactNode` / `branchNaming`                                           | `mind/primitives.ts`                  | exact lookup: the identity fold, naming a branch exactly as `intern` does                                                              |
+| `canonicalWindows` / `chainReach` / `leafIdRun` / `windowIds`          | `mind/canonical.ts`                   | the window contract: deposits intern windows of `W−1` and `W`, and reads chain them to `W²`                                            |
+| `leadsSomewhere`                                                       | `store.ts`, memoized in `traverse.ts` | admission: `hasNext \|\| hasHalo`                                                                                                      |
+| `corpusN` / `hubBound` / `hubCap`                                      | `mind/traverse.ts`                    | the scale and its cap (`bounded-reads.md`)                                                                                             |
+| `sharedReachMemo`                                                      | `mind/traverse.ts`                    | one `AncestorReach` memo for every `reachOf`/`edgeAncestors` consumer                                                                  |
+| `answersOtherQuestions`                                                | `mind/traverse.ts`                    | the fragment predicate: a form inside other forms, with several continuations, that the question leaves partly outside (`evidence.md`) |
+| `junctionContainersFrom` + `WalkCache`                                 | `mind/junction.ts`                    | the content-addressed ascent shared by the bridge and attention                                                                        |
+| `joinWithBridge`                                                       | `mind/resonance.ts`                   | joining two results outside the search: `bridge(left, right)`, or a bare join traced as `bridgeMiss`                                   |
+| `dismissedKnownContent`                                                | `mind/bridge.ts`                      | the gap guard shared by substitution and CAST: no dismissed window may resolve as known content                                        |
+| `locate` / `alignGraded` / `frameSlots` / `project`                    | `mind/match.ts`                       | the matcher family; gates belong to the consumers (`match-project.md`)                                                                 |
+| `witness` / `windowIndex`                                              | `mind/evidence.ts`                    | order-free W-window coverage, the evidence reading (`evidence.md`)                                                                     |
+| `closed` / `admissible` / `advance` / `closeOver` / `unexplainedSpans` | `mind/derivation.ts`                  | the closure law, its span algebra and its engine (`closure.md`)                                                                        |
+| `Precomputed`                                                          | `mind/pipeline-mechanism.ts`          | the per-response shared analyses (`memoization.md`)                                                                                    |
+| `weigh`                                                                | `mind/pipeline.ts`                    | the price, `moves + PASS·unaccounted` (`cost-model.md`)                                                                                |
+| `Meter`                                                                | `meter.ts`                            | every counter name (`meter.md`)                                                                                                        |
 
 ## Pins
 
-- `test/47` — frame reading split (matcher vs gate vs inventory).
-- `test/50` — CAST analog / consensus floor (dismissed content, `MIN_WEAVE` /
-  `dominates` frame, `carriesFillers` refusal).
+- `test/137` — the law lives once and below: no hand-built transition outside
+  `advance`, no inline re-spelling of a law reading, and no dead export.
+- `test/47` — the frame reading split into matcher, inventory and gate.
+- `test/50` — CAST's shared guards: dismissed content, the frame from
+  `MIN_WEAVE` and `dominates`, and the `carriesFillers` refusal.

package/docs/architecture/fold-contract.md

@@ -1,137 +1,129 @@
-# Fold Contract — One Tree For The Same Bytes
+# Fold Contract — One Tree for the Same Bytes
+
+> **Law:** perception is a pure function of the bytes. A deposit
+> (`perceiveDeposit`) and a question (`perceive`) fold the same bytes into the
+> same tree, and the read side names that tree with the node the write side
+> interned. Nothing absent from the bytes may shape the tree: turn boundaries,
+> offsets and index-aligned grids are excluded.
+
+Identity is content (`store.md`), so a question finds what memory holds only if
+it is cut exactly as the deposit was. When the two sides disagreed, alignment
+went quadratic (5.2M cells on a 476-byte context, against 0 when they agree),
+and cumulative contexts stopped resolving to what they were trained as.
+Conversation state (`ConversationState`, `answeredSpans`, `currentTurnStart`) is
+API metadata and never reaches the geometry. Passing turn boundaries into the
+fold is a correctness bug, not a tuning choice.
+
+## The boundary rule — `contentLevels`
+
+`contentLevels` is the one boundary rule, and `contentBoundaries` is its
+projection.
+
+- **Cuts.** A rolling hash runs over a bounded window of the bytes, and a cut
+  falls where it vanishes. A cut is level `L` when the hash vanishes mod
+  `W^(L+1)`, so level-`L` cuts nest inside level-`(L−1)` cuts, and a level-`L`
+  span averages `W^(L+1)` bytes.
+- **Segments.** A segment runs from `W−1` bytes to `seats.length` bytes, the
+  most one flat node folds, with a forced cut at the maximum.
+- **Grouping.** `groupByLevel` groups segments by their level, never by count.
+
+**Why content, not position.** A change moves only the cut it falls inside.
+After shifts of 1–7 bytes, 99.7% of cuts on real deposits survive, against 14.3%
+for a fixed grid. Grouping by index (a stride, a tile, a fixed-arity row such as
+`riverFold`'s `W`-ary grouping from byte 0) makes the same run a different
+subtree at a different offset.
+
+**The distribution is load-bearing.** Each of these has been changed
+experimentally, and each change broke tests:
+
+| Change                  | Tests broken    |
+| ----------------------- | --------------- |
+| cut rate                | 15–18           |
+| bits read               | 19–21           |
+| normalized chunking     | 5–6             |
+| relaxing the forced cut | the same suites |
+
+The forced cut accounts for 32% of all cuts. Every mechanism downstream is
+fitted to this distribution, so any change here must be re-measured on the whole
+suite. A second copy of the hash loop, which `contentBoundaries` once carried,
+lets the write side and the read side drift without a type error.
 
-> **Law:** `perceiveDeposit` ≡ `perceive` — same bytes ⇒ same tree and same node
-> id. Deposit imposes nothing (no boundaries, no turn convention). Geometry
-> never sees conversation metadata.
+## One shape, two algebras
 
-## The identity
+`groupByLevel` and `foldSlice` are written once, over a fold algebra (`join`,
+`key`), and run over two algebras:
 
-Perception is a pure function of the bytes. The deposit path and the inference
-path compute the same content-defined fold for the same input, so a trained
-context node and `resolve(query)` reach the same node. When the two sides
-disagreed, alignment went quadratic (measured 5.2M cells on a 476-byte context
-vs 0 when they agree) and cumulative contexts stopped resolving to what they
-were trained as.
+- **The vector fold (`perceive`)** produces gists.
+- **The identity fold (`contentIdentity`)** names the node a stream folds to by
+  asking the store bottom-up as it folds.
 
-## Deposit imposes nothing
+Inside an over-long row, grouping also reads each item's `itemKey`: eight raw
+gist coordinates. The identity fold computes only those coordinates, lazily,
+with the same float32 additions in the same order. `exactNode` is the identity
+fold, so resolving a span builds no `D`-dimensional gist. On the 31.7M-node
+store, one join query went from 185 s and 4.4 GB retained to 40 s and 81 MB,
+with the same answer. Written once, the two folds cannot disagree about the
+tree.
 
-No boundaries, no turn convention, nothing read out of the bytes. Conversational
-turn offsets are API metadata — they feed `ConversationState`, `answeredSpans`
-and `currentTurnStart`; the geometry never sees them. Passing turn boundaries
-into the fold is a correctness bug, not a tuning choice.
+## The read side names as the write side names
 
-## Boundaries vs reuse — two problems
+The store's `intern` names a branch by its children first. When the children
+name nothing, it reuses the flat node over the same bytes ("same bytes, same
+node"). Deposits intern flat nodes, so a later deposit's branch is often stored
+as an earlier deposit's window: `ver` + `!` is stored as the window `ver!`.
+`branchNaming` (`mind/primitives.ts`) applies the same order on the read side,
+in `exactNode` and `foldTree`, and an unnamed child does not settle the
+question. On the 31.7M-node store, 7 of 80 dialogue turns asked verbatim used to
+resolve to nothing, costing 26–41 s each on the composition path. They now
+resolve to their own context.
 
-`contentFoldIncremental` and `stablePrefixFold` solve different problems;
-conflating them is what once put an imposed boundary set on the inference path.
+A name found only through the bytes is a flat entry, not a learnt structure. In
+that case `resolve` also asks the canonical class (`exactNaming`'s `byBytes`)
+for the member that leads somewhere. That class is an optional capability
+(`store.md`), and its candidates are hash-then-verified.
 
-| Mechanism                | What it buys                                              | Cost / shape                                                                                    |
-| ------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `contentFoldIncremental` | Transparent segment reuse (cost only)                     | Imposes nothing; tree identical to the cold fold                                                |
-| `stablePrefixFold`       | Caller-supplied cuts left-nested for prefix-ROOT identity | One prefix-ROOT per cut becomes an identical subtree (and same node id) inside the grown stream |
+Known limit: a context stored with cuts at the ends of earlier turns does not
+resolve. No current deposit path produces that shape, and reproducing it would
+mean guessing turn boundaries, which this contract forbids.
 
-Both carry the same precondition: `prev` must be a fold of a byte-identical
-prefix — reuse is keyed on `[start,end)` offsets, which cannot witness byte
-agreement. A mismatched `prev` produced a wrong tree on 336 of 400 random
-streams. `perceiveDeposit` discharges this via the prefix bytes as cache key; a
-conversation advances only by append. A caller that cannot prove the prefix must
-pass no `prev`.
+## Canonical windows — finding a span whatever the fold did
 
-## Identity must not depend on W or absolute offset
+Besides its tree, every deposit interns flat nodes:
 
-`contentLevels` is the single boundary rule (rolling hash over a bounded
-window). Any grouping by index — stride, tile, fixed-arity row — reintroduces
-the grid's phase bug: `riverFold` groups `W`-ary from byte 0, so the same byte
-run is a different subtree at a different offset. The content-defined hash
-removes this: a change upstream moves only the cut it falls inside; downstream
-cuts and segments are unchanged (99.7% cuts preserved on real deposits after
-shifts of 1..7 bytes vs 14.3% for the grid). The `groupByLevel` above the
-segments splits by content level, not by count.
+- its whole stream;
+- each window of `W−1` and `W` bytes, contained by the chunks it overlaps
+  (`canonicalWindows`, `indexSubSpans`).
 
-## `contentLevels` is single source; `contentBoundaries` is projection
+Recognition's canonical reading chains these windows up to `chainReach = W²`
+leaf ids from a position. This write/read pair finds a form embedded at an
+offset where the question's own cuts do not line up with it (`canonical.ts`).
 
-`contentBoundaries(space, bytes)` is `contentLevels(space, bytes).cuts`. It once
-carried its own rolling-hash loop, which is how a write side and a read side
-drift without a type error. Levels are read from the hash the cut was accepted
-at — level `L` when `h` vanishes mod `W^(L+1)` — so level-`L` cuts nest inside
-level-`(L-1)` and expected span is `W^(L+1)` bytes.
+## Incremental folds — reuse is not boundaries
 
-## One shape, two algebras
+`contentFoldIncremental` reuses already-folded segments of a byte-identical
+prefix. The result is the cold fold's tree, so the reuse changes cost only. It
+is the only fold any internal path computes: `perceiveDeposit` keys the reuse on
+the prefix bytes, and a conversation advances only by appending.
 
-Which items group under which parent is decided by the cut levels, the keyring
-and — inside an over-long row — each item's `itemKey` (eight raw gist
-coordinates). `groupByLevel`/`foldSlice` are written ONCE over a fold algebra
-(`join`, `key`) and run over two of them: the vector fold (`perceive`) and the
-identity fold (`contentIdentity`), which names the node a stream folds to by
-asking the store bottom-up and reads only the coordinates `itemKey` hashes,
-lazily, with the same float32 additions in the same order. `exactNode` is the
-identity fold, so resolving a span builds no D-dimensional gist and leaves
-nothing in the perception memo (measured on the 31.7M-node store: one join query
-went 185 s / 4.4 GB retained → 40 s / 81 MB, same answer). A grouping rule
-written twice would be a write/read drift waiting to happen; written once, the
-two folds cannot disagree about the tree.
-
-## Same tree is not enough — the read side names as the write side names
-
-The store's `intern` names a branch by its children, and when they name none it
-looks up the FLAT node over the same bytes and REUSES it (step 1b, "same bytes,
-same node"). Every deposit interns flat nodes — its whole input and each
-canonical window — so a later deposit's branch is often stored as an earlier
-deposit's window (`ver` + `!` stored as the window `ver!`). The same tree is
-then named by a node no child lookup can reach. `exactNode` and `foldTree` name
-a branch exactly as `intern` does (`branchNaming`, `src/mind/primitives.ts`):
-the children first, the flat node over the same bytes when they name nothing —
-and an unnamed child does not settle it, since the write side minted that child
-and still reached step 1b. Measured on the 31.7M-node store: 7 of 80 dialogue
-turns asked verbatim had resolved to nothing and fell to the composition path
-(26–41 s); they now resolve to their own context.
-
-A name found only through the bytes is where the exact lookup used to MISS, and
-a flat index entry is not a learnt structure, so `resolve` still asks the
-canonical class there (`exactNaming`'s `byBytes`): it holds the learnt member
-that leads somewhere, when there is one. The store holds such byte-only names
-from an earlier deposit path (today's deposits always intern the structure
-beside the flat copy), which is why `test/152` builds the state through the
-store's write API.
-
-One stored turn of the same set still does not resolve: its context was stored
-with cuts at the ends of the conversation's EARLIER contexts (103 and 227 bytes
-into a 257-byte context) — a boundary-imposed shape neither today's deposit path
-nor the training-time one produces from these bytes, and that the read side
-could reproduce only by guessing turn boundaries, which this contract forbids.
-
-## Optional canonical capability
-
-`canonAdd`/`canonFind` (`src/store.ts` — `canonCount`/`eachContent`) is an
-optional backend capability. A backend may omit all four; resolution then has no
-equivalence fallback. The store never learns the equivalence — the canonicalizer
-(`Canon` in `src/canon.ts`, e.g. `textCanon`) is injected by the caller and
-every candidate is hash-then-verified (re-canonicalize stored bytes, compare). A
-hash collision costs a read, never a wrong id.
-
-## Cost of changing the cut distribution
-
-The cut rate, which bits are read, `minLen`/`maxLen`, and the forced cut at
-`maxLen` set the segment distribution every downstream mechanism is fitted to.
-Each has been changed experimentally and cost 5–21 tests (rate: 15–18, bits:
-19–21, normalized chunking: 5–6). `W-1` is the minimum (one window minus one);
-`seats.length` is the maximum (one flat node folds exactly one segment). The
-forced cut is load-bearing — relaxing it to reduce the current 32% forced rate
-looked like a tidying but broke the same suites. Re-measure the whole suite for
-any change here.
+`stablePrefixFold` is a separate, public geometry capability. It takes cuts
+supplied by the caller and nests them to the left, so that each prefix root is
+an identical subtree inside the grown stream. No path inside the mind supplies
+such cuts, and confusing the two capabilities is how an imposed boundary set
+once reached inference.
+
+Both capabilities require `prev` to be a fold of a byte-identical prefix. Reuse
+is keyed on offsets, and offsets cannot witness that the bytes agree: a
+mismatched `prev` produced a wrong tree on 336 of 400 random streams. A caller
+that cannot prove its prefix must pass no `prev`.
 
 ## Pins
 
-- `test/59` — shift invariance floors (content-defined cuts preserved over
-  random binary and prose).
-- `test/63` — offset/W invariance and `contentLevels` distribution expectations.
-- `test/148` — the identity fold names exactly what the vector fold names (every
-  sub-span of corpus and noise), and groups exactly as it does over long
-  low-entropy streams that force the `itemKey` split.
+- `test/59` — shift invariance: content-defined cuts survive shifts in random
+  binary and in prose.
+- `test/63` — offset and `W` invariance, and the expected `contentLevels`
+  distribution.
+- `test/148` — the identity fold names exactly what the vector fold names, and
+  groups as it does over long low-entropy streams that force the `itemKey`
+  split.
 - `test/152` — a deposit stored through an earlier deposit's flat window
-  resolves to its own context, both folds name it, and it is answered on the
-  exact path.
-
-See:
-`src/geometry.ts:contentLevels`/`contentBoundaries`/`contentFoldIncremental`/`stablePrefixFold`/`contentIdentity`;
-`AGENTS.md` §2 invariants.
+  resolves to its own context, and is answered on the exact path.

package/docs/architecture/halo-sketch.md

@@ -1,99 +1,108 @@
-# Halo & Sketch — Distributional Memory
-
-A node's **halo** is its distributional signature: the superposition of
-identity-bound company signatures poured from every episode it participated in.
-Its **gist** is the VSA fold of its own bytes — content, not company.
-
-## Two vectors per node, two indexes
-
-| Vector | Encodes                       | Index         | Query          |
-| ------ | ----------------------------- | ------------- | -------------- |
-| gist   | what the node _is made of_    | content index | `resonate`     |
-| halo   | what _company_ the node keeps | halo index    | `resonateHalo` |
-
-Both indexes are RaBitQ-IVF (`src/rabitq-ivf/`) — 1-bit ANN over the same
-vectors; scores are estimates, never identity. Halos are also persisted durably
-(see below).
-
-## Quantization — 2-bit on disk, float in session
-
-A halo is a superposition of quasi-orthogonal signatures, so coordinates are
-Gaussian. Storage exploits this:
-
-- **In-session accumulator** (`_haloExact` in `src/store.ts`): `Float32Array` —
-  exact, additive, incremented by `pourHalo`.
-- **Durable row** (`_dbUpsertHalo`): 2-bit Lloyd–Max quantizer — decision at
-  ±0.9816σ, levels at ±0.4528σ / ±1.5104σ, σ derived from the stored norm
-  (`norm/√D`). Header is the 4-byte norm; body is 2 bits/coordinate. Keeps ≥0.88
-  correlation with the exact vector.
-- **ANN index**: 1-bit RaBitQ, irreversible — answers only "which halos are near
-  this query?"
-
-Re-indexing is geometric: a halo re-enters the ANN when mass is small or crosses
-a power of two (`geometricMass`), so index writes are O(log mass).
-
-## Bottom-k sketch & company profile
-
-A whole-partner signature alone records tokens, not types — halos of genuine
-synonyms would be quasi-orthogonal. `companyProfile` (`src/mind/learning.ts`)
-superposes:
-
-1. the partner's own identity signature, plus
-2. the bottom-k **constituent sketch** — the
-   `k = profileCapacity(D) = floor(√D)` minimal units of its subtree with
-   smallest `unitPriority`, deduped.
-
-The sketch is composable (bottom-k of a union = bottom-k of children's
-sketches), durable derived state via `sketchGet`/`sketchPut`, and bounded: at
-most `k` constituents are classified, each by one `LIMIT`ed parent read
-(`hubBound`). Beyond `√D` terms a single constituent contributes less than
-`1/√D` — below RaBitQ noise — and extra terms shrink every accepted one; the cap
-is a correctness limit.
-
-## Gist vectors
-
-Folded by the river (`src/geometry.ts`): leaves are alphabet vectors, groups
-bind by two-ended seats, intermediate gists stay unnormalized (magnitude ∝
-√len), only the root is normalized. Gist resonance reads byte-proportional
-overlap; halo resonance reads distributional overlap — the two are independent.
-
-## Thresholds & gating
-
-All bars are derived in `src/geometry.ts`; no tunable constant:
-
-| Symbol             | Formula        | Use                                                                                               |
-| ------------------ | -------------- | ------------------------------------------------------------------------------------------------- |
-| `estimatorNoise`   | `1/√D`         | 1σ RaBitQ noise; contrastive margin must clear it                                                 |
-| `significanceBar`  | `3/√D`         | whole-query relatedness — 3σ above chance; gates consensus climb and `analogyStrength`            |
-| `conceptThreshold` | `0.5 + 0.5/√D` | halo concept sharing — structural midpoint + ½σ; gates `haloSiblings`, concept hops, articulation |
-
-The significance bar gates the whole query; `conceptThreshold` gates per-pair
-halo cosine.
-
-## Probes: `haloMass` and `hasHalo`
-
-- `haloMass(id)` — count of poured episodes; evidence weight, tie-breaker in
-  `chooseAmong`.
-- `hasHalo(id)` — existence probe (indexed point check, no vector decode);
-  mirrors `halo(id) !== null`. One tier of the `leadsSomewhere` admission
-  predicate (with `hasNext`/`hasParents`).
-
-Both are `meter`-counted probes, not full decodes — `halo(id)` is the bounded
-vector read; `resonateHalo` is the IVF ANN query.
-
-## Relation to invariants
-
-- **Derived thresholds** — all bars above live in `geometry.ts`.
-- **Exact decides / approximate proposes** — halo scores rank and gate; identity
-  is content-addressed. The graded ladder is exact → halo → gist
-  (`mind/match.ts`).
-- **Bounded reads** — `hasHalo`/`haloMass` are point probes; `resonateHalo` is
-  capped ANN; constituent classification uses `LIMIT hubBound+1` reads. No
-  per-query scan grows with corpus.
+# Halo — Distributional Memory
+
+> **Law:** a node's halo is the superposition of the company it was deposited
+> in. It measures nearness of _use_, independently of the gist, which measures
+> nearness of _form_. It is a statistic over the record: it may propose, never
+> decide (`exact-vs-approximate.md`).
+
+The gist puts `colour` near `colours`. Only the halo can put `colour` near
+`hue`, two words whose bytes have nothing in common.
+
+## How a halo is poured
+
+Each deposited fact `(context → continuation)` makes two pours (`ingestPair`):
+
+- every part of the context newly seen by this deposit receives the
+  continuation's profile, bound to seat 1, _what it led to_;
+- the continuation receives each such part's profile, bound to seat 0, _what led
+  to it_.
+
+Pours add. Each profile is normalized, so one episode pours one unit of mass
+(`haloMass` counts episodes). Addition forgets order and keeps proportion, which
+is why the halo is a statistic rather than a record.
+
+## Company by type, not by token — the profile
+
+A partner's own signature (`companySignature`, a random unit vector seeded by
+its node id) records a token: "occurred near node #4711992". Whole deposits
+almost never recur (whole-span dedup on the trained store is 0.98×), so the
+halos of genuine synonyms came out quasi-orthogonal. The best distributional
+sibling of `Eiffel Tower` scored 0.146 against a bar of 0.516.
+
+So `companyProfile` superposes the partner's own signature with the signatures
+of its **bottom-k constituent sketch**: the `k = profileCapacity(D) = ⌊√D⌋`
+minimal units of its subtree with the smallest identity-keyed priority.
+
+- **The sketch descends to every depth.** Content-defined cuts depend on the
+  surrounding bytes, so a shared unit such as `Paris` is often not a top-level
+  chunk of either partner. A depth-1 read measured 0.0319 against 0.0416 for an
+  unrelated control: no signal.
+- **The sketch is independent of arrival order.** A stop rule like "descend
+  until a unit is attested twice" depends on which partner was trained first,
+  and its pairs never met (0.0165 against 0.0375). The priority is a hash of the
+  unit's id, so a unit shared by two partners is kept by both or by neither.
+- **Hubs are excluded, but still descended into.** A unit with more than `√N`
+  parents (`is`, `the`) would put one shared term into every profile, all halos
+  would correlate, and the concept bar's null model would collapse. Byte atoms
+  are skipped for the same reason. So is a unit that dominates the partner,
+  because that unit is the partner itself.
+- **The sketch is composable and durable.** Bottom-k of a union is bottom-k of
+  the children's sketches. Sketches are stored (`sketchGet`/`sketchPut`), so a
+  partner met again costs `O(k)`.
+
+Every term is a seeded function of a node identity, never of a gist, so
+resemblance of spelling cannot leak into resemblance of use. Two partners
+sharing `j` of `k` discriminating constituents meet at `j/(1+k)`. A profile is
+fixed given the corpus seen so far. As `N` grows, a term can move only from
+contributing to excluded-as-hub.
+
+`k = √D` is a correctness limit, not a budget. Beyond it, one more term
+contributes less than `1/√D`, below the estimator's noise, and dilutes every
+accepted term.
+
+## Storage — exact in session, quantized at rest
+
+| Layer     | Form                                                                                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------------------- |
+| session   | `Float32Array` accumulator, exact and additive (`pourHalo`)                                                             |
+| durable   | 2-bit Lloyd–Max quantizer: decision at ±0.9816σ, levels ±0.4528σ / ±1.5104σ, σ = norm/√D. Correlation ≥ 0.88 with exact |
+| ANN index | 1-bit RaBitQ, answering only "which halos are near this one?"                                                           |
+
+A halo re-enters the index when its mass is at most 4 or a power of two, so
+index writes are `O(log mass)`.
+
+Halo comparisons do not depend on the configured seed, because signatures are
+keyed on node ids. Gist comparisons do: a Mind built with a seed other than its
+store's makes every gist comparison meaningless, while its halo comparisons
+remain valid.
+
+## Where halos are read
+
+| Use                                                                                            | Gate               |
+| ---------------------------------------------------------------------------------------------- | ------------------ |
+| admission: a form _leads somewhere_ if `hasNext \|\| hasHalo` (`store.md`)                     | existence probe    |
+| `locate`'s second tier (halo role), `alignGraded`'s halo-matched sites                         | best halo mate     |
+| synonym tiers: junction bridge, `crossRegionVotes`, substitution bridge                        | `conceptThreshold` |
+| concept hops in `cover`: an edge-less form borrows a halo sibling's continuation, at `CONCEPT` | `conceptThreshold` |
+| CAST's analogy strength                                                                        | `significanceBar`  |
+| `chooseNext`: halo mass breaks ties after `prevCount`                                          | ordering only      |
+
+The bars are derived in `geometry.ts` (`thresholds.md`):
+
+- `estimatorNoise = 1/√D`;
+- `significanceBar = 3/√D`;
+- `conceptThreshold = 0.5 + 0.5/√D`, the structural midpoint plus half a noise
+  unit.
+
+`haloMass` and `hasHalo` are point probes. `halo(id)` is the bounded vector
+read, and `resonateHalo` is the capped ANN query.
 
 ## Pins
 
-- `test/08 storage halo` — halo persistence, 2-bit round-trip,
-  `haloMass`/`hasHalo` contract, index survival across reopen.
-- `test/35 ivf` — RaBitQ-IVF contract (recall vs brute force, sublinear
-  scaling); covers the halo index's own layer.
+- `test/08` — halo persistence, the 2-bit round trip, the `haloMass`/`hasHalo`
+  contract, and the index surviving a reopen.
+- `test/76-type-level-company` — company shared by type: synonyms meet through
+  their constituents.
+- `test/29` C1 — CAST's halo-tier analogy evidence. A profile polluted by byte
+  atoms silenced it.
+- `test/35-ivf` — the RaBitQ-IVF contract under the halo index.