Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: consolidate active planning and archive historical material

Browse Source 
The planning package had grown to where a new agent could not tell what was
authoritative. Phase 0 execution prompts sat beside the specification; four
completed milestone reports sat beside the current one; and upstream AI-DnD's
own `plan/` build log and `docs/` project site still described a hosted,
scripted, multi-user product with accounts — every screenshot in it showed a
Scripts tab and a Sign up button, none of which has existed since M2.

`planning/archive/` now holds the history and says so in its own README:
`phase0/` for the research that chose AI-DnD, `milestone-reports/` for M1 and
M2, `decisions/` for ADR 008, the Phase-0-before-build gate Phase 0 satisfied.
`planning/reports/` holds only the current milestone's report, because that is
the one M4 planning has to read; it moves to the archive when M4's replaces it.

Deleted rather than archived: the Phase 0B execution prompts and the
handoff/status/summary documents, the Phase 0A discovery and triage reports,
upstream's `plan/` and `docs/` trees, and `frontend/README.md`, which was Vite's
template boilerplate. All of it is in Git history, and the two recommendation
reports carry every conclusion the deleted research reached.

Archived documents are kept verbatim. Paths written inside them point at where
those files were when the document was written, which is the point: an evidence
record that has been quietly edited is no longer evidence.

Active documentation is corrected where it pointed at the removed trees or
described removed capability as present. `DEVELOPMENT.md`'s "things M1 did not
touch" list had gone stale at M2 and claimed QuickJS scripting was still tested;
its test count was 604 against an actual 638. `README.md` loses the upstream CI
badge, which reported upstream's pipeline rather than this fork's, and a
reference to `backend/app/worldstate/engine.py`, a file that does not exist.
`planning/README.md` is rewritten as the documentation index.

New: `planning/PROJECT-SOURCES.md` and `planning/project-sources.txt`, the
manifest of what belongs in the ChatGPT project's Sources.

Source comments referring to the deleted trees are reworded; no behaviour
changes. 638 backend tests pass, frontend lints and builds, and a reference scan
over all 48 tracked Markdown files reports no unresolved path in active
documentation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NCbwH7yLGKsj1rhXXzKSCu
This commit is contained in:
JesseMarkowitz
2026-09-03 14:33:07 -04:00
co-authored by Claude Opus 5
parent c8755c21c2
commit d27ee34901
84 changed files with 504 additions and 11271 deletions
Download Patch File Download Diff File Expand all files Collapse all files
planning/archive/milestone-reports/M1-BASELINE-REPORT.md
+466
View File
@@ -0,0 +1,466 @@
# M1 — Production Fork and Offline Baseline: evidence report
**Date:** 2026-09-01/02
**Milestone:** M1, `planning/BUILD-MILESTONES.md`
**Base:** AI-DnD `d72f7c1bda0f34fccd84afb7a25c34eb01c901de` (see `PROVENANCE.md`)
**Scope note:** M1 only. No M2 work was started; nothing was removed from the
inherited hosted/cloud/scripting surface.
This report records what was run and what was observed. Where a condition was
not reproduced exactly as the acceptance test specifies, it says so and says
what was reproduced instead. Nothing untested is called a PASS.
Hostnames and LAN addresses below are **placeholders** — `inference.lan`,
`192.168.0.0/24`. The real ones are in the workspace's untracked notes, not in
this repository. Everything else, including packet counts and digests, is
verbatim.
---
## 1. Test environment
| | |
| --- | --- |
| Host | Ubuntu 24.04.4 LTS, x86-64, 4 cores, 15 GB RAM, **no GPU** |
| Python | 3.12.3 |
| Node / npm | 22.23.1 / 10.9.8 |
| Docker | 29.7.2 |
| Ollama | 0.33.2 (`ollama/ollama@sha256:020e4134285e…`) |
| Narrator model | `qwen2.5:3b-instruct` (`qwen2.5:0.5b` in one earlier run) |
| Second machine | `inference.lan` (`192.168.0.50`), StartOS, Ollama 0.33.0 over HTTPS on 8443 |
| Embedding model | `nomic-embed-text:latest` |
| Application | this fork, working tree on `m1-production-baseline` |
| Browser | the maintainer's own desktop browser, against the native run (§6) |
The lack of a GPU matters and shows up twice below: a cold model load on four
CPU cores can exceed the application's hardcoded 120-second model timeout.
## 2. What was changed
Thirteen upstream files modified; twenty-two added, of which eleven are the
vendored font files and their licences. No upstream file was deleted.
| Change | Files |
| --- | --- |
| Fork lineage and licence provenance | merge commit `7f182a8`, `PROVENANCE.md` |
| Tokenizer no longer downloads | `backend/app/context/encoding.py`, `backend/app/context/vendor/cl100k_base.tiktoken`, `backend/app/context/builder.py` |
| Fonts self-hosted | `frontend/index.html`, `frontend/src/index.css`, `frontend/src/styles/fonts.css`, `frontend/public/fonts/*`, `frontend/tools/vendor_fonts.py`, `.gitattributes` |
| CSP narrowed to same-origin | `backend/app/main.py` |
| TLS verified against the machine's own CA store as well as certifi's | `backend/app/tlstrust.py`, `backend/app/providers/openai_compatible.py`, `backend/app/routers/settings.py`, `backend/requirements.txt` |
| `woff2` served with its real media type | `backend/app/main.py` |
| Loopback binding stated explicitly | `start.sh`, `start.ps1`, `docker-compose.yml`, `Dockerfile` |
| Reproducible environment | `backend/requirements.lock`, `DEVELOPMENT.md` |
| Regression tests | `backend/tests/test_offline_assets.py`, `backend/tests/test_tls_trust.py` |
| Research scratch ignored | `.gitignore` |
## 3. Regression suite
| Suite | Before M1 | After M1 |
| --- | --- | --- |
| `backend/tests` | 632 passed, 0 failed (184.7 s) | **648 passed, 0 failed** (212.1 s) |
| `frontend`: `npm run lint` | — | exit 0 (6 pre-existing `only-export-components` warnings) |
| `frontend`: `npm run build` | — | succeeds |
| `docker build` | — | succeeds |
The 632-test baseline was captured on the pinned upstream commit before any
change, and matches the Phase 0B figure. The sixteen new tests are
`test_offline_assets.py` (10) and `test_tls_trust.py` (6). **There are no known
failing tests and no documented exceptions.**
The two `dist`-reading tests in `test_offline_assets.py` skip if the SPA has
not been built; the run above had it built, so they executed.
### Proof the tokenizer guard is a real guard
With `TIKTOKEN_CACHE_DIR` pointed at an empty directory and Python's socket
functions replaced:
```text
UPSTREAM PATH raises: AssertionError socket opened
VENDORED PATH: 2 tokens, no socket opened
```
The vendored table's SHA-256 is
`223921b76ee99bde995b7ff738513eef100fb51d18c93597a113bcffe865b2a7`, identical
to the digest hardcoded in `tiktoken_ext/openai_public.py`, and the encoding it
produces was checked token-for-token against `tiktoken.get_encoding` over
ASCII, accented text, CJK, emoji, CRLF and special-token literals.
## 4. Run 1 — offline, same-host Ollama
**Setup.** An `--internal` Docker network (no NAT, no external DNS). Ollama
runs in one container; the production image runs in a second container that
**shares Ollama's network namespace**, so Ollama is genuinely on the
storyteller's own loopback and neither has any route out. Both were driven from
a client in the same namespace, over `127.0.0.1:8000`.
**Isolation confirmed from inside the application container, before any test:**
```text
blocked 1.1.1.1:443 OSError: Network is unreachable
blocked openaipublic.blob.core.windows.net:443 gaierror
blocked fonts.googleapis.com:443 gaierror
blocked fonts.gstatic.com:443 gaierror
blocked openrouter.ai:443 gaierror
blocked github.com:443 gaierror
```
**Listening sockets in that namespace:**
```text
127.0.0.1:8000 uvicorn (the storyteller)
[::]:11434 ollama
127.0.0.11:44683 Docker's embedded DNS
```
**Story play.** Campaign "Continuity Test (3b)" created and played for six
turns, twelve actions, all offline:
```text
turn 1: 'The old lighthouse looms dark against the stormy sky, its silence heavy as the wind…'
turn 2: "Gripping the lantern's heavy brass handle, you flick it on and off, each attempt a futile…"
turn 3: 'The lamp room is dim and musty, the thick air choking your breath…'
turn 4: 'You find the dated handwriting, the last entry noting the storm started three days ago…'
turn 5: 'The night outside is a tempest, waves crashing against the shore with a deafening roar…'
turn 6: 'The cabinet is cold and heavy, the lock stubbornly refusing to budge…'
```
**Browser asset graph, fetched over loopback with no route out:**
```text
GET / 200 text/html
/favicon.svg 200 9 522 bytes
/assets/index-*.js 200 933 695 bytes
/assets/index-*.css 200 59 902 bytes
/fonts/cinzel-normal-latin.woff2 200 font/woff2 25 904
/fonts/cinzel-normal-latin-ext.woff2 200 font/woff2 14 540
/fonts/crimson-pro-normal-latin.woff2 200 font/woff2 48 200
/fonts/crimson-pro-normal-latin-ext.woff2 200 font/woff2 37 988
/fonts/crimson-pro-italic-latin.woff2 200 font/woff2 51 432
/fonts/crimson-pro-italic-latin-ext.woff2 200 font/woff2 39 808
/fonts/inter-normal-latin.woff2 200 font/woff2 48 256
/fonts/inter-normal-latin-ext.woff2 200 font/woff2 85 068
```
Every URL `index.html` references is same-origin. The response carried:
```text
content-security-policy: default-src 'self'; script-src 'self';
style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:;
connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self';
frame-ancestors 'none'
x-content-type-options: nosniff referrer-policy: same-origin x-frame-options: DENY
```
**Packet capture** (tcpdump in the same namespace for the whole run, 6 074
packets):
```text
total packets: 6074
loopback (127.0.0.0/8): 6062
non-loopback unicast: 0
remainder (12): received mDNS / ICMPv6 router solicitations from the
bridge — inbound multicast, not sent by this namespace
TCP connections opened: 127.0.0.1:8000 (storyteller API)
127.0.0.1:11434 (Ollama)
127.0.0.1:11499 (the deliberately dead port in A05)
two ephemeral loopback ports (Ollama's model runner)
```
**One DNS observation, and it is not the storyteller.** Four queries appear,
all failing:
```text
127.0.0.11.53 > … ServFail q: A? ollama.com.
127.0.0.11.53 > … ServFail q: AAAA? ollama.com. (×2 each)
```
`ollama.com` is queried by **the Ollama server itself**, in the shared
namespace, not by the storyteller. It failed, nothing depended on it, and no
story data could have been in it. It is recorded here rather than dismissed:
on a deployment with a route to the Internet, the inference server has its own
outbound behaviour, and the storyteller's local-only guarantee does not extend
to it. Confirming and, if wanted, suppressing that is an Ollama configuration
question — worth settling before release, and out of M1's scope.
## 5. Run 2 — offline, Ollama on a second machine on the LAN
**Setup.** Ollama 0.33.0 on `inference.lan` (`192.168.0.50`), a **separate
physical machine** on the trusted LAN, serving HTTPS on port 8443 with a
certificate issued by `CN = StartOS Local Intermediate CA`. `qwen2.5:3b-instruct`
and `nomic-embed-text` were installed there for this run.
The storyteller runs in a container on this host with `NET_ADMIN`, its default
route **deleted** and replaced by a route to `192.168.0.0/24` only, its
resolver pointed at nothing, and `inference.lan` supplied as a static hosts
entry. So: the LAN is reachable, the Internet is not, and the endpoint is
configured explicitly rather than discovered. Uvicorn binds `127.0.0.1:8000`
inside that container.
```text
route table: 172.17.0.0/16 dev eth0 …
192.168.0.0/24 via 172.17.0.1 dev eth0 (no default route)
listeners: LISTEN 127.0.0.1:8000 (nothing on 172.17.0.3)
```
**Isolation, checked from inside before anything else:**
```text
outbound Internet
blocked 1.1.1.1:443 OSError: Network is unreachable
blocked 140.82.121.4:443 OSError: Network is unreachable
blocked 104.16.0.1:443 OSError: Network is unreachable
name resolution
no resolution github.com / openrouter.ai / fonts.gstatic.com /
openaipublic.blob.core.windows.net (gaierror)
the approved LAN host
inference.lan -> 192.168.0.50
TLS OK, peer CN = inference.lan
```
**Model discovery over the LAN endpoint:**
```json
{"ok": true, "models": ["qwen2.5:3b-instruct", "nomic-embed-text:latest"]}
```
**Story play.** Nine turns, then a tenth after a restart. That machine has
faster hardware than this one, and it shows:
```text
turn 1 (13.0s): "The lamp flickers faintly, a single coal barely keeping the structure's shadow at bay."
turn 2 ( 4.9s): "My lantern's light has failed. Checking the wick, I find it's burnt down to a stub."
turn 3 ( 4.4s): 'I turn the wick higher, attempting to coax more flame from the almost-embers.'
turn 4 ( 5.9s): 'The storm shutter blocks out everything but the dark ocean…'
turn 5 ( 6.8s): 'I insert the key and hear the satisfying click as the lock turns…'
turn 6 ( 8.1s): 'Inside the box, I find a small vial of oil and a note warning…'
turn 7 (10.6s) … turn 9 (14.8s)
```
**State extraction, summaries and embeddings** ran through the same endpoint:
the memory bank produced memories and embedded them with `nomic-embed-text` on
the remote host, so the narrator, the summarizer and the embedder all went
over the LAN, not just the narrator.
**Restart and resume.** The storyteller container was restarted while the
inference host was left alone:
```text
before restart: 18 actions, head 18, digest f24caf86a744ab36
after restart: 18 actions, head 18, digest f24caf86a744ab36
endpoint still https://inference.lan:8443/v1
embedding model still nomic-embed-text:latest, memories intact
next turn (6.4s): 'You make your way back to the lighthouse, lantern in hand…'
```
**Packet capture** across the whole run:
```text
all packets: 1633
loopback (127.0.0.0/8): 730
to/from inference.lan 192.168.0.50: 893
any other unicast: 0
TCP connections opened: 192.168.0.50:8443 (19)
127.0.0.1:8000 (17)
DNS queries: none — no name was looked up at all
```
Zero packets to anything but the storyteller's own loopback and the approved
inference host, and not a single DNS query, because the endpoint was configured
rather than resolved.
### 5.1 What had to be fixed to get here: TLS trust
The first attempt failed, and the failure was the application's:
```text
{"ok": false, "detail": "Connection failed: [SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: self-signed certificate in certificate chain"}
```
`httpx` verifies against the `certifi` bundle, which carries the public web's
CAs and nothing else. The host's certificate comes from a local StartOS CA that
the user had already installed at `/usr/local/share/ca-certificates/local-ca.crt`,
which is why `curl` and the browser accepted the same endpoint on the same
machine. Confirmed directly:
```text
certifi bundle (httpx default) FAIL SSLCertVerificationError
system trust store OK peer CN=inference.lan
```
This is not an edge case for this product. A trusted-LAN inference host is a
first-class v1 deployment (`planning/DECISIONS/002-ollama-only-v1.md`), and such
a host is unlikely to hold a publicly-issued certificate.
`backend/app/tlstrust.py` builds one verification context that **unions** the
platform CA store with certifi's bundle, and all four outbound HTTP clients use
it. Deliberately a union rather than a swap: using the platform store alone
would be a behaviour change, and an image with an empty or stale system store
would start failing on endpoints that used to work. A union can only add trust
the user has already granted at the operating-system level.
Verification itself is untouched — `verify_mode=CERT_REQUIRED`,
`check_hostname=True`, and no "insecure" escape hatch was added. Measured after
the change:
```text
OK inference.lan (local CA) CN=inference.lan
OK github.com (public CA) CN=github.com
OK pypi.org (public CA) CN=pypi.org
certifi-only context still rejects inference.lan (so the union is what changed)
```
`backend/tests/test_tls_trust.py` holds the line in both directions: it asserts
every certifi root survives in the union, that verification is not weakened,
and — by walking the AST of the two modules that make outbound requests — that
no fifth HTTP client is ever added without the shared context.
### 5.2 An earlier container-only run
Before a second machine was available, the same sequence was run with Ollama in
a separate container, network namespace and IP on an `--internal` network. It produced the
same result (all 20 model requests to the configured endpoint, zero other
unicast packets) and is superseded by the run above, which has the physical
separation A06 actually asks for.
## 6. Run 3 — native (non-Docker) run, same-host Ollama
The production build run directly from the venv, SPA served by FastAPI, Ollama
on host loopback:
```text
LISTEN 0 2048 127.0.0.1:8000 users:(("uvicorn",pid=341269,fd=14))
LISTEN 0 4096 127.0.0.1:11434
connect to 192.168.0.10:8000 (this host's LAN address) -> Connection refused
GET http://127.0.0.1:8000/ -> 200
```
A campaign was created and played on this instance too. **This run had Internet
available** — its purpose was the native listener check and a real end-to-end
run outside Docker, not the offline proof, which Runs 1 and 2 carry.
**The UI was opened in a real browser.** No browser automation was available in
this session, so this step was done by hand: the maintainer loaded
<http://127.0.0.1:8000>, saw the campaign list render, clicked into the
"Continuity Test (native run)" campaign, and saw the adventure and its
transcript. So the inherited SPA loads, runs, and talks to the API from a
browser — the last M1 claim that had been resting on inference rather than
observation.
Two limits on what that shows, stated so the evidence is not read wider than it
is. It was this native run, which **had Internet available**, so it is not
itself offline evidence; the offline proof that the page needs nothing remote
is the asset-graph fetch in §4, made with no route out. And the browser's
network panel was not inspected, so "the browser requested nothing external" is
carried by §4 and by the CSP — which names no remote origin and would block one
— rather than by a devtools capture.
## 7. Acceptance results
| ID | Result | Evidence |
| --- | --- | --- |
| **A01** Start application offline | **PASS** | Run 1: app started, campaign created, six turns generated, with `1.1.1.1` unreachable and no name resolving. The "open UI" step is covered by the asset-graph fetch there and by the browser render in §6. |
| **A02** Storyteller loopback default | **PASS** | Run 1 and Run 2 listeners are `127.0.0.1:8000` only; Run 3 refuses connections on the host's LAN address; `docker-compose.yml` publishes to `127.0.0.1`. |
| **A03** No cloud API key | **PASS** | `api_key` empty in every run; connection test, turns, summaries and embeddings all succeeded. |
| **A04** Campaign survives restart | **PASS** | Run 1: 12 actions before and after a container restart, identical transcript and head. Run 2: identical digest `dd59e2a564df4e62` across restart, then play resumed. |
| **A05** Failed model call does not corrupt story | **PASS** | Two induced failures (nonexistent model; dead endpoint port) plus one natural timeout. Accepted-prefix digest `2ca6ab528178e44e` unchanged through all of it; AI-action count stayed at 6; recovery by `continue` produced turn 7 with the prefix still unchanged. See §7.1. |
| **A06** Trusted-LAN Ollama inference | **PASS** | Run 2 — Ollama on `inference.lan`, a second physical machine on the trusted LAN, over verified HTTPS, with the storyteller's Internet route removed and its listener on `127.0.0.1`. Nine turns plus a post-restart turn, summaries and embeddings included. Capture: 893 packets to the approved host, 730 loopback, **zero** elsewhere, **zero** DNS queries. Required a TLS trust fix first — §5.1. |
| **H01** No unexpected outbound connections | **PASS for the application** | Zero non-loopback unicast packets in Run 1; in Run 2, zero packets outside loopback and the approved host and zero DNS queries of any kind. One caveat, not the storyteller's: Ollama itself queried `ollama.com` (§4). |
| **H02** No telemetry | **PASS** | No outbound destination in either capture; the inherited `analytics.py` writes to two local SQLite tables and opens no socket (Phase 0B static analysis, re-confirmed by the captures). |
| **H03** No cloud provider required | **PASS as stated** | Nothing cloud was reachable in Runs 1 and 2 and everything worked. The test's *preferred* final state — "cloud provider controls are absent, not merely unused" — is **not** met and is M2's scope by design. |
| **H11** No first-use runtime asset download | **PASS** | First turn on a fresh database succeeded with no route out; the whole browser asset graph resolved same-origin; the tokenizer is built from a vendored, digest-checked table. |
### 7.1 A05 in detail, including a real behaviour worth knowing
Baseline: 12 actions, 6 of them AI, digest `2ca6ab528178e44e`.
```text
invalid local model -> events ['player','error']
"Endpoint or model not found (HTTP 404) … model
'no-such-model-v9' not found"
13 actions, still 6 AI actions
endpoint down (:11499)-> events ['player','error']
"Could not connect to http://127.0.0.1:11499/v1 —
is the AI server running?"
14 actions, still 6 AI actions
accepted prefix through the pre-failure head: 12 actions, digest 2ca6ab528178e44e — unchanged
the two added rows: [28] story 'I strike a match.'
[29] story 'I strike a match again.'
recovery (continue) -> 40 SSE events, done; 15 actions, 7 AI actions
prefix digest still 2ca6ab528178e44e
```
**The player's own typed action is committed before the model is called**
(`run_player_turn` in `backend/app/routers/adventures/turns.py`), so a failed
turn leaves the player's text at the head with no reply. No AI output is ever
partially committed. That satisfies A05 as written — prior story intact, the
failed turn not committed as accepted, retry available — and it is deliberate:
it means a model failure never eats what the player typed. It is worth stating
explicitly because "the story is unchanged" is not literally true; "the
accepted story is unchanged" is.
## 8. Findings and open items
Nothing here blocks M1. Each is recorded because it was observed, not inferred.
1. **The model timeout is 120 s and hardcoded** (`httpx.Timeout(120, connect=10)`
in `backend/app/providers/openai_compatible.py`). On this GPU-less
four-core host, a *cold* load of `qwen2.5:3b-instruct` — or two models
contending after the memory bank pulls in `nomic-embed-text` — exceeded it
three times during these runs. Once warm, a full turn took 9 s. This is
presented as an environment/tuning finding, not an application defect; a
configurable timeout is a small change, and changing product behaviour was
outside M1's scope.
2. **Ollama queries `ollama.com` on its own account** (§4). Outside the
storyteller's code, inside the user's trust boundary. Worth settling before
release: the local-only claim covers what this application sends, and a user
reading a packet capture will see that query.
3. **The memory bank is off per adventure by default** (`auto_summarize` and
`memory_bank_enabled` are false on a new adventure) even when an embedding
model is configured globally. Discovered while trying to exercise
embeddings; it is inherited behaviour, not a regression.
4. **`docs/*.html` still links Google Fonts.** That is upstream's GitHub Pages
project site; it is not served by the application, not part of any build,
and not covered by the runtime rule. Left alone deliberately, and the
regression tests scope themselves to `frontend/` so they do not give a false
signal about it.
5. **A trusted-LAN endpoint over HTTPS needed a code change to work at all**
(§5.1), and it was found only by pointing the application at a real
StartOS-hosted Ollama. Static review would not have found it: every
candidate report and every local run up to that point used plain HTTP to
loopback, where certificate verification never happens. It is fixed and
tested, and recorded here because the class of bug — "works for curl,
fails for us" — is worth remembering when M2 formalises endpoint policy.
6. **The browser's own network panel was never inspected** (§6). The UI has
now been rendered by hand and works, and §4 shows the page's whole asset
graph resolving same-origin with no route out, so nothing rests on
inference. A devtools capture during an offline session would still be the
most direct form of that evidence, and costs a minute if anyone wants it.
## 9. Definition of done
| Requirement | Status |
| --- | --- |
| Starts with outbound Internet blocked after setup | met — Runs 1 and 2 |
| Opens the inherited browser UI locally | met — rendered in a browser, campaign opened and read (§6) |
| Generates and persists turns through same-host Ollama | met — Run 1 |
| Generates and persists turns through a configured remote Ollama | met — Run 2, on a second physical machine |
| Restarts and resumes the campaign | met — Runs 1 and 2 |
| Survives a failed model call without corrupting accepted state | met — §7.1 |
| No first-use tokenizer/font/runtime-asset request | met — §3, §4 |
| Storyteller UI/API loopback-bound by default | met — §4, §5, §6 |
| Regression suite passes, or failures documented | met — 648 passed, 0 failed |
Every line of the definition of done is met, and none of them rests on an
untested assumption. **No M2 work has been started.**
## 10. Artefacts not committed
The packet captures (`offline-samehost.pcap` 2.7 MB, `offline-lan.pcap` 0.8 MB,
`lan-remote-host.pcap` 0.4 MB) and the throwaway driver scripts live in this
session's scratchpad, not in the repository. Everything drawn from them is
quoted above; the procedure in `DEVELOPMENT.md` regenerates them.
planning/archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md
+995
View File
@@ -0,0 +1,995 @@
# M1 — Implementation Review Report
**Date:** 2026-09-02
**Milestone:** M1, *Establish Production Fork and Offline Baseline*
**Audience:** the architecture/design reviewer deciding whether to prepare M2
**Companion:** `planning/reports/M1-BASELINE-REPORT.md` holds the raw run logs
and packet-capture output this report summarises. Where the two differ in
detail, that one is the primary record.
Hostnames and LAN addresses are **placeholders** (`inference.lan`,
`192.168.0.0/24`). The real ones are in the workspace's untracked notes, never
in this repository. Packet counts, digests, timings and command output are
verbatim.
---
# A. Executive Result
**Overall M1 result: PASS.**
- **Is the application a playable production baseline?** Yes. A campaign can be
created, played, persisted, restarted and resumed from the inherited browser
UI, with outbound Internet blocked. This was exercised end to end, not
inferred: three separate runs, plus a by-hand browser check in which the
campaign list rendered and a campaign was opened and read.
- **Were both Ollama paths demonstrated?** Yes, both at runtime. Same-host
loopback in an air-gapped container; trusted-LAN against Ollama 0.33.0 on a
**second physical machine**, over TLS, with the storyteller's default route
deleted so the LAN was reachable and the Internet was not.
- **Proceed to M2?** Yes.
- **Blockers before M2?** **None.** Section M lists debt and inherited
behaviour, none of which blocks M2 and most of which M2 removes by design.
One qualification worth the reviewer's attention: M1 required a code change
that was **not in its planned scope** — outbound TLS verification (§G, §J).
Without it the trusted-LAN path did not work at all against a realistic host,
so it was in M1's critical path even though the milestone text never mentions
it.
---
# B. Repository / Provenance
| | |
| --- | --- |
| Branch | `m1-production-baseline` |
| HEAD | `c1a73b3d77e48491196e8887ee5abc2f818af05e` |
| HEAD signature | good (`%G? = G`) |
| Working tree | clean apart from one documentation correction, below |
### M1 commits
| Commit | Sig | Parents | Subject |
| --- | --- | --- | --- |
| `c1a73b3` | G | `7f182a8` | M1: make the first story turn work with no Internet |
| `7f182a8` | G | `717670a`, `d72f7c1` | Fork AI-DnD at d72f7c1 as the production base |
`7f182a8` is the fork import: a merge with **two parents** — the planning
package's own history (`717670a`) and upstream AI-DnD (`d72f7c1`). `c1a73b3`
is all of the M1 work.
### Upstream
| | |
| --- | --- |
| Project | AI-DnD, <https://github.com/parththakkar106/AI-DnD> |
| Pinned commit | `d72f7c1bda0f34fccd84afb7a25c34eb01c901de` |
| Subject | "Stop paying twice for a block a retry can still throw away" |
| Position | tip of `upstream/main` when the fork was taken, 1 Sep 2026 |
| Substituted? | **No.** The pinned commit was fetched and verified before use. |
### How provenance is preserved
Upstream history is *in* this repository rather than copied out of it, so the
claim is checkable rather than asserted:
```console
$ git cat-file -t d72f7c1bda0f34fccd84afb7a25c34eb01c901de
commit
$ git merge-base --is-ancestor d72f7c1bda0f34fccd84afb7a25c34eb01c901de HEAD && echo yes
yes
$ git rev-list --count d72f7c1bda0f34fccd84afb7a25c34eb01c901de
172
```
All 172 upstream commits are reachable, not a squashed snapshot. Upstream paths
are unchanged (`backend/`, `frontend/`, `docs/`, …), so a later upstream commit
can still be fetched and cherry-picked against matching files.
### Licence and provenance files
| File | State |
| --- | --- |
| `LICENSE` | **unmodified.** `git diff d72f7c1 HEAD -- LICENSE` is empty. MIT, © 2026 Parth Thakkar. |
| `PROVENANCE.md` | **new.** Upstream commit, licence terms, re-verification commands, both vendored assets with sources and digests, and the full list of what M1 changed. |
| `frontend/public/fonts/OFL-*.txt` | **new.** SIL OFL 1.1 text for each vendored family, shipped beside the fonts as the licence requires. |
### Final `git status`
Clean except for one file, which is a **documentation correction, not an
implementation change**:
```text
M planning/reports/M1-BASELINE-REPORT.md
```
Signing the fork-import commit re-hashed it from `46d34dc` to `7f182a8`, and
the baseline report's change table still cited the pre-signing hash. That one
line now cites `7f182a8`. It is uncommitted and needs a signed commit; §N has
the command. No other file differs from `c1a73b3`.
---
# C. What Changed
`c1a73b3` — **35 files changed, 102 102 insertions, 23 deletions.** The
insertion count is dominated by two vendored assets: the tokenizer table
(100 256 lines) and three OFL licence texts (279 lines). Excluding vendored
data and the baseline report, M1 is **1 101 inserted lines against 23 deleted**
— code, tests, generated CSS and documentation. Of those, roughly 390 are new
application code and tests, 352 are documentation, and the rest is the
generated font CSS, the lockfile and the vendoring script.
```text
.gitattributes | 4 +
.gitignore | 4 +
DEVELOPMENT.md | 246 +
Dockerfile | 5 +
PROVENANCE.md | 106 +
backend/app/context/builder.py | 9 +-
backend/app/context/encoding.py | 90 +
backend/app/context/vendor/cl100k_base.tiktoken | 100256 +++++++++++++++
backend/app/main.py | 29 +-
backend/app/providers/openai_compatible.py | 14 +-
backend/app/routers/settings.py | 4 +-
backend/app/tlstrust.py | 47 +
backend/requirements.lock | 57 +
backend/requirements.txt | 4 +
backend/tests/test_offline_assets.py | 160 +
backend/tests/test_tls_trust.py | 93 +
docker-compose.yml | 7 +-
frontend/index.html | 10 +-
frontend/public/fonts/OFL-*.txt | 279 +
frontend/public/fonts/*.woff2 | Bin 0 -> 351196 bytes
frontend/src/index.css | 1 +
frontend/src/styles/fonts.css | 90 +
frontend/tools/vendor_fonts.py | 137 +
planning/reports/M1-BASELINE-REPORT.md | 466 +
start.ps1 | 2 +-
start.sh | 5 +-
```
**Nothing inherited was deleted.** The 23 deletions are lines replaced in
place, not features removed. Removal is M2's job.
### Tokenizer
| File | Origin | What changed | Why M1 needed it |
| --- | --- | --- | --- |
| `backend/app/context/vendor/cl100k_base.tiktoken` | **new** (vendored data) | The `cl100k_base` BPE table, 1.7 MB, SHA-256 `223921b7…65b2a7`. | The download this replaces is what killed the first story turn offline. |
| `backend/app/context/encoding.py` | **new** | Builds a `tiktoken.Encoding` from the vendored table, verifying its SHA-256 against the digest `tiktoken` itself pins for the source URL. | Removes the network from the code path entirely, rather than relying on a warm cache or an env var. |
| `backend/app/context/builder.py` | **inherited, modified** | `_encoding()` delegates to the new module; its `functools.lru_cache` moves there (one cache instead of two). | Single call site; every turn goes through it. |
### Fonts and browser assets
| File | Origin | What changed | Why M1 needed it |
| --- | --- | --- | --- |
| `frontend/public/fonts/*.woff2` | **new** (vendored data) | Cinzel, Crimson Pro, Inter as variable fonts, Latin + Latin-Ext, 343 KiB total. | The SPA fetched these from Google on every page load. |
| `frontend/public/fonts/OFL-*.txt` | **new** | SIL OFL 1.1 licence text per family. | Required by the OFL for redistribution. |
| `frontend/src/styles/fonts.css` | **new, generated** | `@font-face` declarations pointing at `/fonts/…`. | Replaces the Google stylesheet. |
| `frontend/tools/vendor_fonts.py` | **new** | Regenerates both of the above from the Google Fonts API. | Keeps the vendored bytes reproducible instead of opaque. |
| `frontend/index.html` | **inherited, modified** | Two `preconnect` hints and the Google stylesheet `<link>` removed, replaced by a comment pointing at the script. | The actual remote-asset request. |
| `frontend/src/index.css` | **inherited, modified** | One `@import` for `fonts.css`, first in a load-bearing cascade order. | Faces must be declared before `tokens.css` names the families. |
| `.gitattributes` | **inherited, modified** | `*.woff2`/`*.woff` marked binary. | Prevents line-ending normalisation corrupting a font. |
### Security headers and listener
| File | Origin | What changed | Why M1 needed it |
| --- | --- | --- | --- |
| `backend/app/main.py` | **inherited, modified** | CSP: `fonts.googleapis.com` and `fonts.gstatic.com` dropped, `font-src 'self'` added, plus `object-src 'none'`, `base-uri 'none'`, `form-action 'self'`. Separately, `mimetypes.add_type("font/woff2", …)` so the fonts are served with their real type instead of `application/octet-stream`. | M1's "tighten the CSP so runtime assets are local". The policy now names no remote origin at all. |
| `start.sh`, `start.ps1` | **inherited, modified** | `--host 127.0.0.1` stated explicitly rather than inherited from uvicorn's default. | A02 is a requirement, not a default worth inheriting silently. |
| `docker-compose.yml` | **inherited, modified** | Publishes `127.0.0.1:8000:8000` instead of `8000:8000`. | `8000:8000` publishes on every host interface — the storyteller on the LAN, unauthenticated. |
| `Dockerfile` | **inherited, modified** | Comment only, explaining why the in-container listener is `0.0.0.0` and that the port must be published to loopback. | The 0.0.0.0 bind reads like a contradiction of A02 without it. |
### Outbound TLS *(unplanned; see §G and §J)*
| File | Origin | What changed | Why M1 needed it |
| --- | --- | --- | --- |
| `backend/app/tlstrust.py` | **new** | One cached `SSLContext` unioning the platform CA store with certifi's bundle. | Without it the trusted-LAN path fails against any host with a locally-issued certificate. |
| `backend/app/providers/openai_compatible.py` | **inherited, modified** | Three `httpx.AsyncClient(…)` calls take `verify=tlstrust.ssl_context()`. | Turns, completions and embeddings. |
| `backend/app/routers/settings.py` | **inherited, modified** | The connection-test client takes the same context. | Otherwise **Test connection** disagrees with what a turn would do. |
| `backend/requirements.txt` | **inherited, modified** | `certifi` declared. | It is now imported by name rather than arriving via httpx. |
### Environment, tests, documentation
| File | Origin | What changed | Why M1 needed it |
| --- | --- | --- | --- |
| `backend/requirements.lock` | **new** | The exact tested closure, 40 pins including transitive and dev dependencies. | M1's "reproducible dev/test environment". `requirements.txt` keeps the ranges. |
| `backend/tests/test_offline_assets.py` | **new** | 10 tests: vendored-table integrity, tokenizer opens no socket, golden token counts, CSP names no remote origin, no remote URL in markup/CSS, every declared font file exists, built SPA clean. | Both fixed bugs were invisible on a machine that had been online once. |
| `backend/tests/test_tls_trust.py` | **new** | 6 tests: verification not weakened, context cached, certifi roots survive the union, and an AST walk asserting every `httpx.AsyncClient` passes `verify=` — including that no third module starts making requests. | Guards the §G change in both directions. |
| `DEVELOPMENT.md` | **new** | Setup, run modes, same-host and trusted-LAN Ollama (including the private-CA case), test commands, the offline re-verification procedure, and what M1 deliberately left alone. | M1's environment/configuration documentation. |
| `.gitignore` | **inherited, modified** | `/phase0b/` ignored. | Phase 0B research scratch — virtualenvs, databases, downloaded models. |
---
# D. User-Visible M1 Capability
Everything below was done through the running application. The browser step was
confirmed by hand by the maintainer: the campaign list rendered at
`http://127.0.0.1:8000`, a campaign was clicked, and the adventure and its
transcript displayed.
### What a user can do now
1. **Start the application locally** — `./start.sh` for development, or a built
SPA served by FastAPI on `127.0.0.1:8000` for production. Both bind loopback.
2. **Configure a model** — Settings → endpoint URL, model, API mode, output and
context budgets. **Test connection** lists the endpoint's models.
3. **Create a campaign** and give it a persona.
4. **Generate narration** — Do / Say / Story / Continue, streamed over SSE.
5. **Persist and resume** — campaigns survive a clean restart with transcript
and head position intact; the adventures list reopens them.
6. **Use same-host Ollama** — `http://127.0.0.1:11434/v1`, the default endpoint,
with no Internet at any point.
7. **Use trusted-LAN Ollama** — an explicitly configured endpoint on another
machine, `http://…:11434/v1` or `https://…/v1` with a private CA, while the
storyteller UI/API stays on loopback.
8. **Recover from a failed model call** — a clear error, accepted history
untouched, and play continues.
The inherited surface also still works and is reachable from the nav: Home,
Adventures, Scenarios (with the stat-schema and NPC editors), Scripts (the
CodeMirror JavaScript editor), Settings, plus AI Chat and the Visitors
dashboard, which local installs always see.
### First-run step worth knowing
`Settings.model` defaults to `""`, so **a user must pick a model before the
first turn**; the endpoint already defaults to `http://localhost:11434/v1`.
Nothing tells them this on the way in. Cosmetic in M1, a real onboarding
question for M8.
### Inherited limitations still visible, deferred by design
| What the user sees | Milestone that addresses it |
| --- | --- |
| **Undo deletes turns and there is no Redo.** Verified in code, not assumed: `POST /adventures/{id}/undo` deletes the trailing AI action and its player action and prunes covering memories; no redo endpoint or control exists anywhere in the backend or SPA. | M3 |
| Account, hosted and cloud-provider surfaces exist in the tree; the endpoint field accepts any URL. | M2 |
| RPG world-state machinery — stats, flags, milestones, cast — with relative-delta proposals. | M5 |
| JavaScript campaign scripting, sandboxed in QuickJS. | M2 removes it |
| The Visitors analytics dashboard (local counters, two SQLite tables, no outbound request). | M2 |
| Memory bank and auto-summarisation are **off per adventure by default**, even when an embedding model is configured globally. | M6 |
| No named Save Points; no imported knowledge; UI is still AI-DnD's. | M4, M7, M8 |
---
# E. Acceptance-Test Results
Every row is runtime behaviour observed in a running system. Where a check was
source-level, the row says so and does not claim PASS on that basis.
| ID | Result | Procedure | Evidence | Caveat |
| --- | --- | --- | --- | --- |
| **A01** Start application offline | **PASS** | Run 1 (§F). `--internal` Docker network; app started; campaign created; six turns. | Isolation proven first — `1.1.1.1:443` → `Network is unreachable`, every name → `gaierror`. Six turns generated and persisted. Whole browser asset graph fetched over loopback, all 200. | The UI render was confirmed in a browser on the *native* run, which had Internet (§F). |
| **A02** Storyteller loopback default | **PASS** | Listener enumerated from `/proc/net/tcp` in each container; `ss -ltnp` on the native run; a TCP connect to this host's LAN address. | Runs 1, 2, 3 all show `LISTEN 127.0.0.1:8000` and nothing else. Native run: `connect 192.168.0.10:8000 → Connection refused`. `docker-compose.yml` publishes `127.0.0.1:8000:8000`. | In Docker the *in-container* listener is `0.0.0.0`; loopback-only exposure comes from the published port. A hand-run `docker run -p 8000:8000` would defeat it — §M. |
| **A03** No cloud API key | **PASS** | `api_key: ""` in every run; connection test, turns, summaries and embeddings all exercised. | `"api_key_set": false` in each run's settings dump; all operations succeeded. | — |
| **A04** Campaign survives restart | **PASS** | Run 1: 6 turns → `docker restart` → re-read. Run 2: same, plus a further turn. | Run 1: 12 actions, head 27, identical transcript before and after. Run 2: digest `f24caf86a744ab36` identical across restart; endpoint, embedding model and memories preserved; next turn produced in 6.4 s. | — |
| **A05** Failed model call does not corrupt story | **PASS** | Two induced failures (nonexistent model on a live endpoint; dead endpoint port) plus one natural timeout, then recovery. | Accepted-prefix digest `2ca6ab528178e44e` unchanged throughout; AI-action count stayed at 6 across both failures; recovery via `continue` produced turn 7 with the prefix still unchanged. | The player's own typed action **is** committed before the model call, so the row count grows. §H. |
| **A06** Trusted-LAN Ollama inference | **PASS** | Run 2 (§F). Ollama 0.33.0 on a second physical machine over HTTPS; storyteller's default route deleted, LAN-only route added, resolver pointed at nothing, host supplied as a static hosts entry. | Model discovery returned both models; nine turns (4–14 s); memories embedded on the remote host; restart and resume; capture shows 893 packets to the approved host, 730 loopback, **0** elsewhere, **0** DNS queries. | Required the §G TLS fix first — the first attempt failed with `CERTIFICATE_VERIFY_FAILED`. |
| **H01** No unexpected outbound connections | **PASS for the application** | `tcpdump -i any` inside each run's network namespace, for the whole run. | Run 1: 6 074 packets, 6 062 loopback, **0 non-loopback unicast**. Run 2: 1 633 packets, 730 loopback, 893 to the approved host, **0** other unicast, **0** DNS. | Ollama itself queried `ollama.com` in Run 1 — not the storyteller, and it failed. §K. |
| **H02** No telemetry | **PASS** | The same captures, plus reading `analytics.py`. | No outbound destination in either capture. `analytics.py` writes two local SQLite tables, opens no socket, records no IP or user agent, and HMACs the user id. | The dashboard still exists in the UI. M2 removes it. |
| **H03** No cloud provider required | **PASS as written** | Runs 1 and 2, with nothing cloud reachable. | Every operation succeeded with no cloud endpoint and no key. | The test's *preferred* final state — "controls are absent, not merely unused" — is **not** met. That is M2's scope by design, not an M1 gap. |
| **H11** No first-use runtime asset download | **PASS** | Run 1 on a **fresh database and fresh container** with no route out: first turn generated, then the full asset graph fetched. | First turn succeeded where upstream raised `ConnectionError`. `index.html` references only same-origin URLs; all 8 woff2 files served locally as `font/woff2`; CSP names no remote origin. Independently: with sockets blocked, upstream's code path raises `AssertionError: socket opened` and the vendored path returns a token count. | Browser devtools were not inspected; the claim rests on the server-side asset graph and the CSP. |
**Not tested, and not claimed:** any acceptance test outside M1's scope (B, C,
D, E, F, G, I, J, K series). No result above is inferred from source
inspection alone.
---
# F. Offline and Network Evidence
### Run 1 — same-host Ollama, air-gapped
| | |
| --- | --- |
| Topology | Ollama in one container; the production image in a second container **sharing Ollama's network namespace**, so Ollama is genuinely on the storyteller's loopback. Network is Docker `--internal`: no NAT, no external DNS. |
| Storyteller listener | `127.0.0.1:8000` |
| Ollama endpoint | `http://127.0.0.1:11434/v1` — same-host loopback |
| Outbound Internet actually blocked? | **Yes**, proven before testing: `1.1.1.1:443` → `OSError: Network is unreachable`; `openaipublic.blob.core.windows.net`, `fonts.googleapis.com`, `fonts.gstatic.com`, `openrouter.ai`, `github.com` → `gaierror` |
| Expected destinations observed | `127.0.0.1:8000` (API), `127.0.0.1:11434` (Ollama), `127.0.0.1:11499` (the deliberately dead port in A05), two ephemeral loopback ports (Ollama's model runner) |
| Unexpected attempts | **None from the application.** 6 062 of 6 074 packets loopback; **0 non-loopback unicast**; the remaining 12 are received mDNS/ICMPv6 multicast from the bridge. |
| DNS | Four queries, all `ollama.com`, all `ServFail` — issued by **the Ollama server**, which shares the namespace. Not the storyteller. §K. |
| First-turn asset download | **None.** Fresh database, fresh container; the first turn narrated instead of raising `ConnectionError`. No font, tokenizer or script request appears in the capture. |
### Run 2 — trusted-LAN Ollama, Internet blocked
| | |
| --- | --- |
| Topology | Ollama 0.33.0 on `inference.lan` (`192.168.0.50`), a **separate physical machine** on the trusted LAN, HTTPS, certificate from a local StartOS CA. Storyteller in a container on this host with `NET_ADMIN`: default route **deleted**, replaced by a route to `192.168.0.0/24` only; resolver pointed at nothing; the host supplied as a static hosts entry. |
| Storyteller listener | `127.0.0.1:8000` — nothing on the container's own LAN-facing address |
| Ollama endpoint | `https://inference.lan:8443/v1` — explicitly configured, non-loopback, TLS |
| Outbound Internet actually blocked? | **Yes.** By IP: `1.1.1.1`, `140.82.121.4`, `104.16.0.1` → `Network is unreachable`. By name: `github.com`, `openrouter.ai`, `fonts.gstatic.com`, `openaipublic.blob.core.windows.net` → `gaierror`. The LAN host resolved and TLS-verified: `peer CN = inference.lan`. |
| Expected destinations observed | `127.0.0.1:8000` (17 connections), `192.168.0.50:8443` (19 connections) |
| Unexpected attempts | **None.** 1 633 packets: 730 loopback, 893 to the approved host, **0 other unicast**. |
| DNS | **Zero queries of any kind** — the endpoint was configured, not resolved. |
| First-turn asset download | **None.** No name resolves at all, and the turn succeeded. |
Confirmed by the application's own request log: every model request went to
`…/v1/chat/completions` and `…/v1/embeddings` on the configured host, and no
other URL — narrator, summariser and embedder alike.
### Run 3 — native, non-Docker
Production build from the venv, SPA served by FastAPI, Ollama on host loopback.
`LISTEN 127.0.0.1:8000` and `127.0.0.1:11434`; the LAN address refuses
connections. A campaign was created and played, and this is the instance the
browser check used. **This run had Internet available** — its purpose was the
native listener check and a real out-of-Docker run, not the offline proof.
---
# G. tiktoken, Fonts, CSP, and Runtime Asset Fixes
### The tokenizer download
**Cause.** `backend/app/context/builder.py` called
`tiktoken.get_encoding("cl100k_base")`. That fetches the BPE table from
`openaipublic.blob.core.windows.net` on first use and caches it under the
system temp directory. `count_tokens` runs on **every** turn, for context
budgeting. On a developer machine that had been online once the cache was warm
and the download invisible; on an air-gapped install the first turn died with
`ConnectionError` instead of narrating.
**Fix.** The table is vendored at
`backend/app/context/vendor/cl100k_base.tiktoken`, and
`backend/app/context/encoding.py` constructs the `Encoding` directly from it —
the same merge table, pattern string and special tokens `tiktoken` uses.
Nothing in the tokenizer path can reach the network: not a cache that happens
to be warm, not an environment variable a deployment could forget.
Three things make this trustworthy rather than merely working:
- The file's SHA-256 is `223921b76ee99bde995b7ff738513eef100fb51d18c93597a113bcffe865b2a7`,
**identical to the digest `tiktoken_ext/openai_public.py` pins for that URL**,
and it is re-checked every time the encoding is built. A truncated checkout
or a substituted table fails loudly instead of silently changing every token
count the context budget derives from.
- A test asserts that digest still appears in `tiktoken`'s own source, so a
future upgrade pointing `cl100k_base` at a different table is caught.
- The encoding was compared token-for-token against `tiktoken.get_encoding`
across ASCII, accented text, CJK, emoji, CRLF and special-token literals.
**Proof the guard is real**, with `TIKTOKEN_CACHE_DIR` pointed at an empty
directory and Python's socket functions replaced:
```text
UPSTREAM PATH raises: AssertionError socket opened
VENDORED PATH: 2 tokens, no socket opened
```
### Remote fonts
**Behaviour.** `frontend/index.html` carried two `preconnect` hints and a
stylesheet `<link>` to `fonts.googleapis.com` for Cinzel, Crimson Pro and
Inter. Every page load fetched that stylesheet and then font files from
`fonts.gstatic.com` — an Internet dependency at runtime, and a third party
learning when the story is being read.
**Fix.** Self-hosted. `frontend/tools/vendor_fonts.py` downloads the same faces
once at development time into `frontend/public/fonts/` and generates
`frontend/src/styles/fonts.css`. Variable fonts and the Latin + Latin-Ext
subsets: 8 files, 343 KiB, covering every weight the design uses. OFL text
ships beside them. Greek, Cyrillic and Vietnamese subsets are deliberately not
vendored; text in them falls back to the system stack.
### CSP
```diff
- style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
- font-src https://fonts.gstatic.com;
+ style-src 'self' 'unsafe-inline';
+ font-src 'self';
+ object-src 'none'; base-uri 'none'; form-action 'self';
```
Final policy, as served:
```text
default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
font-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none';
base-uri 'none'; form-action 'self'; frame-ancestors 'none'
```
No remote origin remains. `'unsafe-inline'` stays on `style-src` because React
writes inline `style` attributes; it is deliberately absent from `script-src`.
Separately, `woff2` was being served as `application/octet-stream` because
Python's mimetypes table has no entry for it on a slim Debian image. Browsers
accept it anyway — a `@font-face src` carries its own `format()` hint — but
`main.py` now registers the correct type.
### Outbound TLS *(unplanned — see §J)*
**Cause.** `httpx` verifies against the `certifi` bundle, which carries the
public web's CAs and nothing else. A trusted-LAN Ollama frequently has no
public certificate. Against a real StartOS-hosted Ollama the connection test
returned:
```text
{"ok": false, "detail": "Connection failed: [SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: self-signed certificate in certificate chain"}
```
while `curl` and the browser on the same machine accepted the identical
endpoint, because the CA was installed in the **system** store. Measured:
```text
certifi bundle (httpx default) FAIL SSLCertVerificationError
system trust store OK peer CN=inference.lan
```
**Fix.** `backend/app/tlstrust.py` builds one cached context that **unions**
the platform CA store with certifi's bundle; all four outbound clients use it.
A union rather than a swap on purpose: the platform store alone would be a
behaviour *change*, and an image with an empty or stale system store would
start failing on endpoints that previously worked. A union can only add trust
the user already granted at the OS level.
Verification is untouched — `verify_mode=CERT_REQUIRED`, `check_hostname=True`,
and **no "insecure" escape hatch was added**. After the change:
```text
OK inference.lan (local CA) CN=inference.lan
OK github.com (public CA) CN=github.com
OK pypi.org (public CA) CN=pypi.org
certifi-only context still rejects inference.lan (so the union is what changed)
```
### Fresh-data offline first-turn test
**Passed.** Run 1 used a fresh Docker volume and a fresh container on a network
with no route out and no external DNS. The first turn of a newly created
campaign generated and persisted. No tokenizer, font or other runtime asset
request appears in the 6 074-packet capture.
---
# H. Persistence and Failure Recovery
### Clean restart
| Run | Before | After |
| --- | --- | --- |
| 1 (same-host) | 12 actions, head 27 | 12 actions, head 27, transcript identical line for line |
| 2 (trusted-LAN) | 18 actions, head 18, digest `f24caf86a744ab36` | 18 actions, head 18, digest `f24caf86a744ab36` |
Run 2 additionally confirmed the endpoint (`https://inference.lan:8443/v1`),
the embedding model and all memories survived, and produced a further turn in
6.4 s afterwards.
### Failed model request
Baseline: 12 actions, 6 of them AI, accepted digest `2ca6ab528178e44e`.
```text
invalid local model -> events ['player','error']
"Endpoint or model not found (HTTP 404) … model
'no-such-model-v9' not found"
13 actions, still 6 AI actions
endpoint down (:11499) -> events ['player','error']
"Could not connect to http://127.0.0.1:11499/v1 —
is the AI server running?"
14 actions, still 6 AI actions
accepted prefix through the pre-failure head:
12 actions, digest 2ca6ab528178e44e — unchanged
rows added by the failures:
[28] story 'I strike a match.'
[29] story 'I strike a match again.'
recovery (continue) -> 40 SSE events, done; 15 actions, 7 AI actions
prefix digest still 2ca6ab528178e44e
```
**No partially accepted turn, in either failure.** The AI-action count never
moved; the accepted prefix is bit-identical before, during and after.
**One behaviour the reviewer should know.** The player's own typed action is
committed *before* the model is called (`run_player_turn`), so a failed turn
leaves the player's text at the head with no reply, and the row count grows.
That satisfies A05 as written — prior story intact, failed turn not committed
as accepted, retry available — and it is deliberate: a model failure never eats
what the player typed. It is stated because "the story is unchanged" is not
literally true; "the accepted story is unchanged" is. Whether a dangling player
action is the right *user-facing* recovery state is an M3 question.
---
# I. Test Suite / Regression Baseline
| Check | Command | Result |
| --- | --- | --- |
| Backend, before M1 | `python -m pytest tests/ -q` on the pinned upstream commit | **632 passed, 0 failed**, 184.7 s |
| Backend, after M1 | `python -m pytest tests/ -q` | **648 passed, 0 failed, 0 skipped**, 212.1 s |
| Backend, **with no Internet** | same suite in a container on an `--internal` network | **648 passed, 0 failed**, 253.6 s |
| Frontend lint | `npm run lint` (oxlint) | **exit 0**, 6 warnings, 0 errors |
| Frontend build | `npm run build` (vite 8.1.3) | **succeeds**, 1.13 s |
| Image | `docker build .` | **succeeds** |
| Typecheck | — | none exists; the SPA is plain JSX with no TypeScript config. |
The 632-test baseline was captured on the pinned upstream commit *before* any
change and matches the Phase 0B figure independently.
### New M1 tests — 16
**`backend/tests/test_offline_assets.py` (10)** — vendored table present and
intact; the pinned digest still matches `tiktoken`'s own; token counting opens
no socket (sockets monkeypatched to raise); golden token counts; round-trip
over awkward characters; CSP names no remote origin; `index.html` fetches
nothing remote; stylesheets fetch nothing remote; every declared font file
exists; the built SPA is clean.
**`backend/tests/test_tls_trust.py` (6)** — verification not weakened; context
cached; every certifi root survives the union; and an **AST walk** over the two
modules that make outbound requests asserting each `httpx.AsyncClient` passes
`verify=`, plus that no third module has started making requests. That last one
catches the failure no runtime test would: a *new* client added later, which
would work perfectly until someone pointed it at a LAN endpoint.
### Remaining failures
**None.** No failing test, no skipped test, no documented exception, and **no
M1 regression**. Nothing was inherited red — the 632-test baseline was green on
the first attempt on the pinned commit.
Two `dist`-reading tests in `test_offline_assets.py` skip when
`frontend/dist/` has not been built. In the runs above it had been, so they
executed and are counted in the 648.
### Internet requirement
**No test requires Internet access** — confirmed by running the entire suite in
a container with no route out and no DNS. All 648 passed. Two pre-existing
warnings persist: a Starlette `httpx` deprecation notice, and a `SyntaxWarning`
for an invalid escape sequence in `tools/rewrite_memories.py`, both inherited
and both untouched by M1.
---
# J. Deviations From the M1 Plan
### Added scope
1. **Outbound TLS trust (`backend/app/tlstrust.py`) — the significant one.**
Not in M1's scope list. `BUILD-MILESTONES.md` places "explicit Ollama
endpoint policy" in M2. But M1's own scope requires *verifying* trusted-LAN
generation, and its Definition of Done requires turns through such a host.
Against a realistic LAN Ollama — TLS with a locally-issued certificate — that
was impossible without this change. The choice was to change it or to report
A06 as blocked. It is small (one module, four call sites), does not weaken
verification, and adds no configuration surface.
2. **`woff2` media type** (one line in `main.py`). Found while verifying the
self-hosted fonts. Cosmetic, but wrong is wrong.
3. **`backend/requirements.lock`.** M1 says "reproducible dev/test
environment"; the inherited `requirements.txt` uses `>=` throughout, so a
fresh checkout resolved to whatever was newest that day. The lock is the
concrete deliverable for that line.
4. **`base-uri`, `object-src`, `form-action` in the CSP.** M1 says "tighten the
CSP as needed". Removing the two Google hosts was the requirement; these
three cost nothing and were added while the policy was open.
5. **`/phase0b/` in `.gitignore`** — housekeeping, so `git status` is readable.
### Omitted scope
**None.** Every item in M1's scope list was implemented and demonstrated.
### Changed assumptions
1. **"Trusted-LAN" was assumed to mean plain HTTP.** Every planning reference
writes `http://…:11434/v1`, and Ollama's own default is cleartext. The real
LAN host serves **HTTPS only** (plain HTTP 307-redirects), because it is a
StartOS server. This is what surfaced the TLS defect. §L.
2. **A06 was initially reproduced without physical separation.** Before a
second machine was available, Run 2 used a separate container, namespace and
IP, and was going to be reported as PASS-with-qualification. A real second
machine then became available and the run was redone properly — which is
what exposed the TLS defect the container stand-in had hidden, since a
container endpoint was plain HTTP.
### Workarounds
1. **Blocking Internet without root.** No passwordless sudo here, so host
firewall rules were unavailable. Run 1 used a Docker `--internal` network.
Run 2 used `NET_ADMIN` inside the container to delete its default route and
add a LAN-only route — stronger than a firewall rule, since there is no
route to drop packets on.
2. **Packet capture without root.** `tcpdump` in a container joined to the
target namespace with `NET_RAW`.
3. **Browser verification by hand.** No browser automation in the session; the
maintainer confirmed the render directly. Devtools were not inspected. §K.
### Unexpected inherited behaviour
Four, all in §K: the model timeout, Ollama's own DNS lookup, the per-adventure
memory-bank defaults, and the pre-model commit of the player's action.
---
# K. Technical Findings / Surprises
### Affecting local-only security
1. **Ollama phones home.** In Run 1 the capture shows four DNS queries for
`ollama.com`, issued by the **Ollama server**, not the storyteller. They
failed and nothing depended on them. But it sits inside the user's trust
boundary and outside this application's code, and a user reading a packet
capture will see it. The local-only claim covers what *this* application
sends; that distinction should be stated in the release material rather than
discovered. Suppressing it is an Ollama configuration question, deliberately
not investigated here.
2. **Loopback in Docker depends on the publish flag, not the bind.** The
in-container listener is `0.0.0.0`, which is the only address a published
port can reach. `docker-compose.yml` publishes `127.0.0.1:8000:8000`, so the
shipped path is safe — but a hand-run `docker run -p 8000:8000` puts an
unauthenticated storyteller on the LAN. Comments now say so in both files.
Whether the app should *refuse* to serve on a non-loopback bind without an
explicit opt-in is an M2 policy question.
### Affecting trusted-LAN inference
3. **The TLS defect (§G) is the most important finding in M1.** Beyond the fix,
the lesson is methodological: it was undetectable by static review and
undetectable by every local run that used loopback HTTP, because
certificate verification never happens there. It surfaced within minutes of
pointing the application at a real host. **M2's endpoint-policy work should
be validated against a real LAN host, not a container stand-in.**
4. **A CA in a container is not the CA on the host.** Running against a
private-CA endpoint from Docker requires the CA inside the image or
bind-mounted. Documented in `DEVELOPMENT.md`; it will matter for any future
packaged distribution.
5. **The model timeout is 120 s and hardcoded** (`httpx.Timeout(120,
connect=10)`). On this GPU-less four-core host a *cold* model load, or two
models contending after the memory bank pulls in the embedder, exceeded it
three times. Once warm, a full turn took 6–9 s. Presented as a tuning
finding rather than a defect — but a first-run user on modest hardware will
likely meet it, and a configurable timeout is a small change.
### Affecting dependency packaging
6. **The vendored tokenizer table is 100 256 lines / 1.7 MB.** It dominates the
M1 diff. The alternative — `TIKTOKEN_CACHE_DIR` — was rejected as a
deployment-time promise that a packaging step could forget. The digest check
makes the vendored copy auditable.
7. **`certifi` is now a direct dependency**, declared in `requirements.txt`
rather than arriving via httpx.
8. **Node version.** The Dockerfile builds on Node 24 with a comment saying
npm 10 refuses the lockfile; `npm ci` in fact succeeded on Node 22.23.1 /
npm 10.9.8. No `.nvmrc` was added, because asserting a constraint that was
not tested would be worse than documenting what was.
### Affecting browser/runtime assets
9. **`docs/*.html` still links Google Fonts.** Upstream's GitHub Pages project
site — not served by the application, not part of any build, not covered by
the runtime rule. Deliberately untouched; the regression tests scope
themselves to `frontend/` so they do not give a false signal about it.
10. **Only devtools were left unchecked.** The page's whole asset graph was
fetched and verified same-origin with no route out, the source and built
bundle contain no remote reference, and the CSP would block one. A devtools
capture during an offline session is the one more direct form of this
evidence and costs about a minute.
### Affecting model-provider configuration
11. **`Settings.model` defaults to `""`.** A new install cannot generate a turn
until a model is chosen, and nothing prompts for it (§D).
12. **`netguard` is inert locally by design.** It rejects non-public addresses
only when `AIDND_MULTI_USER=1`, which local installs never set — which is
why a LAN endpoint is accepted at all. M2's endpoint policy replaces this,
and should keep that asymmetry deliberate rather than inherit it silently.
### Affecting repository structure and testability
13. **The fork merge preserves all 172 upstream commits**, so upstream fixes
can still be cherry-picked. Worth protecting: a future squash or filter
would throw it away.
14. **The AST-based test in `test_tls_trust.py`** guards a class of regression
no runtime test can reach — a new HTTP client added later. The same shape
may be worth reusing in M2 when the provider surface is cut down.
15. **The suite is fully offline-capable** (§I), so CI needs no network beyond
dependency install.
### Affecting future removal of hosted/cloud/scripting code
16. **M1 removed nothing**, so M2's removal surface is exactly what Phase 0B
described. Two M1 changes touch files M2 will edit heavily —
`providers/openai_compatible.py` and `routers/settings.py` — but both are
one-line `verify=` additions, so the TLS work should survive that
refactoring as long as the shared context follows any new client.
---
# L. Planning Documents That May Need Revision
Reported, not edited. No planning architecture document was changed by M1.
### 1. `planning/DECISIONS/002-ollama-only-v1.md` — Consequences
**Discrepancy.** The ADR treats a trusted-LAN Ollama as an addressing question
only. It does not anticipate that such a host may be reachable **only over
TLS**, with a certificate from a private CA. The real test host is exactly
that, and the application could not talk to it until M1 changed how outbound
TLS is verified.
**Recommended correction.** Add a consequence: the storyteller must verify
against the operating system's CA store as well as the bundled one, so a user
who has installed their own CA is honoured; and no option to skip verification
should be offered.
### 2. `planning/DECISIONS/004-local-only-production.md` — Consequences
**Discrepancy.** "Production packaging must contain all runtime assets required
for ordinary story use" is right but understates it. Both M1 findings were
*first-use* downloads invisible on any machine that had been online once, and
neither was findable by static analysis.
**Recommended correction.** Add that offline claims must be validated on a
network with no route out and a fresh cache, and that vendored runtime assets
should carry a verifiable digest.
### 3. `planning/V1-ACCEPTANCE-TESTS.md` — A06
**Discrepancy.** A06's preconditions do not say whether the LAN endpoint is
HTTP or HTTPS, and every example elsewhere shows `http://`. The HTTPS
private-CA case is the one that broke, and A06 as written could be passed
against a plain-HTTP host without ever exercising it.
**Recommended correction.** Add a step covering an HTTPS endpoint with a
locally-issued certificate, and a pass condition that verification is performed
rather than bypassed.
### 4. `planning/V1-ACCEPTANCE-TESTS.md` — A05
**Discrepancy.** "Failed turn is not partially committed as accepted" is
satisfied, but the observable state is a dangling player action at the head
with no reply (§H). A reader could reasonably expect the row count not to move.
**Recommended correction.** State that the player's own input is retained by
design, and that the invariant is about *accepted* history.
### 5. `planning/BUILD-MILESTONES.md` — M1 Scope
**Discrepancy.** M1's scope lists four hardening items but not outbound TLS
trust, which turned out to be on its critical path.
**Recommended correction.** Note retrospectively that M1 also covered it, so
M2's "explicit Ollama endpoint policy" is not planned as if it were still open.
### 6. `planning/V1-ACCEPTANCE-TESTS.md` §3 — Standard Test Environment
**Discrepancy.** The environment list assumes one local Ollama and does not
mention hardware class. Model cold-load time on a GPU-less host exceeded the
application's fixed 120 s timeout three times during M1.
**Recommended correction.** Record hardware class alongside model name, and
note that a cold load may exceed the client timeout on modest hardware.
---
# M. Risks / Technical Debt Carried Into M2
### Blockers before M2
**None.**
### Acceptable technical debt
| Item | Risk | Suggested milestone |
| --- | --- | --- |
| **120 s hardcoded model timeout.** Cold loads on modest hardware exceed it; the user sees "The AI endpoint timed out." | Medium — a first-run user on a slow box may conclude the app is broken. | M2, with the endpoint policy |
| **Ollama's own `ollama.com` lookup.** Outside this codebase, inside the user's trust boundary. | Low technically, medium for the local-only claim. | Decide before release; document either way |
| **Docker loopback depends on the publish flag.** A hand-run `-p 8000:8000` exposes an unauthenticated API to the LAN. | Medium. | M2 |
| **`Settings.model` defaults to `""`.** No first turn until a model is chosen; nothing prompts. | Low. | M8 |
| **Memory bank off per adventure by default** even with an embedding model configured. Cost me a wasted verification cycle. | Low, but it makes M6's features look absent. | M6 |
| **Vendored tokenizer table, 1.7 MB.** Needs re-vendoring if the encoding ever changes. | Low — digest-checked, and a test catches a `tiktoken` change. | — |
| **No frontend typecheck.** Plain JSX, lint only. | Low. | M8 |
| **`docs/*.html` links Google Fonts.** Not served by the app. | Very low. | M2 or M8 |
| **The `dist` tests skip when the SPA is unbuilt.** A green suite alone is not full evidence. | Low — documented in `DEVELOPMENT.md`. | — |
### Inherited AI-DnD behaviour intentionally left in place
All of this was outside M1's scope and is **explicitly non-scope** in the M1
brief. It is listed so nobody reports it as an M1 gap:
- multi-user/account/guest/auth flows, demo-key behaviour, hosted rate limits;
- the self-hosted analytics tables and Visitors dashboard (local-only, no
outbound request);
- Render and Neon deployment paths; Postgres/`psycopg` support;
- the OpenRouter default-endpoint constant and attribution-host check;
- arbitrary remote model-provider configuration in the Settings UI;
- QuickJS campaign scripting and the AI-Dungeon-compatible script surface;
- **destructive Undo with no Redo** — verified in code, and the single largest
inherited correctness gap. M3;
- RPG world-state machinery and relative-delta proposals. M5;
- Story Cards as the only imported-knowledge mechanism. M7;
- AI-DnD's UI organisation and vocabulary. M8.
---
# N. Reproduction / Verification Commands
### Environment
```bash
git clone <this repo> && cd interactive-story
git checkout m1-production-baseline
python3 -m venv backend/.venv
backend/.venv/bin/pip install -r backend/requirements.lock
(cd frontend && npm ci && npm run build)
```
### Provenance
```bash
git remote add upstream https://github.com/parththakkar106/AI-DnD.git
git fetch --no-tags upstream
git cat-file -t d72f7c1bda0f34fccd84afb7a25c34eb01c901de # -> commit
git merge-base --is-ancestor d72f7c1bda0f34fccd84afb7a25c34eb01c901de HEAD
git diff --stat d72f7c1bda0f34fccd84afb7a25c34eb01c901de HEAD -- LICENSE # -> empty
```
### Tests
```bash
(cd backend && .venv/bin/python -m pytest tests/ -q) # 648 passed
(cd frontend && npm run lint && npm run build)
docker build -t storyteller .
```
Prove the suite needs no network:
```bash
docker network create --internal offline
docker build -t storyteller . && \
printf 'FROM storyteller\nRUN pip install --no-cache-dir pytest\n' | docker build -q -t storyteller-test -
docker run --rm --network offline -v "$PWD":/src:ro -w /src/backend \
-e AIDND_DB_PATH=/tmp/test.db storyteller-test python -m pytest tests/ -q
```
### Run 1 — offline, same-host Ollama
```bash
docker network create --internal offline
docker run -d --name ollama --network offline -v ollama-models:/root/.ollama ollama/ollama
docker exec ollama ollama pull qwen2.5:3b-instruct
# The app shares Ollama's network namespace, so Ollama is on its loopback and
# neither has a route out.
docker run -d --name app --network container:ollama -v story-data:/data \
storyteller uvicorn app.main:app --host 127.0.0.1 --port 8000
# Isolation, before testing anything:
docker exec app python -c "import socket; socket.create_connection(('1.1.1.1',443),timeout=4)"
# -> OSError: Network is unreachable
# Listener:
docker exec app sh -c "grep -c . /proc/net/tcp" # or the /proc parser in the baseline report
```
Configure and play:
```bash
docker exec app python - <<'PY'
import json, urllib.request
B = "http://127.0.0.1:8000/api"
def call(m, p, b=None):
d = json.dumps(b).encode() if b is not None else None
r = urllib.request.Request(B+p, data=d, method=m, headers={"Content-Type":"application/json"})
with urllib.request.urlopen(r, timeout=900) as f: t = f.read().decode()
return json.loads(t) if t.strip() else None
call("PUT", "/settings", {"endpoint_url":"http://127.0.0.1:11434/v1",
"model":"qwen2.5:3b-instruct","api_mode":"chat","api_key":"",
"max_output_tokens":120,"context_token_budget":2048})
print(call("POST", "/settings/test"))
adv = call("POST", "/adventures", {"title":"Continuity Test","persona_name":"Vale"})["id"]
d = json.dumps({"type":"story","text":"I am Vale, a lighthouse keeper."}).encode()
r = urllib.request.Request(f"{B}/adventures/{adv}/actions", data=d, method="POST",
headers={"Content-Type":"application/json","Accept":"text/event-stream"})
with urllib.request.urlopen(r, timeout=900) as f:
for line in f:
line = line.decode().strip()
if line.startswith("data: ") and '"done"' in line:
print(json.loads(line[6:])["action"]["text"][:120])
PY
```
Restart and resume: `docker restart app`, then re-read
`GET /api/adventures/{id}/actions?limit=500` and compare.
### Run 2 — trusted-LAN Ollama, Internet blocked
On the **inference machine**, if it serves plain HTTP:
```bash
OLLAMA_HOST=0.0.0.0:11434 ollama serve
ollama pull qwen2.5:3b-instruct && ollama pull nomic-embed-text
```
If it serves HTTPS with a private CA, install that CA where the storyteller
runs — inside the image for a container:
```dockerfile
FROM storyteller
COPY local-ca.crt /usr/local/share/ca-certificates/
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates iproute2 \
&& update-ca-certificates && rm -rf /var/lib/apt/lists/*
```
On the **storyteller machine** — LAN reachable, Internet not:
```bash
docker run -d --name app-lan --cap-add=NET_ADMIN \
--add-host inference.lan:192.168.0.50 --dns 127.0.0.1 \
-v story-data-lan:/data storyteller-lan \
uvicorn app.main:app --host 127.0.0.1 --port 8000
docker exec app-lan ip route del default
docker exec app-lan ip route add 192.168.0.0/24 via 172.17.0.1 dev eth0
```
Then set `endpoint_url` to `https://inference.lan:8443/v1` (or
`http://192.168.0.50:11434/v1`) and play as above. `POST /api/settings/test`
should list the remote host's models.
### Packet capture (no host root needed)
```bash
printf 'FROM alpine\nRUN apk add --no-cache tcpdump\n' | docker build -q -t tcpdump-img -
docker run -d --name cap --network container:app --cap-add=NET_RAW \
-v "$PWD/cap":/cap tcpdump-img tcpdump -i any -n -w /cap/run.pcap
# … run the campaign …
docker stop cap
docker run --rm -v "$PWD/cap":/cap tcpdump-img sh -c '
tcpdump -r /cap/run.pcap -nn "not net 127.0.0.0/8 and not host 192.168.0.50 and not multicast" | wc -l
tcpdump -r /cap/run.pcap -nn -vv "udp port 53" | grep -oE "q: [A-Z]+\? [^ ]+" | sort | uniq -c'
```
### The one uncommitted file
```bash
git add planning/reports/M1-BASELINE-REPORT.md planning/reports/M1-IMPLEMENTATION-REPORT.md
git commit -S -m "Add the M1 implementation review report"
```
---
# O. Recommendation
## READY FOR M2 WITH NOTED NON-BLOCKING ISSUES
M1 delivered its whole scope and its Definition of Done is met on runtime
evidence rather than inspection: the application starts and plays with no route
to the Internet, through same-host Ollama and through Ollama on a second
physical machine; campaigns persist across restart; a failed model call leaves
accepted history bit-identical; no runtime asset is fetched; the listener is
loopback in every run; and the suite is green at 648 tests, including with no
network at all. Nothing was removed from the inherited codebase, so M2 begins
against exactly the surface Phase 0B described.
The issues in §M are non-blocking and mostly land naturally inside milestones
that already exist. Two deserve a decision rather than a queue entry: the
hardcoded 120 s model timeout, which a first-run user on modest hardware will
probably meet before anything else, and Ollama's own `ollama.com` lookup, which
is outside this codebase but inside the claim the product makes about itself.
The finding worth carrying into M2 planning is not a defect but a method. The
TLS gap was invisible to static review and to every local run that used
loopback HTTP, and it appeared within minutes of pointing the application at a
real LAN host. M2 owns the endpoint policy; it should be validated the same
way, against a real second machine rather than a container stand-in.
planning/archive/milestone-reports/M2-BASELINE-REPORT.md
+928
View File
@@ -0,0 +1,928 @@
# M2 — Baseline Report (evidence record)
**Date:** 2026-09-02
**Milestone:** M2, *Remove Hosted, Cloud, Scripting, and Unneeded Deployment Surface*
**Companion:** `planning/reports/M2-IMPLEMENTATION-REPORT.md` interprets this file.
Where the two disagree on a runtime or test fact, **this file is the record.**
This is measurement, not commentary. Command output is quoted verbatim.
Anything inferred rather than observed is labelled **[inferred]**.
Hostnames and LAN addresses are **placeholders** — `inference.lan`,
`192.168.0.50`, port `8443`. The real ones are in the workspace's untracked
notes, never in this repository. Packet counts, digests, timings and status
codes are exact.
---
## 0. Test environment
| | |
| --- | --- |
| Host | Ubuntu 24.04.4 LTS, x86-64, 4 cores, 15 GB RAM, **no GPU** |
| Python | 3.12.3 |
| Node / npm | 22.23.1 / 10.9.8 |
| Docker | 29.7.2 |
| Ollama (same-host) | `ollama/ollama:latest` in a container, models from a shared volume |
| Ollama (LAN) | 0.33.0 on a **second physical machine**, HTTPS, certificate from a private CA |
| Models | `qwen2.5:0.5b`, `qwen2.5:3b-instruct`, `nomic-embed-text` |
| Image under test | `m2-final`, built from the working tree by `docker build .` |
> **Timings in this file are not benchmarks.** This host was shared with
> unrelated work during the review; `uptime` reported a 1-minute load average
> ranging from **1.79 to 74.08** across the session on four cores. Where a
> measurement was taken under load, it says so. Latency figures are recorded
> because they mattered to a *timeout* result, not as performance data.
---
## 1. Repository and provenance
```console
$ git rev-parse --abbrev-ref HEAD
m2-local-only-surface
$ git log --format='%H %G? %s' -3
8c65ae99deda49b22f415d5868987e00bbcb173c G M2: cut the hosted product away from the local one
1a28a9a708985e7c98dcbcb87c189e7582ec288d G Apply post-M1 corrections to the planning package
645f07f06d226e274c33d96e71d9c374413ef771 G Add the M1 implementation review report
```
All three commits verify (`%G? = G`). The repository signs every commit; nothing
in this milestone is unsigned.
### Commit chain
| Commit | Sig | Parent | Meaning |
| --- | --- | --- | --- |
| `8c65ae9` | G | `1a28a9a` | **The M2 commit.** One commit, no merges. |
| `1a28a9a` | G | `645f07f` | Post-M1 planning corrections — the M1 baseline this milestone started from |
| `7f182a8` | G | `717670a`, `d72f7c1` | the fork import, two parents |
### Upstream ancestry
```console
$ git cat-file -t d72f7c1bda0f34fccd84afb7a25c34eb01c901de
commit
$ git merge-base --is-ancestor d72f7c1bda0f34fccd84afb7a25c34eb01c901de HEAD && echo yes
yes
$ git rev-list --count d72f7c1bda0f34fccd84afb7a25c34eb01c901de
172
$ git diff --stat d72f7c1bda0f34fccd84afb7a25c34eb01c901de HEAD -- LICENSE
(no output)
```
All 172 upstream commits reachable; `LICENSE` byte-identical to upstream; no
re-import or upstream substitution occurred. `PROVENANCE.md` and
`DEVELOPMENT.md` are present and were updated for M2.
### Private data
```console
$ grep -rn "<the real LAN hostname>\|<the real LAN subnet>\|<the real port>" \
--include=*.py --include=*.md --include=*.jsx --include=*.js \
--include=*.yml --include=*.txt backend frontend *.md *.yml Dockerfile
(no output)
```
No private hostname, LAN address, certificate or credential is committed.
### Working tree
At the M2 commit the tree was clean. **This review then modified six files**
(§9), so `git status` is *not* clean as this report is written:
```text
M backend/app/memorybank.py
M backend/app/models.py
M backend/app/routers/adventures/turns.py
M backend/app/routers/chat.py
M backend/requirements.lock
M backend/tests/test_local_only_surface.py
```
Every runtime result below was produced by an image built from that modified
tree, except where explicitly marked as pre-fix.
---
## 2. Change inventory
```console
$ git diff --shortstat 1a28a9a 8c65ae9
94 files changed, 1395 insertions(+), 6578 deletions(-)
```
**Added (3):**
```text
backend/app/endpoints.py
backend/tests/test_endpoint_policy.py
backend/tests/test_local_only_surface.py
```
**Deleted (24):**
```text
backend/app/accesslog.py backend/tests/test_accesslog.py
backend/app/analytics.py backend/tests/test_analytics.py
backend/app/cleanup.py backend/tests/test_guest_cleanup.py
backend/app/netguard.py backend/tests/test_netguard.py
backend/app/security.py backend/tests/test_ratelimit_hardening.py
backend/app/routers/analytics.py backend/tests/test_reasoning_param.py
backend/app/routers/auth.py
backend/app/routers/scripts.py frontend/src/pages/Analytics.jsx
backend/app/routers/adventures/scripts.py frontend/src/pages/Scripts.jsx
backend/app/scripting/__init__.py frontend/src/pages/ScriptEditor.jsx
backend/app/scripting/engine.py frontend/src/pages/Play/panels/ScriptsPanel.jsx
backend/app/scripting/pipeline.py frontend/src/pages/Play/drawers/StatusDrawer.jsx
render.yaml
```
**Largest modifications:**
```text
+93 -37 backend/app/routers/settings.py
+54 -82 backend/app/providers/openai_compatible.py
+44 -166 backend/tests/test_chat.py
+38 -81 backend/app/routers/chat.py
+37 -222 backend/app/auth.py
+32 -69 backend/app/main.py
+31 -195 backend/app/limits.py
+28 -178 backend/app/models.py
+22 -43 backend/app/database.py
+19 -58 frontend/src/pages/Settings.jsx
+18 -97 backend/app/routers/adventures/turns.py
+15 -85 frontend/src/App.jsx
```
---
## 3. Surface reduction, measured
### API routes (from the OpenAPI schema, not by grep)
| Prefix | M1 | M2 |
| --- | ---: | ---: |
| `/api/adventures` | 25 | 21 |
| `/api/analytics` | 3 | **0** |
| `/api/auth` | 4 | **0** |
| `/api/scripts` | 5 | **0** |
| `/api/chat` | 2 | 2 |
| `/api/scenarios` | 5 | 5 |
| `/api/settings` | 2 | 2 |
| `/api/story-cards` | 4 | 4 |
| `/api/debug`, `/api/health` | 2 | 2 |
| **Total** | **52** | **36** |
### Dependencies
```console
$ diff <(M1 requirements.txt) <(M2 requirements.txt) | grep '^<'
< quickjs>=1.19
< cryptography>=42
< psycopg[binary]>=3.2
```
Installed closure, measured by building a clean venv from `requirements.txt` +
`requirements-dev.txt`:
| | M1 | M2 |
| --- | ---: | ---: |
| Python packages installed | 40 | **34** |
| Packages gone | — | `cffi`, `cryptography`, `psycopg`, `psycopg-binary`, `pycparser`, `quickjs` |
| npm runtime dependencies | 6 | **3** |
| npm packages installed (`npm ls --all`) | 53 | **32** |
### Code size
| | M1 | M2 | Δ |
| --- | ---: | ---: | ---: |
| `backend/app` Python lines | 14 298 | 11 632 | −2 666 |
| `frontend/src` JS/JSX lines | 6 523 | 5 239 | −1 284 |
| `frontend/src/pages` files | 21 | 16 | −5 |
### Environment variables actually read (`os.environ`)
```console
$ grep -rn "os.environ" backend/app/
backend/app/database.py:18:_env_db_path = os.environ.get("AIDND_DB_PATH")
backend/app/main.py:30: for o in os.environ.get("AIDND_CORS_ORIGINS", "").split(",")
```
Two, down from ten. `AIDND_MULTI_USER`, `AIDND_SECRET_KEY`, `AIDND_COOKIE_SECURE`,
`AIDND_DEMO_API_KEY`, `AIDND_DEMO_ENDPOINT_URL`, `AIDND_DEMO_MODELS`,
`AIDND_DEMO_TURNS_PER_DAY`, `AIDND_POWER_USERS`, `AIDND_ANALYTICS_EMAILS`,
`AIDND_TRUSTED_PROXY_HOPS`, `AIDND_DATABASE_URL` and `DATABASE_URL` are no
longer read. Four of those names still appear in the tree **as prose in
comments** explaining what was removed; `grep` above shows no read.
---
## 4. Test suite
```console
$ cd backend && .venv/bin/python -m pytest tests/ -q
606 passed, 1 warning in 126.29s (0:02:06)
```
Zero failed, zero skipped, zero xfailed. The one warning is the inherited
Starlette/`httpx` deprecation notice, present since M1.
### Accounting for every test
Counted by diffing collected node IDs between `1a28a9a` (M1) and the working
tree, not by reading diffs:
| | Count |
| --- | ---: |
| Distinct test functions, M1 | 610 |
| Distinct test functions, M2 | 561 |
| Node IDs gone | 88 |
| Node IDs new | 39 |
| Collected tests (with parametrisation), M1 | 648 |
| Collected tests, M2 | **606** |
**Gone, by file:**
| File | Gone | Disposition |
| --- | ---: | --- |
| `test_analytics.py` | 25 | whole file — subject removed |
| `test_guest_cleanup.py` | 14 | whole file — subject removed |
| `test_accesslog.py` | 12 | whole file — subject removed |
| `test_ratelimit_hardening.py` | 8 | whole file — subject removed |
| `test_chat.py` | 8 | demo-key pinning and the power-user gate |
| `test_reasoning_param.py` | 5 | whole file — subject removed |
| `test_netguard.py` | 5 | whole file — replaced by `test_endpoint_policy.py` |
| `test_prompt_caching.py` | 4 | OpenRouter upstream routing |
| `test_memory_rewrite.py` | 4 | 2 retired (Postgres DSN masking), **2 renamed** |
| `test_delete_state.py` | 1 | **renamed** |
| `test_branch_forking.py` | 1 | **renamed** |
| `test_branch_clause.py` | 1 | scripting history API |
**Four of the 88 are renames with equivalent coverage**, so 84 tests were
genuinely retired:
```text
test_branch_forking: test_switching_restores_the_script_and_world_state
-> test_switching_restores_the_state_a_branch_left_behind
test_delete_state: test_deleting_the_ai_turn_rewinds_the_script_state
-> test_deleting_the_ai_turn_rewinds_the_counter
test_memory_rewrite: test_an_owner_with_no_api_key_is_skipped
-> test_an_adventure_with_no_model_configured_is_skipped
test_memory_rewrite: test_an_api_key_on_the_command_line_covers_that_owner
-> test_a_model_on_the_command_line_covers_that_adventure
```
**New, by file:** `test_local_only_surface.py` 18, `test_endpoint_policy.py`
14, `test_chat.py` 3, plus the 4 renames. Collected with parametrisation:
`test_endpoint_policy.py` 31, `test_local_only_surface.py` 32.
### Instrumentation conversion, not deletion
Eight files used a QuickJS `output` hook (`state.gold += 10`) as deterministic
instrumentation for the **state snapshot and rollback machinery**, which M2 does
not touch. The counter moved to the world-state engine — the model emits a
` ```state ` delta block, the referee applies it — and the assertions are
unchanged in substance. Affected: `test_take_state`, `test_attempt_siblings`,
`test_branch_forking`, `test_bundle_v2`, `test_delete_state`,
`test_retry_variants`, `test_story_tree_baseline`, `test_turn_flow_integration`,
plus `test_state_revert` converted from `script_state`/`state_after` to
`world_state`/`world_state_after`.
### Frontend and image
```console
$ npm run lint # oxlint
exit 0 # 7 warnings, all pre-existing react/only-export-components
$ npm run build
dist/assets/index-C9v6AJ3R.js 395.41 kB │ gzip: 120.01 kB ✓ built in 496ms
$ docker build .
exit 0
```
There are no automated frontend tests in the repository — none existed at M1
either.
Bundle size: **933.69 kB → 395.41 kB** (M1 → M2), from removing CodeMirror with
the script editor.
---
## 5. Offline run — same-host Ollama
**Topology.** `--internal` Docker network (no NAT, no external DNS). Ollama in
one container; the `m2-final` image in a second container sharing Ollama's
network namespace, so Ollama sits on the storyteller's own loopback. tcpdump ran
in that namespace for the whole session.
### 5.1 Isolation, verified before any test
```text
blocked 1.1.1.1:443 OSError
blocked 140.82.121.4:443 OSError
no resolution fonts.googleapis.com
no resolution fonts.gstatic.com
no resolution openaipublic.blob.core.windows.net
no resolution openrouter.ai
no resolution api.openai.com
no resolution github.com
```
### 5.2 Listeners
```text
LISTEN 127.0.0.1:8000 <- the storyteller
LISTEN 127.0.0.11:42229 <- Docker's embedded DNS
LISTEN 127.0.0.1:43093 <- Ollama's model runner
LISTEN 127.0.0.1:43313 <- Ollama's model runner
LISTEN [::]:11434 <- Ollama itself
```
Nothing the storyteller owns is bound off loopback.
### 5.3 Ollama-only settings and diagnostics
```json
endpoint: http://127.0.0.1:11434/v1 | model: qwen2.5:0.5b
embed: nomic-embed-text:latest | timeout: 600
connection test: {"ok": true, "models": ["qwen2.5:7b-instruct",
"qwen2.5:3b-instruct", "nomic-embed-text:latest", "qwen2.5:0.5b"]}
```
### 5.4 Story generation and streaming
```text
turn 1 ( 1.7s, 90 stream chunks): 'Oh, how unfortunate! A lighthouse keeper indeed! The light'
turn 2 ( 35.2s, 90 stream chunks): 'I climb the spiral stair to the lamp room. My hand tightly'
turn 3 ( 7.1s, 90 stream chunks): "I search the keeper's log for the last entry. The last ent"
turn 4: ERROR {'type': 'error', 'detail': 'The AI endpoint timed out.'}
```
Turn 4 timed out at the configured 600 s. The application logged no error. Ollama
reported the model still resident. `uptime` at the time: 1-minute load average
had risen from 1.79 to the tens on four cores from unrelated work on this host.
**[inferred]** the timeout is host contention rather than an application fault;
what is *measured* is that no application error was logged and that the same
build produced turns in 1.7–35.2 s minutes earlier.
### 5.5 Local embeddings, end to end through the app
```text
wrote memory id=1, embedded=False
turn to trigger the pass (101.6s)
memories: 1 embedded with the local model: 1
```
Direct timing of the embedding endpoint from inside the container:
```text
embedding round trip: 3.4s, dim=768
second embedding (warm): 0.1s
```
### 5.6 Branch-scoped memory isolation — positive and negative controls
```text
main branch = 1
memories on main: 0 ALPHA present: False
forking at AI action 22 (an earlier turn, so this starts a new line)
fork events: ['chunk', 'chunk', 'done']
branches now: 2, fork = 5
ON THE FORK (0 memories)
ALPHA visible: False <- ALPHA is anchored at main's head, which is BELOW the
fork point, so the fork correctly does not inherit it
BETA written here, visible: True <- positive control
BACK ON MAIN (1 memories)
ALPHA visible: True <- positive control
BETA visible: False <- NEGATIVE CONTROL, must be False
```
The decisive result is the last line: a memory written on the fork is **not**
visible on main.
### 5.7 A05 — a failed model call, and a hand-edited database
```text
baseline: (8 actions, 3 accepted AI turns, digest 07615da99b014b70)
-- invalid local model --
events: ['player', 'error']
error: Endpoint or model not found (HTTP 404). Check the endpoint URL and that model 'n…
after: (7, 3, 'e18de9dff6455e0d')
-- endpoint refused by policy at request time --
(the settings row was edited directly with sqlite3, behind the app's back,
to https://openrouter.ai/api/v1)
events: ['player', 'error']
error: This endpoint can't be used — openrouter.ai is a cloud inference service — this build…
after: (8, 3, '157c882c60579617')
```
The **accepted AI-turn count stayed at 3** through both failures. Only the
player's own typed action was added each time, which is M1's documented and
deliberate behaviour.
The second case is the strongest form of the endpoint evidence: the request-time
check refused a cloud endpoint that had been written straight into SQLite,
bypassing the API's save-time validation entirely.
### 5.8 Restart and resume
```text
before restart: 8 actions, digest 157c882c60579617
branches: 2 memories: 1
after restart: 8 actions, digest 157c882c60579617
branches: 2 memories: 1
settings preserved: endpoint http://127.0.0.1:11434/v1 timeout 600
context inspection: ['narrator', 'persona', 'history', 'used_memories']
```
### 5.9 Packet capture — whole offline session
```text
all packets: 5131
loopback (127.0.0.0/8): 5086
non-loopback unicast: 0
TCP connections opened outside loopback: (none)
```
DNS queries, attributed by timestamp rather than assumed:
| Name | First seen | Attribution |
| --- | --- | --- |
| `fonts.googleapis.com` | 16:44:02.800449 | **the isolation probe** in §5.1 |
| `openaipublic.blob.core.windows.net` | 16:44:02.802749 | the isolation probe |
| `openrouter.ai` | 16:44:02.803260 | the isolation probe |
| `api.openai.com` | 16:44:02.803956 | the isolation probe |
| `github.com` | 16:44:02.804747 | the isolation probe |
| `ollama-container` | 18:28:55.684172 | the endpoint-policy edge-case test (§7) |
| `ollama.com` | 16:53:29 … 18:28:05 | **the Ollama server's own lookup** |
```text
capture window: 16:44:02.800136 .. 18:51:29.080336
first packet to the storyteller API: 16:44:47.639083
```
Every cloud/font/tokenizer lookup landed within **5 milliseconds of the capture
starting and 45 seconds before the storyteller received its first request** —
they are the deliberate probe, not the application. `ollama.com` recurs
throughout and is issued by the separately installed Ollama service, the same
observation M1 recorded.
---
## 6. Offline run — trusted-LAN Ollama over HTTPS
**Topology.** Ollama 0.33.0 on a **second physical machine** on the trusted LAN,
serving HTTPS with a certificate from a private CA. The storyteller ran in a
container with `NET_ADMIN`, its **default route deleted** and replaced with a
route to the LAN subnet only, its resolver pointed at nothing, and the host name
supplied as a static hosts entry.
### 6.1 Isolation and binding
```text
=== isolation ===
blocked 1.1.1.1:443 OSError
blocked 140.82.121.4:443 OSError
no resolution github.com
no resolution openrouter.ai
no resolution fonts.gstatic.com
=== the approved LAN host ===
inference.lan -> 192.168.0.50
TLS verified, peer CN = inference.lan
=== listeners ===
LISTEN 127.0.0.1:8000
```
Nothing listens on the container's own LAN-facing address.
### 6.2 Diagnostics and generation
```text
endpoint: https://inference.lan:8443/v1 | timeout: 600 s
diagnostics: {"ok": true, "models": ["qwen2.5:3b-instruct", "nomic-embed-text:latest"]}
turn 1 ( 10.7s, 24 chunks): 'You check the oil and wick, their greasy slicks staining your hand'
turn 2 ( 4.0s, 17 chunks): 'The air is thick with the musty scent of the old building as you a'
turn 3 ( 4.6s, 26 chunks): 'You find the last entry: "Exhausted... Oil\'s low..." The room feel'
memories: 1 embedded via the LAN host: 1
```
### 6.3 Every model request the application made
```text
4 https://inference.lan:8443/v1/chat/completions
1 https://inference.lan:8443/v1/embeddings
```
Narration and embeddings both went to the configured host over verified TLS. No
other URL appears.
### 6.4 Retry keeps the discarded attempt
Measured on the shipped image, against the LAN host:
```text
head AI action before retry: 8 take_count 1
retry produced (13.7s): 'You jot down a hurried note: "Visited lamp—oil low—oil lamp '
head AI action after retry: 9 take_count 2 take_index 1
alternate takes retained: 2
- 'Your pen touches the cold wood of the log, the friction'
- 'You jot down a hurried note: "Visited lamp—oil low—oil '
branches: 1
```
A retry at the tip files the new attempt as a sibling at the same coordinate and
keeps the one it replaced. No branch is created, which is correct for a retry at
the head.
### 6.5 Restart and resume
```text
before restart: 8 actions, digest 66cc82944f8b6eef
after restart: 8 actions, digest 66cc82944f8b6eef
endpoint preserved: https://inference.lan:8443/v1 timeout 600
memories: 1
```
### 6.6 Packet capture
```text
all packets: 685
loopback: 364
to/from the LAN Ollama host: 308
any other unicast: 0
DNS queries: none
```
Zero DNS: the endpoint was configured, not discovered.
---
## 7. Endpoint policy
Run inside the shipped image:
```text
ALLOW same-host loopback http://127.0.0.1:11434/v1
ALLOW localhost name http://localhost:11434/v1
ALLOW IPv6 loopback http://[::1]:11434/v1
ALLOW LAN literal http://192.168.1.50:11434/v1
ALLOW link-local http://169.254.10.5:11434/v1
ALLOW CGNAT / mesh VPN http://100.64.3.4:11434/v1
ALLOW IPv6 unique-local http://[fd00::5]:11434/v1
ALLOW docker internal name http://ollama-container:11434/v1
REJECT cloud provider https://openrouter.ai/api/v1
openrouter.ai is a cloud inference service — this build talks to Ollama on your own mach…
REJECT cloud provider https://api.openai.com/v1
REJECT public IPv4 http://8.8.8.8:11434/v1
8.8.8.8 resolves to 8.8.8.8, which is a public Internet address — …
REJECT public IPv6 http://[2001:4860:4860::8888]/v1
REJECT unspecified address http://0.0.0.0:11434/v1
0.0.0.0 … is not on this machine and not on your own network …
REJECT wrong scheme ftp://127.0.0.1/v1
```
Over the HTTP API, from inside the offline container:
```text
=== cloud and public endpoints are refused ===
400 https://openrouter.ai/api/v1 That endpoint can't be used — openrouter.ai is a cloud…
400 https://api.openai.com/v1 …
400 https://api.groq.com/openai/v1 …
400 http://8.8.8.8:11434/v1 …8.8.8.8 … is a public Internet address…
=== local and LAN endpoints are accepted ===
200 http://127.0.0.1:11434/v1
200 http://192.168.1.50:11434/v1
200 http://[::1]:11434/v1
```
Request-time enforcement against a hand-edited database is in §5.7.
`test_endpoint_policy.py` (31 collected) resolves hostnames through a stub, so
it exercises the policy rather than the machine's DNS. It covers the split-horizon
case: a name resolving to both `192.168.1.50` and a public address is refused.
---
## 8. TLS trust
```console
$ grep -rn "verify=False\|ssl._create_unverified\|CERT_NONE\|check_hostname = False" backend/app
(the only match is prose in tlstrust.py saying such an option deliberately does not exist)
$ grep -rn "httpx.AsyncClient(\|httpx.Client(" backend/app
backend/app/routers/settings.py:122
backend/app/providers/openai_compatible.py:214
backend/app/providers/openai_compatible.py:326
backend/app/providers/openai_compatible.py:360
```
Four clients, all four passing `verify=tlstrust.ssl_context()`. Enforced by
`test_tls_trust.py`, which walks the AST of the two modules that make outbound
requests and fails if any `httpx.AsyncClient` is constructed without `verify`,
or if a third module starts making requests:
```console
$ .venv/bin/python -m pytest tests/test_tls_trust.py -q
6 passed in 0.20s
```
Runtime confirmation of certificate **and** hostname verification against the
real private-CA host is §6.1 (`TLS verified, peer CN = inference.lan`), and of
all four paths — settings/test, narration, model listing, embeddings — §6.2–6.3.
### Modules that can open an outbound connection at all
```console
$ grep -rln "httpx\|requests\.\|urllib.request\|socket\.\|aiohttp\|websocket" backend/app
backend/app/endpoints.py # getaddrinfo only, for the policy
backend/app/providers/openai_compatible.py
backend/app/routers/settings.py
backend/app/tlstrust.py # builds the SSL context; opens nothing
```
Remaining absolute URLs anywhere in backend application code:
```text
3 http://127.0.0.1
2 http://localhost
1 https://openaipublic.blob.core.windows.net <- a comment and a SOURCE_URL
constant in encoding.py; never fetched
```
---
## 9. Defects found during this review
Three, all found by running the shipped build rather than by reading it. Each was
corrected because the M2 evidence could not otherwise be accurate; each is
reported rather than absorbed.
### 9.1 The memory bank was broken — summaries and embeddings silently stopped
```text
Task exception was never retrieved
future: <Task finished coro=<run_post_turn() ...> exception=AttributeError(
"'Settings' object has no attribute 'api_key_plain'")>
File "/app/backend/app/memorybank.py", line 155, in summary_provider
settings.api_key_plain,
```
M2 removed `Settings.api_key_plain` with the API key, but `memorybank`'s two
provider factories still read it. It failed in a fire-and-forget background
task, so nothing surfaced to the user and no test caught it: every memory test
stubs those factories out. **All 604 tests passed with this defect present.**
Fixed by rewriting both factories. Covered by a new test that constructs every
provider factory from a real `Settings` row.
### 9.2 The configurable model timeout never reached the turn engine
`settings.model_timeout_seconds` was stored, validated, exposed in the API and
rendered in the UI — and not passed to `OpenAICompatibleProvider` in
`turns.py` or `chat.py`, so generation used the module default. The M2 exit
criterion "no longer an undocumented hardcoded limitation" was therefore only
half met: the constant had moved, but the setting was inert.
Fixed in both call sites. Covered by a new test that drives the turn endpoint,
the chat endpoint and the summariser factory and asserts the configured value
reaches each.
### 9.3 `requirements.lock` still pinned the removed packages
```console
$ grep -n "quickjs\|psycopg\|cryptography" backend/requirements.lock
25:cryptography==50.0.1
36:psycopg==3.3.5
37:psycopg-binary==3.3.5
45:quickjs==1.19.4
```
`DEVELOPMENT.md` tells a new developer to install from the lock, which would have
reinstalled all three. Regenerated: 40 pins → 34.
### Verification after the fixes
```console
$ .venv/bin/python -m pytest tests/ -q
606 passed, 1 warning in 126.29s
$ npm run lint # exit 0
$ npm run build # ✓ built in 496ms
$ docker build . # exit 0
```
All §5 and §6 runtime evidence above was produced by an image built **after**
these fixes.
---
## 10. M1 capability regression checks
| M1 capability | Result | Evidence |
| --- | --- | --- |
| Vendored tokenizer, no first-turn download | PASS | §10.1 |
| Self-hosted fonts | PASS | §10.2 |
| Same-origin runtime assets | PASS | §10.2 |
| Restrictive CSP | PASS | §10.2 |
| Loopback storyteller default | PASS | §5.2, §6.1, §11 |
| Same-host Ollama | PASS | §5.3–5.4 |
| Trusted-LAN Ollama | PASS | §6.2 |
| HTTPS / private-CA trusted-LAN | PASS | §6.1–6.3 |
| Certificate + hostname verification | PASS | §6.1, §8 |
| Offline story generation | PASS | §5.1, §5.4 |
| SQLite persistence | PASS | §5.8, §6.4 |
| Full regression suite green | PASS | §4 |
### 10.1 Tokenizer, inside the shipped image, offline
```text
vendored table sha256 matches pin: True
count_tokens with sockets blocked: 6 tokens
```
### 10.2 Browser asset graph, fetched over loopback with no route out
```text
CSP: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
font-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none';
base-uri 'none'; form-action 'self'; frame-ancestors 'none'
referenced by index.html:
/favicon.svg LOCAL
/assets/index-*.js LOCAL
/assets/index-*.css LOCAL
font urls inside the stylesheet:
/fonts/cinzel-normal-latin-ext.woff2 200 font/woff2 14540
/fonts/cinzel-normal-latin.woff2 200 font/woff2 25904
/fonts/crimson-pro-italic-latin-ext.woff2 200 font/woff2 39808
/fonts/crimson-pro-italic-latin.woff2 200 font/woff2 51432
/fonts/crimson-pro-normal-latin-ext.woff2 200 font/woff2 37988
/fonts/crimson-pro-normal-latin.woff2 200 font/woff2 48200
/fonts/inter-normal-latin-ext.woff2 200 font/woff2 85068
/fonts/inter-normal-latin.woff2 200 font/woff2 48256
```
Unchanged from M1, including the `object-src`/`base-uri`/`form-action`
directives M1 added.
---
## 11. Storyteller network exposure
| Launch path | Listener / publish | Verified by |
| --- | --- | --- |
| `./start.sh` (native dev) | `uvicorn --host 127.0.0.1 --port 8000` | file assertion in `test_local_only_surface.py` |
| `start.ps1` (Windows) | `--host 127.0.0.1` | same test |
| Production native (documented in `DEVELOPMENT.md`) | `--host 127.0.0.1` | documentation |
| `docker compose up` | `ports: - "127.0.0.1:8000:8000"` | test parses the published mappings and asserts every one starts `127.0.0.1:` |
| Container process itself | `--host 0.0.0.0` | deliberate; the only address a published port can reach |
`DEVELOPMENT.md` states that publishing the port to `0.0.0.0` is a deliberate
decision this project's threat model does not cover. The `Dockerfile` carries the
same warning next to `EXPOSE`.
Two supporting checks:
* `AIDND_CORS_ORIGINS="*"` makes the application **refuse to start**:
`RuntimeError: AIDND_CORS_ORIGINS must not contain '*'…`
* An unknown `/api/...` path now returns **404** instead of the SPA's HTML with
status 200 (verified for ten removed endpoints, §12).
---
## 12. Removed-surface verification, at runtime
From inside the offline container:
```text
=== removed surfaces answer 404 ===
404 GET /auth/me 404 GET /analytics/summary
404 GET /auth/login 404 GET /analytics/collect
404 GET /auth/register 404 GET /analytics/access
404 GET /auth/logout 404 GET /scripts
404 GET /adventures/2/scripts
404 GET /adventures/2/script-state
=== no API key in the settings surface ===
api_key present: False has_api_key present: False
after trying to set one: False
```
```console
$ python -c "import app.scripting"
ImportError # asserted by test_the_application_has_no_scripting_engine
$ grep -rn "import quickjs" backend/app
(no output)
```
---
## 13. Inert schema retained for compatibility
Verified present in the database and unread by the application.
| Object | Was | Status |
| --- | --- | --- |
| table `scripts` | script library | unmapped; no model, no query |
| table `adventure_scripts` | per-adventure script copies | unmapped |
| table `analytics_daily` | visitor counters | unmapped |
| table `analytics_visitor_days` | visitor funnel | unmapped |
| table `access_log` | sign-ins, addresses, devices | unmapped |
| column `adventures.script_state` | scripting shared state | written `{}` only |
| column `actions.state_after` | scripting state per node | written `{}` only |
| column `settings.api_key` | encrypted cloud key | never read or written |
| column `settings.reasoning_max_tokens` | OpenRouter thinking budget | never read |
| column `users.demo_turns_used` / `_date` | demo cap tally | never read |
| table `users` + `user_id` FKs | multi-user ownership | **active**, one row, internal identity only |
No destructive migration was performed. One additive migration was added:
```python
(77, "ALTER TABLE settings ADD COLUMN model_timeout_seconds INTEGER NOT NULL DEFAULT 300")
```
Existing M1 databases open unchanged: the offline run in §5 used the volume
carrying campaigns created before these fixes, and §5.8 shows the transcript
digest surviving both an image replacement and a restart.
---
## 14. What was not measured
Stated so the implementation report does not overclaim.
1. **No browser rendered the UI.** No browser automation was available. §10.2
fetches the complete asset graph the page references, with correct media
types and the CSP, but nobody looked at the rendered page. This is unchanged
from M1, where the maintainer confirmed the render by hand.
2. **Sustained multi-turn play under the memory bank was not completed on this
host.** Turns 1–3 succeeded; turn 4 timed out under third-party CPU load
(§5.4). The individual capabilities — narration, streaming, embeddings,
memory writes, retry, fork, restart — were each measured separately.
3. **No load, soak or long-campaign testing.** Out of scope for M2.
---
# 15. Closeout note — appended 2026-09-03
**This section was appended after the fact and is not part of the original
evidence record.** Everything above was written on 2026-09-02 and describes the
repository as it stood then. Nothing above has been rewritten, including its
references to a working tree that was dirty at the time.
## What the original report correctly said
The report above correctly described commit `8c65ae9` — the M2 implementation
commit — as **not containing** the three fixes this review found. At the time it
was written, those fixes existed only in the working tree, six files ahead of
that commit. Every runtime measurement in this report was produced by an image
built from that fixed tree, which the report states plainly.
## What happened afterwards
The six-file correction was committed:
```text
8652fe7cd84bca5173abb03b2a692f15fea8a98c M2 review: two regressions the green suite hid, and the reports
```
That commit carries the six implementation/test/lockfile files **and** the two
M2 reports themselves, which is why this report's own history begins there. The
provenance distinction the review asked for is preserved regardless:
`8c65ae9` is the M2 implementation, `8652fe7` is the review correction, and the
two were never squashed.
## Verification at closeout
Re-run on 2026-09-03 against the committed tree — not the working tree — so that
what was verified is exactly what the repository contains:
```text
backend .venv/bin/python -m pytest tests/ -q 606 passed in 133.26s
frontend npm run lint 7 warnings, 0 errors, exit 0
frontend npm run build built in 932ms; index.js 395.41 kB
root docker build -t storyteller-m2-closeout . exit 0
git status --short clean
```
The 606 figure matches the count this report recorded, from the same tree.
Dependency removal was verified in the built image rather than only in the
lockfile:
```text
$ docker run --rm --entrypoint sh storyteller-m2-closeout -c "pip list | grep -iE 'quickjs|psycopg|cryptography|cffi|pycparser'"
ABSENT: none of quickjs/psycopg/cryptography/cffi/pycparser installed
32 packages total
```
The network measurements in §5, §6 and §10 were **not** re-run. The six
corrected files change provider construction and a timeout value; they do not
touch the endpoint policy, the TLS trust context, or the bind addresses, so the
captures above remain the evidence for the network boundary.
planning/archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md
+850
View File
@@ -0,0 +1,850 @@
# M2 — Implementation Review Report
**Date:** 2026-09-02
**Milestone:** M2, *Remove Hosted, Cloud, Scripting, and Unneeded Deployment Surface*
**Audience:** the architecture/design reviewer deciding whether to accept M2 and start M3
**Evidence:** `planning/reports/M2-BASELINE-REPORT.md`. Section references below
(§) point into it, and where this report and that one differ on a runtime or
test fact, **the baseline report is the record.**
Hostnames and LAN addresses are placeholders (`inference.lan`, `192.168.0.50`).
---
# A. Executive result
```text
Overall M2 result: PASS
```
**Recommendation: ACCEPT M2 WITH NON-BLOCKING DEBT AND PROCEED TO M3.**
Directly, in the order asked:
| Question | Answer |
| --- | --- |
| Is it genuinely a single-user local storyteller? | **Yes.** No login, no accounts, no sessions; all four `/api/auth/*` routes 404 (§12). |
| Is Ollama the only production inference backend? | **Yes.** No cloud provider code, no key, and public addresses are refused at the wire (§7). |
| Are hosted/cloud/account/scripting surfaces actually removed? | **Yes** — removed, not hidden. 52 API routes → 36; `/api/auth`, `/api/analytics`, `/api/scripts` gone entirely (§3, §12). |
| Does same-host Ollama still work? | **Yes** (§5.3–5.4). |
| Does trusted-LAN Ollama still work? | **Yes**, against the real second machine (§6.2). |
| Does HTTPS/private-CA still work with verification on? | **Yes** — `TLS verified, peer CN = inference.lan`, all four clients on the shared trust context, no bypass exists (§6.1, §8). |
| Does it still run with Internet blocked? | **Yes** (§5.1, §6.1). |
| Did any M1 behaviour regress? | **Yes — two, both found by this review and both fixed** (§A.1). |
| Should the project proceed to M3? | **Yes.** |
| Blockers before M3? | **None.** |
## A.1 Two M1 regressions that M2 shipped, and this review caught
These are the most important findings and they are not buried.
**1. The memory bank was silently broken.** M2 removed
`Settings.api_key_plain`, but `memorybank`'s two provider factories still read
it. Summaries and embeddings raised `AttributeError` inside a fire-and-forget
background task — no user-visible error, no log a player would see, no failing
test. **All 604 tests passed with the memory bank dead** (§9.1).
**2. The configurable model timeout never reached the turn engine.** The
setting was stored, validated, exposed in the API and rendered in the UI, and
then not passed to the provider. M2's own exit criterion — "the model timeout is
no longer an undocumented hardcoded 120-second limitation" — was half met: the
constant had moved but the setting was inert (§9.2).
A third, smaller: `requirements.lock` still pinned `quickjs`, `psycopg` and
`cryptography`, so the documented setup path would have reinstalled all three
(§9.3).
All three are corrected in the working tree, with tests that would have caught
the first two. **The M2 commit `8c65ae9` does not contain these fixes**; the tree
is six files ahead of it and needs a follow-up commit. Every runtime result in
the baseline report was produced by an image built from the fixed tree.
**What this says about the milestone is more useful than the defects
themselves:** a subtractive milestone's risk is not what it deletes, it is what
still reaches for the deleted thing from a code path no test exercises. Both
defects were in *background* or *plumbing* paths. §K returns to this.
---
# B. Repository and provenance
| | |
| --- | --- |
| Branch | `m2-local-only-surface` |
| HEAD | `8c65ae99deda49b22f415d5868987e00bbcb173c` (signed, `%G? = G`) |
| M2 commit | `8c65ae9`, one commit, parent `1a28a9a` |
| M1 starting point | `1a28a9a` (post-M1 planning corrections) |
| Upstream ancestry | `d72f7c1…` is an ancestor of HEAD; 172 upstream commits reachable |
| `LICENSE` | byte-identical to upstream |
| Private data committed | none (§1) |
| Working tree | **six files modified** by this review (§A.1) |
No unrelated upstream re-import occurred. `PROVENANCE.md` records what M2
removed and what it retained; `DEVELOPMENT.md` documents the new surface.
---
# C. Implementation inventory
**94 files changed, +1 395 −6 578.** Three added, twenty-four deleted, sixty-seven
modified. Grouped by purpose:
### 1. Single-user / account removal
Deleted `routers/auth.py`, `cleanup.py` (guest-retention sweeper),
`accesslog.py`, `security.py` (session signing + key encryption). `auth.py` cut
from 259 to 74 lines: it now resolves one implicit local user and nothing else.
Frontend: the `/auth/me` bootstrap, `AuthModal`, guest nudge, log-in/sign-up/
log-out controls, and the 401-and-retry dance in `api.js`.
### 2. Analytics removal
Deleted `analytics.py`, `routers/analytics.py`, `pages/Analytics.jsx`, the
`trackPageview` beacon, the `ApiErrorMiddleware` that fed the error tally, the
lifespan flusher, and every `record_event` call site. Three model classes
unmapped.
### 3. Hosted database / deployment removal
`render.yaml` deleted. `database.py` reduced to SQLite only —
`AIDND_DATABASE_URL`, `DATABASE_URL`, the psycopg URL normaliser and the
serverless pre-ping are gone. `psycopg[binary]` removed.
### 4. Cloud-provider removal
`_OPENROUTER_HOST`, `_PREFERRED_UPSTREAM`, `_apply_provider_routing`,
`_apply_reasoning_budget`, the `Authorization` header, the `api_key` field and
its Fernet encryption. `cryptography` removed.
### 5. Ollama-only configuration
`OpenAICompatibleProvider(endpoint_url, model, api_mode, read_timeout)` — no
key, no reasoning budget. `ProviderConfig`/`resolve_provider_config` deleted
outright; callers read `Settings` directly.
### 6. Endpoint policy — **the only addition**
`backend/app/endpoints.py` (179 lines) replaces `netguard.py`, inverting its
rule (§F).
### 7. Trusted-LAN / TLS preservation
M1's `tlstrust.py` untouched. All four HTTP clients still pass
`verify=tlstrust.ssl_context()`; `test_tls_trust.py` enforces it by AST walk.
### 8. QuickJS / scripting removal
`app/scripting/` (3 files), both script routers, `Script`/`AdventureScript`
models, the `scenario_scripts` table, script schemas, script export/import,
`Scripts.jsx`, `ScriptEditor.jsx`, `ScriptsPanel.jsx`, `StatusDrawer.jsx`,
`ScriptReport`. `quickjs` removed; CodeMirror removed from npm.
### 9. Hosted-policy removal
`limits.py` cut from 345 to ~150 lines: rate limiting, `X-Forwarded-For` client
IP, login throttling and per-user quotas gone. **Kept**: request body ceiling,
per-adventure row caps, import list caps.
### 10. Settings simplification
Removed: API key field, "Remove key" button, demo banner, reasoning budget.
Added: Ollama endpoint help text stating the policy, and a model-timeout field.
### 11. Model timeout
`CONNECT_TIMEOUT = 10`, `DEFAULT_READ_TIMEOUT = 300`, `EMBED_READ_TIMEOUT = 60`,
plus `Settings.model_timeout_seconds` (migration 77, default 300, bounded
30–3600).
### 12. Loopback protections
`docker-compose.yml` publishes `127.0.0.1:8000:8000`; `--proxy-headers` dropped;
`AIDND_CORS_ORIGINS="*"` now refuses to start; an unknown `/api/...` path 404s
instead of returning the SPA with status 200.
### 13. Tests
Two new files (63 collected). Eight files converted from JS instrumentation to
the world-state engine. Six files retired with their subsystems.
### 14. Documentation
`DEVELOPMENT.md` gained the endpoint policy and the diagnostics table;
`.env.example` cut from 110 lines to 24; `PROVENANCE.md` records M2.
## Deliberately retained
| Retained | Why |
| --- | --- |
| `users` table and `user_id` foreign keys | The M2 brief permits it. Removing them means a migration across most of the schema to delete a column that costs nothing. One row; nothing creates a second; no request carries an identity. |
| Five inert tables, six inert columns | A destructive migration would risk an existing campaign database for tidiness. Unmapped or written-empty; nothing reads them (§13). |
| `providers/openai_compatible.py` name | It speaks OpenAI's *protocol* to Ollama. Renaming would churn a file M3 does not touch, for no behaviour change. |
| AI Chat scratchpad | Not hosted-only. It is a local tool for checking a model or prompt, and the endpoint policy constrains where it can talk. |
| RPG world-state engine | M5's scope. M2 additionally now *depends* on it as test instrumentation (§K.2). |
| Destructive Undo, no Redo | M3's scope, explicitly out of M2. |
---
# D. Single-user / hosted-account removal
| Classification | Contents |
| --- | --- |
| **Code removed** | `routers/auth.py`, `cleanup.py`, `accesslog.py`, `security.py`, 185 of 259 lines of `auth.py`, `AuthModal`, the account nav block, the session-retry logic |
| **Code retained but inert** | none in this area |
| **Schema retained for compatibility** | `users` + `user_id` FKs (active but single-row); `users.demo_turns_used`/`_date`; `settings.api_key` |
| **Production functionality still active** | **none** |
* **Can a local user meet a login requirement?** No. There is no login UI, no
session cookie, and `get_current_user` always succeeds.
* **Are account APIs reachable?** No — 404 on all four (§12).
* **Are hosted account modules imported at runtime?** No; the files do not exist.
* **Does the database retain user identifiers?** Yes, one row.
* **Merely internal now?** Yes, and documented as such in `auth.py`'s docstring
and `PROVENANCE.md`.
* **Did avoiding the schema rewrite reduce risk?** **Materially.** `user_id`
appears on scenarios, adventures, settings and memories, and the ownership
filters run through the story-tree and memory queries M3 will modify. A
schema rewrite would have put a migration under those queries in the same
milestone that removed accounts — two risky changes entangled. Keeping the
column made M2 a deletion rather than a redesign.
No active hosted-account functionality remains.
---
# E. Analytics / telemetry
**Removed:** the collection module, the routes, the beacon, the Visitors page and
nav link, the error-tally middleware, the batch flusher, and every call site.
**Retained inert:** three tables, unmapped, never opened.
No destructive migration was performed because dropping tables from a live
campaign database buys nothing and can fail.
**Verified at runtime, not asserted:** across a full offline session of 5 131
packets — settings, campaign creation, four turns, embeddings, a fork, two
induced failures, a restart — there were **zero non-loopback unicast packets**
and no TCP connection opened outside loopback (§5.9). The only DNS names that
appear are the ones my own isolation probe deliberately looked up, all within
5 ms of the capture starting and 45 seconds before the storyteller received its
first request, plus `ollama.com` from the Ollama service itself.
Analytics is removed, not merely hidden: collection does not occur.
---
# F. Hosted database / deployment, and the endpoint policy
## Database
Postgres, Neon, `psycopg`, the URL normaliser and `render.yaml` are gone;
production is SQLite at `AIDND_DB_PATH`. An existing M1 database opens
unchanged — the offline run used a volume carrying campaigns created before the
fixes, survived an image replacement and a restart with digest
`157c882c60579617` unchanged (§5.8). Story-tree persistence is unaffected;
branch count, memory count and context inspection all survive restart.
One Postgres-shaped abstraction is retained: `migrations.py` and `tools/dbmeter.py`
carry comments and a `_for_dialect` helper for SQL that differed between
SQLite and psycopg. Removing it would churn the migration history for no gain.
## Endpoint policy — the design centre of M2
`endpoints.py` **inverts** the rule it replaces. `netguard.py` refused *private*
addresses, to stop a hosted visitor making the server fetch an internal service.
The threat here is the opposite: the user is trusted, and what must not happen is
the story reaching the public Internet. So the new rule refuses *public*
addresses.
The line is drawn by **address against an explicit allowlist of networks**, not
by hostname and not by asking `ipaddress` what it thinks is private:
```text
127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
169.254.0.0/16 100.64.0.0/10 ::1/128 fc00::/7 fe80::/10
```
Every address a name resolves to must be in one. Applied twice: on save, for a
good error; and before every outbound request, because DNS moves.
Measured behaviour (§7): loopback v4 and v6, `localhost`, all three RFC1918
ranges, link-local, CGNAT, IPv6 ULA and a Docker-internal name are **accepted**;
four cloud providers, public IPv4 and IPv6, `0.0.0.0` and a wrong scheme are
**refused**, each with a reason naming what to do instead.
### What it guarantees, and what it does not
**Guarantees.** No request leaves for an address outside those networks, from any
of the four clients, whatever is stored. Demonstrated against a **hand-edited
SQLite row** — the settings row was rewritten to `openrouter.ai` with `sqlite3`,
bypassing the API entirely, and the next turn was refused at the wire (§5.7).
That is the strongest available form of this evidence.
**Does not guarantee.** The allowlist is *address* scope, not *ownership* scope:
if a hostile host sits on the user's own LAN, the policy permits it — as it must,
since that is what "trusted LAN" means. A rebinding window exists in principle
between the policy's `getaddrinfo` and httpx's own connect; closing it would mean
pinning the resolved address into the connection, which is a larger change than
M2 warranted. Neither is a v1 concern: both require an attacker already inside
the trusted network.
**One design finding worth flagging** (§K.1): writing this rule around
`ipaddress.is_private` / `is_reserved` — the obvious approach — is wrong in a way
that is easy to ship. Python classifies IPv6 loopback `::1` as *reserved*, so
that version refused `http://[::1]:11434/v1`, an ordinary same-host endpoint. It
also calls the documentation ranges *private*, so they would have been allowed.
The explicit CIDR list exists because of that, and the reasoning is recorded in
the module docstring.
---
# G. Ollama-only provider
**Providers in production code: one.** `OpenAICompatibleProvider`, speaking
OpenAI's `/v1` protocol to Ollama.
* Provider options visible to the user: **none**. There is no selector, because
there is nothing to select between.
* OpenAI / OpenRouter / Groq / cloud APIs: **gone** — constants, routing,
attribution and the reasoning-budget parameter.
* Cloud API-key fields: **gone** from the model API, the UI and the request
headers. The column is inert.
**The module name is not the question.** The question the brief poses —
*can production use still send story content to a public inference service
through normal configuration?* — was tested directly rather than reasoned about:
saving a cloud URL is refused with HTTP 400 (§7), and a cloud URL written
straight into the database is refused at request time (§5.7). No.
---
# H. Trusted-LAN and TLS regression
Re-verified after M2 on the **real second physical machine** used in M1, over
HTTPS with a private CA (§6).
| Check | Result |
| --- | --- |
| Endpoint class | `https://inference.lan:8443/v1`, non-loopback, private CA |
| Connection | succeeded; diagnostics listed both installed models |
| Certificate validation | performed and passed |
| Hostname verification | performed — `peer CN = inference.lan` |
| CA trust | the machine's own CA store, unioned with certifi |
| Narration | 3 turns, 4.0–10.7 s |
| Model listing/discovery | via the same trust path |
| Embeddings | 1 memory embedded through the LAN host |
| Settings / Test Connection | same trust path |
| Retry | new take filed, both attempts retained (§6.4) |
| Restart and resume | digest `66cc82944f8b6eef` unchanged; endpoint and timeout preserved |
| Capture | 308 packets to the approved host, 364 loopback, **0 elsewhere, 0 DNS** |
Every model request went to the configured host: 4 `chat/completions`, 1
`embeddings`, nothing else.
**No `verify=False`, insecure fallback or "ignore certificate errors" path
exists.** The only textual match for such a thing in the tree is prose in
`tlstrust.py` saying it deliberately does not exist. All four clients use the
same context, enforced by an AST-walking test that also fails if a *fifth*
client appears (§8). No client uses different trust behaviour.
---
# I. QuickJS and scripting removal
Removed: the QuickJS dependency, `app/scripting/` entire, both routers, the
`onInput`/`onModelContext`/`onOutput` hooks in the turn engine, the `Script` and
`AdventureScript` models, script schemas, script export/import (bundles that
carry `scripts` now import with the story intact and the scripts ignored), the
Scripts page, the script editor, the in-play Scripts panel, the script-state
drawer and the Insights script report.
**Imported content cannot execute JavaScript.** There is no engine to execute it
in — `import app.scripting` raises `ImportError` and no module imports `quickjs`
(§12). A scenario or bundle carrying script source is data that nothing reads.
## Test-coverage accounting
This is where a subtractive milestone can hide damage behind a green number, so
it is spelled out. Of 88 node IDs that disappeared, **4 are renames** and 84 were
genuinely retired (§4).
| Category | Count | Verdict |
| --- | ---: | --- |
| Whole files whose subject was removed (`analytics`, `guest_cleanup`, `accesslog`, `ratelimit_hardening`, `reasoning_param`) | 64 | Obsolete product behaviour intentionally deleted. No coverage lost — the behaviour is gone. |
| `test_netguard.py` | 5 | **Replaced**, not lost: `test_endpoint_policy.py` (31 collected) covers the inverted rule far more thoroughly. |
| `test_chat.py` demo-key pinning and power-user gate | 8 | Subject removed. The file keeps and extends what the page still does. |
| `test_prompt_caching.py` OpenRouter routing | 4 | Subject removed. The prompt-layout and usage tests, which are the file's point, are untouched. |
| `test_memory_rewrite.py` Postgres DSN masking | 2 | Subject removed with Postgres. |
| `test_branch_clause.py::test_user_scripts_are_handed_the_path` | 1 | **Equivalent coverage retained.** It asserted the scripting history API saw the branch path; the test directly above it asserts the same invariant one layer down on `history.story_actions`/`count`/`tail`, which is where the branch clause lives. |
| Instrumentation conversion, 8 files | 0 retired | **Coverage retained in full.** A JS counter was measuring the *state snapshot and rollback machinery*, which M2 does not touch. The counter moved to the world-state engine; the assertions are unchanged in substance. |
**No meaningful coverage was lost.** One area gained a great deal: endpoint
policy went from 5 tests of the opposite rule to 31 of the current one.
---
# J. Settings surface, and the model timeout
## Settings after M2
**Remains:** Ollama endpoint (with help text stating the policy), narrator model,
embedding model, temperature, max output tokens, context budget, API mode,
narrator prompt, memory-bank capacity and top-k, **model timeout**, Test
connection, and the provider debug log.
**Removed:** the API key field and its "Remove key" button, the demo-key banner,
the reasoning budget, and the "OpenAI-compatible" framing on the endpoint field.
**Is it correct for v1?** Yes. Every field maps to something the product does,
and nothing offers a capability the product refuses. It is not *polished* — that
is M8 — but it is not misleading, which is what M2 asked for.
One onboarding gap survives from M1 and is not new: `Settings.model` defaults to
`""`, so a fresh install cannot generate a turn until a model is named, and
nothing prompts. M2 improves the *diagnosis* — the connection test now warns when
the endpoint is reachable but has no model by the configured name — without
fixing the onboarding, which is M8's.
## Model timeout
| | Value |
| --- | --- |
| Connect timeout | 10 s, constant — a wrong address should fail fast |
| Generation/read timeout | `Settings.model_timeout_seconds`, default **300 s** |
| Allowed range | 30–3600, enforced by the schema (422 outside) |
| UI | a numeric field with help text about cold loads |
| Config source | database row, not an environment variable |
| Embeddings | separate 60 s constant — short calls that never cold-load |
| Connection test | separate 15 s constant — a listing, not a generation |
**Demonstrated no longer a fixed 120 s constant:** `test_the_timeout_is_configurable`
sets 900 through the API and reads it back;
`test_the_configured_timeout_reaches_every_generating_client` drives the turn
endpoint, the chat endpoint and the summariser factory with a recording provider
and asserts the configured value reaches each; `test_an_unusable_timeout_is_refused`
rejects 0, −1, 29 and 3601. The offline run used 600 s and the LAN run used 600 s,
both read back after restart (§5.8, §6.5).
The retained fixed timeouts are the three above, each named and each justified by
the shape of the call.
---
# K. Important surprises
Four. None invented for completeness.
## K.1 An address policy written the obvious way is wrong
Writing the endpoint rule around `ipaddress.is_private` / `is_global` /
`is_reserved` — which is what the inherited `netguard.py` did and what any
reviewer would expect — produces a rule that **refuses IPv6 loopback**
(`::1` is classified reserved) and **accepts the documentation ranges** (they
are classified private). The first was caught by a test asserting
`http://[::1]:11434/v1` is allowed. This is worth knowing beyond this project:
the standard library's classifications answer a different question than "is this
on my own network".
## K.2 Removing scripting made the product depend on the world-state engine — in the tests
Eight test files used a QuickJS counter as instrumentation for the state
rollback machinery. The natural replacement was the world-state engine, so those
tests now assert rollback *through* the RPG delta protocol. **M5 plans to replace
that protocol** with typed narrative-state events. M5 will therefore have to move
this instrumentation a second time. It is cheap — the counter is one schema entry
and one reply template in `tests/fakes.py` — but M5's brief should say so rather
than discover it.
## K.3 The largest surviving subsystem is the one M2 could not touch
`migrations.py` is **1 128 lines**, the biggest file in the backend, and M2
reduced it by one line while adding one. It carries the full history of a schema
that M2 has now partly orphaned: migrations that create `scripts`,
`analytics_daily` and `access_log`, and backfills for `state_after`. This is
correct — migration history must not be rewritten — but a reviewer expecting the
"trust and maintenance surface" to have shrunk proportionally should know that a
tenth of the backend is history that only grows.
## K.4 Two defects hid in exactly the places a subtractive milestone cannot see
Both regressions (§A.1) were invisible to a 604-test green suite, for the same
reason: the code that still reached for a removed thing sat in a path no test
executed with real objects. The memory-bank factories are stubbed in every
memory test; the timeout argument was never asserted. **The lesson is a testing
one, not a coding one:** after removing an attribute, the cheapest useful test is
one that constructs each consumer from a real object, and after adding a setting,
one that proves it arrives. Both now exist.
---
# L. Acceptance matrix
| Requirement | Result | Evidence / notes |
| --- | --- | --- |
| Single-user, no login | PASS | §12 — four auth routes 404 |
| Hosted account/guest/demo removed | PASS | §C.1, §D |
| Hosted rate-limit policy removed | PASS | `limits.py` 345→~150 lines; resource bounds kept |
| Analytics/Visitors removed | PASS | §E |
| No telemetry generated | PASS | §5.9 — 0 non-loopback unicast in 5 131 packets |
| Render path removed | PASS | `render.yaml` deleted |
| Neon path removed | PASS | §F |
| Postgres runtime removed | PASS | `psycopg` gone from requirements and closure |
| SQLite M1 data still works | PASS | §5.8 — digest survives image replacement and restart |
| Ollama-only production provider | PASS | §G |
| Cloud API keys removed | PASS | §12 — absent from the API, unsettable |
| Public inference endpoints blocked | PASS | §7, §5.7 — including against a hand-edited DB |
| Loopback Ollama accepted | PASS | §7 — v4, v6 and `localhost` |
| Trusted-LAN Ollama accepted | PASS | §6.2 |
| TLS/private-CA support preserved | PASS | §6.1 |
| TLS verification preserved | PASS | §8 — no bypass exists; AST-enforced |
| QuickJS removed | PASS | §12 |
| Executable campaign scripting removed | PASS | §I |
| Settings narrowed to v1 model | PASS | §J |
| Connection diagnostics appropriate | PASS | five distinguished failure kinds + a model-not-found warning |
| Hardcoded 120 s limitation resolved | **PASS after the §9.2 fix** | Was PARTIAL as committed: the setting existed but was inert |
| Supported launch paths loopback-only | PASS | §11 — all four paths, test-enforced |
| Offline operation preserved | PASS | §5.1, §5.4 |
| Story/tree/retry preserved | PASS | §6.4 — `take_count 2`, both attempts retained |
| Context inspection preserved | PASS | §5.8 |
| Memory isolation preserved | **PASS after the §9.1 fix** | §5.6 — negative control holds. Was FAIL as committed: the bank was dead |
| No M3 work started | PASS | Undo still destructive, no Redo, no head cursor |
Two rows are "PASS after the fix". As committed at `8c65ae9` they were **FAIL**
and **PARTIAL**. Both fixes are in the working tree; neither is a blocker,
because both are corrected and tested — but the commit itself does not meet the
criteria, which is why §N recommends a follow-up commit before M3 begins.
---
# M. V1 acceptance-test mapping
| ID | Result | Notes |
| --- | --- | --- |
| **A01** offline startup | PASS | §5.1, §5.4 |
| **A02** loopback default | PASS | §5.2, §6.1, §11 |
| **A03** no cloud API key | PASS | Stronger than at M1: the field no longer exists |
| **A04** restart persistence | PASS | §5.8, §6.5 |
| **A05** failed model call integrity | PASS | §5.7 — accepted AI turns held at 3 across two induced failures |
| **A06** trusted-LAN Ollama | PASS | §6 — real second machine, HTTPS, private CA |
| **H01** no unexpected outbound | PASS | §5.9, §6.6 |
| **H02** no telemetry | PASS | §E |
| **H03** no cloud provider required | **PASS, and now in its preferred form** | H03 says the *preferred* final v1 is "cloud provider controls are absent, not merely unused". M1 met the base condition; **M2 meets the preferred one.** |
| **H04** model output cannot execute shell/tools | PASS, strengthened | The only execution surface was QuickJS, now removed. No shell, MCP or tool framework exists. |
| **H10** local API/CORS behaviour | PASS, strengthened | `AIDND_CORS_ORIGINS="*"` refuses to start; an unknown `/api` path 404s instead of returning HTML 200 |
| **H11** no first-use runtime download | PASS | §10.1, §10.2 |
Two acceptance tests deserve planning attention (§O): A05's wording, already
corrected post-M1, and H10, which M2 has now exceeded in a way the test does not
describe.
---
# N. Security review of the simplified product
## Resulting architecture
```text
Browser (loopback only)
│ same-origin; CSP names no remote origin
▼
Storyteller — FastAPI + SPA, bound 127.0.0.1:8000, no authentication
│
├─► SQLite on the local filesystem (the only persistence)
│
└─► exactly one approved Ollama endpoint (endpoints.py)
same-host loopback OR a user-named address on their own network
HTTP, or HTTPS verified against the machine's CA store
```
## Every remaining way story text could leave the machine
Found by static search plus runtime confirmation, not by assuming dead code is
unreachable:
| Path | Status |
| --- | --- |
| `providers/openai_compatible.py` — 3 clients | The intended egress. Policy-checked before every request, TLS-verified. |
| `routers/settings.py` — 1 client | Model listing. Same policy, same trust context. |
| `endpoints.py` — `getaddrinfo` | Resolves names for the policy. Opens no connection. |
| Analytics / telemetry | **Gone.** |
| Remote runtime assets | **Gone** since M1; re-verified (§10.2). |
| Cloud provider constants | **Gone.** |
| Hosted auth | **Gone.** |
| Arbitrary endpoint use | **Refused** by address (§7). |
| Scripting runtimes | **Gone.** |
| Shell / MCP / tool frameworks | Never existed. |
| Remote database | **Gone.** |
Only four modules in `backend/app` can open an outbound connection at all, and
the only absolute remote URL left in backend code is a `SOURCE_URL` constant in
`encoding.py` documenting where the vendored tokenizer table came from — never
fetched (§8).
## Residual risk, stated plainly
1. The API is **unauthenticated by design**. Loopback binding is the whole
control. Publishing the port defeats it; the code refuses the easy mistakes
(wildcard CORS, the default compose mapping) and the documentation warns
about the deliberate one.
2. A hostile host **on the user's own LAN** is permitted by the endpoint policy,
because that is what trusted-LAN means.
3. The **Ollama service has its own network behaviour** (`ollama.com`), outside
this codebase and inside the user's trust boundary. Unchanged from M1 and
still worth settling before release.
---
# O. Planning-document recommendations
Reported, not applied. No planning document was edited by this task.
### 1.
```text
Document: BUILD-MILESTONES.md, M5
Recommended change: Note that eight test files now use the world-state delta
protocol as instrumentation for state rollback, and that
replacing that protocol means moving the instrumentation
(one schema entry and one helper in tests/fakes.py).
Why M2 evidence: §K.2 — the QuickJS counter those tests used was replaced
with the RPG engine, which M5 plans to replace in turn.
Urgency: later (before M5 is briefed)
```
### 2.
```text
Document: SECURITY-THREAT-MODEL.md
Recommended change: Record the endpoint policy as implemented — an explicit
allowlist of networks, applied on save and before every
request — together with what it does not guarantee: a
hostile host on the trusted LAN, and the rebinding window
between the policy's resolution and the connection.
Why M2 evidence: §F. The threat model predates the policy and describes the
inherited SSRF guard's opposite rule.
Urgency: before M3
```
### 3.
```text
Document: V1-ACCEPTANCE-TESTS.md, H10
Recommended change: H10 currently reads only "privileged local APIs do not
allow arbitrary wildcard cross-origin writes". M2 goes
further: a wildcard origin makes the app refuse to start,
and an unknown /api path 404s rather than returning the SPA
with status 200. State both as pass conditions.
Why M2 evidence: §11. Both were defects found and fixed during M2; without
a test that names them they can regress unnoticed.
Urgency: later
```
### 4.
```text
Document: TECHNICAL-DESIGN.md §5.1
Recommended change: Mark items 3 and 4 of the hardening list resolved. Item 3
(hosted/auth/analytics/Postgres/cloud/QuickJS) is done in
full; item 4 (endpoint validation reflecting this product's
threat model) is done by endpoints.py.
Why M2 evidence: §C, §F. The document currently marks both open — M1 left
them so.
Urgency: before M3
```
### 5.
```text
Document: DECISIONS/ — a new ADR
Recommended change: Record the endpoint policy as a decision: address-based
allowlist rather than hostname matching, deny by default,
enforced at save and at request time, never traded against
TLS verification. Include the ipaddress-classification
finding as the reason the CIDRs are spelled out.
Why M2 evidence: §F, §K.1. This is a load-bearing security decision that
currently exists only as a module docstring.
Urgency: before M3
```
### 6.
```text
Document: SPECIFICATION.md
Recommended change: None. M2 changed no product requirement; it removed
capability the specification never asked for.
Urgency: —
```
---
# P. Technical debt after M2
| Item | Classification | Note |
| --- | --- | --- |
| **The three §9 fixes are uncommitted** | **pre-release — do first** | Six files ahead of `8c65ae9`. Until committed, the branch's HEAD contains a dead memory bank. |
| `Settings.model` defaults to `""`; nothing prompts | M8 | Inherited from M1. Diagnosis improved, onboarding not. |
| Ollama's own `ollama.com` lookup | pre-release | Outside this codebase, inside the product's claim about itself. |
| Inert tables and columns | optional cleanup | Safe legacy remnants. A cleanup migration is cheap once the schema settles — after M3/M5, not before. |
| `migrations.py` at 1 128 lines | optional cleanup | Dead/inert history, not active behaviour (§K.3). |
| 4 pre-existing unused imports | optional cleanup | Present since M1; `pyflakes` is otherwise clean. |
| Unused `request: Request` parameters in three routers | optional cleanup | Left by removing the rate limiter. Harmless. |
| No frontend tests | M8 | None existed at M1 either. Lint and build only. |
| `docs/*.html` links Google Fonts | M8 or pre-release | Upstream's project site; not served by the app. |
| Rebinding window in the endpoint policy | optional | §F. Requires an attacker already on the trusted LAN. |
**Nothing here is a blocker for M3** except committing the fixes, which is
housekeeping rather than engineering.
---
# Q. M3 readiness
M3 is the production history work: non-destructive Undo, Redo, active-head
movement, divergence, and active-head export/import.
**Did M2 alter the chokepoints M3 will modify?** Barely, and helpfully:
| M3 chokepoint | M2's effect |
| --- | --- |
| `attempts.py` — snapshot/restore/rollback | `ATTEMPT_KEYS` lost `"script"`; `restore_state` and `snapshot_outcome` no longer carry script state. **One less shared state to move.** |
| `tree.py` — placement, head, lineage | **Untouched.** |
| `context/lineage.py`, `context/history.py` | **Untouched.** |
| `routers/adventures/takes.py` — retry, takes, undo | Only the removal of `ScriptPipeline` arguments and the demo cap. `undo_turn` is byte-for-byte the inherited destructive implementation. |
| `routers/adventures/turns.py` | Hook calls removed, so `generate_turn` has 4 parameters instead of 5 and no longer branches on script stop. **Simpler to reason about.** |
| `bundle.py` — export/import | `scripts`/`scriptState` no longer exported; old bundles importing them are ignored gracefully. M3 adds the active-head field to a smaller format. |
**Is the Phase 0B undo/redo spike still applicable?** Yes. It touched three
backend files — the tree, the attempt machinery and the takes router — and M2
changed none of their logic. If anything the spike is easier to apply now: it no
longer has to carry `script_state` alongside `world_state` through every
rollback.
**Did the removals simplify or complicate M3?** Simplified, in three concrete
ways: one shared state instead of two through the rollback paths; no demo-cap or
rate-limit preconditions wrapped around the turn and retry endpoints; and a
provider constructed from `Settings` directly rather than through a
`ProviderConfig` indirection.
**Tests M3 should preserve or rewrite.** Preserve as the contract:
`test_story_tree_baseline`, `test_retry_variants`, `test_take_state`,
`test_take_parentage`, `test_attempt_siblings`, `test_branch_forking`,
`test_delete_state`, `test_state_revert`, `test_bundle_v2`. **Note that these now
carry the world-state instrumentation** (§K.2) — M3 must not mistake it for RPG
coverage. `test_state_revert` and `test_delete_state` assert *destructive* undo
semantics and will need rewriting when undo stops deleting; that is expected M3
work, and those files should be rewritten rather than deleted.
**Anything to fix before history changes?** Only the uncommitted fixes. Nothing
M2 discovered touches history semantics.
**Should M3 proceed as planned?** **Yes, unchanged in scope.** Two additions to
its brief: it inherits a single shared state rather than two, and it must be told
that the state-rollback tests are instrumented through the world-state engine.
---
# R. Final recommendation
```text
Recommendation: ACCEPT M2 WITH NON-BLOCKING DEBT AND PROCEED TO M3
```
**Reasons.**
1. Every M2 requirement is met, and the ones that matter most were tested at
runtime rather than read: cloud endpoints refused against a hand-edited
database, trusted-LAN HTTPS working against a real second machine with
verification on, and captures showing zero packets outside loopback and the
approved host.
2. The product is materially simpler, not just smaller: 52 API routes → 36, ten
environment variables → two, 6 Python packages and 21 npm packages gone,
−2 666 backend lines, −1 284 frontend lines, and a 933 kB bundle down to
395 kB. The trust surface shrank in the places that carry story data.
3. H03's *preferred* v1 condition — cloud controls absent rather than unused —
is now met, which M1 could not claim.
4. No M1 capability is regressed **in the working tree**. Two were regressed in
the commit; both are fixed and both now have the tests that would have caught
them.
5. M3's chokepoints are untouched or simplified, and the Phase 0B spike still
applies.
**The one thing to do first** is commit the six-file fix (§A.1). Until then the
branch head contains a silently broken memory bank, and anyone building from
`8c65ae9` would inherit it.
The three planning corrections marked *before M3* in §O — the threat model, the
technical-design hardening list, and a new ADR for the endpoint policy — are
documentation of decisions already made, not new work, and can be done alongside
the M3 brief.
---
# S. Closeout note — appended 2026-09-03
**Appended after the fact.** Sections A-R above were written on 2026-09-02 and
are left as they were, including §A.1's and §P's statements that the fixes were
uncommitted at the time. Those statements were true when written and are the
reason this note exists rather than an edit.
## The one thing §R said to do first
§R closed with: *"The one thing to do first is commit the six-file fix (§A.1).
Until then the branch head contains a silently broken memory bank."*
Done:
```text
8652fe7cd84bca5173abb03b2a692f15fea8a98c M2 review: two regressions the green suite hid, and the reports
```
The commit carries the six implementation/test/lockfile files **and** these two
reports. `8c65ae9` remains the M2 implementation commit and was not amended or
squashed, so the provenance distinction §R wanted — original implementation
versus review-discovered correction — survives in the history.
Confirmed present in that commit, against `8c65ae9`:
| Defect | Fix as committed |
| --- | --- |
| §9.1 dead memory bank | `memorybank.py` — both provider factories stop reading the removed `Settings.api_key_plain`; `summary_provider` now passes `model_timeout_seconds` |
| §9.2 inert timeout | `turns.py`, `chat.py` and the summariser factory pass `settings.model_timeout_seconds` into the provider |
| §9.3 stale lock | `requirements.lock` drops `quickjs`, `psycopg`, `psycopg-binary`, `cryptography`, and the transitive `cffi` and `pycparser` |
| — | `test_local_only_surface.py` gains the two regression tests: every factory built from a real `Settings` row, and the configured timeout arriving at each generating client |
The separate short timeout classes were kept, as §9.2 required: `CONNECT_TIMEOUT`
(10 s), `EMBED_READ_TIMEOUT` (60 s) and the connection-test/model-list path are
unchanged, and only the generation read timeout became configurable.
## Verification at closeout
Re-run on 2026-09-03 against the **committed** tree, working tree clean:
```text
backend pytest tests/ -q 606 passed in 133.26s
tests/test_local_only_surface.py 32 passed
test_endpoint_policy + test_tls_trust + test_offline_assets
47 passed
frontend npm run lint 7 warnings, 0 errors, exit 0
frontend npm run build 395.41 kB, exit 0
root docker build exit 0
image quickjs/psycopg/cryptography/cffi/pycparser absent (32 packages)
```
The packet-capture exercises were not repeated; the corrected files do not touch
the network boundary. See §15 of the baseline report.
## Planning recommendations from §O
Three were marked *before M3* and are now applied, in commit
`Planning: record M2 closeout decisions`:
- **§O.2** — `SECURITY-THREAT-MODEL.md` §10A records the endpoint policy as
implemented, with both residual limits stated; §71A item 5 is marked resolved;
§77 notes the required defaults are now met.
- **§O.4** — `TECHNICAL-DESIGN.md` §5.1 items 3 and 4 are marked done, and a new
§5.2 records the M1/M2 production architecture as fact rather than intention.
- **§O.5** — **ADR 011, *Local Inference Endpoint Policy***, records the
decision, including the `ipaddress`-classification finding from §K.1 as the
reason the CIDRs are spelled out.
The remaining three are also applied, ahead of the *later* urgency §O gave them,
since they are one-paragraph edits: **§O.1** as an M5 note in
`BUILD-MILESTONES.md` about the world-state instrumentation, and **§O.3** as a
strengthened H10 in `V1-ACCEPTANCE-TESTS.md`. **§O.6** correctly asked for no
change to `SPECIFICATION.md`, and none was made.
Two additions beyond §O, both drawn from evidence in this report:
- an M6 note in `BUILD-MILESTONES.md` requiring background memory failure to be
observable and at least one real provider-construction path to be tested —
§A.1 and §9.1 are the argument for it;
- **H12, *Inference Endpoint Enforcement***, in `V1-ACCEPTANCE-TESTS.md`, whose
fourth pass condition is the database-edited-behind-the-API case this review
demonstrated at runtime in §F.
`BUILD-MILESTONES.md` also gained M2's `## Status: COMPLETE` block, matching M1's.
## Not done in this closeout
M3 was not begun. Undo still deletes, and there is still no Redo. The debt table
in §P is unchanged apart from its first row, which this note closes.