joakimp/mempalace-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reconcile the RFC-001 docs with what is actually deployed

Browse Source 
Audit of every doc touching the global-palace rollout against the running
fleet. Each correction below was verified against the filesystem or the host,
not against another doc:

- synlig-primary-runbook: the decommission `rm -rf ~/.mempalace` now carries a
  STOP block. That tree holds the fleet palace *and* the only copy of the
  bearer token every client authenticates with; the old "empty today" comment
  stopped being true when the palace was seeded on 2026-08-14. Adds an ordered
  safe decommission, and drops count-based join verification.

- phase-1-exposure-runbook: new S3.8, how to verify a flip actually took --
  the procedure that until now existed only in an untracked handover file.
  Three claims that fail independently (env var / curl / the palace-path
  discriminator) plus an explicit list of checks that produce FALSE POSITIVES:
  drawer counts (both sides were seeded from the same palace, and `status`
  counts chunks not drawers), write-then-read through the same transport, and
  the `mempalace` CLI -- which has no remote support at all, so post-flip it
  reads the dead local archive and reports success.

- rfc-001: status Draft -> Phases 0-1 implemented. Records that the join was a
  file-level copy, which SIDESTEPPED the S7.6 diary-dedup question rather than
  answering it -- so S7.6 remains a hard blocker for the second machine, which
  is the one that will actually exercise merge semantics.

- ARCHITECTURE, SKILL, contrib/README, extensions/pi/README all claimed pi
  feeds the palace automatically, unconditionally. That is gated on
  mempalace-toolkit >= 29e660e and every deployed image predates it, so the
  claim is currently false fleet-wide. Each site now states the gate plus a
  check that inspects the *deployed* file rather than repo HEAD.

- extensions/pi/README: plaintext http://mempalace.lan example -> https
  endpoint; the two transports are either/or (no dual-write, no local mirror);
  the bridge fails CLOSED, so "the agent has no mempalace_* tools" is the
  expected symptom of a server/token/DNS fault, not of a broken install.

- contrib/README: documents mempalace-serve.service, which this directory has
  shipped since day one without explaining it (linger, the load-bearing
  172.17.0.1 bind and why loopback is the unsafe-looking-safe option, the
  token path, and an uninstall warning).

- Fixes a pre-existing stray ```sh fence that was swallowing S3.2's heading and
  the token command into a code block.

Docs only; no behaviour change.
This commit is contained in:
Joakim Persson
2026-08-14 22:57:22 +02:00
parent 2293f1c89b
commit ec436ed3ad
7 changed files with 443 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/synlig-primary-runbook.md
+75 -6
View File
@@ -3,6 +3,18 @@
Companion to [`rfc-001-global-palace.md`](./rfc-001-global-palace.md). Records what was actually done
on the primary, with verified evidence, so the next session (or the next machine) does not re-derive it.
> **Status 2026-08-14 17:00 — SUPERSEDED IN PART. The primary is live, exposed, and seeded.**
> Serving since 2026-08-12 at `https://mempalace.jordbo.se/mcp`. Seeded 2026-08-14 15:07 from
> EMB-7KJ4VR4G's palace — 14,777 drawers / 9 wings / 16,337 embeddings / KG 46 entities, 34 triples,
> now 14,803 drawers. One client (EMB-7KJ4VR4G's pi-devbox container) is flipped and verified
> end-to-end. Both Phase 0 blockers below are cleared.
>
> **Read §3 "Deliberately NOT done" as a record of the 2026-08-10 state, not of today's** — every
> item in it has since been done. And before running anything in §5 Rollback, read the warning at the
> top of it: `~/.mempalace` on synlig is no longer disposable.
Original status, kept for the record:
**Status 2026-08-10 00:30 — Phase 0 prep complete. Not serving. Nothing exposed.**
Blocked on two things, both deliberately left to Joakim: the Pangolin update on nyvaken, and one `sudo`.
@@ -62,10 +74,21 @@ ln -sfn palace/knowledge_graph.sqlite3 ~/.mempalace/knowledge_graph.sqlite3
ln -sfn palace/known_entities.json ~/.mempalace/known_entities.json
```
Relative targets, so a home-directory move survives. `hallways.json` is deliberately **not** symlinked:
Relative targets, so a home-directory move survives. `hallways.json` was originally left **un**symlinked:
it is already palace-derived, and its HOME path is a warning-only legacy probe (`hallways.py:73-95`) that
never auto-migrates.
> **Update 2026-08-14 — `hallways.json` is now symlinked too**, during the seeding session:
> ```sh
> ln -sfn palace/hallways.json ~/.mempalace/hallways.json
> ```
> Rationale changed: the point is no longer "only symlink what the code demands" but *all real state
> lives under `palace/` as a single backup unit*, so one `palace/` copy is a complete copy. All three
> parent-level paths now resolve, which matters because mempalace 3.6.0 resolves these three paths
> inconsistently (MCP server: palace-relative; KG CLI default: `~/.mempalace`; `hallways.json`:
> `dirname(palace_path)`; `known_entities.json`: hardcoded `~`). Revert by deleting the symlink if it
> ever causes trouble.
Verified the symlink assumption rather than trusting it (`python3 sqlite3` on synlig, temp dir):
| Check | Result |
@@ -119,10 +142,21 @@ standing up a network-reachable service while you were asleep was not mine to de
## 3. Deliberately NOT done
> **⚠️ Historical — this section describes 2026-08-10 and is no longer true.** All five items were
> done between 2026-08-12 and 2026-08-14. Kept because the *reasoning* for deferring them is still
> the record of why the order was chosen. Current state per item is inlined below.
- **Nothing is serving.** No listener on 8765; no mempalace process. Re-verified at the end of the run.
→ **Now serving** since 2026-08-12 (`mempalace-serve.service`, `systemctl --user`), reachable at
`https://mempalace.jordbo.se/mcp` via newt/Pangolin.
- **No client `.env` was touched.** Your working setup is exactly as you left it (R6: reversible).
→ **One client flipped 2026-08-14**: four variables on EMB-7KJ4VR4G, `docker-compose.yaml` unchanged.
Still reversible in ~30s (§3.8 of [`phase-1-exposure-runbook.md`](./phase-1-exposure-runbook.md)).
- **No data joined.** The palace is empty. The §4.4 join needs the diary-dedup decision (§7.6) first —
replaying diaries today duplicates them, and the primary is the one place that must stay clean.
→ **Seeded 2026-08-14** from *one* palace by file-level copy. This sidestepped §7.6 rather than
solving it: a file-level copy replays no diaries, so it cannot duplicate them. **§7.6 is still a
hard blocker for the second machine to join.**
- **nyvaken untouched.** Read nothing, changed nothing.
- **No sudo.** `sudo -n` on synlig requires a password.
@@ -167,13 +201,48 @@ standing up a network-reachable service while you were asleep was not mine to de
pointing any client at it.
6. **Then, and only then**, Phase 1 client flip — one machine first, and remember opencode containers
need the §4.1 sidecar merge (or Phase 1.5) before the `.env` takes effect.
7. **Before the first join:** settle §7.6 diary dedup, then dry-run §4.4 from **one** palace and check
counts.
7. **Before the first join:** settle §7.6 diary dedup, then dry-run §4.4 from **one** palace.
> **Correction 2026-08-14 — do NOT verify a join "by checking counts", which is what this item
> originally said.** Counts are not evidence, in either direction. `mempalace status` counts
> **chunk rows**, not logical drawers (3 drawers plus one 2-chunk diary presented as +9), and chunk
> counts legitimately differ between two palaces whenever a drawer was updated on either side,
> because an update re-chunks to the new length and deletes the surplus rows. Diffing chunk-id sets
> is a useful first pass but **over**-reports: a chunk id present on one side only is the ordinary
> signature of an edit, not of loss. This cost real time on 2026-08-14 — a missing
> `chunk_000007` was read as a truncated seed, when in fact the two palaces held two revisions of
> one drawer and nothing was lost. **Adjudicate by fetching the parent drawer on both sides and
> comparing the reassembled `content`.**
## 5. Rollback
> **⚠️ STOP — 2026-08-14. Do not run this block as it was originally written.** `~/.mempalace` on
> synlig is now the fleet primary. That tree holds the only central palace (14,803 drawers, seeded
> from EMB-7KJ4VR4G) **and the server's bearer token** at `~/.mempalace/server/<hash>/token` — the
> single credential every flipped client authenticates with, of which there is no second copy.
> `rm -rf ~/.mempalace` destroys both. The original comment ("empty today — check before running once
> it isn't") is far too soft for a destructive command someone runs under pressure, which is exactly
> why it is being replaced rather than amended.
Stopping the service is safe and reversible on its own, and is the whole of what "rollback" should
normally mean now:
```sh
systemctl --user disable --now mempalace-serve # if enabled
~/.local/bin/uv tool uninstall mempalace
rm -rf ~/.mempalace # empty today — check before running once it isn't
systemctl --user disable --now mempalace-serve # clients fail CLOSED — they lose the palace
# tools; they do NOT fall back to a local palace
```
To genuinely decommission the primary, in this order:
1. Flip every client back first (§3.8 of [`phase-1-exposure-runbook.md`](./phase-1-exposure-runbook.md),
in reverse) so nothing is pointed at a host that is about to lose its palace.
2. Copy `~/.mempalace/palace/` **and** the token file off the host, and verify the copy by comparing
reassembled drawer `content`, not counts (see §4 item 7).
3. Only then remove anything. Never `rsync --delete` into `~/.mempalace` — the token lives inside it.
The two destructive steps below were written on 2026-08-10, when `~/.mempalace` was genuinely empty.
Kept for the record; **must not be run while the primary is live**:
```sh
~/.local/bin/uv tool uninstall mempalace
rm -rf ~/.mempalace # ⚠️ DESTROYS THE FLEET PALACE AND THE ONLY TOKEN
```