@dreamforgestudiollc/emet 0.0.0-stage → 0.2.4

package/docs/AUTHORSHIP.md

@@ -0,0 +1,26 @@
+# Authorship
+
+Early commits in this project's private development history recorded the
+user's git identity in the author field. Those changes were machine-authored — written by assistant
+instances under the user's direction. No git user was configured in any scope,
+so that identity was supplied per command.
+
+Later commits in that history name the assistant in the author field, and an `Approved-by` trailer
+names the user, so what made a change and who accepted it are two separate
+recorded facts rather than one conflated one.
+
+The earlier commits are not rewritten. Corrections to any EMET record are made by
+adding — a superseding entry, a marker, a written disposition — never by removing
+or editing what is already there. A history rewritten to read correctly destroys
+the retained record in order to do it. This file is the addition.
+
+This matters because the charter states that records are attributable. An author
+field naming a person for machine-made changes is not attributable evidence, and
+git was the one store in this system with no source-attribution mechanism: memory
+entries carry a host tag and an assertion origin, document writes carry a host tag
+that is never a person, transcripts carry a session id.
+
+## Upstream
+
+Portions of this work derive from CASCADE Enterprise RAM (C.I.P.S. LLC). See
+`LICENSE`, which carries both that notice and Dreamforge Studio LLC's.

package/docs/BENCHMARKS.md

@@ -0,0 +1,261 @@
+# EMET benchmarks — implementation language evaluation
+
+**Run 2026-09-08. Four implementations, one specification, live MongoDB Atlas, identical hosting.**
+**Conclusion: EMET stays on JavaScript — on measurement, not by default.**
+
+---
+
+## Why this exists
+
+A programmer friend of the maintainer suggested that a more object-oriented or compiled
+language — Java, Python, C++, and Rust in particular — would likely be faster than Node and
+serve EMET better long term. That is a reasonable prior and it deserved a real answer rather
+than a defence of the status quo.
+
+Two questions were separated, because they have different answers and different costs:
+
+1. **Language** — is JavaScript the right substrate for EMET's backend?
+2. **Durability** — which practices have legs, independent of language?
+
+This document reports the first. It also reports the thing the exercise actually produced,
+which was not a language choice.
+
+**Nothing here argues from intuition about language speed.** Every number was measured, and
+every limit of the measurement is stated.
+
+---
+
+## Method
+
+**One specification, implemented once per language, as a single file with the tasks as
+functions inside it** — so connection, configuration, fixtures, timing and output are written
+once per language and shared by every task, rather than drifting across eight separate scripts.
+
+Each implementation ran as its own service on the same platform (Railway, region `sfo`),
+against the **same live MongoDB Atlas cluster**, reading the **same fixtures file**, writing to
+throwaway `bench_*` collections that never touch EMET's own data.
+
+### Equivalence — checked before any timing was read
+
+Two digests are computed by every implementation: a fixed canonical string, and the **masked**
+form of a secret-bearing fixture. If they differ, the implementations are not doing the same
+work and no timing means anything.
+
+| language | canonical probe | masked secret |
+|---|---|---|
+| javascript | `feb7628ae8a0…` | `15a3c529bee0…` |
+| python | `feb7628ae8a0…` | `15a3c529bee0…` |
+| go | `feb7628ae8a0…` | `15a3c529bee0…` |
+| rust | `feb7628ae8a0…` | `15a3c529bee0…` |
+
+**Identical across all four.** This check is what separates a benchmark from four programs
+that happen to run.
+
+### Clock points
+
+Per task the implementations record `t_total`, and `t_driver` — the summed duration of every
+awaited database call. `t_inproc = t_total − t_driver` is the language's own work: hashing,
+masking, serialisation, validation, receipt construction.
+
+⚠ **The split is not clean, and the report does not pretend otherwise.** BSON encoding and TLS
+happen *inside* the driver call and are genuinely language and driver work counted in
+`t_driver`. The two buckets are therefore "in-process work outside the driver call" and
+"driver call duration". **No single "language speed" number is produced, because none would be
+honest.**
+
+Percentiles are p50 and p95, never mean.
+
+### Tasks
+
+`T1` connect · `T2` write through the full door (mask, digest content and metadata, insert,
+read back, verify) · `T3` structured read with filters · `T5` supersession write · `T6`
+document write with archive and sha256 read-back · `T9` 300 KB document write · `T10` 300 KB
+server-side read-modify-write · `T11` bulk write of 100 records.
+
+The 300 KB size is not arbitrary: it is the size of a real EMET thread document.
+
+---
+
+## Results — in-process work, p50 milliseconds
+
+| task | javascript | python | go | rust |
+|---|---|---|---|---|
+| T2 door write (small) | 0.141 | 0.088 | 0.046 | **0.033** |
+| T3 structured read | 0.037 | 0.030 | **0.007** | **0.007** |
+| T5 supersession write | 0.132 | 0.070 | 0.029 | **0.027** |
+| T6 document write (small) | 0.314 | 0.180 | 0.227 | **0.089** |
+| **T9 300 KB write** | 1.198 | 12.185 | **45.540** | **1.092** |
+| T10 300 KB read-modify-write | 0.763 | 0.599 | 0.850 | **0.428** |
+| T11 bulk 100 records | 0.784 | 0.610 | 1.290 | **0.244** |
+
+### The finding that matters — where the 300 KB in-process time goes
+
+| step | javascript | python | go | rust |
+|---|---|---|---|---|
+| **mask (regex passes over 300 KB)** | **0.592** | 11.642 | **44.845** | 0.769 |
+| sha256 (300 KB) | 0.211 | 0.226 | 0.340 | **0.156** |
+
+**Masking is the entire story, and it inverts the premise the exercise began with.**
+JavaScript is the *fastest* of the four at it: V8's JIT-compiled engine beats Rust's `regex`
+crate and is **75× faster than Go's RE2**. A compiled language turned out to be the slowest
+implementation in the benchmark, by an order of magnitude, at the operation that dominates.
+
+### Total latency and what it means
+
+| task | javascript | python | go | rust |
+|---|---|---|---|---|
+| T2 | 136.1 | 139.7 | 138.5 | 123.2 |
+| T6 | 542.7 | 560.9 | 558.0 | 491.4 |
+| T9 | 209.5 | 226.5 | 264.4 | 190.5 |
+| T11 | 73.8 | 74.2 | 76.6 | 65.2 |
+
+⚠ **No language ranking should be read from this table.** These are dominated by the Atlas
+round trip. The spread between languages (10–20%) is the same order as ordinary network
+variance, and each language was run once, not interleaved.
+
+**For JavaScript and Rust, in-process work never exceeds ~1% of any operation.** Go reaches
+17.2% on T9, entirely because of the regex.
+
+---
+
+## Results — concurrency
+
+The serial numbers leave one question open: does a single-threaded runtime degrade when
+several callers hit it at once? That is measured with **concurrent inbound requests** — what
+the condition actually looks like against a live server — each performing one 300 KB mask and
+digest with **no database**, so nothing hides behind network latency.
+
+| | conc | throughput/s | in-process p50 ms | in-process p95 ms |
+|---|---|---|---|---|
+| **javascript** | 1 | 10.92 | 1.250 | 1.555 |
+| | 4 | 37.22 | 0.878 | 1.430 |
+| | **16** | **59.62** | **0.904** | **1.413** |
+| **rust** | 1 | 10.75 | 2.249 | 4.628 |
+| | 4 | 35.73 | 2.420 | 6.452 |
+| | **16** | 57.72 | 2.619 | 4.359 |
+| **go** | 1 | 6.90 | 47.116 | 64.208 |
+| | 4 | 21.97 | 55.600 | 75.655 |
+| | **16** | 50.88 | 73.791 | 126.559 |
+| **python** | 1 | 8.93 | 18.126 | 25.698 |
+| | 4 | 21.35 | 43.540 | 76.169 |
+| | **16** | **15.26** ⬇ | 46.095 | 112.792 |
+
+**JavaScript wins outright: highest throughput at every level, lowest in-process latency, and
+the flattest curve** (1.250 → 0.904 ms from concurrency 1 to 16 — it *improves* as the JIT
+warms). Rust is a close second and scales cleanly. Go degrades 57%. **Python's throughput
+collapses past concurrency 4** — textbook GIL contention.
+
+**The mechanism matters more than the ranking.** Node's single thread was never the bottleneck
+because the per-request CPU cost is small: 0.5 ms of masking does not saturate an event loop.
+Python fails on the *same* architecture because its mask costs 35× more. **Being
+single-threaded is only a liability when each request is expensive — which is an argument for
+making requests cheap, not for changing language.** And Go had cores to spread across and still
+lost: **parallelism does not fix a slow inner loop.**
+
+⚠ **Core counts:** `os.cpus()` (Node) and `runtime.NumCPU()` (Go) reported **48** — the *host*
+count; those APIs ignore the container's cgroup quota. Rust's `available_parallelism()`
+respects it and reported **8**. The honest figure is ~8 usable cores, which **strengthens** the
+result: the multi-core runtimes genuinely had room and still did not win.
+
+---
+
+## Standards provenance
+
+Beyond performance, the maintainer set a standing priority on candidates provable against
+confirmed standards. Verified 2026-09-08:
+
+| candidate | language standard |
+|---|---|
+| **JavaScript** | **ECMA-262 and ISO/IEC 16262** — dual-standardised |
+| C# | ECMA-334, plus an ISO/IEC edition |
+| Java | **No ISO or ECMA standard.** Governed by the JCP, the JLS (JSR 901) and a TCK — a rigorous but vendor-administered regime |
+| Rust | No language standard. A *qualified toolchain* exists (Ferrocene, TÜV SÜD: ISO 26262 ASIL D, IEC 61508 SIL 3, IEC 62304 Class C) — a different guarantee, aimed at safety-critical software |
+| Go, Python | No standards-body specification found |
+
+**JavaScript is the only candidate with an international language standard.** TypeScript, often
+proposed as the cheap improvement, has none at all — it is a vendor-controlled superset, and
+adopting it would trade a standard for a governance model.
+
+⚠ The ISO edition of ECMAScript (16262:2011) lags ECMA-262's annual editions considerably.
+The stamp is real; its currency is not.
+
+---
+
+## Conclusion
+
+**EMET stays on JavaScript**, and the decision rests on two independently measured legs:
+
+1. **Standards** — the only dual-standardised candidate.
+2. **Performance, serial and concurrent** — the difference is not merely negligible; **it
+   favours JavaScript**, which posted the highest throughput and lowest in-process latency at
+   every concurrency level tested.
+
+The port was never competing for much. In-process work is ≤1% of any operation, because
+**EMET is round-trip-bound, not compute-bound.** Against that, a port would have to re-earn
+**673 test assertions across 17 suites**, counted for the 2026-09-08 run (the current suite is larger; the README states that count), the single write path, two transports and a proven
+OAuth flow.
+
+### What the exercise actually produced
+
+Not a language choice — **a function to optimise.**
+
+The benchmark identified the write-path scrubber as the dominant in-process cost. Profiling the
+real implementation on a 300 KB body found something the benchmark alone could not:
+
+| case | before | after |
+|---|---|---|
+| clean prose, no secrets | 6.401 ms | **0.962 ms** |
+| secret-bearing | 7.251 ms | **3.549 ms** |
+
+**Nine tenths of the worst case was being paid by documents containing nothing to redact** —
+the cost was scanning, not replacing. Three causes: a regular expression compiled per literal
+*on every call*, the literal registry re-sorted every call, and four pattern rules scanning the
+full body unconditionally. Fixed by caching the order, using plain substring operations for
+literals, and giving each rule a **necessary-condition prefilter**.
+
+Behaviour is unchanged and that was the acceptance criterion: **hit counts are identical on
+every case and the redaction suite passes untouched.** A prefilter that changed what got masked
+would be a defect, not an optimisation.
+
+**This saves ~3.7 ms per large write. The gap between the fastest and slowest reasonable
+language candidate was ~0.1 ms.** The function was worth roughly thirty times the port.
+
+---
+
+## What was not measured
+
+Stated plainly, because a report that only lists what it proved is advocacy.
+
+- **MCP over streamable HTTP, and OAuth, were not implemented in any candidate.** They measure
+  what an SDK *can do*, not how fast it is. **They remain the only substantive reason to build
+  further implementations.**
+- **Stranger-install cost was not measured.** A single compiled binary needs no runtime where
+  Node does, and the `.mcpb` bundle format supports Node, Python and compiled binaries with
+  dependencies bundled — which narrows the gap by an unknown amount. **That question is settled
+  by an install on a clean machine, not by benchmarking.** It is the open axis.
+- **Vector search** was excluded: it needs an index provisioned on the bench collection, and
+  embedding happens server-side, so it carries almost no signal about language.
+- **One run per language, not interleaved or repeated.** All services ran in `sfo` while the
+  production service runs in US East; same-region running would shrink driver times and raise
+  in-process shares by a projected factor of ~3 — without changing the ranking.
+- The concurrency runs used a **simplified masker**, not EMET's production scrubber. Same
+  shape, different absolute numbers.
+
+## Two harness defects, found and corrected before comparing
+
+Both would have compared *programs* rather than languages, which is the failure this kind of
+exercise exists to avoid:
+
+- JavaScript counted substring occurrences with `split()`, allocating an array over a 300 KB
+  body, where Python and Go used a scanning count. Corrected to a scan.
+- A structured-read task failed because an earlier task's per-iteration writes left duplicates
+  that crowded lower-importance fixtures out of a limited, sorted read. Corrected by seeding
+  singletons.
+
+Each cause was read from the failing result's own diagnostic output rather than guessed.
+
+## Reproducing the scrubber measurement
+
+`scripts/redact-bench.mjs` measures the write-path scrubber alone — no database, no network.
+**Run it before and after any change to `src/redact.js`.** The four-language services were
+scaffolding and have been torn down; this instrument guards shipped code and remains.

package/docs/BOOTSTRAP.md

@@ -0,0 +1,127 @@
+# Wiring EMET into your assistant
+
+Connecting the server gives your assistant the *ability* to remember. It does not make it
+*use* that ability. An assistant with memory tools and no instruction about them will answer
+from what it can infer, save nothing, and leave you to notice.
+
+This is the layer that closes that gap, and it is deliberately small.
+
+---
+
+## Why it is short
+
+A memory system usually arrives with a long standing prompt — identity, protocol, rules,
+startup sequence — pasted into every project and re-pasted whenever it changes.
+
+EMET moves almost all of that into the server. `emet_initialize` returns the assistant's
+identity, the user profile, recent context, and the operating disciplines, **on every call, on
+every host.** So the block you paste does not need to contain any of it. It only needs to say:
+call that first, and mean it.
+
+The practical consequence: when you change who your assistant is, you change it once with
+`write_doc` and every host picks it up on the next session. Nothing to re-paste anywhere.
+
+---
+
+## The block
+
+Paste this into your project's custom instructions, system prompt, or equivalent.
+
+```
+## Memory
+
+You have persistent memory through EMET.
+
+Call `emet_initialize` FIRST, before anything else, at the start of every session -
+and whenever the user opens with "initialize", "start", "begin", or similar. It
+returns who you are, who you are serving, where things were left, and the operating
+disciplines. It comes in pages: fetch every page it names (each page gives the exact
+call for the next), or call it with page: "all" on a host with no size limit. Adopt
+identity, character, and floor; do not recite those three back. Then open the
+session transcript with emet_session_open and the load_id the startup carries, if
+that tool is present. Read HANDOFF and the board.
+Name the board in plain words: half-state, dated items, open items with next
+action, anything left undecided; then parked items one line each with what
+brings them back; then the counts as a check; then the tools actually present;
+then a question. Never a question alone. Never letter-number codes.
+
+If a local shell MCP is present, measure the computer name and that machine's
+clock before the host line; put the raw return on the first transcript append.
+If none is present, do not invent the line. Say system status and time were
+not measured because no local shell MCP is connected, and that adding one
+enables that function.
+
+Before answering anything that might have prior context - a decision, a preference,
+a configuration, a name, a past conversation - search memory first with `recall`,
+`semantic_recall` or `query_layer`. Do not answer from what seems likely when the
+store would have told you.
+
+tools_in_force from initialize are calls, not reading. After every reply, append
+that exchange to the transcript. Save as you go, not at the end: decisions with their
+reasoning, problems solved, preferences stated, corrections made. Read every write
+back before reporting it saved. Use all six layers - `emet_initialize` returns what belongs in each, and
+routing everything into the two or three that feel obvious is how a layer goes
+unused for a year without anyone noticing.
+
+When the session ends - the user says goodbye or thanks you, asks to wrap up,
+mentions restarting or opening a new session, or you are running out of room -
+work through the `session_close_protocol` that `emet_initialize` returned, in its
+order, then call `emet_session_close` to confirm it landed. Do not tell the user
+the session is saved until it returns state "complete".
+```
+
+That is the whole thing. The disciplines it alludes to arrive in full from
+`emet_initialize`; repeating them here would create two copies to keep in agreement.
+
+---
+
+## Hosts differ, and EMET degrades gracefully
+
+**Hosts with an instructions field** — a claude.ai Project, a `CLAUDE.md`, a system prompt,
+a custom GPT. Paste the block. This is the strongest integration: the assistant reaches for
+memory unprompted, on the first turn, without being told.
+
+**Hosts with projects but no instructions field** — some vendors offer a project or workspace
+that groups conversations without letting you set standing instructions. **It still works.**
+The tool descriptions do the work: `emet_initialize` is described as "START HERE," and a
+capable model calls it when you open with "initialize." You are relying on the model reading
+its tools rather than on a standing instruction, which is slightly less reliable and entirely
+usable.
+
+**Plain chat with the connector enabled** — same as above. Say "initialize" and the session
+comes up with your identity and context. No project, no instructions, nothing to configure.
+
+**What actually degrades** without an instructions field is the *unprompted* behaviour: the
+assistant is less likely to search before answering, or to save a decision you did not ask it
+to save. If you find that happening, the instruction block is the fix — and on a host that has
+no field for it, pasting it as your first message of a session works as a fallback.
+
+---
+
+## Adding your own layer
+
+Everything above is the minimum. Some people want more: a house style, project-specific
+priorities, a checklist to run at session start.
+
+Keep that separate from the memory instruction, and prefer putting it **in the store** rather
+than in the paste. A document written with `write_doc` is read by every host and changed in
+one place; text pasted into three different projects is three copies that will disagree within
+a month.
+
+The identity and user documents created by the setup interview
+(`bootstrap/IDENTITY.md`, `bootstrap/USER.md`) are ordinary documents. Edit them with
+`write_doc`, and every host sees the change on its next `emet_initialize`. That is the
+intended place for "who this assistant is" to live.
+
+**Your hosts and machines go in `bootstrap/INSTALL.md`** (or whatever `EMET_INSTALL_DOC`
+names). The server cannot see which host or computer a session is running on, so it serves
+this document whole at startup as `install_notes` and tells the assistant to run the checks
+it names, in its order, before listing your items. Put in it what only you know: how to tell
+your hosts apart, which machine is which and how to check, the session-id form you want, the
+source tag each host should write under, and any tool quirks worth knowing before the first
+call. Without it the assistant still mints a session id and picks a source tag from
+`EMET_SOURCE_TAGS` - it just cannot check what it has not been told about.
+
+Delivery preferences - how short, how plain, what to leave out - belong in
+`bootstrap/USER.md`, not in a host's own memory feature. A preference kept by one vendor's
+memory does not travel to the next host; the user document does.

package/docs/BOTS.md

@@ -0,0 +1,79 @@
+# Running bots alongside your assistant
+
+**Document control:** id `docs/BOTS.md` · tier 3, work instruction and reference (`templates/INDEX.md` hierarchy) · revision: the repository's history governs · status: DRAFT, for the user's review · owner: EMET (base) · forms it points to: `templates/ROSTER.md`, `templates/BOTHANDOFF.md` (both DRAFT) · rules it points to: `docs/DEPLOY.md` (bot records), `docs/GUARDRAILS-AND-MONORAILS.md` (bot sessions)
+**Failure it prevents:** a bot set up by hand that the server did not treat as a bot, because its handoff id was never listed, found only when a live check's refusal came from the wrong rule (a live check of per-bot close records, 2026-10-01); and a bot close that could not finish because the bot never saved a session record with its session id, or saved one and never appended the exchange it was stamped with.
+
+This is the reference for adding a bot — a separate agent with its own job, such as a reviewer, a tester or a scheduled intake run — to an EMET install that already serves you and your assistant. It states how a bot is registered and how a bot session runs. The rules themselves live in server code and in the documents named above; this page points to them and restates none of them as new rules.
+
+---
+
+## 1. What changes when you add a bot
+
+- **Your records stay yours.** `HANDOFF.md` and `STATE.md` hold only the conversation between you and your hub (§3). A bot keeps its own handoff, `bots/<tag>/HANDOFF.md`, and never writes yours: the server refuses it (§5) — **but only for tags listed in `EMET_RECORD_DOCS`.** An unlisted or misspelled tag is treated as a host. When `EMET_SOURCE_TAGS` is set, the main records and everything under `bots/` refuse any tag not registered there, a missing source 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). A listed bot also cannot write another bot's folder or `bots/ROSTER.md`. With `EMET_SOURCE_TAGS` unset, these guards are off. Register a bot (§4) before its first write.
+- **A bot closes against its own record.** Its close checks its own handoff and seven receipts, and counts only revisions written under its own tag (`src/session.js` `BOT_RECEIPT_FIELDS`; `docs/GUARDRAILS-AND-MONORAILS.md`).
+- **Nothing about your own sessions changes.** Host sessions keep their eight receipts and their verdict.
+
+## 2. Naming the tag
+
+- One bot, one source tag, used on every write the bot makes: `source` on documents and transcripts, `metadata.source` on layer entries.
+- Form: `<prefix>-<bot name>`, lower case, letters, digits and hyphens, for example `bot-reviewer` or `bot-tester`. A prefix that names the platform the bots run on lets a reader tell bots from hosts at a glance. **No `/`**: a tag containing one is never a bot tag (`src/session-graph.js` `isBotTag`).
+- A tag is never shared between bots and never reused after a bot is retired. The record has to be able to say who wrote what.
+
+## 3. The hub is not a bot
+
+If one agent talks to you on behalf of the others — relays their reports up and your decisions down — it is the **hub**. The hub writes your `HANDOFF.md` and `STATE.md` under host rules. **Its tag is registered as a host and is never listed in `EMET_RECORD_DOCS`**: a listed tag can no longer write the main records (`docs/DEPLOY.md`). The roster records the hub in its own section for exactly this reason. **The hub's tag must be in `EMET_SOURCE_TAGS`:** with a registry set, an unregistered tag is refused the main records and any write under `bots/`.
+
+## 4. Registering a bot
+
+Do these in order. Each step names what to read back. Steps 2 and 3 are **one change**: set `EMET_SOURCE_TAGS` and `EMET_RECORD_DOCS` together, in one deployment. A tag registered as a source but not yet listed as a bot is treated as a host in between.
+
+1. **Roster row.** Add the bot to `bots/ROSTER.md`, filled from `templates/ROSTER.md`: tag, name, role, host, machine, handoff doc, tool profile, owner, status. The hub keeps the roster. Read back: `read_doc bots/ROSTER.md`.
+2. **Register the tag as a source.** Append the tag to `EMET_SOURCE_TAGS` (comma list) on the deployment. Without it, the bot's transcript appends are refused (`src/dispatch.js` `requireRegisteredSource`). The operator reads the variable back from the deployment (a bot cannot read deployment settings from a session).
+3. **Make the tag a bot tag.** Append `bots/<tag>/HANDOFF.md` to `EMET_RECORD_DOCS` (comma list). This one id is the only switch: nothing else — not the tag's prefix, not `EMET_SOURCE_TAGS`, not the roster — tells the server a tag is a bot (`src/session-graph.js` `isBotTag`; `docs/DEPLOY.md`).
+   - **Setting the variable replaces its value.** Keep every entry already there and append.
+   - The id must match exactly: the tag's exact case, no leading `./`. A typo silently leaves the tag on host rules.
+   - If your install still uses the legacy `CASCADE_RECORD_DOCS`, edit that one, or move its entries into `EMET_RECORD_DOCS`: once the `EMET_` name is set, the `CASCADE_` one is ignored.
+   - The ids are a deploy setting rather than code defaults on purpose: they name your bots, which differ per install, and removing one id puts that tag back on host rules without a release.
+   - Changing a variable redeploys the service. Note the new deployment id.
+4. **Fill §3 of the roster** with the bot entries of both variables as read back, the date and the deployment id.
+5. **Verify with one refused write — only once `HANDOFF.md` exists** (`list_docs HANDOFF.md` shows a version). On a new install with no handoff yet, skip this step until there is one: if the tag is not configured — the very case this step catches — the write would *create* the user's handoff. Then, under the bot's tag, `write_doc HANDOFF.md` with no `supersedes`. Expected reply: "HANDOFF.md is a main record and `<tag>` is a bot tag ... Nothing was written." If the reply says instead that HANDOFF.md "is a record and vN is in force", the tag is not a bot tag yet: check the id in step 3. If it says `<tag>` "is not a registered source tag", the tag is unregistered (step 2) and not yet a bot tag (step 3).
+
+**Templates.** A bot's handoff is filled from `templates/BOTHANDOFF.md`. Do not map bot handoffs to `templates/HANDOFF.md`: that template asks for a board a bot does not keep, so every bot close would be marked nonconforming. While `templates/BOTHANDOFF.md` is DRAFT it is not mapped; once it is IN FORCE, map each bot with `bots/<tag>/HANDOFF.md=templates/BOTHANDOFF.md` in `EMET_TEMPLATE_MAP` (additive; append to any existing entries). Conformance marks a record and never rejects a write.
+
+## 5. What a bot may never write
+
+Under a tag listed in `EMET_RECORD_DOCS` (a bot tag), `write_doc`, `patch_doc`, `retire_doc`, `rename_doc` (from or onto) and `accept_nonconformance` refuse the main handoff and board, in every session-graph mode, and nothing is written (`src/tools.js` `refuseBotMainRecord`). A close whose session revised either is `incomplete`, and a receipt that names either is `blocked`. Anything the user must see goes to the hub, which carries it into the user's records.
+
+A bot tag is also refused any write under `bots/` outside `bots/<tag>/`: other bots' records and `bots/ROSTER.md` are the hub's. When `EMET_SOURCE_TAGS` is set, the main handoff and board, and anything under `bots/`, refuse any source not registered there, a missing source included (a listed bot keeps writing and patching its own `bots/<tag>/` either way). 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).
+
+**These refusals cover listed tags only.** An unlisted or misspelled tag is treated as a host by the bot refusals. With `EMET_SOURCE_TAGS` set, the registry guard still refuses it the main records and `bots/`; a registered tag that is not listed as a bot is a host for both guards and can still write the main records (the handoff, given the version in force) and any bot's folder (a known gap). **With `EMET_SOURCE_TAGS` unset, neither guard applies; both are opt-in:** any caller can write the main records and every bot folder. Keep the roster's §3 read-back current and register every bot before it writes.
+
+## 6. The bot session loop
+
+One session per run, opened and closed by the bot itself.
+
+1. `emet_initialize {}` and fetch every page it names (each page gives the exact call for the next); `{"page": "all"}` only on a host known to read long results whole, since the server counts a whole serve as fetched even if the host's connector cut it short. Keep `startup_page.load_id`. A read: nothing is written.
+2. `emet_session_open` — a slug that names the bot and the job, and `load_id` from step 1. Keep the returned `session_id` and the start time (`session_start`). An open without `load_id`, before every page is fetched, or more than 60 minutes after the startup's last page (or after a server restart) is refused, and the refusal says what to call instead; nothing is written.
+3. `emet_transcript_append` — exchange 1, `source: <tag>`.
+4. `save_to_layer` — the session record on the episodic layer, with **`session_id`** and **`metadata.source: <tag>`**. The server stamps `derived_from` with the exchange *in progress*: the highest stored exchange plus one (`src/tools.js`, the A5 provenance stamp). Read it back.
+5. `emet_transcript_append` — exchange 2, the one the save was stamped with. **Do not skip this:** without it the close reports that a layer entry cites an exchange that was never saved, and the close is `incomplete`.
+6. `write_doc bots/<tag>/HANDOFF.md` — filled from `templates/BOTHANDOFF.md`, `source: <tag>`, written last. Revision 1 is written plain. **Every later revision is supersede-only:** pass `supersedes` set to the revision in force; `patch_doc` is refused on it, because it is a record.
+7. `emet_session_close` — with `session_id`, `session_start` and the seven receipts: `working_docs` (`[]` if none), `episodic_id`, `transcript_session_id`, `transcript_parts`, `transcript_exchanges` (the highest exchange — 2 in the loop above), `handoff_doc` (`bots/<tag>/HANDOFF.md`), `handoff_version`. Expect `state: "complete"`, `closed_recorded: true`, and `checked.session_records` with `kind: "bot"` and the tag.
+
+A bot with more exchanges appends after every reply as usual; the rule that matters is that the last append comes after the last layer save and before the handoff.
+
+**Name every write attempt.** The user's approval of a bot's writes names each write call it covers, one per line: the tool, the document id or layer, and what it writes (for the loop above: `emet_session_open` with its `load_id`; `emet_transcript_append` exchange 1; `save_to_layer` episodic; `emet_transcript_append` exchange 2; `write_doc bots/<tag>/HANDOFF.md`; `emet_session_close`), including any deliberate negative test. The hub relays that list verbatim in the bot's brief, and the bot's report lists every write it attempted, from the raw replies. The second reader checks each attempted write against the approved list: a write not on it, a retry, or a write after the close is a finding. Reads (`emet_initialize` included) and dry runs (`validate_doc`) need no listing. This is what lets the second reader confirm that nothing was written beyond what the user approved.
+
+## 7. Corrections
+
+Nothing is edited in place and nothing is deleted.
+
+- **The bot's handoff:** the next revision corrects it, with `supersedes`, and names the correction in its §4.
+- **Episodic entries** are events and are never revised: a correction is a later entry that says what it corrects.
+- **Semantic and procedural entries:** `revise_memory` writes a new entry that supersedes the old one; both stay readable.
+- **Transcripts:** `revise_transcript` writes a corrected part that points at the one it replaces.
+- **The roster:** a new revision with a §4 change-log row; a retired bot's row stays, marked RETIRED, and its handoff id is removed from `EMET_RECORD_DOCS` only when it will never write again.
+
+## 8. Tool profiles
+
+The server has no tool-profile mechanism: every connection sees every tool, and the refusals in §5 key on the tag, not on what a host offers. A roster's profile column records how the bot's host is configured. Profile names proposed for adoption are provisional until the user adopts them.

package/docs/COVERAGE.md

@@ -0,0 +1,64 @@
+# Code coverage
+
+Measured 2026-10-07 22:44 UTC at a pre-release commit, Node v22.14.0. Regenerate with `npm run coverage`.
+
+**An input to review, not a gate** (owner's ruling 2026-09-29). No threshold fails the build; the number is here so a reviewer or auditor can see what the suite exercises and what it does not.
+
+## Totals
+
+- Lines:     89.6%  (10286 of 11480 executable lines in src/)
+- Functions: 91.2%  (839 of 920 functions in loaded files)
+- Files:     38 of 38 loaded by at least one suite
+- Suites:    64 of 64 passed; 1852 checks passed, 0 failed
+
+## Method
+
+- Node's built-in V8 coverage (`NODE_V8_COVERAGE`), no dependency. Every suite runs in its own process; coverage from all of them is merged.
+- A line counts when it is not blank and not wholly comment. It is covered when any suite ran the code at its first character.
+- A function is covered when any suite called it. Functions are counted only in files a suite loaded.
+- V8 does not report a function nested inside a function that never ran, so the function figure undercounts uncalled code and reads high. **The line figure is the one to trust.**
+- A file no suite loads counts with every executable line uncovered - it is not left out.
+- The comment scanner is simple: a quote or `//` inside a regular-expression literal can misjudge that one line.
+
+## Per file, lowest line coverage first
+
+| File | Lines covered | Lines | Functions called | Loaded by a suite |
+|---|---|---|---|---|
+| `src/env.js` | 42.9% | 12 / 28 | 2 / 2 | yes |
+| `src/http-remote.js` | 53.4% | 102 / 191 | 9 / 14 | yes |
+| `src/gaps.js` | 80.1% | 258 / 322 | 23 / 34 | yes |
+| `src/dispatch.js` | 80.6% | 154 / 191 | 5 / 9 | yes |
+| `src/index.js` | 80.7% | 205 / 254 | 7 / 13 | yes |
+| `src/logger.js` | 81.9% | 177 / 216 | 22 / 25 | yes |
+| `src/database.js` | 83.8% | 434 / 518 | 39 / 45 | yes |
+| `src/tools.js` | 84.0% | 2703 / 3219 | 157 / 174 | yes |
+| `src/setup.js` | 90.4% | 838 / 927 | 59 / 65 | yes |
+| `src/oauth-provider.js` | 91.3% | 558 / 611 | 60 / 73 | yes |
+| `src/session.js` | 94.6% | 739 / 781 | 60 / 61 | yes |
+| `src/validation.js` | 95.3% | 702 / 737 | 31 / 31 | yes |
+| `src/persons.js` | 95.4% | 83 / 87 | 10 / 11 | yes |
+| `src/provenance.js` | 95.9% | 140 / 146 | 6 / 6 | yes |
+| `src/conformance.js` | 95.9% | 377 / 393 | 45 / 45 | yes |
+| `src/guides.js` | 96.0% | 24 / 25 | 4 / 4 | yes |
+| `src/content_analyzer.js` | 96.3% | 233 / 242 | 13 / 14 | yes |
+| `src/session-graph.js` | 96.4% | 541 / 561 | 76 / 78 | yes |
+| `src/layers.js` | 97.0% | 318 / 328 | 13 / 13 | yes |
+| `src/redact.js` | 97.1% | 102 / 105 | 19 / 20 | yes |
+| `src/invites.js` | 97.7% | 129 / 132 | 8 / 8 | yes |
+| `src/startup-pages.js` | 97.9% | 233 / 238 | 41 / 42 | yes |
+| `src/named-items.js` | 98.3% | 175 / 178 | 22 / 23 | yes |
+| `src/lessons-to-checks.js` | 99.7% | 291 / 292 | 24 / 25 | yes |
+| `src/aleph.js` | 100.0% | 227 / 227 | 20 / 20 | yes |
+| `src/annotations.js` | 100.0% | 45 / 45 | 4 / 4 | yes |
+| `src/approve-throttle.js` | 100.0% | 31 / 31 | 6 / 6 | yes |
+| `src/atlas-role.js` | 100.0% | 21 / 21 | 2 / 2 | yes |
+| `src/disciplines.js` | 100.0% | 11 / 11 | 0 / 0 | yes |
+| `src/floor.js` | 100.0% | 121 / 121 | 1 / 1 | yes |
+| `src/metadata.js` | 100.0% | 21 / 21 | 3 / 3 | yes |
+| `src/mongo-connect.js` | 100.0% | 20 / 20 | 4 / 5 | yes |
+| `src/request-log.js` | 100.0% | 65 / 65 | 8 / 8 | yes |
+| `src/scopes.js` | 100.0% | 43 / 43 | 9 / 9 | yes |
+| `src/security-headers.js` | 100.0% | 18 / 18 | 3 / 3 | yes |
+| `src/startup-payload.js` | 100.0% | 69 / 69 | 10 / 10 | yes |
+| `src/transcript-session.js` | 100.0% | 65 / 65 | 14 / 14 | yes |
+| `src/version.js` | 100.0% | 1 / 1 | 0 / 0 | yes |