# 🤖 memoria

The Oficina suite's memory. One instance per team.

This file is binding. Where it disagrees with a general skill, this file
wins. Where it disagrees with the design spec, the spec wins and this file
is wrong — fix it in the same commit.

**The design:** `docs/superpowers/specs/2026-09-03-memoria-design.md`. Its
§1 is the settled-decisions table, §1.2–§1.11 record what ten independent
reviews changed. Don't relitigate a settled decision in a drive-by.

---

## The one rule

> **memoria never speaks a passage without asking whoever owns it whether
> this person may see it, right now.**

Sibling content: the sibling decides, per person, per query (§4.1).
Content with no other owner — Notion, Drive, mail, uploads — memoria owns
outright and says so (§4.2).

The second rule is Sheets': **the bucket never holds a readable passage.**
Chunks, titles and headings are sealed. So is the index, which is why it
lives in memory and nowhere else: FTS5 keeps term postings in plaintext.

---

## Two rules this app has already broken once each

**A guard you have never seen fail is a guard written to pass.** Three of
the first five gates here could not fail for the thing they named — one
grepped `main.go` for `os.Exit` near a variable and a neighbouring error
path supplied it; one checked for the string `"result"`, which is a
substring of `"0 results"`; one scanned a directory the index was not in.
Two more named a test that had been renamed away. **After writing any
gate, break the thing it guards, watch it go red, revert.** Do it per
path, not per file, and say in the test comment what you mutated and when.

**And do not choose your own mutations.** Gate 17 shipped with three, each
verified red; a reviewer then tried five ordinary chi idioms and every one
passed green, including a route that served a *declared* path outside the
session gate. Three green mutations picked by the author prove the author
is consistent, not that the gate works — they are the cases already
defended against while writing it. **Have someone who did not write the
gate pick the mutations.** §Review's argument, one level down. (§1.9.)

**Assert the state, not the copy — and if your own mutation cannot reach
a guard, the guard is the finding.** Both of these were learnt on the same
afternoon, from the two mutations out of twenty that survived while
building §4.1's policy layer (2026-09-06).

`Outcome.Record` filing the silent `NOT_VISIBLE` rulings alongside the
loud ones rendered an identical page — nothing prints them — while
quietly accumulating a per-app count of passages the reader may not see,
one switch arm or debug print from being the leak §4.1 forbids. The test
read `Lines()` and could not tell the two apart; the test that catches it
reads the struct.

And `scatter`'s short-slice fallback could not be reached by any fixture,
because the function above it is total. Changing that fallback from
`UNKNOWN` to `VISIBLE` left the suite green. A defence nothing can reach
is the same object as a guard written to pass, whatever the intent — so
either make it reachable (extract it, call it directly, as `scatter` now
is) or delete it. Leaving it in place with a comment is the third option
and it is the one that ships broken.

**A count that fails is not a count of zero.** `chunkCount` returned 0 on
error, and the page then told the reader "so this is a real absence rather
than an empty index" — the codebase's own worst failure shape, asserted on
the line written to prevent it. Anything that cannot be determined says
so; it never renders as a confident zero.

---

## Mechanical rules

**Data**
- **Never `scope.Owned` or `scope.OwnedBy`.** Both are single-column
  equality on `user_id`, and memoria's documents and chunks are
  team-shared. Applied to them a list returns only the creator's rows and
  fails as a plausible empty list, not as an error. (The scaffold's
  AGENTS.md said the opposite; it was wrong for this app.)
- A row that isn't yours **404s, never 403s**.
- Scope `tx`, never the outer handle, inside transactions.
- Never bind a request body onto a GORM model. Explicit `map[string]any`
  plus a `.Select` allowlist.
- Migrations are additive-only. New code over an old DB is always safe.
- **No document content, title, heading, snippet or query text in any log
  line, error string or metric label.** `carlos logs` is platform-held
  storage we cannot grep. Gate 4 enforces it; it was missing once, and
  what it found when written was that we were logging sign-in links.
- **A model provider's response body is content too.** An OpenAI-compatible
  4xx can echo the input that caused it, so the provider's error path is a
  content path. Never log one verbatim — status and a fixed string. Gate 31
  (spec §10); nothing calls a provider before slice 2, so this lands with
  the first call and not after it.
- **An ADDITION to derived state is made after the transaction commits,
  under `context.WithoutCancel`.** A client closing the tab must not
  leave the index disagreeing with the database.
- **A REMOVAL from derived state is made before it**, and `Store.Delete`
  carries the argument. The two orders fail in opposite directions:
  indexing early can leave the index holding passages the database does
  not have, which is a citation to text that is not there; un-indexing
  early can only leave a stored document unfindable until the next boot,
  which the app says out loud. Where they disagree, the order that cannot
  produce a live citation wins. Delete was written the other way and did
  produce one — found by a code review, 2026-09-04.
- **A hit is not a citation until the database says the passage is still
  there.** `Store.Search` drops any hit whose chunk row is gone. Ordering
  makes the divergence rare; only this makes it harmless, and it is what
  makes `ErrIndexLag`'s sentence true — without it, "stored but not
  findable" was said about a document whose previous revision was still
  answering searches.

**The suite contract**
- **Read the route out of the module, never out of memory.** `RouteS3` is
  `/suite/s3` and the item id is a **path segment** —
  `/suite/s3/{item_id}?revision=` — which the constant's own line says and
  the conformance harness fires. Written as `?item_id=` it 404s against
  every conforming sibling, and memoria reads a 404 as "not team-visible,
  or gone". `url.PathEscape`, not `QueryEscape`: a space is `%20` in a
  path and `+` in a query.
- **A cap on a response has to be detectable, not just applied.** S1 and
  S2 get that free — truncated JSON does not parse. An S3 body is
  plaintext, so read one byte past the cap and error on it, or a large
  document is silently indexed as its own first 2 MiB.
- A sibling document's coordinate is `(sealed item id, sibling revision)`.
  **`Document.Revision` is memoria's own counter and is not it**, and
  `ExternalID` is a one-way fingerprint that cannot be asked about.

**Sealing**
- `internal/memoria/seal` is the only encryption surface. One HKDF purpose
  per kind of thing sealed.
- **A content hash is not a coordinate.** `external_id` was a bare
  SHA-256 of the body, which let anyone with the bucket confirm the team
  held a document they already had. Identifiers derived from plaintext are
  keyed (`seal.Fingerprint`) or they are content.

**Frontend**
- No build step. Every affordance works scriptless.
- **Colours are tokens, never literals**, so light and dark resolve
  through `theme.css`. Gate: `TestNoColourLiteralsInAppCSS`.
- **`layout.html` must link `theme.css`.** `tokens.css` defines eleven
  tokens, none of them colours; without the theme every colour resolves to
  `initial` and whole shorthand declarations go invalid — rules vanish
  rather than the page going grey. **The v0.17.0-era scaffold omitted this
  link**, which is how the rule was learnt; `rastrillo new` on v0.23.0
  emits both, verified 2026-09-05. The rule stays because the failure is
  silent, not because the scaffold still causes it — and `rastrillo doctor`
  now checks the vendored files this app copies.
- The attribute grammar (`rst-btn="primary compact"`), never the class
  spelling. Utilities stay classes.
- **The design system has a vocabulary, and a word outside it renders as
  nothing.** `rst-callout="danger"` styles nothing: tokens.css carries the
  tone in `data-tone`, so a value on the attribute itself matches the base
  selector and no tone. Every flash in this app rendered untoned for
  months and **three tests pinned it there**, written from the same guess
  as the markup. Grep the stylesheet for the attribute before writing it.
  Gate: `TestEveryTemplateAttributeIsInTheDesignSystem`, which checks
  names *and* whether a value is one anything selects on.
- **Look at the page.** `tools/drive` serves the app with sign-in off so a
  browser can see it. It found three bugs in its first run that the whole
  Go suite passed over — a heading trail rendering as "› Revenue", a
  snippet repeating its own heading, and a submit button floating over the
  textarea. A template test proves markup exists, not that it renders.
  It then found two more in the sources page the day that page was built:
  a warning-toned callout containing the words "No refusal anomaly",
  because one flag carried two unrelated states; and a warning on every
  row of every freshly-woken instance, because "not polled yet" is the
  ordinary state of a wake. Neither changes a string a test looks for.
  **If you add a section to a page, add it to drive too** — the section
  that is not seeded is the section nobody sees.

**rastrillo**
- **rastrillo is `amadan.net/rastrillo/rastrillo`.** The old path,
  `github.com/carlosframework/rastrillo`, stops at v0.23.0: code importing
  it gets no fix, and its own checks cannot tell (Memoria zoomed iOS on
  every tap for a month that way). `TestNoPreMoveRastrillo` allows one
  import of it, native.go's second sessions handle for rastrillo/native's
  server, until that server moves; `native_exchange_test.go` proves the
  bridge. The app itself reads sessions through `a.sess`, the new
  package. The CLI is a go.mod `tool`: `go tool rastrillo …`, never a
  `rastrillo` from PATH.
- **After `go tool rastrillo doctor --fix`, run `go run
  ./scripts/writeestilo` and delete what it added.** At 29e4491 --fix
  overwrites rastrillo.js with the old shim (the old busy rule inside,
  which fights estilo's busy.js) and adds select.js, datetime.js and
  calendar.js, which no page links. `TestBusyFilesAreEstilos` and
  `TestNoUnusedRastrilloScriptsOnDisk` fail until both are done. **At
  fb806a2 --fix refuses outright** while go.mod still requires the old
  path (native.go's handle above): copy `ui/tokens.css` from the pinned
  module by hand, and `TestVendoredAssetsMatchTheLibrary` says when.
- **The CSP is rastrillo's default, which refuses inline style
  attributes** (fb806a2). Nothing Memoria serves standalone carries one;
  `TestNoPageCarriesAStyleAttribute` reads every page's markup and `make
  browser`'s `TestPagesRenderUnderTheProductionCSP` watches for
  violations in Chromium. Draw with attributes and memoria.css, never
  `style=`; `memoria.ServeOptions` says why there is no policy of our own.
  The one exception is the native kit's approval page, whose inline
  `<style>` is allowed by hash on `/native/authorize` alone;
  `TestNativeApprovalStyleIsTheHashedOne` re-hashes it, so a native bump
  that changes its CSS fails CI rather than shipping it unstyled.
- **A field styled with `font: inherit` under a selector heavier than a
  bare `input`** loses tokens.css's 16px-on-touch rule, and iOS zooms on
  tap. Restate `font-size: max(1rem, 1em)` for it under `(pointer:
  coarse)`, as memoria.css does for `[rst-stack]`'s fields.
  `TestNoZoomOnTap` (`make browser`) measures every field.

**Auth**
- `requireSession` **fails closed**. The test seam is `AppForTest`, named
  so it cannot be reached by accident, and two gates hold both ends. An
  earlier version failed open and justified it with a test that did not
  exist.
- The app refuses to start without a DEK, an instance key, owners, and
  either SMTP or an explicit `MEMORIA_ALLOW_LOGGED_MAIL=1` — because
  without SMTP rastrillo logs the magic link, and that link is a live
  credential in storage we cannot delete.

**Deploys**
- One binary, `CGO_ENABLED=0`, cgo-free SQLite.
- `carlos deploy`, never `carlos ship`. Flags before the binary path.
- `make release`, never a bare `go build`, or `/api/version` reports `dev`
  forever. Poll the process, not `X-Carlos-Version`.

---

## Review

Every spec and every branch is reviewed by a model that did not write it,
before it is approved or merged, and the reviewing model is recorded.
**Seventeen passes so far, on two strands that ran in parallel and are
counted together here because they are one project.** Spec drafts 1–3 by
GPT Sol and Fable; draft 4 by Fable 5.1; draft 5 by a reviewer **whose
attribution is disputed** — it named itself as the model that wrote the
draft, so that pass may not satisfy this rule at all. The slice-0 code by
Fable, the drag-and-drop branch by Fable 5.1, and five on the suite strand:
the §8.3 provider amendment, §8.4's shape, gate 17 with the live-key
verification, the doctrine adoption, and an adversarial mutation pass on
the sign-in dial gate (gate 33 since the merge renumbered it). Slice 1's
S1/S3 clients, §4.1's policy layer and §6.5's fan-out by Fable 5.1
(2026-09-06): twenty-two mutations, eleven survived. The roster, the poll
loop and the warm-up by Fable 5.1 (2026-09-07): twelve mutations, seven
survived, and five of its ten probes found live defects rather than gate
gaps. The breaker and the sources page by Fable 5.1 (2026-09-07):
nineteen, thirteen survived, three live defects.

**Every one returned REQUEST CHANGES.** The most useful have been the ones
aimed at tests rather than prose. The provider review found a rule broken
in the paragraph that stated it, twice, and a fourth gate that could not
have gone red (§1.7); the next found a product ruling argued from two
misread sections of this same spec (§1.8); the next mutation-tested a gate
its author had already mutation-tested and broke it five more ways (§1.9);
the adoption review found a rule invented while citing the section that
forbade it, plus eight contradictions in sections the commit never opened
(§1.10); and the gate-27 pass found **two live bypasses in shipped code**,
not mutations. The drag-and-drop review found two more the same way — by
re-running the mutations their author claimed to have run, rather than
taking the claim. The slice-1 review found two more, and the first is the
worst kind: `Content` fired S3 at `?item_id=`, and the module declares
the route as `/suite/s3/{item_id}?revision=` on the line that names the
constant. Against a conforming sibling every fetch would have 404'd, read
as "not team-visible, or gone" — the plausible empty list on the one call
that fills the corpus — and §8.1's S3 breaker would then have reported a
permissions anomaly for a routing bug. **The test pinned the wrong shape
too**, which is why it was green: an author's fixture is written from the
same wrong model as the code, so it cannot be the thing that catches it.
The next review found the same failure again in a different field: suite
hosts are `<team>.<app>`, this repo's own documented example had them
reversed, every fixture copied the example, and nothing checked — so the
roster accepted an address every call would then be refused for, before
dialling, forever, with a page blaming a healthy app.

**The pattern is one failure wearing several coats:** the writer checks
their work against their own model of it rather than against the thing.
Open the section you are citing. Open the constant you are calling. Run
the mutation you did not think of.

**A test written from the same model as the code is part of the code.**
It cannot catch a wrong assumption; it records one. The S3 route, gate
23's bounds, the sixth disposition born silent, the swapped host labels —
each had a test, each test agreed with the bug. What found them was
somebody who had read the module and the spec instead.

**Grepping for a string is not reading a selector — or a route, or a
constant.** The callout tone was got wrong three times: `rst-callout=
"danger"`, then `[rst-callout] data-tone=`, and only then the
`rst-tone` the stylesheet actually pairs with the attribute spelling.
The second attempt was the commit that described fixing the first, and
its tests passed because `data-tone="negative"` *is* in the stylesheet —
inside the class selector standing next to the one needed. A check that
greps will confirm any spelling that appears anywhere in the file. Read
the selector, the route declaration, the constant.

**The section you did not open is where the fix already was.** §8.1's
breaker clause was amended here on a real observation and a wrong
remedy; §13 already carried the correct one, three thousand lines down,
and it was not opened. The amendment was made in the course of fixing
another instance of exactly this. **Before amending a section, grep the
spec for what it governs** — the open-items list is where the last
person left the answer.

**A gate over source text proves a call is spelled, never that it is
reached.** The `cmd/` wiring gate walks the AST for a call expression, and
a reviewer defeated it twice in ordinary Go: `app.UseAuth(a)` inside a
closure nobody invoked, and the sibling wiring behind `if len(apps) > 1`
so a one-sibling instance ran unwired. Both read as present. The answer is
not a cleverer walk — that is a race against however the next person
writes it — but to **leave nothing in `main` worth getting wrong**: move
the logic into a function with tests and let the gate watch for one call
disappearing. `WireSiblings` is that shape.

**And an absence gate needs its presence half even when the absence is
the point.** "PolledAt was not set after a failed poll" passed against a
Poll that never set it at all; the test only ever failed on page one, so
neither half of the real behaviour was pinned. Assert the thing happens
before asserting when it must not.
When you retire something, grep for it by name — the sections you did not
open are where an adoption commit goes wrong, because a rewritten section
has been read twice and an untouched dependant never.

**Review a merge against both parents, never against the result.** The
merge review found more than the four passes before it combined, and it
found it by diffing the merge against each side rather than reading what
came out. Reading the output cannot tell you what is missing, and a merge
is the one change whose defects are all absences (§1.11).

**And a reviewer's self-reported model id is not evidence.** Record what
was dispatched and what came back, and record the disagreement when they
differ — twice now they have.

---

## Authorship

🤖 / 👨 markers, `Co-Authored-By` trailers. AI is a guest with a name tag:
opt-in, disclosed, and every path works with it switched off — which in
slice 0 means the whole product does.

## Work in a worktree, and catch main up first

Take a worktree for the work. Do not work in the shared checkout.

    git -C <repo> fetch origin
    git -C <repo> worktree add ../<repo>-<task> -b <branch> origin/main

Both halves matter, for different reasons.

**The worktree**, because several sessions share this machine and some
share this repository, and a checkout has one HEAD, one index and one
working tree between all of them. A branch switch under somebody else's
uncommitted work destroys it with nothing on screen to say so, and two
sessions editing the same paths disagree quietly instead of conflicting
loudly. A worktree gives the work its own HEAD and its own files, and
costs a directory.

**From `origin/main`, after a fetch** — not from whatever the checkout
happens to be sitting on. A branch cut from a stale main is a merge
conflict scheduled for later, against files somebody else has renamed in
the meantime. A branch cut from another task's branch is worse: it
carries that task's commits into yours, where they are reviewed as
though you wrote them, and the two can only be separated by hand.

Remove it when the work has landed — `git worktree remove` — so that
`git worktree list` keeps saying something true.

Written down because of 2026-09-17, in `meet`. The shared checkout was
sitting on one task's branch while holding a *different* task's feature
uncommitted on disk — some four hundred lines, a new migration among
them — put there by a session nobody else knew was working in that tree.
Two other sessions were meanwhile coordinating over the same checkout by
asking each other not to touch it, which is the arrangement a worktree
makes unnecessary. Nothing was lost. Nothing about the arrangement would
have said so if it had been, and by then the same feature existed twice,
once on each side of a rename, because the two sessions had branched
from different starting points.