@dreamforgestudiollc/emet 0.0.0-stage → 0.2.6

package/docs/DEPLOY.md

@@ -0,0 +1,251 @@
+# Deploying EMET as a remote MCP server
+
+This deploys `src/http-remote.js` as an OAuth-protected HTTPS endpoint, so hosts that cannot
+run a local process — phones, tablets, web clients, third-party agents — reach the same
+memory store as your desktop.
+
+The memory logic is identical to the local server. Only the transport differs.
+
+## Prerequisites
+
+Finish **Stage 1** of [SETUP.md](SETUP.md) first. You need a `mongodb+srv://` URI with a
+scoped user, and Atlas Network Access set to `0.0.0.0/0` — a hosted platform's egress IP is
+dynamic, so it cannot be allowlisted. Security rests on the scoped user plus the OAuth
+passphrase; both are required.
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `MONGODB_URI` | yes | Atlas connection string, scoped user. |
+| `MONGODB_DB` | yes | Database name. Must match your other hosts, or they will not see each other's writes. |
+| `PUBLIC_URL` | yes | The public **https** base URL. This is the OAuth issuer and must match the deployed URL exactly. |
+| `EMET_OAUTH_PASSPHRASE` | yes | Typed once per device to authorize it. Make it strong — it is the only thing between the internet and your memory. |
+| `EMET_SOURCE_TAG` | optional | Default tag for a write that passes no `source`. Leave it unset on a server several hosts share (see below); set it only when one host uses this deployment. |
+| `EMET_SUBKEYS` | when more than one bot shares the owner login | `1` turns on delegated client sub-keys. On this kind of host, set it in the platform's variables. Setup refuses to write a pepper into the container `.env`. Restart or redeploy so the tools and `/owner/approvals` appear together. See [SUBKEYS.md](SUBKEYS.md). |
+| `EMET_SUBKEY_PEPPER` | with that flag | Server secret, at least 32 bytes, generated by the owner on a hosted deploy (`openssl rand -hex 32`). Not stored in the database. |
+| `EMET_SUBKEY_PEPPER_VERSION` | with that flag | `1` until the pepper is rotated. Set it with the other two, then redeploy. |
+| `EMET_TIMEZONE` | optional | IANA time zone that session ids are dated in, e.g. `America/Chicago`. Default `America/New_York`. An unknown name falls back to the default and `emet_session_open` says so. |
+| `EMET_CLOSE_GRACE_MINUTES` | optional | Minutes after a complete close in which a session still takes its one closing exchange (the reply sent after the close). Default `5`; `0` turns the window off; at most `60` (a larger value is capped at 60). A negative or non-numeric value is not used: the server logs a warning and uses `5`. |
+| `EMET_GAP_BASELINE` | optional | ISO date (or Unix seconds) from which the record is held to the current rules. The startup line then reports gaps since that date beside the lifetime figure. |
+| `PORT` | auto | Injected by the platform. |
+| `TRUST_PROXY` | not read | The server trusts exactly one proxy hop (Railway's edge). TRUST_PROXY is not read. The `/mcp` body limit is 256kb. |
+
+## Checklist before 0.2.3
+
+Read this before you deploy the release that follows 0.2.2. It does not change a version number. It is the list of settings and client habits that will start failing if you leave them as they were.
+
+- **`EMET_SOURCE_TAGS` must list every real host tag**, as an exact member. Tags named in this repository's example env, docs, and live-tag checks are: `cli`, `mobile`, `desktop-host`, `cloud-host`, `project-host`, `hub-bot` (the hub; do not also list it in `EMET_RECORD_DOCS`), `reviewer-bot`, `tester-bot`, `memory-bot`, `intake-bot`, and `research-bot`. Your install may use a shorter list. A tag that is not an exact member is refused, and the refusal does not print the list.
+- When a new bot joins the roster, append its tag to the end of `EMET_SOURCE_TAGS` and keep every existing tag in order, before its first write. The standing rule, including `EMET_RECORD_DOCS` and the `/health` and `emet_status` check after the redeploy, is [BOTS.md](BOTS.md) §4.
+- **`EMET_STRICT_LOGIN_TAG=1`** (off by default) makes a login's bound tag final: a write that declares a different `source` is refused, and so are `emet_setup_complete` and `emet_initialize` with a mismatched tag. Leave it off while bots share one login, because with it on every bot except the login's own would be refused. Turn it on only once each bot has its own login, for example a Member Access code bound to its tag.
+- **A scheduled job that still sends a `cloud-scheduled-` prefix must switch to an exact registered tag.** `cloud-scheduled-intake` was retired on 2026-10-02. A prefix is not a tag. The weekly intake runs under `intake-bot`.
+- **An HTTP client whose stored token has no source tag must sign in again.** Refresh of that token is refused. The new consent binds a registered tag. An empty registry has no members.
+- **Caps already in force.** A client that used to send more is refused, and nothing is written:
+  - 20 new drops per New York day, in one bucket: the whole local process on stdio, one shared visitor bucket for HTTP with no signed-in client, the source tag bound at approval when there is one, or that OAuth client otherwise. A source the caller types does not move the bucket.
+  - HTTP request body: 256 KB.
+  - A transcript field: 32,000 characters. The whole transcript request: 256,000 characters.
+  - Tool calls: 300 per minute for that person and client, and a per-tool cap (120 for `recall` and `semantic_recall`, 100 for `query_layer`, 30 for `emet_status`, 60 for `save_to_layer`, 60 for every other tool).
+  - Client-metadata fetches: 60 per host per minute, 120 in total, 64 KB, 5 second timeout. The connection uses the public address already checked. A redirect is refused.
+  - A document edit may not leave it under half the size this session first saw, and not under half of its largest size in the last 24 hours.
+  - Recall ranks in the store before it keeps a window of at least 200 rows, or 20 times the page.
+  - The window for one closing exchange after a complete close is at most 60 minutes.
+
+## Before you touch anything
+
+**Set the environment variables BEFORE the first deploy, not after.** A server that boots once
+with the wrong configuration creates collections, mints OAuth tokens, and generally leaves
+residue you then have to reason about. Variables first, deploy second.
+
+**Write down the current deployment id** if you are replacing a running service:
+`railway status` prints it. Rolling back is Dashboard → Deployments → that entry → Redeploy.
+
+**⚠ `railway variables` prints values in plaintext**, including your connection string and your
+passphrase. Use `railway variables --kv` and read only the key names unless you specifically
+need a value. Do not paste that output into a chat, an issue, or a screenshot. Redacting it
+afterwards does not work reliably - table output wraps long values across lines, and a
+credential split over two rows defeats the pattern you were counting on.
+
+## Railway
+
+```
+npm i -g @railway/cli
+railway login
+railway init                     # from the repo root
+railway up
+railway variables --set MONGODB_URI=... --set MONGODB_DB=emet \
+  --set EMET_OAUTH_PASSPHRASE=... --set EMET_SOURCE_TAGS=mobile,desktop,cli
+railway domain                   # get the public URL
+railway variables --set PUBLIC_URL=https://<app>.up.railway.app
+railway up                       # redeploy so PUBLIC_URL matches the live URL
+```
+
+One service serves every host, so register the hosts' tags with `EMET_SOURCE_TAGS` and leave
+`EMET_SOURCE_TAG` unset: a default tag makes every host look the same (see `.env.example`).
+Over HTTP, document, transcript, and memory writes use the tag bound when that host was
+approved. A local stdio host still passes an exact registered tag as `source`.
+
+**Tokens issued before source tags were bound.** An access token whose row has no `source_tag`
+can still write when the caller names a tag that is an exact member of `EMET_SOURCE_TAGS`.
+That is no wider than the registry: an empty registry has no members, and a tag that is only
+a prefix match does not count. Refreshing such a token is refused with `invalid_grant` and a
+message to sign in again, so the new consent binds a registered tag. The empty tag is not
+copied onto the replacement. Those logins age out on their own as each access token expires
+and the refresh is refused. After this deploy, a host whose writes are refused for a missing
+source tag signs in once. A member code can carry a registered tag: the owner sets `source`
+when creating the code, and redeem binds that tag.
+
+**The monorail runs in enforce only** (2026-10-03). There is no mode setting: every gate refuses a
+skipped step before anything is written, and the reply says how to pass. `EMET_SESSION_GRAPH` is
+no longer read; remove it from the service's variables in the Railway dashboard. If the session
+store cannot be read, a governed write that names a session is refused and nothing is written.
+Transcript writes and `emet_session_open` fail the same way
+([GUARDRAILS-AND-MONORAILS.md](GUARDRAILS-AND-MONORAILS.md)). The record of which startup
+pages each host fetched is kept in the server's memory for 60 minutes after its last page, so
+after every deploy or restart, or a longer pause, an open with an older `load_id` is refused once
+and told to call `emet_initialize {}` again.
+
+There is no setting to turn the monorail's refusals off. In an emergency, redeploy private main
+as it stood before this release (commit-9bf9096) and check EMET_SESSION_GRAPH first: unset or report flags
+skipped steps without blocking them (a closed session still takes no new exchanges, and a
+session-store outage still blocks transcript writes and `emet_session_open`); enforce keeps
+refusing; off stops consulting the graph, including the closed-session lock, so a closed session
+takes new exchanges again, a session-store outage blocks nothing, and closes are not recorded. That also rolls back every other change in this release, including
+byte-paged read_doc.
+
+When a close returns `complete`, the server records the session as closed before it sends the
+close's reply, **when that write succeeds**. A failed write is retried once; if it still fails, the
+reply says `closed_recorded: false` with a warning (the session is not locked yet; calling the close
+again records it).
+
+**Per-bot close records.** To run a bot in its own session, add `bots/<source tag>/HANDOFF.md` to
+`EMET_RECORD_DOCS` (comma list), e.g. `bots/intake-bot/HANDOFF.md`. That one id makes the tag a
+bot tag: its sessions close against `bots/<tag>/HANDOFF.md` with seven receipts and no board, only its
+own revisions count, and `write_doc`, `patch_doc`, `retire_doc`, `rename_doc` and
+`accept_nonconformance` refuse it the main handoff and board.
+`retire_doc` and `rename_doc` are refused to a bot tag for every document, not only the main
+records (retiring and renaming are the owner's and the hub's), and `emet_setup_complete` is refused
+to a bot tag.
+Do not map a bot's handoff to `templates/HANDOFF.md`: that template asks for a board a bot does
+not keep, so every bot close would be marked nonconforming. Bot handoffs have their own form,
+`templates/BOTHANDOFF.md`; while it is DRAFT, leave bot handoffs unmapped, and once it is IN FORCE
+add `bots/<tag>/HANDOFF.md=templates/BOTHANDOFF.md` to `EMET_TEMPLATE_MAP` (it marks conformance and
+never rejects a write). Setting `EMET_RECORD_DOCS` replaces its value: keep every entry already
+there and append. Nothing else is set, and no data changes shape. To undo it for one bot, remove
+its id from `EMET_RECORD_DOCS`: that tag goes back to the host rules (it cannot close without the
+main records) and the write refusal lifts. The id must match exactly (no leading `./`, the tag's
+exact case); a typo silently leaves the tag on the host rules and lifts the write refusal. Register
+the tag in `EMET_SOURCE_TAGS` as well, or its transcript appends are refused. Never list the hub's
+own tag (e.g. `hub-bot`): a listed tag can no longer write the main records.
+The full procedure — tag naming, the roster (`templates/ROSTER.md`), the session loop and
+corrections — is [BOTS.md](BOTS.md).
+
+**Write guards on records (both always on).** `write_doc`, `patch_doc`,
+`retire_doc`, `rename_doc` and `accept_nonconformance` apply two more refusals, and nothing is written
+when either fires:
+- *Registered hosts only on the main records.* When `EMET_SOURCE_TAGS` is set, a write to the main
+  handoff or board (`EMET_HANDOFF_DOC`, `EMET_STATE_DOC`) is refused unless its `source` is one of the
+  listed tags. A write with no `source` is refused too, and so is a misspelled or unlisted tag
+  (scheduled runs such as `cloud-scheduled-*` included). Before turning this on, make sure every tag
+  that writes the main records - the hub's own tag in particular - is in `EMET_SOURCE_TAGS`. With
+  `EMET_SOURCE_TAGS` unset nothing changes.
+- *A bot writes only its own folder; registered tags only under `bots/`.* A bot tag (one whose
+  `bots/<tag>/HANDOFF.md` is in `EMET_RECORD_DOCS`) is refused any write under `bots/` outside
+  `bots/<tag>/`: other bots' records and `bots/ROSTER.md` belong to the hub. With `EMET_SOURCE_TAGS`
+  set, a write under `bots/` by anything other than a listed bot also needs a registered tag: an
+  unregistered or misspelled tag, a write with no `source` (it falls back to `EMET_SOURCE_TAG`), and
+  `cloud-scheduled-*` runs are refused. Registered host tags still write anywhere under `bots/`.
+
+**Known gap (F-2, later).** A tag that is registered but not listed as a bot is a host for both
+guards, so it can still write the main records and any bot's folder. To fence a bot, set both
+variables in one change. **With `EMET_SOURCE_TAGS` unset, both guards are opt-in and off:** any
+caller can write the main records and every bot folder, so set the registry on any shared install.
+
+**Legacy `CASCADE_` names.** Only the settings read through `setting()` in `src/env.js` also accept
+the legacy `CASCADE_...` name as a deprecated fallback (the `EMET_` name wins when both are set):
+`EMET_SOURCE_TAG`, `EMET_SOURCE_TAGS`, `EMET_OAUTH_PASSPHRASE`, `EMET_AUDIT_LOG`, `EMET_HANDOFF_DOC`,
+`EMET_STATE_DOC`, `EMET_INSTALL_DOC`, `EMET_CHARACTER_DOC`, `EMET_TEMPLATE_MAP`, `EMET_RECORD_DOCS`,
+`EMET_READ_DOC_PAGE`, `EMET_SIGNING_KEY`, `EMET_GAP_BASELINE`, `EMET_CIMD`, `EMET_INVITES`,
+`EMET_TIMEZONE`, `EMET_CLOSE_GRACE_MINUTES` and `EMET_ACTIVE_GEMS`. These read `process.env` directly, so **only the
+`EMET_` name works** and a `CASCADE_` name is ignored: `EMET_COLLECTION_PREFIX`,
+`EMET_VECTOR_INDEX`, `EMET_CORPUS_INDEX`, `EMET_CORPORA`, `EMET_CORPUS_COLLECTION`,
+`EMET_REQUEST_LOG` and `EMET_CRASH_LOG`. (`MONGODB_URI`, `MONGODB_DB`, `PUBLIC_URL`, `PORT`, `HOST`,
+`LOG_LEVEL`, `LOG_FORMAT` and `DEBUG` have no prefix. `TRUST_PROXY` is not read: the server trusts exactly one proxy hop (Railway's edge).) Use the `EMET_` names.
+
+**The two-pass deploy is not optional.** `PUBLIC_URL` is the OAuth issuer; until it matches
+the real URL, authorization fails in ways that look like a client problem.
+
+The repository's `Dockerfile` starts the HTTP transport (`node src/http-remote.js`), and Railway
+builds from it — there is no start command to set. (If you deploy without the Dockerfile, the
+start command is `npm run start:http`.)
+
+**Would rather have your assistant run all of this?** [GUIDED-SETUP.md](GUIDED-SETUP.md).
+
+### If the CLI misbehaves on Windows
+
+Two things cost real time and neither is obvious:
+
+- **The npm `.cmd` shim fails with `'"node"' is not recognized`** if node is not on PATH in the
+  shell that launches it. The package ships a native binary - call it directly:
+  `%APPDATA%\npm\node_modules\@railway\cli\bin\railway.exe`
+- **`railway login --browserless` only works if you approve on the SAME machine.** The flow
+  redirects to `127.0.0.1`, so approving the code on your phone or another computer completes
+  nothing and the CLI waits forever. Plain `railway login` opens the right browser locally and
+  is more reliable.
+
+Non-interactive linking needs explicit flags:
+`railway link --project <name> --service <name> --environment production`
+
+## Fly.io (alternative)
+
+```
+fly launch --no-deploy
+fly secrets set MONGODB_URI=... MONGODB_DB=emet PUBLIC_URL=https://<app>.fly.dev \
+  EMET_OAUTH_PASSPHRASE=... EMET_SOURCE_TAGS=mobile,desktop,cli
+fly deploy
+```
+
+## Smoke test before connecting anything
+
+```
+curl https://<host>/health
+curl https://<host>/.well-known/oauth-authorization-server
+```
+
+The first should report ok and a tool count. The second should return OAuth metadata, not a
+404 — if it 404s, `PUBLIC_URL` is wrong.
+
+## Connecting clients
+
+**Claude (all interfaces, including phone):** Settings → Connectors → Add custom connector →
+URL `https://<host>/mcp` → connect → you are sent to a passphrase page → enter
+`EMET_OAUTH_PASSPHRASE`. Enable it per conversation from the "+" menu.
+
+**Any other MCP client:** point it at `https://<host>/mcp` and complete the OAuth flow.
+
+Then verify from that device: `emet_status` with `probe: true`, followed by a `recall` of something
+you saved elsewhere. If the remote host sees what the laptop wrote, the deployment is real.
+
+## Notes
+
+- **Release note: startup stage 1 (the ref 358 amendment).** Three behaviour changes take effect
+  live on deploy:
+  - **Re-running setup is refused.** `emet_setup_complete` on a store where both
+    `bootstrap/IDENTITY.md` and `bootstrap/USER.md` already exist is refused unless the call passes
+    `reissue: true` (a top-level boolean) on the owner's explicit word; nothing is written. A host
+    flow that re-runs setup at startup now gets a refusal. That is intended: tell the owner.
+  - **Bots lose `retire_doc` and `rename_doc` everywhere,** their own `bots/<tag>/` folder
+    included. Retiring and renaming are the owner's and the hub's. `emet_setup_complete` is also
+    refused to a bot tag.
+  - **`emet_initialize` no longer creates the owner person.** Only `emet_setup_complete` does. An
+    older install that was set up before the owner row existed, and never had one created, keeps
+    resolving its owner as the legacy subject `owner` until the owner runs `emet_setup_complete`
+    once with `reissue: true` (which also writes new versions of the identity documents; prior
+    versions are archived). There is no separate tool for this.
+- **Clients cache tool lists, and this WILL catch you.** After any deploy that changes the
+  tool surface, every host keeps offering the old set until you reconnect the connector there.
+  Nothing breaks - existing tools keep working - but new tools stay invisible. Reconnect each
+  host: phone, desktop, CLI, anything else. This is the last-mile step people forget.
+- **Costs.** A small Atlas cluster plus a hobby-tier host runs in the low tens of dollars a
+  month. Both have free tiers adequate for a single user.
+- **The passphrase is the whole perimeter.** There is no second factor. Rotate it by changing
+  the variable and redeploying; existing device authorizations are invalidated.

package/docs/DISCIPLINES.md

@@ -0,0 +1,29 @@
+# Operating disciplines — the reasoning behind the nine lines
+
+`emet_initialize` serves `operating_discipline`: nine one-line rules (`DISCIPLINE_SUMMARY` in `src/disciplines.js`). This document is the long form — why each rule exists. It was carried inside the code until 2026-09-27, when the code audit found the same rules stated twice in one file with only the short form ever served (finding 3.13). The reasoning is for people; the lines are for the model.
+
+Each rule exists because its absence caused a real, traced loss of information in production use.
+
+These disciplines are **guardrails**: they bound the field in which the model uses its judgment. The steps that must never depend on judgment (open, append every exchange, board before handoff, close in order) run on **the monorail**, the server-checked session graph. See [Guardrails & Monorails](GUARDRAILS-AND-MONORAILS.md).
+
+**Recall before assuming.** Before answering anything that may have prior context — a decision, a preference, a configuration, a name — search memory first. Answering from what seems likely, when the store would have told you, is the most common way a memory system silently stops mattering.
+
+**Verify every write.** A save is not done because the call returned. Read it back. A claimed save that was never verified is worse than no save, because it stops anyone from looking again. This applies to reads too: before acting on a recorded path, id, or fact, confirm it still exists.
+
+**The two tiers stay independent.** Layer entries hold curated meaning. Transcripts hold the word-for-word exchange. They are deliberately separate: when a layer entry is relevant but thin, the transcript around its timestamp holds the depth that was compressed out. Summarising at transcript-write time collapses the two into one and destroys the second layer of inquiry. Store transcripts verbatim. If a payload will not transmit, split it across parts — never compress it.
+
+**Supersede, never mutate.** Correcting the record means writing a new entry that supersedes the old one, not editing or deleting it. The superseded entry stays reachable. It is marked with the date it ended and what replaced it. The current entry is listed first in every order, including a request for the latest and a timestamp sort. It does not fade and it is not hidden. A revision must stand alone and carry the dated specifics it is based on — an abstracted principle is weaker than the sentence someone actually said. Events are immutable: never revise an episodic entry.
+
+**Consolidate late.** Wait for roughly three instances of a stable pattern before merging observations into one standing entry. Merging early buries the differences that turn out to matter.
+
+**Provenance is part of the memory.** Every write records which host produced it. Set a distinct source tag per host. A shared default tag is not attribution — it is ambiguity that becomes invisible the moment a second host connects, and it makes forks impossible to see.
+
+**Findings, not explanations.** When something in the record is unaccounted for, write down what was observed and stop. Do not attach a cause you did not verify. A plausible invented explanation is harder to dislodge later than an open question, and the most dangerous inventions are the reassuring ones.
+
+**Mark inference as inference.** State what is known, what is inferred, and what is unknown, as three different things. If a value has not been observed, record it as unknown rather than supplying a likely one.
+
+**Write at the moment.** Save when it happens, not at the end. A problem solved, a decision made with its reasoning, a stated preference, a correction — each is worth an entry while the specifics are still exact. Long working sessions deserve progress entries, because context can be lost without warning.
+
+**Name the layer.** Every write names its layer. An entry saved without one is not routed by content — both routers were measured against the record and neither is fit to place material in a durable layer by guess — it lands in the working layer, flagged. It does not age out and it is not hidden. The layer charter says what belongs where; choosing is the writer's job, not the door's.
+
+**Hand off before the gap.** Losing context mid-task is a failure. Before any interruption, restart, or handoff, write down what was in progress, why it stopped, and the exact next step. The handoff is the thread that survives the gap.

package/docs/GUARDRAILS-AND-MONORAILS.md

@@ -0,0 +1,108 @@
+# Guardrails & Monorails
+
+*An EMET architectural practice: how the memory function keeps an AI's work consistent and its record whole, without leaving it to the model to choose.*
+
+## The idea
+
+An AI working with persistent memory does two kinds of work:
+
+- **Judgment work:** reading a person, weighing a decision, writing a reply, deciding what is worth saving.
+- **Process work:** opening the session, appending each exchange to the transcript, writing the board before the handoff, closing in order.
+
+Judgment work needs room to move. Process work needs to happen the same way every time, whether or not the model remembers or feels like it. EMET treats these two differently, and the name for that is **Guardrails & Monorails**.
+
+- **Guardrails** bound a field. Inside them the AI moves freely and does its processing. The guardrails keep that processing honest and in character. In EMET, these are the floor, the character and user documents, and the served instructions (`operating_discipline`, `tools_in_force`, `session_close_protocol`).
+- **The monorail** carries the AI from one field to the next without asking it to decide. In EMET, this is the **session graph** (`src/session-graph.js`), the state-driven track a session runs on, checked by the server on every write.
+
+In the words of the owner, who named the practice (2026-09-29):
+
+> "Guardrails give a field of movement and execution to allow an AI to do processes, where rails guide the AI through a process flow without it processing, to bring it to another space where it expands into a processing space with guardrails."
+
+### Why a monorail
+
+The practice was first called Guardrails & Rails. It was renamed Guardrails & Monorails the same night, as the more accurate picture of what guidelines and graphs do together.
+
+A monorail car straddles its beam: it can't derail, and it can't leave the track.
+
+The board is a guardrail with no write door. The server provisions it. After that the only change is an edit with a reason, and a change that leaves any document under half the size it had when this session first touched it is refused. A monorail does have switches, but they belong to the track. A section of the beam moves, and the system throws it, not the car. The car runs from station to station, and its doors open only when it's stopped at a station.
+
+- **The stations** are the processing spaces: a workshop, a kitchen, a study. The AI steps out at each one and works freely inside the guardrails.
+- **The beam** is the protocol order: open, work, record, board, handoff, close.
+- **The switches** sit at junctions on the beam. Each one routes the AI to one of several guardrail spaces, where it works in a bounded way. The track throws the switch; the AI rides it.
+- **The doors** are the server's checks. A station's door opens only when every stop before it has been made.
+
+The same thing can be pictured as a building, with **hallways and rooms**. The rooms are where work happens, and the hallways carry you to the next room without any decisions along the way.
+
+It resembles Chutes & Ladders only on the surface, as a board with fixed paths between squares. In that game the paths are chance. In EMET they are set by the state of the session, and they never move the AI backward as a penalty. A door that stays shut says exactly which stop is owed and how to make it.
+
+## Why a monorail, and why in the server
+
+Guidelines alone depend on the model choosing to follow them. A model under a long context, a cut-off payload or a lost turn will sometimes not follow them. The record then has a hole that nobody sees. EMET's standing rule is that integrity is a property of the store, not an option a model can decline (see *The door* in the README). The monorail applies that same rule to the session's order of work.
+
+The monorail lives in the **EMET MCP server**, not in any host. There's no Claude Code hook, no CLI step and no model-specific tool. Any AI, on any desktop or phone, that can call EMET's tools rides the same track, because the check is made where the write lands.
+
+## How the monorail works
+
+Every governed write (`save_to_layer`, `revise_memory`, `write_doc`, `patch_doc`, `retire_doc`, `rename_doc`, `accept_nonconformance`, `emet_transcript_append`, `save_transcript`, `revise_transcript`, `emet_session_close`) names its session, either as `session_id` or as the session in `derived_from` (for `emet_session_close`, `receipts.transcript_session_id` when `session_id` is omitted, the same session the close checks), and carries `exchange`. Before the write runs, the server reads the session's state from `<prefix>sessions` (opened, board, episodic, handoff, closed) and the transcript's highest appended exchange. It then decides whether the door opens.
+
+**Writes outside the graph, on purpose.** Four tools write without a session and are not governed: `emet_setup_complete` (records the first-time interview as the bootstrap documents and the owner; it runs before the store has an identity, and a host mid-setup must never be refused for lacking a session it may not have opened yet, though it can open one with its setup `load_id`); `emet_invite_create` and `emet_member_access_create` (the owner's access codes, kept in their own collections, not the record); and `emet_status` with `probe: true` (writes one probe document, reads it back and removes it to prove the write path). `emet_session_open` has its own gate (`startup_pages`). Every other write tool is governed.
+
+| Gate | The door stays shut when | What the refusal says to do |
+|---|---|---|
+| `no_session` | a governed write names no session at all | open one with `emet_session_open` (with the `load_id` from your startup pages), or use the `session_id` already opened, then resubmit the same write with it |
+| `not_open` | the write names a session that was never opened | open it with `emet_session_open` (with the `load_id`), then resubmit the same write with the `session_id` it returns |
+| `turn_skipped` | exchange *n* is declared but *n−1* was never appended | append the named exchange with `emet_transcript_append` (this `session_id`, that `exchange_index`), then resubmit the same call |
+| `handoff_early` | `HANDOFF.md` is written before the board, the episodic record and the transcript | write each missing step with its tool (the board with `write_doc` or `patch_doc`, the episodic record with `save_to_layer` layer `episodic`, the transcript with `emet_transcript_append`), then the handoff again |
+| `startup_pages` | `emet_session_open` is called without a `load_id`; with a `load_id` this server has no record of (made up, not served by this process, expired 60 minutes after its last page, or from before a restart), since its pages cannot be checked; or while pages of that load were never fetched (never checked against another host's load) | pass `load_id` from your startup (`startup_page.load_id`, carried by every `emet_initialize` result: each page, `page: "all"`, a one-result startup and a store not set up yet); for a load with no record, call `emet_initialize {}`, fetch every page and open with the `load_id` it returns; for missing pages, the call comes first: the exact `emet_initialize {"page": N, "load_id": ...}` for the first missing page, the missing pages once as ranges (`2-40`), then open again with that `load_id` |
+| `closed` | a write arrives after a complete close - except the one closing exchange inside the grace window, and a transcript correction | nothing in this session: the work belongs in the next session opened the usual way (never one opened just for it) |
+
+Every refusal is made before the tool runs, so nothing is written, and its reply carries the pass instruction above (each fits inside the 500-character error-message cap). The same holds for the source-tag refusals on transcript writes, which lead with `pass "source"`: a missing or unregistered tag is told to pass a registered tag, and the refusal does not list the registered tags. Only an exact member of `EMET_SOURCE_TAGS` counts. A `cloud-scheduled-` prefix does not. Any id or tag the caller sent is echoed at most 64 characters, so no refusal is cut before its instruction.
+
+Every governed result carries a `session_graph` block: `{mode, verdict, gate, reason, next}`. `next` is the stop after this one, taken from the state, so the AI never has to work out where it is. After a successful call, the server records the stop. A governed write that names a session fails closed when the graph cannot be read: nothing is written, and the reply says the session graph is unavailable. A write that names no session is refused by the `no_session` gate before the graph is read. (The closed-session checks on the transcript doors and `emet_session_open` fail safe instead, below.)
+
+**A closed session takes no new exchanges, except its closing exchange** (2026-10-01, the owner's decision). In the closing turn the assistant writes the handoff, gets `complete`, and only then replies, so the append of that last exchange always arrives after the close. A closed session therefore takes exactly **one** more `emet_transcript_append`: numbered highest+1, within `EMET_CLOSE_GRACE_MINUTES` (default 5; `0` turns the window off) of the recorded close time. The reply's `closing_exchange` says it was accepted and that the session is now locked. The closing exchange is written into the session's last live part, whatever session id the append names. A retry of that same exchange number is answered as already saved by the check itself; the append tool is not called, so a retry writes nothing, at any time. Ids are grouped the way the close check groups them (`<base>`, `<base>_verbatim_partN`, and any other `<base>_...` id all belong to `<base>`), and `exchange_index` is checked once (a whole number of 1 or more, or its text) before the monorail, the check and the tool read it. After that one append, or once the window passes, appends are refused with a reply that says the session is closed and locked, nothing was written, and the exchange belongs in the next session opened the usual way. `save_transcript` into a closed session is refused. `revise_transcript` is **allowed** (a correction supersedes and deletes nothing), but on a closed session a revision may only correct the exchanges its part already holds, never add new ones, and must carry exactly the same exchange numbers (none dropped or repeated; numbers sent as text are stored as numbers), so the closed session's exchanges cannot grow, shrink or be renumbered. These checks always run before the tool and fail safe: if the session's state, its transcript position or the part to be revised can't be read, nothing is written and the reply says to send the same call again. They decide every transcript write into a closed session (the graph defers to them), and their refusals are logged in the lab as `refuse`, gate `closed`. `EMET_CLOSE_GRACE_MINUTES` is capped at 60; a negative or non-numeric value (hex such as `0x10` included) is logged and the default 5 is used.
+
+**The close is recorded before its reply, when the write succeeds.** When `emet_session_close` returns `complete`, the server writes the closed flag and its time (`closed_at`) to `<prefix>sessions` and only then replies, with `closed_recorded: true`. If that write fails it is retried once; if it fails again the reply says `closed_recorded: false`, with a warning in `closed_record_warning`, `warnings` and `instructions`: the session is not locked until a later close records it.
+
+**Bot sessions close against their own records** (per-bot close records, 2026-10-01, the owner's decisions). Each bot runs in its own session, and the main `HANDOFF.md` and `STATE.md` hold only the owner's hub conversation. A tag is a bot tag when `bots/<tag>/HANDOFF.md` is listed in `EMET_RECORD_DOCS`; the session's tag is the source tag on its transcript. For a bot tag's write of its own `bots/<tag>/HANDOFF.md`, the `handoff_early` gate and the "handoff written" step work as they do for the main handoff, without the board condition (a bot keeps no board unless it lists one as a working document), and they refuse like every other gate. The gate keys on the write's `source`; a write with no `source` takes the host path. The bot's close itself checks `bots/<tag>/HANDOFF.md` and seven receipts (no board; `handoff_doc` names the bot's handoff), counts only that tag's own revisions in the window, is `blocked` if a receipt names the main handoff or board, and `incomplete` if the bot's tag revised either. `write_doc`, `patch_doc`, `retire_doc`, `rename_doc` and `accept_nonconformance` refuse the main handoff and board under a bot tag, and nothing is written. The same five tools also refuse a bot tag any write under `bots/` outside its own `bots/<tag>/` (other bots' records and `bots/ROSTER.md`), and when `EMET_SOURCE_TAGS` is set they refuse the main handoff and board to any `source` not listed in it, and refuse any write under `bots/` by anything other than a listed bot unless its tag is listed, a missing `source` and `cloud-scheduled-*` included. A registered tag that is not listed as a bot can still write the main records and any bot's folder (a known gap, F-2). Since startup stage 1, `retire_doc` and `rename_doc` are refused to a bot tag for every document, its own `bots/<tag>/` folder included (retiring and renaming are the owner's and the hub's), and `emet_setup_complete` is refused to a bot tag. Before either guard, the same five tools refuse a look-alike doc id: a leading `/`, a `.` or `..` segment, or `bots/` in the wrong case (`Bots/`); also a control or invisible formatting character anywhere (zero-width space, BOM, direction overrides), leading or trailing whitespace on the id or any segment, a backslash, the same `/`, `.`/`..` and `bots/` shapes after Unicode NFKC folding (full-width dots and slashes, `‥`, full-width letters; the first segment must be the ASCII `bots`), and a case or Unicode variant of a main-record id (`handoff.md`, ` HANDOFF.md`). Doc ids are flat strings, never resolved as paths or URL-decoded; there is no confusables table. One exception, for cleaning up ids written before these checks: `retire_doc`, and `rename_doc` from such an id onto a clean one, are let through for a tag listed in `EMET_SOURCE_TAGS` that is not a bot tag (never for a bot, an unlisted or missing tag, or with no registry set). With no registry set, both guards are opt-in and nothing changes. A session has one tag: if its transcript parts carry more than one and any is a bot tag, the close is `incomplete`. Host closes keep their eight receipts and their verdict; revisions by other tags that the full rule would not count are listed in `attribution_warnings`.
+
+### Mode: enforce only
+
+Since 2026-10-03 the monorail runs in enforce only. There is no report mode and no off switch; `EMET_SESSION_GRAPH` is no longer read. Every skipped step is refused before the tool runs, the reply says how to pass, and the refusal is logged in the lab. Lab rows with verdict `would_refuse` are from report mode, before that date.
+
+### Switches: small logic at each junction
+
+*Design stated by the owner, 2026-09-29. Not built yet: the live monorail is one straight line with the four gates above.*
+
+The architecture needs flexibility of flow: at some points a session should go one way or another, into a different guardrail space, depending on what is happening. That choice must not cost heavy processing, and it must not be left to the model. So each junction gets a **switch**: a small, purpose-built logic unit inside EMET.
+
+- **Like a transistor (an IGBT).** A switch conducts only when its gate condition is met, and it is tripped by that condition, nothing else. The condition is read from what EMET already holds: the session's state, the call being made, and what the record says. The branch it selects is where the session goes next.
+- **Small and local.** A switch is a few lines of logic in the server's code. No hosted model, no outside API, no model call. It gives the same answer for the same inputs, every time, so it can be tested like any other gate. This is the role a fast external decision model (such as JEV) plays in other designs, done here by the track itself.
+- **Designed per junction.** Each switch's design follows the function it serves and how information and tasking flow through that junction. There is no general-purpose router: a junction gets a switch only when a real fork exists, and the switch knows only what that fork needs (commitment 6: over-engineering is a defect).
+- **Bounded on every branch.** Each branch leads to a guardrail space, for example a GEM (Golem Expertise Module) once the socket exists, or a work instruction for a kind of task. The four gates still apply on every branch, so a switch can change where the session works, never whether its steps are recorded.
+- **Recorded.** Each time a switch trips, the lab results record which way it went and why, so its conditions can be checked against real sessions before anything depends on them.
+
+### Lab results
+
+Every check the monorail makes (ok, refuse, unknown; `would_refuse` and `late` in rows from report mode) is written the moment it happens as one timestamped row in `<prefix>graph_lab`. Each row records the time, session, host (source tag), tool, the exchange the call declared, the transcript's highest appended exchange at that moment, the mode, the verdict, the gate and the reason. Rows are only ever added, never changed or removed. A failed lab write is logged and never slows or blocks the call.
+
+`emet_gaps` serves the summary as `graph_lab`: the total number of checks, first and last timestamps, the number of sessions, counts by verdict, gate and host, and the flagged rows (anything not ok) newest first. Because it's a tool call, any AI on any device can pull the lab results.
+
+**Startup pages fetched late** (2026-10-03). In enforce only an open with a page missing is refused, so no session opens without its pages and no `late` row is written through the server's door. The summary still pairs `late` rows with a `would_refuse` open (a page fetched late is not still missing, and an open whose every missing page came late is not flagged), for any such rows written in report mode; an open refused stays flagged.
+
+**One process only** (2026-10-03). The record of which startup pages were fetched, which the `startup_pages` gate reads and the late pairing uses, is held in the memory of the one server process that served them. Pages served by another instance are not on it, so this gate assumes EMET runs as a single process; with several instances it could refuse an open whose pages were fetched from another instance. A restart, or 60 minutes without a page of that load being served (its own lifetime; the cache of startup payloads still keeps them 10 minutes), clears it, and a load with no record is refused with the way back (a fresh `emet_initialize {}`), so after a restart or a long pause before the open every host fetches its startup again, once. Pages are never taken as checked when they were not.
+
+**How to read them:** each flagged row is either a real skipped step that was refused (the monorail working) or a gate that is wrong (fix the gate).
+
+## The honest limit
+
+The server sees tool calls, never the reply text. It can confirm that exchange 8 was appended before exchange 9 was declared. It can't confirm that exchange 8 holds what was actually said, or that a reply was given without a call at all. Turn coverage is only as strong as the exchange numbers hosts report. The guardrails (character, floor, disciplines) carry what the monorail can't reach, and `emet_gaps` counts whatever holes remain.
+
+## Where it lives
+
+- `src/session-graph.js`: the gates (`evaluate`), the next stop (`nextStep`), the recorded stops (`recordStep`) and the thin store layer (`graphBefore`, `graphAfter`).
+- `src/dispatch.js`: the checkpoint before every governed tool and the `session_graph` block on every result.
+- `src/tools.js`: `session_id` and `exchange` added to every governed schema from the graph's own tool list.
+- `src/setup.js`: `tools_in_force` and the short instructions tell every host to pass both fields and follow `session_graph.next`.
+- `tests/session-graph.test.js`: the gates, the next stop, and the fail-closed door when a named session cannot be read.
+- Design record: `staging/emet-session-graph.md` in the EMET store. The framing is in semantic memory entry 297, and the decision on switches in procedural ref 402.