# Implementation plan — §8.9, the model half of the fact box Against `docs/superpowers/specs/2026-09-03-memoria-design.md` §8.9 and amended decision 15. Branch `feat/model-fallback`, worktree `../memoria-model-fallback`, cut from `origin/main` `1a7f988` (which is the fact box, landed 2026-09-27) plus the decision-15 spec commit. **This is memoria's first provider call.** Nothing in the binary talks to a model today, so this plan builds the minimum of slice 2 that §8.9 needs — a chat client, a switch, a disclosure — and nothing of the embedding half (gates 28-30 stay unbuilt). --- ## 0. Things the spec does not settle, which the code forces Raised here so the reviewer rules on them rather than finding them in a diff. Each has a proposed answer. **0.1 The per-keystroke route.** `GET /search` renders the results region on every debounced keystroke (`search.js`, `DEBOUNCE_MS = 120`), and §8.8 puts the box inside that region so page and fragment agree. A model fallback there fires on typing pauses, not just on Enter. *Proposed:* allow it, and bound it three ways. The call rides the request context, so `search.js`'s `inflight.abort()` on a changed query cancels the TensorX request rather than paying for it. A hard deadline — **800 ms, §6.5's sibling deadline, reused rather than invented** — after which the box renders without the model row. And the call only happens when AI is on **and** the query names a valueless kind **and** deterministic extraction found nothing for it. Rejected: model only on the full-page route, which makes page and fragment disagree about the box — the thing §8.8 put the box inside the define to prevent. **0.2 Decision 4 says every answer names its provider. §8.9 does not say the box does.** A model-sourced row is model output. *Proposed:* it carries the 🤖 marker (AGENTS.md §Authorship) and the model id, and a deterministic row does not — so the reader can tell which rows a checksum vouched for and which a model pointed at. This is a spec gap to be closed in the same branch. **0.3 Address has a deterministic half, and Paul's rule says use it first.** §12's struck row named it: "an eircode certifies the lines above it". *Proposed: not in this branch.* It is a real improvement and the right next step, but it is a second recogniser with its own label and boundary problems, and §8.9 is already the first provider call. Recorded in §12 as the next deterministic step for Address; the model handles Address alone until it lands. Flagged because it is exactly the "as much as possible deterministically" the ruling asks for, and deferring it is a choice. **0.4 A short returned string trivially passes the verbatim check.** "Dublin" appears in half the corpus. *Proposed:* the model must name **which** passage (by index) its span came from, the check is against **that** passage only, and a span must carry at least two lines' worth of structure — ≥ 12 characters and at least one comma, newline or digit. Structural, stated, and not a validator. --- ## 1. `internal/memoria/fact` — the Address kind `Kind` gains `Address`. The lexicon gains `address`, `postal address`, `office address`, `where are we` — longest-first already ensures `email address` still means Email. **No recogniser**: `Address` has no entry in `recognisers`, so `Scan` never yields one and the deterministic path is unchanged. `fact.Validated(k)` reports whether a kind has a recogniser, which is what decides whether the model may be asked. Tests: `address` primes Address; `email address` still primes Email only; `Scan` never returns an Address. ## 2. `internal/memoria/provider` — new package, the TensorX client The only code in memoria that dials a model. - **Base URL is a constant**, `https://api.tensorx.ai/v1`. Decision 13: a configurable base URL is how an owner points memoria at a proxy while the page still says "one named provider". The test seam is an unexported constructor taking an `*http.Client` and a base, reachable only from the package's own tests — the `AppForTest` pattern. - **Model id is a constant**, `deepseek/deepseek-v4-flash-0731` (§8.2's `model.cheap`). Swapping it is a code change and a review, per §8.2. - `Extract(ctx, kind, passages []string) ([]Pointer, error)` where `Pointer{Passage int; Text string}`. JSON-mode request; the response is parsed strictly (`suite`'s strictjson pattern) and a malformed one is an error, never a partial result. - **The response body is capped and the cap is detectable** — read one byte past it and error (AGENTS.md, the S3 lesson). - **Nothing from the response is ever logged** — status code and a fixed string only (gate 31, AGENTS.md "a provider's response body is content"). The prompt is not logged either. - **800 ms deadline** applied inside, on top of the caller's context. ## 3. `config.go` — on or off - `MEMORIA_AI` — `on` or unset. Decision 4: opt-in per team, the owner's choice. Anything other than `on` or empty is a startup error, so a typo does not silently mean off. - `MEMORIA_TENSORX_KEY` — required when `MEMORIA_AI=on`, **refused at startup** if AI is on and it is absent (loud), and ignored when AI is off. A key present with AI off does not turn AI on. ## 4. `store.go` — the fallback, after everything deterministic In `addFacts`, after the per-kind deterministic rules have run: 1. For each wanted kind with **no validator** that produced **no** box, and only if a provider is configured: 2. send the ruled passages' texts (already opened for the deterministic pass — no second read) to `provider.Extract`; 3. for each returned pointer, **locate `Text` in passage `Passage` with `strings.Index`** — not anywhere, that passage; drop if absent or if it fails 0.4's structural bound; 4. slice the span from the document at that index — the model's own string is now discarded — and derive the label with `fact`'s label rules at that offset; 5. apply §8.8's identity, collision and cap rules unchanged; 6. mark the rows `Model: "deepseek/deepseek-v4-flash-0731"`. Any provider error or timeout → no model rows, the page renders as it would have, one log line carrying status and a fixed string. ## 5. Template, CSS A model row gets `rst-fact-model` and renders `🤖` plus the model id beside the citation. Deterministic rows unchanged. ## 6. README and §3.6 The README's first paragraph currently says no model call exists anywhere and "no document ever leaves this instance". With `MEMORIA_AI=on` that stops being true. **It has to say so before the code that makes it false can ship** — §11: slice 2 "does not land before its disclosure copy does". The wording must be reconciled with decision 16 (ZDR, treat as local), which is proposed on `design/zdr-treat-as-local` and not merged; this branch writes the conservative version and notes where decision 16 would soften it. ## 7. Gates **39**, as §8.9 specifies, against an `httptest` stub provider: presence (span in the passage → renders, document bytes, document label, 🤖); a span in no passage → no box and not logged; a span that is only in a withheld passage → no box; the full citation tuple and the recorded request contents; and **the deterministic-first ordering: a validated kind never calls the provider at all**, asserted by counting requests at the stub, not by reading the page. *(An earlier version of this line listed "the model's text rendered instead of the sliced span → red" as a mutation to catch. It cannot be caught and does not matter: for an exact match the bytes are identical. What matters is the coordinate, which the tuple assertions see.)* Plus: AI off → the stub receives zero requests for every query (the decision-5 floor, asserted as absence-of-traffic with a presence half where AI on does call it); startup refusals for the config; the response cap is detectable; a timeout renders the page without the row. ## 8. Review cadence "Continuous review", per Paul. A review after each of: the spec (Astra, running), steps 1-3 (the client and config — the egress surface, so the highest-stakes review), steps 4-5, and the whole branch before merge. Each by a model that did not write it, mutations chosen by the reviewer.