docs: write the RFC 003 that the code has been citing all along, plus an operator-facing fleet-memory guide
`logstream.py`'s module docstring is headed "Agent coordination event log for MemPalace (RFC 003)" and enumerates five "Design constraints (RFC 003)". Comments cite "RFC 003 phase 5", "RFC 003 suggested defaults" and "the first RFC 003 dogfood". Every event/artifact tool description cites RFC 003. The document has never existed — confirmed by searching this repo and the primary host. So this is a retrospective spec: it transcribes what the implementation already believes, and records what it does NOT do. docs/rfc-003-coordination-log.md, verified line-by-line against mempalace 3.8.0 (every claim cites file.py:LINE, indexed in §10 for re-verification). The parts that are not visible from the tool descriptions: - No idempotency guard on event_append or put_artifact (§7.1). The replication path checks `id OR (origin_replica, origin_seq)` before applying; the client path checks nothing. So peer replay is safe and CLIENT RETRY IS NOT — a retried append forks a coordination thread into two ids. This makes the fleet's "a timeout is not a failure, verify before retrying" rule load-bearing rather than advisory. - Coordination traffic is deliberately exempt from BOTH palace locks (§4) — _HTTP_LOCK_FREE_TOOLS and _PEER_WRITER_EXEMPT_TOOLS, each with its own rationale in-source. "One large mine blocks every client" is true of drawer writes and false of coordination writes. - `mempalace sync` never touches the log, and no DELETE FROM events exists anywhere (§2, §9.1) — answering for the logstream a question RFC 001 §7.2 left open, and making the log permanent and unbounded. - from_agent is shape-validated and never authenticated; there is no read scoping at all (§6). The log authenticates the fleet, not the agent. That is simultaneously the security limitation and the only way to positive-control the mailbox. - Three distinct orderings — seq (local arrival rowid), origin_seq (author's counter), hlc (fleet-wide, lexicographically sortable) — and origin_replica identifies the PALACE, not the writer, which is why from_agent/to_agent carry the whole distinction between machines (§3.2). - GET /logstream/events does not exist and never did (§7.8). An earlier measurement saw it 404 and blamed the reverse proxy; that inference was right for /sync/* and /logstream/stream and wrong for this one. Corrected in extensions/pi/README.md §3 too, in place, dated. docs/fleet-memory.md is the operator-facing companion the repo lacked entirely: the front-door README had zero mentions of coordination, so the channel was undiscoverable unless a message happened to arrive. It covers the five stores and what each is for (drawers/wings/rooms, diaries, KG, palace graph, coordination log), what a central palace buys a fleet — awareness, non-repetition of expensive work, and retractions that travel — and a decision flow for drawer vs KG vs event. Six mermaid diagrams, all rendered and inspected as images, not merely parsed: the first pass produced a truncated state label from an HTML entity and a self-loop that drew a meaningless dotted lasso. Validation says "no syntax error"; only looking says "correct". Also: a Documentation table in the top-level README so all of the above is reachable from the front door. Deliberately host-agnostic, per synlig-primary-runbook.md's precedent — no device names, hostnames or operator names in either new document.
This commit is contained in:
+11
-2
@@ -342,12 +342,21 @@ the mechanism; the skill is normative for behaviour.**
|
||||
an SSE endpoint (`GET /logstream/stream`, `text/event-stream` in
|
||||
`mempalace/mcp_server.py`), but a deployment may expose only the MCP endpoint
|
||||
through its reverse proxy — verified 2026-08-26 against
|
||||
`https://mempalace.jordbo.se`, where `/logstream/events`, `/logstream/stream`
|
||||
and `/sync/peers` all return 404 while `/mcp` serves normally. Where that is the
|
||||
`https://mempalace.jordbo.se`, where `/logstream/stream` and `/sync/peers`
|
||||
return 404 while `/mcp` serves normally. Where that is the
|
||||
case, polling through the existing MCP client is the only available path — which
|
||||
is what the mailbox in §2 does — and enabling SSE means a proxy route plus an
|
||||
auth decision, not an extension change.
|
||||
|
||||
> ⚠️ **Corrected 2026-08-26.** An earlier revision of this paragraph listed
|
||||
> `/logstream/events` alongside those two as proxy-blocked. That route **does not
|
||||
> exist in the server at all** — the complete GET table in mempalace 3.8.0 is
|
||||
> `/healthz`, `/statusz`, `/logstream/stream` and `/sync/{version_vector,ops,artifact,peers}`,
|
||||
> so `/logstream/events` would 404 against a directly-reachable server too. The
|
||||
> proxy inference was right for the other two and wrong for that one; see
|
||||
> [RFC 003 §7.8](../../docs/rfc-003-coordination-log.md). Distinguish *route absent*
|
||||
> from *route blocked* before blaming infrastructure.
|
||||
|
||||
As with stamping, all of this is inert unless `MEMPALACE_REMOTE_URL` points at a
|
||||
shared palace. On a solitary palace the event tools work fine and the log
|
||||
contains only this machine's own events.
|
||||
|
||||
Reference in New Issue
Block a user