# 🤖 Movement — design

**Status:** design, revised three times on 2026-09-01, and ready to implement
against. Approved in brainstorming by Paul on 2026-09-01; revised the same day
against three review passes dispatched to **Fable** — 22 findings, then 14
against the first revision ("not ready"; rulings 13, 14, 19 and 20 changed
mechanism), then one blocker and two corrections against the second, all
applied. Every ruling is dated and attributed, with the rejected alternative
beside it.
**Reviewing model, per §11:** dispatched to Fable, 2026-09-01, three times.
*(Recorded as what was dispatched, not what an agent self-reported — models
are unreliable about their own identity.)*
**Rulings 12–26 postdate Paul's approval** and carry only the review passes,
not his. Several reverse or materially change what he approved — most of all
ruling 12 (the instance key moved out of the database and into the
environment) and ruling 15 (confirmation moved from GET to POST). They need his
eyes before plan 2 puts anything in front of a visitor.
**Scope:** the Movement recruitment app: a public signup surface, a confirmed
email list, and an admin view over it. It does not define a mailing-list
sender; §13 names the trigger for that.

---

## 0. The one rule

> **An address joins the list only by clicking a link in its own inbox, and
> the public surface never reveals which addresses have.**

Both halves are load-bearing and both are tested from the first commit.

The first half is what makes the list worth having. Proof of work and a
honeypot raise the cost of submitting an address; neither says anything about
whether the address exists, receives mail, or belongs to the person who typed
it. Only a deliberate action from inside that inbox does. So a row is inert
until confirmed: never exported, never counted, never mailed beyond its own
confirmation.

The second half is what stops the signup form doubling as a membership
oracle. Every public response — status, headers, body — is identical whether
an address is unknown, pending, or long confirmed. An app whose subject is who
will associate themselves with a position on AI must not let a stranger
enumerate who did.

**What the rule does not claim.**

- The server reads every address in plaintext and holds the key that seals its
  challenges. This is not an encrypted-at-rest app and the README will not
  imply it is.
- **Timing is not covered.** Responses are identical in content; they are not
  constant-time. Rejecting paths do no writes and are measurably faster than
  the accepting one. Ruling 19 states the invariant that is actually tested,
  and this is the limit of the claim.

---

## 1. Settled decisions (don't relitigate casually)

| # | Ruling | Rejected | Who, when |
|---|---|---|---|
| 1 | **Three stance routes, each server-rendered with its own template, all posting to one `/signup`** | Single page with JS-revealed stance (copy is the product; it wants three reviewable files); session-backed wizard (mints sessions for anonymous visitors to buy nothing) | Paul, 2026-09-01 |
| 2 | **Proof of work is required; JavaScript is mandatory to sign up** | PoW when JS is present, falling back to honeypot + seal + rate limit (recommended by this session); no PoW at all | Paul, 2026-09-01 |
| 3 | **The PoW challenge is bound to the submitted email address** | An unbound nonce-only challenge — solved once, replayed across thousands of addresses | Proposed by this session, 2026-09-01 |
| 4 | **Double opt-in: a row is pending until confirmed from its own inbox** | Store immediately; store immediately and send a welcome mail | Paul, 2026-09-01 |
| 5 | **Admin is a magic link to an allowlist of addresses** | A shared password — one secret between people, rotated only by redeploy, and revoked for nobody | Paul, 2026-09-01 |
| 6 | ~~The instance key is generated on first boot and stored in the database~~ — **superseded by ruling 12** | — | Proposed by this session, 2026-09-01; superseded same day |
| 7 | **The app is reachable at `movement.bdj.oncarlos.com` and nowhere else for v1** | Attaching a custom domain now; attaching one before launch | Paul, 2026-09-01 |
| 8 | **The anti-replay token is HMAC-sealed, not encrypted** | Encrypting it. Nothing in it needs to be secret from its holder; it needs to be unforgeable, which is a signature's job | This session, 2026-09-01 |
| 9 | **A filled honeypot answers an ordinary success and stores nothing** | Answering an error, which teaches a crawler which field to avoid | This session, 2026-09-01 |
| 10 | **Unconfirmed rows are swept by a `carlos schedule` tick** | A `time.Ticker` (meaningless in a hibernating process); never sweeping | This session, 2026-09-01 |
| 11 | **All user-facing copy passes the copy-review gate before it enters a template** | Drafting final copy inside this spec, where it would ship unreviewed | This session, 2026-09-01 |
| 12 | **The instance key and origin arrive as `MOVEMENT_INSTANCE_KEY` and `MOVEMENT_ORIGIN`; the app refuses to boot without either** | Ruling 6's mint-into-the-database (its stated justification was false — `carlos secrets`/`env` do work through a logged-in console — and it would put the token-forging key into the Litestream replica); baking a key in via ldflags | This session, 2026-09-01, on corrected facts |
| 13 | **A nonce is recorded as *spent* on acceptance — `INSERT … ON CONFLICT DO NOTHING` into `spent_nonces`, where zero rows affected means replay. Nothing is written when a challenge is minted** | An unconsumed nonce (one seal replayed for two hours, every replay mailing the same victim again); **and** the first revision's mint-time `challenges` table, which made every stance-page GET a serialised write against the single SQLite writer — a crawler at 50 req/s is 4.3M rows a day and a denial of service on the one thing the app cannot do without | This session, 2026-09-01, revised same day after the second review |
| 14 | **`/signup` never writes `Confirmed`, `ConfirmedAt`, `Stance`, `Background`, `TokenHash` or `TokenExpiry` on a confirmed row. A confirmed address gets no write, no send, and the same page** | Blanket upsert (lets a stranger un-confirm any address or re-file a named person under a different stance); **and** "leave the row untouched" stated without naming columns, which left the confirmed path undefined and, on the likeliest reading, unbounded mail to precisely the addresses already on the list | This session, 2026-09-01, revised same day after the second review |
| 15 | **Confirmation is a POST from a page the GET renders** | Confirm-on-GET, which mail-scanning gateways trigger on arrival — confirming people who never clicked, and burning the link before the human reaches it | This session, 2026-09-01 |
| 16 | **The app refuses to boot on the `mail.Logged` fallback unless the origin is loopback** | `mail.FromEnv`'s silent default, which writes magic links, confirmation tokens and addresses into `carlos logs` — the exact thing §7 forbids | This session, 2026-09-01 |
| 17 | **The admin allowlist is re-checked on every admin request, and admin sessions last 8 hours** | `Authorize` at sign-in only, with the 30-day default TTL — a removed admin keeps access for a month | This session, 2026-09-01 |
| 18 | **The scheduled-tick route is mounted outside the CSRF-protected router and guarded by `carlos.Tick` alone** | Mounting it inside, where `csrf.Protect` refuses a POST carrying no browser headers — a permanent 403 the platform reads as "do not retry" | This session, 2026-09-01 |
| 19 | **Every `/signup` outcome renders the same bytes. The accepting path is one write transaction and at most one send; every rejecting path writes nothing** | The first revision's "every non-honeypot outcome is one write", which was false — it put the honeypot check *after* a write, and contradicted three other passages saying the honeypot writes nothing | This session, 2026-09-01, revised same day after the second review |
| 20 | **Outbound mail is budgeted: 3 per address per 24h, 200 per hour globally, both persisted, and auth's sign-in mail draws on the same global budget** | The in-memory limiter alone (resets on every hibernation, restart and deploy); **and** the first revision's unnumbered budgets, whose counters sat on columns that the pending overwrite and the sweep both reset — an attacker just waits | This session, 2026-09-01, revised same day after the second review |
| 23 | **`POST /signin` is app-owned: it checks `MOVEMENT_ADMINS` before delegating to `auth.Begin`, and answers the same redirect either way** | Mounting `auth.Begin` directly, which sends a magic link *before* `Authorize` ever runs — making the app a mailer for any address on the internet, from our verified identity. `sheets` hit this in production | This session, 2026-09-01 |
| 24 | **The send happens after the write transaction commits, in a goroutine bounded by a deadline** | A send inside the transaction. `mail.Send` discards its context and `smtp.SendMail` dials with no deadline, so a hung SES connection would hold the single writer and stall every other signup and the tick | This session, 2026-09-01 |
| 25 | **The `mail.Logged` fallback is detected by checking `CARLOS_SMTP_HOST`/`CARLOS_SMTP_FROM` before calling `FromEnv`, and `Mailer` is always passed explicitly** | Detecting the fallback by type — `loggedSender` is unexported, so it cannot be. `auth.New` also substitutes `Logged` for a nil `Mailer`, which is the same leak by another door | This session, 2026-09-01 |
| 26 | **Every user-facing string is drawn from an `internal/copy` table keyed by ID; templates contain no literal copy. Unreviewed entries are marked placeholders, and the app refuses to boot with any placeholder remaining when `MOVEMENT_ORIGIN` is the canonical host — canaries and loopback boot, showing a banner** | Placeholder text written into templates and cleaned up later (AGENTS.md forbids it); **and** "a release build refuses while placeholders remain", which was unbuildable — there is one build, `carlos ship` publishes it, and the canary serves it, so refusing at build time would make plan 1 impossible to review on a canary as the cadence requires | This session, 2026-09-01, extended after the third review |
| 21 | **`/admin` lists confirmed rows; pending appears only as a count** | Listing pending rows — an address nobody has proven owns it, joined to a stance, which is exactly the pair §7 protects | This session, 2026-09-01 |
| 22 | **Pinned: Go 1.25, rastrillo v0.23.0; the app is scaffolded with `rastrillo new movement`** | Hand-writing the app shape, which redoes the scaffold's work and skips its pin test, CI files and browser harness | This session, 2026-09-01 |

---

## 2. Shape

Five public routes, seven admin, two platform.

```
GET  /                     headline, the link out to carlosframework.com, three choices
GET  /<stance-a>           tailored message + signup form   (slugs settled at copy review)
GET  /<stance-b>           "
GET  /<stance-c>           "
POST /signup               one handler for all three; stance arrives as a hidden field
GET  /confirm?token=…      renders a page with one Confirm button — burns nothing
POST /confirm              burns the token, marks the row confirmed

GET  /signin               the form, and where auth redirects every outcome
POST /signin               magic link begin        (rastrillo/auth)
GET  /auth/callback        "
GET  /auth/verify          "
POST /signout              "
GET  /admin                confirmed rows, newest first, plus a pending count
GET  /admin/export.csv     confirmed rows only

POST /tick/sweep           outside the CSRF router; carlos.Tick guards it
GET  /healthz              from rastrillo.Serve — never hand-rolled
GET  /api/version          "
```

All seven admin routes answer **404** when `MOVEMENT_ADMINS` is empty —
including `GET`/`POST /signin`. Leaving sign-in live under an empty allowlist
would let anyone make the app send magic-link mail from its verified identity
to any address, and `/auth/verify` would answer 403 rather than the promised
404, which is itself a signal.

`cmd/movement/main.go` stays a thin dispatcher: `rastrillo.Resolve` →
`db.Open` → `movement.App` → blank `opts.DBPath` → `rastrillo.Serve`. The
blanking is not optional; `Serve` re-opens the database if `DBPath` survives,
and a second connection to a single-writer SQLite file is a deadlock waiting
for traffic.

---

## 3. Configuration, and refusing to boot

Three variables, read once at boot, delivered by `carlos env`/`carlos secrets`
(both of which work through a logged-in console — the earlier claim that they
were direct-bucket-only was wrong):

| Variable | Purpose | Missing |
|---|---|---|
| `MOVEMENT_ORIGIN` | absolute origin; base of every emailed link, and the argument to `csrf.Protect` and `auth.Config.Origin` | refuse to boot |
| `MOVEMENT_INSTANCE_KEY` | hex-encoded 32 bytes; seals auth's pending blob and the challenge | refuse to boot |
| `MOVEMENT_ADMINS` | comma-separated admin addresses | boot, all admin routes 404 |

A missing origin refuses at boot; a *wrong* one boots happily and mails links
to the wrong host, so it is worth getting right once. This matters directly
for canary review, which AGENTS.md requires: a canary runs at
`<canary>.movement.bdj.oncarlos.com`, and a hard-coded production origin
would have the canary mailing links into production.

`auth.New` refuses an empty `InstanceKey` on its own, but with a framework
message at the wiring call. Refusing at boot, naming the variable an operator
must set, is the difference between a five-minute fix and an afternoon.

**The mail fallback is refused too (rulings 16 and 25).** `mail.FromEnv`
returns `mail.Logged` when SMTP is unconfigured, and `Logged` writes recipient,
subject and body — the magic link, the confirmation token, the address — into
platform-held storage §7 says cannot be grepped clean.

The check is on the **environment, before calling `FromEnv`**: if
`CARLOS_SMTP_HOST` or `CARLOS_SMTP_FROM` is empty, refuse to boot unless the
origin is loopback, where it warns loudly instead. Detecting the fallback by
inspecting the returned value is not possible — `loggedSender` is unexported —
so an earlier draft's "the app detects that fallback itself" was a sentence
with no mechanism behind it. `auth.New` also substitutes `Logged` for a nil
`Mailer`, which is the same leak through another door, so `Mailer` is always
passed explicitly.

---

## 4. The signup path

1. `GET /<stance>` mints a challenge: a random nonce, an issued-at, a
   difficulty, and an HMAC over the three (§6). All four travel as hidden
   fields. **Nothing is written.** The seal already proves the server issued
   the nonce, so a row at mint time buys nothing and costs everything (ruling
   13).
2. The visitor types an address and a note. On submit the module solves the
   proof of work (§5) in a Worker and posts the counter.
3. The server checks, in this order, answering identically to every failure:
   **honeypot empty** → seal valid → age within bounds → field bounds (§8) →
   PoW satisfied. The honeypot is first because it is free, needs no seal, and
   must not sit behind anything that writes.
4. One transaction on the writer: `INSERT` the nonce into `spent_nonces`
   `ON CONFLICT DO NOTHING` — **zero rows affected means replay, and the
   transaction rolls back** — then the signup write, then the budget bump.
5. The signup write, per ruling 14:
   - **unknown** → insert pending, mint a token, store its SHA-256;
   - **pending** → overwrite `Stance`, `Background`, `TokenHash`,
     `TokenExpiry` through an explicit `.Select` allowlist that **excludes the
     budget columns and `CreatedAt`**, so an attacker cannot reset a budget by
     re-submitting;
   - **confirmed** → no write to the row and no send at all. The nonce is
     still spent, as it is for every accepted submission.
6. After the transaction commits (ruling 24), and subject to the budgets in
   §9, the confirmation mail is sent.
7. The response is the same "check your inbox" page in every case — including
   the confirmed case, the budget-suppressed case, and every rejection.

**Ruling 13 is what makes replay cost something, and its shape matters.** The
first revision persisted the nonce when the challenge was minted. That made
every stance-page GET a serialised write against a single-writer SQLite file —
and a crawler, a link scanner, an uptime monitor or a prefetcher would each
produce millions of rows a day and contend for the one connection every
signup needs. Recording nonces as *spent*, on acceptance, bounds the table by
completed proof-of-work solves: rows now cost the attacker rather than us.

Without it, one solved challenge is replayable for two hours and each replay
mails the same address again — a mail-bombing primitive aimed at a stranger's
inbox, sent from your verified identity, with SES reputation as the collateral.
An in-memory set would not survive hibernation, which is this process's normal
state.

**Ruling 14 is what protects the signal.** A blanket upsert lets anyone who
knows an address knock it off the list, or — worse for an app that exists to
sort people by stance — re-file a named person under a stance they never
chose. The rule now names the columns rather than saying "untouched", because
"untouched" left the confirmed path undefined: it neither said a mail was sent
nor that one wasn't, and the reading that sends one is unbounded mail to every
address already on the list. Confirmed means no write, no send, same page.
Changing one's stance after confirming is not built (§13).

`GET /confirm` renders a page with a single Confirm button; `POST /confirm`
hashes the token, marks the row, and clears the hash. Ruling 15 exists because
link-scanning gateways fetch every URL in an arriving mail: confirm-on-GET
would let Outlook Safe Links confirm a row no human ever clicked, and then
show the human "this link is no longer valid." An expired, unknown, or burned
token renders one page, identical for all three.

---

## 5. Proof of work

The client must find a counter such that

```
SHA-256(nonce ‖ ":" ‖ lowercased-email ‖ ":" ‖ counter)
```

has at least `difficulty` leading zero bits. The server re-runs that one hash.

**Binding the address into the preimage is ruling 3.** Unbound, a challenge is
solved once and reused against every address in a list. Bound, the cost is one
solve per address — the axis a bulk signup attack actually scales along.

**What proof of work does not do.** 2^18 SHA-256 is under a millisecond on a
commodity GPU; a determined attacker solves thousands of bound challenges a
second. PoW prices out casual and scripted abuse, and nothing more. The
defence against a serious bulk attack is the persisted mail budget in §9, not
this. §9 says so plainly so that nobody later mistakes the speed bump for the
wall.

**Difficulty starts at 18 bits and is a tunable constant**, carried in the
seal. §12 requires it be re-set against real mid-range hardware before launch,
recording **p95 and p99, not the mean** — solve time is geometric, and p99 is
about 4.6× the mean, so calibrating on the average ships a form that hangs for
one visitor in a hundred. A raised difficulty does not apply to seals already
issued; that two-hour tail is accepted.

**The solver runs in a Worker**, not on the main thread — 262k hashes in plain
JS freezes a phone for seconds. Same-origin workers are allowed by the default
`default-src 'self'` policy. It reports progress, and the submit button stays
disabled until it finishes.

**The hash is a small synchronous SHA-256 inside the module.** WebCrypto's
`subtle.digest` is async per call; a worker could manage it, but a hand-rolled
~50 lines with no promise round-trip per attempt is simpler and matches the
hand-written-`.mjs` convention rastrillo already uses.

**No-JS visitors cannot sign up (ruling 2).** This session recommended a
fallback; Paul chose otherwise with the trade-off stated. The mechanism must
be the workable one: **the form renders with its submit button `disabled`, and
the module removes `disabled` once loaded.** JavaScript cannot enable a
control inside `<noscript>`, so an earlier phrasing that put the live control
there was unbuildable. This ordering also fails safe — a module that throws
leaves the button disabled rather than live and inert.

**And the page does not say why.** An earlier draft of this section required
an explanation in `<noscript>`, on the grounds that a visitor who cannot join
should at least hear it from us. Paul removed it on 2026-09-02 after copy
review — proof of work is our problem, not theirs, and a paragraph about bots
and arithmetic is noise on a page whose whole job is asking someone a question
about themselves. The honest consequence: a no-JS visitor meets a disabled
button and no reason. It is a dead end rather than a deception, which is the
line that matters, and it is why the button must never render enabled.

---

## 6. Keys and seals

`MOVEMENT_INSTANCE_KEY` is 32 random bytes hex-encoded — `openssl rand -hex 32`.
`auth.Config.InstanceKey` is a `string` and accepts any non-empty value, which
it hashes with its own label; hex is this app's convention, not a framework
requirement. The challenge HMAC key is **derived from it with a distinct
label** rather than used raw, mirroring auth's own domain separation, so that
two subsystems sharing one secret cannot be made to verify each other's
tokens.

It does **not** derive confirmation tokens — those are 32 random bytes, stored
only as a SHA-256, following the `auth_links` pattern. An earlier draft said
both, and key-derived tokens die on any key rotation.

**The PoW preimage lowercases ASCII only.** JavaScript's `toLowerCase` and
Go's `strings.ToLower` disagree on some Unicode, and a disagreement here is a
silent `pow_short` that no visitor can diagnose and no log explains.

**The seal** is `HMAC-SHA256(key, nonce ‖ issuedAt ‖ difficulty)`, a hidden
field. Rejected on mismatch, on an age under **3 seconds**, or over **2
hours**. The floor is a claim that nobody reads three positions, picks one and
writes about themselves in less time. It is only meaningful because ruling 13
makes the nonce single-use — per seal, a floor is trivially waited out once.

**Confirmation tokens expire in 24 hours.** A re-submission of a pending row
issues a new token and a new expiry; the old hash is replaced and the old link
is dead.

---

## 7. Data

```go
type Signup struct {
    ID           int64
    Email        string `gorm:"uniqueIndex"`  // lowercased; the index is the dedupe
    Stance       string                       // internal key, never a visitor-facing label
    Background   string                       // capped at 2000 runes, C0 controls stripped
    Confirmed    bool
    ConfirmedAt  *time.Time
    TokenHash    []byte                       // SHA-256 of a random token; cleared on burn
    TokenExpiry  time.Time
    LastMailedAt *time.Time                   // the per-address budget in §9
    MailCount    int
    CreatedAt    time.Time
    UpdatedAt    time.Time
}

type SpentNonce struct {                      // ruling 13; written on acceptance only
    Nonce     string `gorm:"primaryKey"`
    ExpiresAt time.Time                       // issuedAt + 2h, from the sealed timestamp
}

type MailCounter struct {                     // the global budget, §9
    HourBucket string `gorm:"primaryKey"`      // UTC, "2006-01-02T15"
    Count      int
}
```

`Stance` stores a stable internal key, never the label a visitor read. Labels
are copy and copy changes; a column that changes with them is a migration per
wording tweak and a corrupted history for rows already stored.

There is no `User` model and no ownership column, because there is no owned
resource. Worth naming: rastrillo's most expensive trap is `sessions.UserID`
returning `(0, false)` under the `auth` plugin, where the session subject is a
verified address rather than a numeric id. This app never calls it. The admin
view is gated on the way in and reads the whole table — correct here, a severe
bug in an app with tenants.

Migrations are additive-only, generated with `rastrillo migration generate`;
`BootSchema = migrate.Merge(sessions.Schema, auth.Schema, Schema)`, in that
order, because auth's backfill reads the sessions table.

---

## 8. Input bounds

Unbounded free text reaches three dangerous places: an SMTP header, a CSV cell,
and the database.

- **Email** — rejected if it contains CR or LF (header injection, before it
  ever reaches `Send`), over 254 bytes, or fails `net/mail.ParseAddress`.
  Stored lowercased.
- **Background** — capped at 2000 runes, C0 control characters stripped.
- **The request** — wrapped in `http.MaxBytesReader`.
- **Stance** — must be one of the three known keys; anything else renders the
  same page as every other rejection.
- **The CSV** — every cell is escaped against formula injection. A value
  beginning `=`, `+`, `-`, `@`, tab or CR executes when the export is opened in
  Excel, and this export exists to be opened in Excel. Prefixed and quoted per
  OWASP, and tested.

---

## 9. Mail budgets

Two budgets, both **persisted**, because the in-memory limiter resets on every
hibernation, restart and deploy — and this process hibernates as its normal
state.

- **Per address: 3 mails per 24 hours**, counted in `LastMailedAt` and
  `MailCount` on the row. Past it, the send is suppressed and the same page
  renders.
- **Globally: 200 mails per hour**, in `MailCounter`. Past it, the same page
  renders and the app logs `mail_budget`. This exists because the real damage
  from a bulk attack is not junk rows, it is thousands of mails to strangers
  from a verified identity, followed by SES suspension.

**Two ways a budget silently resets, both closed.** The pending overwrite
excludes the budget columns from its `.Select` allowlist (§4 step 5), and the
sweep age is longer than the per-address window (§10) — otherwise an attacker
re-submits, or simply waits for the sweep, and the counter starts again.

**The counter is bumped in one statement** —
`INSERT … ON CONFLICT(hour_bucket) DO UPDATE SET count = count + 1` — inside
the signup transaction. A read-then-write across two statements is a lost
update waiting for concurrency, even behind a single writer. Fixed hour buckets
let a burst straddle a boundary and send up to twice the ceiling in one rolling
hour; at these numbers that is acceptable and it is written down rather than
discovered.

**Admin sign-in mail draws on the same global budget** (ruling 23). It is sent
by `rastrillo/auth` rather than by our own handler, so the `mail.Sender` handed
to `auth.New` is wrapped to pass through the counter. A budget that counts only
the mail we remember sending is not a budget. Three things the wrapper must
get right, because `auth.Begin` calls `Send` synchronously and with no deadline
of its own:

- commit the count **before** attempting the send;
- apply its own deadline, since nothing upstream will;
- **return `nil` when it suppresses for budget.** Returning an error makes
  `Begin` redirect to `?err=` instead of `?sent=1` and log the failure with the
  address attached — a different response, which is the thing ruling 23 exists
  to avoid.

One residual, accepted: signin's own per-address limiter can answer `?err=rate`,
and only an allowlisted address ever reaches it. That is a narrow oracle for
admin membership, not list membership, so it sits outside the one rule — but
"the same redirect either way" is true of our check, not of every path beneath
it.

**The budget counts attempts, not successes.** Three failed sends during SES's
post-`enable` propagation window will lock an honest address out for 24 hours,
with re-submission (§10) unavailable until it clears. Conservative on purpose,
and stated so it is a choice rather than a surprise.

The in-memory per-address limiter from `password/limit.go`'s shape stays as a
cheap filter, but §5 and this section both state that it is not the defence.
**It is checked after proof of work, not before.** Keyed by address and
consulted first, it would let a stranger trip a victim's budget for free and
lock them out of signing up; behind the solve, tripping someone else's costs
real work.

---

## 10. Errors and logging

Every rejected submission renders the same page with the same status. The
server logs a reason code — `seal_invalid`, `nonce_spent`, `too_fast`,
`too_old`, `pow_short`, `honeypot`, `bounds`, `mail_failed`, `mail_budget` —
**with no address attached**.

**A mail-send failure renders the same page.** The pending row survives and
re-submitting is the recovery path. This is not hypothetical: §11 notes that
freshly minted SES credentials fail for the first minute or two after
`carlos email enable`, and those sends land exactly here.

**The send is bounded by us, because the framework does not bound it**
(ruling 24). `mail.Sender.Send` takes a context and discards it, and
`smtp.SendMail` underneath dials with no deadline; `rastrillo.Serve` sets no
write timeout by default. So a hung SES connection would hold the handler
open indefinitely — and, if the send sat inside the write transaction, would
hold the single writer connection with it and stall every other signup and
the scheduled tick. The send therefore happens **after commit**, in a
goroutine with its own deadline. A sender that never returns must not be able
to block a second submission, and that is a test.

That deadline must be **well under the platform's idle window** — seconds
against minutes — because a goroutine outliving the response is exactly the
shape §11a rejects for the tick. It is safe here only because it is short. A
`SIGTERM` landing mid-send loses that one mail after its budget bump; §10's
re-submit path is the recovery, and it is not worth more machinery than that.

**One malformed-address exception.** A syntactically invalid address is
rejected visibly, with an error naming the field. That leaks nothing: it is a
property of the string the visitor just typed, not of any address's state on
the list. Everything else — an expired tab, a sub-3s submit, a spent nonce —
renders the same page, so an honest visitor with a typo is the one case that
gets told what went wrong rather than being quietly dropped.

The honeypot answers **success** (ruling 9) and writes nothing. A crawler that
gets an error learns which field to leave alone; one that gets a confirmation
page learns nothing.

**All app logging goes through one internal package** that accepts typed reason
codes and **no `error` values and no strings drawn from request data**. The
guard test forbids any other `slog` import in the app. "No call site takes both
an address and a stance" is not mechanically checkable over arbitrary Go —
wrappers, structs, a `%v` of a `Signup` — so the boundary is enforced by making
the sensitive pair unreachable from a log call rather than by pattern-matching
for it.

Excluding `error` is not fussiness: `rastrillo/mail` formats its failures as
`send to <address>`, so logging a send error verbatim would print the address
beside a request path that carries the stance — the sensitive pair, assembled
by accident. SMTP failures are classified to a reason code and the error
dropped. A test drives a failing sender with a known address and asserts it
never appears in captured output.

One accepted exception: `rastrillo/auth` logs through its own logger, and the
addresses it sees are admins signing in. Those are never paired with a stance,
so they stay.

Templates render into a buffer before anything is written, so a template error
becomes a clean 500 rather than a half-painted page.

---

## 11. Admin

`rastrillo/auth` is the magic-link plugin; its `Mailer` is a `mail.Sender`,
the same interface `carlos email enable` feeds through `CARLOS_SMTP_*` and
`mail.FromEnv("CARLOS", logger)`. No adapter, no third-party provider, no AWS
key in the app.

**`POST /signin` is ours, not the framework's (ruling 23).** `auth.Begin`
classifies the address and sends the mail *before* `admit` ever consults
`Authorize` — so mounting it directly makes this app a mailer that anyone can
point at any address, from our verified sending identity, at roughly twenty
messages per fifteen minutes. The IP half of the framework's own budget
collapses to the edge's address behind the platform, so it is not the brake it
looks like. `sheets` hit this in production and fixed it the same way: an
app-owned handler that checks `MOVEMENT_ADMINS` first and answers the identical
`?sent=1` redirect whether or not the address is on it.

**The allowlist is re-checked on every admin request (ruling 17).**
`auth.Config.Authorize` is consulted only when a magic link is redeemed;
`RequireSession` thereafter checks only that a session exists, and the default
TTL is 30 days. Without a per-request middleware, removing someone from
`MOVEMENT_ADMINS` does nothing for a month. Admin sessions are capped at 8
hours via `auth.Config.SessionTTL` — not `RequireFreshSession`, which is a
step-up mechanism for sensitive routes layered on a longer session, not a way
to shorten one. A surface listing named people's political positions does not
want a month-long cookie.

**How removal actually takes effect.** `MOVEMENT_ADMINS` is read once at boot.
A process's environment is fixed at exec — re-reading `os.Getenv` per request
sees nothing new, and an earlier draft of this section claimed otherwise. What
makes removal fast is the platform: `carlos env set` convergence re-renders and
**bounces** socket-exec instances within a few seconds, and hibernation
respawns the process on the next wake anyway. The per-request allowlist check
is what then invalidates an existing session, rather than leaving it live until
its 8 hours are up.

Gate 10 must therefore model a restart. A test that calls `t.Setenv` mid-run
would pass while proving nothing, which is worse than no test.

`/admin` lists **confirmed rows only**, newest first, with a count of pending
(ruling 21). A pending row is an address nobody has proven owns it joined to a
stance — the pair §7 exists to protect — and showing it to satisfy curiosity
about the funnel is the wrong trade. `/admin/export.csv` is confirmed rows,
escaped per §8, and that restriction is a test, not a convention.

Two platform notes, both of which have bitten people: freshly minted SMTP
credentials fail for the first minute or two while SES propagates, and a `535`
in that window is not a real failure; and DKIM is the only working alignment
rail, since SPF's envelope sender is a region subdomain that strict alignment
reads as a different domain. DKIM signing is never turned off.

---

## 11a. The sweep

One tick, `POST /tick/sweep`, mounted on the outer `http.ServeMux` beside
`mux.Handle("/", r)` so it sits outside `csrf.Protect` (ruling 18), guarded by
`carlos.Tick` alone. Declared with
`carlos schedule set -app movement -name sweep -every 1h -path /tick/sweep`.

It runs **synchronously inside the request** — a 202 and a goroutine risks the
instance hibernating mid-job — and does three things:

1. Deletes unconfirmed rows older than **30 days**. Longer than the 24-hour
   per-address mail budget on purpose (§9): a sweep shorter than the budget
   window is a way to reset the budget by waiting. The cost is that a pending
   row outlives its own 24-hour token by 29 days, purely to hold a counter —
   junk rows and Litestream replica size are the price of ruling 20. If that
   ever matters, moving the per-address budget to its own table keyed by an
   address hash lets this drop back to about 48 hours.
2. Deletes `spent_nonces` past `ExpiresAt`.
3. Calls `auth.Sweep(now)` for expired magic links and sessions, which nothing
   else in the app does.

All three are idempotent, so at-least-once delivery needs no dedupe and
`carlos.TickOccurrence` is not used. Confirmed rows are never touched, and
neither is a pending row with a live token.

A tick that 403s records `app refused` in the schedule's last status, but
nothing alerts on it and `next` still advances, so `carlos schedule ls` reads
much like success at a glance. The platform treats 4xx as "do not retry". Gate
11 stands in front of that.

---

## 12. Testing gates

`make test` and `.amadan/ci.d/*` are one definition, never two lists that
drift — the scaffold's own targets, plus `version-check`, plus a
**`test-browser`** step. Gates 3 and 7 need a real browser (`-tags browser`,
chromedp), and a gate that no CI definition runs is not a gate. If the runner
cannot get Chromium, they stop being called gates and become a documented
manual step before each deploy.

1. **No enumeration.** `POST /signup` against unknown, pending and confirmed
   addresses returns identical status, headers and body — and so do the
   budget-suppressed, limiter-tripped, mail-failed and invalid-stance paths.
   §0 names timing as outside the claim.
2. **Export excludes the unconfirmed**, and every cell is formula-escaped.
3. **PoW is enforced and bound.** A short solution is rejected; a solution
   valid for one address is rejected for another. This gate must cross from
   the browser solver to the Go verifier — the scaffold's chromedp harness
   under `-tags browser` — because a Go-only test proves the check, not the
   scheme.
4. **The nonce is single-use.** A byte-identical replay of a valid, accepted
   POST is rejected and **sends no second mail**. This is ruling 13's gate and
   the most important one in the list. Plus: a stance-page GET writes no row.
5. **A confirmed row is immutable from `/signup`.** Re-submission with a
   different stance changes nothing, does not un-confirm, and **sends no mail**.
5a. **Budgets survive.** Re-submitting a pending row does not reset its mail
   count, and neither does anything the sweep does.
5b. **A non-allowlisted address posted to `/signin` sends no mail** and gets
   the same redirect as one that does.
5c. **A hung sender does not block a second submission**, and the send happens
   after the transaction commits.
6. **Seal bounds.** Forged seal, under 3s, over 2h — rejected identically.
7. **Honeypot** returns the success page and writes no row. Plus a browser-rig
   assertion that Chrome's autofill leaves the field empty.
8. **Confirmation is single-use and POST-only.** A `GET /confirm` confirms
   nothing; a second POST on a burned token is indistinguishable from an
   unknown one.
9. **Admin fails closed.** With `MOVEMENT_ADMINS` empty, all seven admin
   routes answer 404 — iterated, not spot-checked.
10. **A removed admin loses access on the next request after the instance
    cycles**, not on session expiry. The test restarts the app with a changed
    allowlist and re-uses the old session cookie — `t.Setenv` mid-run would
    pass without proving anything, since the environment is fixed at exec.
11. **The tick reaches the sweep.** A POST with no browser headers and a valid
    bearer must not 403 — the CSRF trap in ruling 18, which fails silently and
    permanently.
12. **The sweep spares the confirmed** and anything with a live token.
13. **Boot refusals.** Missing `MOVEMENT_ORIGIN`, missing
    `MOVEMENT_INSTANCE_KEY`, and an empty `CARLOS_SMTP_HOST`/`CARLOS_SMTP_FROM`
    on a non-loopback origin each refuse to start.
14. **Logging containment.** No `slog` import outside the logging package, and
    a failing sender's address never reaches captured output.
14a. **Templates carry no literal user-facing text** — every string resolves
    through `internal/copy`. With a placeholder remaining, the app refuses to
    boot on the canonical origin and boots with a banner on a canary.
15. **Difficulty is calibrated**, p95 and p99 recorded on real hardware.

---

## 13. Deliberately not built yet

| Thing | Trigger |
|---|---|
| Changing stance after confirming | Someone asks; today a confirmed row is immutable (ruling 14) |
| Push into mailing-list software | A CARLOS-family mailing list app exists |
| Self-service unsubscribe and deletion | Before the first bulk send |
| Passkey second factor on admin | A third admin, or the first export leaving this machine |
| A custom domain | Paul asks; the platform host is ruling 7 for v1 |
| Funnel analytics beyond a pending count | Asked for twice |
| i18n | — |

A thing deferred without a trigger is a thing forgotten.

---

## 14. Sequencing

Two plans, split at the copy gate.

**Plan 1 is copy-independent only because of ruling 26.** Every user-facing
string resolves through an `internal/copy` table keyed by ID, so plan 1 fills
that table with marked placeholders and never writes copy into a template.
Routes are mounted by internal stance key until copy review settles the slugs.

**Where the placeholder check runs matters**, because there is only one build:
`make release` produces it, `carlos ship` publishes it, and the canary serves
that same binary. A build-time refusal would make plan 1 impossible to review
on a canary, which the shipping cadence requires. So the check is at **boot,
against the origin**: with placeholders remaining, the app refuses to start
when `MOVEMENT_ORIGIN` is the canonical host, and starts with a visible banner
on a canary or loopback origin. Unreviewed words can be reviewed; they cannot
reach production.

**Plan 1 — the engine.** Every gate in §12 except 15 green at its end.

1. `rastrillo new movement`, pins, `BuildVersion` stamping, the platform
   contract. `/healthz` and `/api/version` come from `rastrillo.Serve` and are
   never hand-rolled.
2. Config, the three boot refusals (§3), and the logging package with its
   containment test.
3. `internal/copy` and its placeholder discipline (ruling 26).
4. The seal, label-derived keys, and `spent_nonces` consumed on acceptance.
5. The PoW verifier in Go, the Worker solver, and the browser-crossing test.
6. Models, migrations, and the signup handler: every check, bound, and the one
   transaction.
7. Confirmation: GET renders, POST burns.
8. `carlos email enable`, the wrapped mailer, both budgets, send-after-commit.
9. Admin: app-owned `/signin`, allowlist, per-request re-check, list, escaped
   CSV export.
10. The sweep tick, mounted outside the CSRF router.

**Plan 2 — the surface.**

11. Copy review, then the real strings into `internal/copy`, the stance slugs,
    and the templates and static assets around them.
12. Deploy to a canary, calibrate difficulty at p95/p99, record it.
13. Promote, and verify `X-Carlos-Version` on the canonical host.

---

## Open

- **The third stance label.** "Love AI, never thought about its ethical
  issues" describes a real group accurately but will not be self-selected by
  it — it asks someone to volunteer that they have not thought about
  something. Those people will pick the middle option, polluting the one
  signal this app exists to isolate. The label needs to be something that
  group would own willingly, with the diagnosis living in Paul's reading of
  the bucket rather than in the words on the button. Settled at copy review.
- ~~**The headline against carlosframework.com.**~~ **Settled by Paul,
  2026-09-01, during `PRODUCT.md` capture:** the page is about both CARLOS and
  the ethics, and says so — the tension between them is the message, not a
  problem to resolve in favour of one. The remaining constraint is factual
  rather than strategic: carlosframework.com leads with cost, security,
  resilience, privacy and sovereignty, so nothing here may describe CARLOS in
  terms that page would contradict. `PRODUCT.md` §Positioning is now the
  authority; copy review writes to it rather than deciding it.
- **Ruling 21 costs Paul something.** Pending rows carry the free-text note,
  and hiding them means not reading what someone wrote until they confirm. If
  that is the wrong trade, ruling 21 is the row to revise — but it should be
  revised deliberately, not discovered as a missing feature.
- **Difficulty.** 18 bits is an estimate. Gate 15 closes it.