# The engine at 2026-10-18 — architecture note

**Scope.** The hosted engine behind metatronmind.com, as it exists at `HEAD` of the hosted branch on
18 October 2026. This note is the document half of the pack for *The engine, on the record*. It is
written from the code and from the engine's own public reads; where a number is live, it is from the
captures in this pack and the date is stated.

**Reading rule.** The code at `HEAD` is the authority for what exists. `docs/OVERVIEW-MANUAL.md` and
`docs/ARCHITECTURE.md` in the engine repository are the long-form descriptions; this note is the
short, current one. Anything dated before the Epoch 2 boundary (`eaf6239`, 2026-09-12) is testimony
about the previous system, not a description of this one.

---

## 1. What it is

**A grounded retrieval engine over a validated dictionary.** Text is read in, chunked, screened and
embedded; a question is embedded the same way and answered from the entries nearest to it. There is
**no online learning**: nothing in the query path changes the store, and a question cannot make the
next question answer differently.

The separation that matters:

- **The store** is the durable asset. It holds passages with vectors, node labels and provenance back
  to their chunk and document.
- **The harness** decides what may reach the writer: it gathers candidates, scores them, applies the
  grounding floor and the ladder, and assembles the attribution record.
- **The writer** is a language model that phrases what it is handed. It reads rendered text only —
  never vectors, never geometry — which is why it can be replaced without changing what the store
  knows.

Per query, the engine pages the relevant slice of the store into the model's window, so the effective
knowledge is the store, not the model's weights. The model needs to *express* what is paged in, not
to *know* it.

## 2. Initialization: what the engine starts with

Three layers, from `server/initialization.ts`:

1. **Identity** — 240 entries from `server/datasets/identity.json`.
2. **Scaffold** — 520 entries from `server/datasets/generalist-scaffold.json` (40 per label). These
   are also the entries the generalist's anchors are derived from.
3. **Baseline snapshot** — saved as `generalist-baseline`, the reset target.

240 + 520 = **760**. That is the generalist's size on the live box (`generalistDictionary: 760` in
`cubes-topology.json`). The corpus is not in the generalist; it is in the specialist cubes.

**The 13 labels are 6 axes plus a residual, not 13 independent directions.** The generalist's anchors
are difference vectors over six `POLAR_PAIRS`:

```
Anchor_a = normalize(centroid_a − centroid_b)
Anchor_b = −Anchor_a
```

so amplitudes are antipodal by construction, and the 13×13 anchor Gram matrix has **rank 7**. Node 12
(Existence) is the residual. The labels are a routing and interpretability scheme over a
7-dimensional prior; they are not "13 ways of thinking" in any separable sense.

The init gate is structural and fails closed: six antipodal pairs at cosine ≤ −0.999, Gram rank 7,
average pairwise geodesic 1.69 ± 0.01 rad, scaffold routing ≥ 85%, per-node cross-axis arrivals ≤ 15,
and dictionary size equal to identity + scaffold with zero rejected.

## 3. The query path

1. **Embed.** `nomic-embed-text-v1.5`, **768 dimensions** (`EMBED_DIM = 768`), task-prefixed, normalised
   onto the unit sphere.
2. **Route.** Resonance against the 13 anchors is *geodesic*:
   `geodesicResonance(a,b) = 1 − arccos(a·b) / π` (`server/engine/geodesic.ts`). Arccos is nonlinear,
   so a cosine of 0.95 and 0.90 are 42% apart in arc length. `winnerNode = argmax` — a label, not a
   weight.
3. **Retrieve.** One HNSW search over the vector store (LanceDB), scoped to the routed cube, returns
   the top **50** candidates (`forward-pass.ts`; the fetch pool widens only when the re-ranker is
   active). A second flat search across every ready cube lets specialists contribute candidates on
   the same score; the streams merge on similarity alone.
4. **Score.** `finalScore := querySim`, sorted descending. Raw geodesic similarity between the
   question and the entry's own vector. No additive bonus, no multiplier, no cascade weight: every
   one of those was removed on 2026-09-06 because each measured lower hit@10 than the raw order.
5. **Re-rank, in a band.** The cross-encoder re-ranker (`server/synthesis/reranker.ts`) is enabled on
   this box (`"rereads": true`). It runs only in the ambiguous similarity band — code defaults
   `RERANK_MIN_SIM = 0.62`, `RERANK_MAX_SIM = 0.80` — and scores the top 40 candidates by default. It
   reads rendered text only, and returns its input by reference on any sidecar failure or timeout, so
   it cannot change admission and cannot perturb the store.
6. **Ground or decline.** The best similarity is compared with `GROUNDING_DECLINE_THRESHOLD`
   (0.750 default, **0.760 in production**, `server/chat/retrieve.ts`). The grounding ladder
   (`server/chat/grounding-ladder.ts`, shipped 2026-09-28) then decides *where an answer may come
   from* and records the decision in `record.attribution`.
7. **Write.** The writer is handed the selected passages plus the engine's source note. The
   attribution is data stored with the message and drawn under the answer; the writer cannot forge
   it.

**Cross-cube blend.** One flat HNSW search across every ready cube (`CROSS_CUBE_BLEND`, default on)
interleaves foreign entries into the home cascade by `querySim`. There is deliberately no home-field
bonus: a bonus is exactly what recreated generalist dominance in an earlier build.

**Specialist routing.** `cube-router` selects a specialist by margin (`0.03`) and minimum similarity
(`0.60`), with delegation thresholds at 0.60 (weak parent) and 0.75 (strong), recursively, depth-capped
at 20. The live answered turn in this pack routed to a medical-physiology specialist at depth 1.

## 4. The grounding ladder

A decline is not a single bit. The ladder has three rungs:

| Rung | Source | What a reader can check |
|---|---|---|
| 1 | the store | the passage and its document |
| 2 | the web | the page the engine searched and measured |
| 3 | the model's own training | nothing — and the answer says so |

Three verdicts come from the numbers the gate already computes: `covered` (nearest passage clears the
threshold), `related` (falls short by no more than `GROUNDING_RELATED_MARGIN`, default **0.010**), and
`not-covered` (anything else, or a second reader judged the passages to be about something else).

When the verdict is not `covered` and the asker's tier is given the web, **the engine runs the search
itself** (`server/chat/ladder-search.ts`) and measures each result against the question. A search
counts only if the best result reaches `GROUNDING_LADDER_WEB_FLOOR` — default **0.800**. Measured on
2026-09-28 over eighteen questions: answerable questions' best result scored 0.831–0.884;
conversation, nonsense and personal remarks scored 0.681–0.794. "Results came back" is not "the web
had something to go on."

Who gets which rung is an operator decision, defaulting to: guests get the store and the web; signed-in
accounts and the operator get all three. `none` names nobody; a value that names no known tier names
nobody too, so a typo cannot widen access. On the live box:

```
decline: "ladder"
ladder: { guestWeb: true, guestGeneral: false, accountGeneral: true,
          related: true, writerSearches: true }
```

The footer is the point: the verdict and the account of the turn travel as `record.attribution`, are
stored with the message, and are drawn small under it. Until 2026-09-29 they were two lines written
into the answer; as data the writer cannot forge them.

**What the ladder does not do.** It labels the turn, not the sentence. A `covered` answer can still
contain what the model knew already; a web answer can ignore the pages. It does not set the threshold;
it makes a wrong one cheaper.

## 5. What it does not do

- **No online learning.** The field `learningMs` in `GET /api/system/status` is a legacy alias for
  the store's age. The code comment beside it: *"Nothing in the engine 'learns'; do not build on
  it."* The trainer state on the public box is `stopped`; the only dictionary writer is the operator's
  ingest executor.
- **No public ingest.** `capabilities.ingest` is `false` for an anonymous remote caller, and
  `about.screening` is `false` on this box. Ingestion is an operator path: work-ledger executor →
  chunker → LLM validator (fail-closed) → dictionary + vector store + replayable pair.
- **No claim of infallibility.** The store makes the evidence inspectable, not the interpretation
  correct.
- **A retrieval ceiling.** Below roughly 0.74 similarity the bi-encoder's relevance signal is
  noise-dominated. The gate is also a single global floor by default; per-cube floors exist because
  one floor is wrong for a store holding both a large generalist and a 200-entry specialist.

## 6. The public surface used by the piece

| Endpoint | Returns | Used for |
|---|---|---|
| `GET /api/system/status` | store size, specialist count, forward passes, genesis, reading state, the `about` facts a public page may use, the last calibration | every live count in the piece |
| `GET /api/cubes/topology` | roster totals, generalist size, every specialist's domain and size, per-node counts | the store table |
| `POST /api/chat` | the answer plus the response object: `mode`, `winnerNode`, `resonance`, `matchQuality`, `finalCubeId`, `routedCubeIds`, `blendedCascade`, `harness`, `ladder`, `attribution` | the two turns |
| `GET /api/cubes/registry` | cube roles, depths, off-roster list | the 10,938-entry archaeology cube and the 107-entry resident cube excluded from the public count |

The status handler's own comment is the best short statement of the exclusion: off-roster cubes are
excluded because *"chat cannot reach them, so they aren't part of what it knows"*, and the episodic
store's size must never become a public number.

## 7. Code map

| File (engine repo) | What it is |
|---|---|
| `server/engine/geodesic.ts` | the geodesic similarity the whole system scores on |
| `server/engine/forward-pass.ts` | the pass: amplitudes, routing label, HNSW candidates, raw `querySim` |
| `server/engine/metatron-engine.ts` | the engine object; `getHealth()`; the 13-node constants |
| `server/chat/retrieve.ts` | the production retrieval gate and `GROUNDING_DECLINE_THRESHOLD` |
| `server/chat/grounding-ladder.ts` | the ladder, its three verdicts, the attribution record (shipped here) |
| `server/chat/ladder-search.ts` | the engine-run web search and its relevance measurement |
| `server/synthesis/reranker.ts` | the banded cross-encoder re-rank and its no-op fallback |
| `server/status/public-about.ts` | what a public page may say about *this* box, chosen from the facts |
| `shared/public-copy.ts` | the public sentences, each kept next to what it rests on |
| `tools/verify-public-copy.ts` | the test that the public copy still matches the code — no engine, no network |
| `server/index.ts` | the status handler (including the "nothing learns" comment) |

*The engine repository is not published; the files shipped in this pack are the ones the piece relies
on directly, and the rest are named so the operator can find them.*