@dreamforgestudiollc/emet 0.2.6 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/.env.example +10 -0
  2. package/CHANGELOG.md +18 -1
  3. package/README.md +31 -7
  4. package/areas/emet.md +18 -0
  5. package/areas/garden.md +18 -0
  6. package/areas/health.md +18 -0
  7. package/areas/home.md +18 -0
  8. package/areas/learning.md +18 -0
  9. package/areas/state.md +18 -0
  10. package/docs/DEPLOY.md +32 -1
  11. package/docs/ERROR-CODES-SPEC.md +43 -0
  12. package/docs/ERROR-CODES.md +332 -0
  13. package/docs/GUIDED-SETUP.md +16 -0
  14. package/docs/PERMISSIONS.md +8 -5
  15. package/docs/ROADMAP.md +10 -10
  16. package/docs/SETUP.md +115 -12
  17. package/package.json +3 -2
  18. package/server.json +7 -3
  19. package/src/aleph.js +16 -10
  20. package/src/annotations.js +8 -3
  21. package/src/atlas-role.js +8 -3
  22. package/src/attribution.js +12 -12
  23. package/src/conformance.js +6 -4
  24. package/src/database.js +28 -12
  25. package/src/dispatch.js +33 -16
  26. package/src/error-codes.js +394 -0
  27. package/src/error-log.js +273 -0
  28. package/src/error-report.js +245 -0
  29. package/src/floor.js +6 -4
  30. package/src/gaps.js +2 -2
  31. package/src/gem-check.js +27 -26
  32. package/src/http-remote.js +2 -1
  33. package/src/index.js +1 -0
  34. package/src/invites.js +6 -5
  35. package/src/layers.js +8 -7
  36. package/src/mongo-connect.js +5 -0
  37. package/src/oauth-provider.js +28 -27
  38. package/src/pages.js +806 -0
  39. package/src/persons.js +2 -1
  40. package/src/provenance.js +10 -10
  41. package/src/rune-dispatch.js +10 -10
  42. package/src/session-graph.js +16 -15
  43. package/src/session.js +1 -1
  44. package/src/setup.js +21 -17
  45. package/src/startup-pages.js +3 -2
  46. package/src/startup-payload.js +3 -2
  47. package/src/subkey-store.js +3 -2
  48. package/src/tools.js +254 -177
  49. package/src/validation.js +61 -52
  50. package/src/version.js +1 -1
  51. package/templates/AREA.md +35 -0
  52. package/templates/INDEX.md +7 -6
  53. package/templates/PROCEDURE.md +1 -1
  54. package/templates/SEED.md +2 -2
  55. package/templates/STAGING.md +1 -1
  56. package/templates/THREAD.md +1 -1
package/.env.example CHANGED
@@ -92,6 +92,16 @@ EMET_SOURCE_TAGS=laptop,phone,cli
92
92
  # default is America/New_York.
93
93
  # EMET_TIMEZONE=America/New_York
94
94
 
95
+ # Optional. Address used by emet_error_report for the mailto draft and the
96
+ # structured email a calling assistant can pass to its own mail tool. Unset
97
+ # uses reports@example.com. That address is a placeholder, not a mailbox:
98
+ # configure this to a real address, or the report is returned and goes nowhere.
99
+ # EMET does not send mail. An empty string (a real empty environment
100
+ # variable, not a blank line in this file) returns the report and no email.
101
+ # The assistant may send the report only after showing it to you and getting
102
+ # your OK.
103
+ # EMET_REPORT_EMAIL=
104
+
95
105
  # Optional. Minutes after a complete close in which the session still takes its
96
106
  # ONE closing exchange (the reply sent after emet_session_close). After that one
97
107
  # append, or once the window passes, the session is locked. Default 5; 0 = off;
package/CHANGELOG.md CHANGED
@@ -5,7 +5,24 @@ All notable changes to EMET are listed here, newest first. The format follows
5
5
  [Semantic Versioning](https://semver.org/). EMET is still 0.x: the stored data shapes may
6
6
  change before 1.0.
7
7
 
8
- ## Unreleased
8
+ ## 0.3.0 - 2026-10-20
9
+
10
+ ### Added
11
+ - The public site's subject links open in place as tabs. The hero stays above the tab list. A hash such as `#start` still opens that subject, and the hash updates when the subject changes. With JavaScript disabled, the page is the full document and the header links are anchors. A subject can host a simulator later: the mount stays empty, and demo code loads only when that subject is first shown. Hiding a subject tells a running demo to pause.
12
+ - Stable error codes. Every error EMET returns carries `error.emet_code` (`EMET-<AREA>-<NNN>`). The existing `error.code` field is unchanged, and message text is unchanged. The registry is `src/error-codes.js`. The table is `docs/ERROR-CODES.md`. An uncoded error that reaches a caller is `EMET-INT-001`.
13
+ - An operational error log (`error_log`), capped at 10,000 entries or 90 days, with a daily summary kept in `error_log_summary`. Rotation is a dated job. The log is not a controlled record. It stores no message text, arguments, document content, names, or secrets. A failed log write still returns the original error.
14
+ - Owner-only, read-only `emet_error_report` (34 tools with sub-keys off, 15 of them read-only). It writes nothing and sends nothing. The result is the full report, a `mailto:` draft to `EMET_REPORT_EMAIL` (unset uses `reports@example.com`; an empty string or any value that is not one plain address returns the report and no email), and a structured email `{to, subject, body_text, short_id, version}` a calling assistant can pass to its own email tool. The calling assistant may send this report only after showing the report to its user and getting their OK.
15
+ - Retired error-code numbers stay reserved. A code removed from the registry is added to `RETIRED_CODES` and is not reused.
16
+ - Upgrading to 0.3.0: error-log rotation caps `error_log` at 10,000 entries or 90 days and keeps the daily summaries in `error_log_summary`. Rotation deletes from `error_log`, so an existing database role needs `REMOVE` on `<db>.error_log` and on no other collection. Before the change, save the role: `atlas customDbRoles describe emetRecordKeeper --projectId <id> --output json > role-before.json`. Then append, which leaves every other privilege in place: `atlas customDbRoles update emetRecordKeeper --privilege REMOVE@<db>.error_log --append --projectId <id>`. Atlas UI: Database Access → Custom Roles → edit the role → database `<db>`, collection `error_log`, action `REMOVE`. Afterward, `atlas customDbRoles describe emetRecordKeeper --projectId <id> --output json` must not contain `DROP_COLLECTION` anywhere.
17
+ - An older stray `DROP_COLLECTION` on `_emet_verify` is not cleared by that append command. That append command cannot remove a privilege. Dry-run `node scripts/atlas-role.mjs --project <id> --db <db> --user <dbUsername> --prefix <prefix>`. The dry run calls the read-only `atlas customDbRoles describe emetRecordKeeper --projectId <id> --output json`. It needs Atlas auth and changes nothing. Then `node scripts/atlas-role.mjs --project <id> --db <db> --user <dbUsername> --prefix <prefix> --apply`, or clear it in the Atlas UI. `--prefix <prefix>` is `EMET_COLLECTION_PREFIX` (default `emet_`). `--prefix` overrides `EMET_COLLECTION_PREFIX`. The effective prefix is `--prefix`, or else the env. Re-applying replaces prefixed privilege names if the effective prefix doesn't match the install.
18
+ New installs use `scripts/atlas-role.mjs` (dry run, then `--apply`), passing `--db <db>` and `--prefix <prefix>`. The script sends the full privilege list from `src/atlas-role.js`. See `docs/SETUP.md`.
19
+ ISO 9001 7.5.3 / ISO 13485 4.2.5 document-control wording is unchanged.
20
+ - Topic pages (`emet_page`, `emet_pages`, `emet_page_lint`). A page is a view computed on each request from current records. It is not stored, not written back, and not returned by recall. Every displayed line cites its source. Area selectors are controlled documents `areas/<slug>.md` checked against `templates/AREA.md`. Only the owner creates or edits an area, and only the owner can read a page. Stale after 30 days unconfirmed, overridable on the area. Lint flags and never edits. A Monday `emet_initialize` carries the weekly counts. `STATE.md` stays the hand-kept board; `areas/state.md` is the generated view beside it. ISO 9001 7.5.3 / ISO 13485 4.2.5 document-control wording is unchanged.
21
+
22
+ ### Fixed
23
+ - If the site tab script does not load, the address bar keeps the subject fragment. A demo module path must be same-origin. The subject navigation stays a landmark; the tab list is the list inside it.
24
+ - Area documents stay owner-only on `accept_nonconformance`, as they already are on `write_doc`, `retire_doc`, and `rename_doc`. `as_of` cites the newest document revision in force on that date, latest write and then highest version, so an older history row with no archive date is not cited once a later revision exists. A revision that was archived, with no later revision recorded, is absent from that past view. A superseded or retired record with no end date stays in that past view, labelled "end date unknown", and is not a current line. A document with no version is dropped.
25
+ - A plain report address rejects a local part that starts or ends with a dot or contains `..`, and a domain label that is empty or starts or ends with a hyphen. Addresses such as `k@-x.com`, `k@x..com`, `.k@x.com`, and `k@x.com.` return the report and no email. EMET does not send the report.
9
26
 
10
27
  ## 0.2.6 - 2026-10-20
11
28
 
package/README.md CHANGED
@@ -24,7 +24,7 @@ See also: [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECUR
24
24
  - **Client-side GEM execution.** A GEM may declare a tool. EMET does not run that computation. EMET verifies the record, not the computation. The client runs the tool, and what is written back is checked the same way as any other write.
25
25
  - **Released flag.** A GEM is seated only when its released flag is the boolean true. Any other value is refused. A missing flag is refused except for a legacy manifest pinned by id, version, and file digests.
26
26
  - **Per-client attribution and approvals.** Every write is attributed to the client that made it. A new client is read-limited until it is approved. The approval is recorded.
27
- - **MIT.** Version 0.2.6. EMET is still 0.x: stored document shapes may change before 1.0. Pin a version if you depend on them.
27
+ - **MIT.** Version 0.3.0. EMET is still 0.x: stored document shapes may change before 1.0. Pin a version if you depend on them.
28
28
 
29
29
  The store has one owner, and other people can join only through the optional Guest
30
30
  (read-only) and Member (read and write) access, both off by default.
@@ -43,10 +43,6 @@ EMET is built for document control in environments that work under ISO 9001 and
43
43
 
44
44
  ## 30-second start
45
45
 
46
- > **npm lags the repo.** `npx -y @dreamforgestudiollc/emet` installs 0.2.4 until 0.2.6 is
47
- > published. For 0.2.6, clone this repo and run `npm ci && npm start`, or deploy the
48
- > `Dockerfile`. See [docs/SETUP.md](docs/SETUP.md).
49
-
50
46
  - **Guided setup:** [docs/GUIDED-SETUP.md](docs/GUIDED-SETUP.md) — never deployed anything. Your assistant installs, configures, deploys, and verifies. You sign in when asked and paste the connector URL.
51
47
  - **Setup:** [docs/SETUP.md](docs/SETUP.md) — the manual walkthrough: MongoDB, both transports, and the first-run interview.
52
48
  - **Deploy:** [docs/DEPLOY.md](docs/DEPLOY.md) — remote HTTP with OAuth, so a phone, a browser, or another vendor's agent reaches the same store.
@@ -634,6 +630,20 @@ knowable the fix is `revise_memory` with a real pointer; where it is not, the ga
634
630
  fact and the count stops growing from that date. `emet_initialize` carries the counts beside
635
631
  `layer_health`.
636
632
 
633
+ **Topic pages** are views, not records. An area is a controlled document, `areas/<slug>.md`,
634
+ checked against `templates/AREA.md`. It names layers, tags, keywords, document prefixes, an
635
+ optional client list, a staleness window (default 30 days), and a cap. Only the owner creates
636
+ or edits an area. `emet_page` computes the page on every request from current records. Every
637
+ displayed line cites `[mem:<id> · <layer> · <client> · <YYYY-MM-DD>]` or `[doc:<doc_id>@v<version>]`.
638
+ A line with no source is dropped. Superseded and retired records stay out of the current
639
+ sections unless `include_history` is set, and then only under History. The page is not stored,
640
+ not written back, and not returned by `recall`. `emet_page_lint` flags contradictions,
641
+ superseded-but-current claims, unsourced lines, duplicates, broken links, and long-unconfirmed
642
+ statuses. It writes nothing. A Monday `emet_initialize` carries the weekly counts. `STATE.md`
643
+ stays the hand-kept board; `areas/state.md` is the selector for a generated view beside it.
644
+ The shipped examples are EMET, Health, Learning, Home, and Garden. The owner
645
+ writes those files into the store with `write_doc`. Pages are visible to the owner only.
646
+
637
647
  What can be guaranteed this way: every write attested, attributed, scrubbed, and every absence
638
648
  visible. What cannot be guaranteed without inviting fabrication: every write complete. The
639
649
  store does not promise the latter.
@@ -658,18 +668,22 @@ are in [`docs/GUARDRAILS-AND-MONORAILS.md`](docs/GUARDRAILS-AND-MONORAILS.md).
658
668
 
659
669
  ## Tools
660
670
 
661
- Thirty tools are registered with sub-keys off. With `EMET_SUBKEYS=1`, four more (`emet_subkey_request`, `emet_subkey_claim`, `emet_subkey_revoke`, `emet_subkey_end_session`) and the `subkey` and `session_handle` arguments. The names below are every tool the registry registers, both sets together.
671
+ Thirty-four tools are registered with sub-keys off. With `EMET_SUBKEYS=1`, four more (`emet_subkey_request`, `emet_subkey_claim`, `emet_subkey_revoke`, `emet_subkey_end_session`) and the `subkey` and `session_handle` arguments. The names below are every tool the registry registers, both sets together.
662
672
 
663
673
  <!-- emet-tools -->
664
674
  ```
665
675
  accept_nonconformance
666
676
  corpus_recall
667
677
  emet_client_approve
678
+ emet_error_report
668
679
  emet_floor
669
680
  emet_gaps
670
681
  emet_initialize
671
682
  emet_invite_create
672
683
  emet_member_access_create
684
+ emet_page
685
+ emet_page_lint
686
+ emet_pages
673
687
  emet_session_close
674
688
  emet_session_open
675
689
  emet_setup_complete
@@ -743,7 +757,7 @@ at session *start*, which is the only moment early enough to matter.
743
757
 
744
758
  Every tool declares MCP annotations — `readOnlyHint`, `destructiveHint`, `idempotentHint`,
745
759
  `openWorldHint` — in one table in `src/annotations.js`, which is also the complete statement of
746
- what EMET does to a store. **11 of the 30 tools cannot modify anything**; four can replace the
760
+ what EMET does to a store. **15 of the 34 tools cannot modify anything**; four can replace the
747
761
  visible content of a document; `openWorldHint` is false everywhere. The tools reach this
748
762
  server's own database and nothing else: no filesystem and no shell. The sign-in server fetches
749
763
  a client's metadata document, and only from a public address it has already checked.
@@ -756,6 +770,16 @@ enforcement: what is actually auto-approved is a host-side setting. See
756
770
 
757
771
  ---
758
772
 
773
+ ## Reporting a problem
774
+
775
+ `emet_error_report` is owner-only and read-only. It reads the operational error log and returns the full report, a `mailto:` draft, and a structured email `{to, subject, body_text, short_id, version}`. EMET does not send mail and does not open a network connection for this tool.
776
+
777
+ Read the report first. The draft is addressed to `EMET_REPORT_EMAIL`. When that variable is unset, the address is `reports@example.com`. That address is a placeholder, not a mailbox: configure `EMET_REPORT_EMAIL` to a real address, or the report is returned and goes nowhere. Set the variable to an empty string, or to anything other than one plain address, and the tool returns the report and no email.
778
+
779
+ A calling assistant that has its own email address may pass that structured email to its own email tool. The calling assistant may send this report only after showing the report to its user and getting their OK. EMET will not send it. The code table is [docs/ERROR-CODES.md](docs/ERROR-CODES.md), and the behavior is written up in [docs/ERROR-CODES-SPEC.md](docs/ERROR-CODES-SPEC.md).
780
+
781
+ ---
782
+
759
783
  ## Tests
760
784
 
761
785
  ```
package/areas/emet.md ADDED
@@ -0,0 +1,18 @@
1
+ # Area — EMET
2
+
3
+ ## §0 RECORD CONTROL
4
+ - Template: `templates/AREA.md` · Area revision: the store's version governs
5
+ - Slug: emet
6
+ - Title: EMET
7
+
8
+ ## §1 SELECTOR
9
+ - **Layers:** semantic, procedural, meta
10
+ - **Tags:** emet, memory, document-control
11
+ - **Keywords:** emet, memory
12
+ - **Doc id prefixes:** threads/emet
13
+ - **Source clients:** any
14
+ - **Staleness days:** 30
15
+ - **Item cap:** 40
16
+
17
+ ## §2 SCOPE
18
+ Selector for the EMET topic. This document names what to look at. The page is computed when asked for.
@@ -0,0 +1,18 @@
1
+ # Area — Garden
2
+
3
+ ## §0 RECORD CONTROL
4
+ - Template: `templates/AREA.md` · Area revision: the store's version governs
5
+ - Slug: garden
6
+ - Title: Garden
7
+
8
+ ## §1 SELECTOR
9
+ - **Layers:** semantic, episodic
10
+ - **Tags:** garden, plants
11
+ - **Keywords:** garden
12
+ - **Doc id prefixes:** threads/garden
13
+ - **Source clients:** any
14
+ - **Staleness days:** 30
15
+ - **Item cap:** 40
16
+
17
+ ## §2 SCOPE
18
+ Selector for the garden topic. This document names what to look at. The page is computed when asked for.
@@ -0,0 +1,18 @@
1
+ # Area — Health
2
+
3
+ ## §0 RECORD CONTROL
4
+ - Template: `templates/AREA.md` · Area revision: the store's version governs
5
+ - Slug: health
6
+ - Title: Health
7
+
8
+ ## §1 SELECTOR
9
+ - **Layers:** semantic, procedural, episodic
10
+ - **Tags:** health
11
+ - **Keywords:** health, rest, walk
12
+ - **Doc id prefixes:** threads/health
13
+ - **Source clients:** any
14
+ - **Staleness days:** 30
15
+ - **Item cap:** 40
16
+
17
+ ## §2 SCOPE
18
+ Selector for the health topic. This document names what to look at. The page is computed when asked for.
package/areas/home.md ADDED
@@ -0,0 +1,18 @@
1
+ # Area — Home
2
+
3
+ ## §0 RECORD CONTROL
4
+ - Template: `templates/AREA.md` · Area revision: the store's version governs
5
+ - Slug: home
6
+ - Title: Home
7
+
8
+ ## §1 SELECTOR
9
+ - **Layers:** semantic, episodic
10
+ - **Tags:** home
11
+ - **Keywords:** home
12
+ - **Doc id prefixes:** threads/home
13
+ - **Source clients:** any
14
+ - **Staleness days:** 30
15
+ - **Item cap:** 40
16
+
17
+ ## §2 SCOPE
18
+ Selector for the home topic. This document names what to look at. The page is computed when asked for.
@@ -0,0 +1,18 @@
1
+ # Area — Learning
2
+
3
+ ## §0 RECORD CONTROL
4
+ - Template: `templates/AREA.md` · Area revision: the store's version governs
5
+ - Slug: learning
6
+ - Title: Learning
7
+
8
+ ## §1 SELECTOR
9
+ - **Layers:** semantic, episodic, working
10
+ - **Tags:** learning
11
+ - **Keywords:** learning, notes, practice
12
+ - **Doc id prefixes:** threads/learning
13
+ - **Source clients:** any
14
+ - **Staleness days:** 30
15
+ - **Item cap:** 40
16
+
17
+ ## §2 SCOPE
18
+ Selector for the learning topic. This document names what to look at. The page is computed when asked for.
package/areas/state.md ADDED
@@ -0,0 +1,18 @@
1
+ # Area — State
2
+
3
+ ## §0 RECORD CONTROL
4
+ - Template: `templates/AREA.md` · Area revision: the store's version governs
5
+ - Slug: state
6
+ - Title: State
7
+
8
+ ## §1 SELECTOR
9
+ - **Layers:** semantic, procedural, episodic, working
10
+ - **Tags:** status, decision, open
11
+ - **Keywords:** status, decision
12
+ - **Doc id prefixes:** threads/
13
+ - **Source clients:** any
14
+ - **Staleness days:** 30
15
+ - **Item cap:** 40
16
+
17
+ ## §2 SCOPE
18
+ Selector for the generated state view that runs beside the hand-kept STATE.md board. STATE.md stays the board. This revision does not retire it.
package/docs/DEPLOY.md CHANGED
@@ -13,6 +13,37 @@ scoped user, and Atlas Network Access set to `0.0.0.0/0` — a hosted platform's
13
13
  dynamic, so it cannot be allowlisted. Security rests on the scoped user plus the OAuth
14
14
  passphrase; both are required.
15
15
 
16
+ ## Upgrading to 0.3.0
17
+
18
+ Error-log rotation deletes from `error_log` (10,000 entries or 90 days; daily summaries are
19
+ kept in `error_log_summary`). An existing custom role needs `REMOVE` on that collection only.
20
+ Save the role, then append the privilege. The full note
21
+ is [SETUP.md](SETUP.md#upgrading-to-030).
22
+
23
+ ```
24
+ atlas customDbRoles describe emetRecordKeeper --projectId <id> --output json > role-before.json
25
+ atlas customDbRoles update emetRecordKeeper --privilege REMOVE@<db>.error_log --append --projectId <id>
26
+ atlas customDbRoles describe emetRecordKeeper --projectId <id> --output json
27
+ ```
28
+
29
+ `<db>` is `MONGODB_DB`. `<id>` is the project id from `atlas projects list`. In the JSON after
30
+ the change, a `REMOVE` resource has `"collection": "error_log"`. No `REMOVE` resource has an
31
+ empty collection, and this upgrade adds no other collection.
32
+
33
+ ### Clear a stray DROP_COLLECTION
34
+
35
+ `DROP_COLLECTION` must not appear anywhere in that output.
36
+ An older stray `DROP_COLLECTION` on `_emet_verify` is not cleared by that append command. That append command cannot remove a privilege. Dry run first, then apply. The dry run calls the read-only `atlas customDbRoles describe emetRecordKeeper --projectId <id> --output json`. It needs Atlas auth and changes nothing. `--prefix <prefix>` is `EMET_COLLECTION_PREFIX` (default `emet_`). `--prefix` overrides `EMET_COLLECTION_PREFIX`. The effective prefix is `--prefix`, or else the env. Re-applying replaces prefixed privilege names if the effective prefix doesn't match the install.
37
+
38
+ ```
39
+ node scripts/atlas-role.mjs --project <id> --db <db> --user <dbUsername> --prefix <prefix>
40
+ node scripts/atlas-role.mjs --project <id> --db <db> --user <dbUsername> --prefix <prefix> --apply
41
+ ```
42
+
43
+ Or in the Atlas UI: Database Access → Custom Roles → edit the role and clear `DROP_COLLECTION`.
44
+ Atlas UI for the new privilege: Database Access → Custom Roles → edit the role → collection
45
+ `error_log`, action `REMOVE`. Leave `REMOVE` off every other collection and off the database-wide row.
46
+
16
47
  ## Environment variables
17
48
 
18
49
  | Variable | Required | Purpose |
@@ -35,7 +66,7 @@ passphrase; both are required.
35
66
 
36
67
  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.
37
68
 
38
- - **`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.
69
+ - **`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-cowork`, `cowork-cloud`, `grok-project`, `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.
39
70
  - 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.
40
71
  - **`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.
41
72
  - **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`.
@@ -0,0 +1,43 @@
1
+ # Error codes and the error report
2
+
3
+ This is the behavior EMET 0.3.0 ships. The code table is generated from the registry: [ERROR-CODES.md](ERROR-CODES.md). A code’s meaning does not change. A removed code is added to the retired list, stays in that table, and its number is not reused.
4
+
5
+ ## Where the code goes
6
+
7
+ Every error returned to a caller carries `error.emet_code`, shaped `EMET-<AREA>-<NNN>`. The existing `error.code` field (`VALIDATION_ERROR`, `DATABASE_ERROR`, `INTERNAL_ERROR`, and the rest) is unchanged. Message text is unchanged when a code is added.
8
+
9
+ An error that reaches the caller with no registered code is `EMET-INT-001`.
10
+
11
+ ## The operational log
12
+
13
+ `error_log` is operational bookkeeping. It is not a memory, a document, or a transcript, and it is not a controlled record. No tool edits or deletes a log entry. A dated job removes a row when the log is over 10,000 entries or the row is older than 90 days, whichever comes first, and only after writing a daily summary (`day`, `emet_code`, `tool`, `version`, `count`) that is kept. The job logs how many rows it rotated.
14
+
15
+ A failed log write still returns the original error. The process log hears only the fixed line `error log write failed`.
16
+
17
+ A row stores the time, the code, the class code, the tool name, the version, the transport, the caller tag when that tag is registered, the role (`owner` or `guest`), a correlation id, and a count. It does not store argument values or names, message text, memory or document content, document ids or titles, area or page names, person names or ids, email addresses, IP addresses, tokens, passphrases, client secrets, query strings, or stack traces.
18
+
19
+ ## The report
20
+
21
+ `emet_error_report` is owner-only and read-only. A local stdio session is the owner. On HTTP the signed-in person must have the owner role. Anyone else receives `EMET-AUTH-038` (“The error report is owner-only.”), not an empty report.
22
+
23
+ The tool writes nothing and sends nothing. EMET has no mail sender and opens no network connection for this tool.
24
+
25
+ Inputs are optional: `since` (default 7 days, at most 90), `codes`, `correlation_id`, and `limit` (default 50, maximum 200). A correlation id is looked up on its own, so the id the caller was given still resolves inside the log window even when `since` would exclude that day.
26
+
27
+ The result is, in order:
28
+
29
+ 1. The full report, never truncated.
30
+ 2. A `mailto:` draft, when an address is set.
31
+ 3. A structured email `{to, subject, body_text, short_id, version}`, plus the mailto link, so a calling assistant can pass it to its own email tool.
32
+
33
+ `to` is `EMET_REPORT_EMAIL`. When the variable is unset, the address is `reports@example.com`. An empty string means no email: the tool returns the report and `email: null`. Any other value is treated the same way unless it is one plain address: exactly one `@`, a local part of letters, digits, and `. _ + -` that does not start or end with a dot and does not contain `..`, and a domain of at least two labels separated by dots. A label is letters, digits, and `-`, does not start or end with `-`, and is not empty.
34
+
35
+ The subject is `EMET error report <version> <6 hex characters>`. `body_text` is the full report shown above. The mailto body is that same text when it fits, and a shorter draft when it does not. The link is at most 1,800 characters. Totals stay when they fit. Recent lines are cut to the newest that fit, and the draft says so. The report in the tool output stays complete.
36
+
37
+ ## A bot may send it, after a yes
38
+
39
+ EMET itself never sends the report. A person can open the mailto draft. An assistant that has its own mailbox can send the structured email with its own email tool, addressed to the same `to`.
40
+
41
+ The calling assistant may send this report only after showing the report to its user and getting their OK. That sentence is in the tool description and in the tool output. It is not part of the report body, so the text the recipient reads stays the report.
42
+
43
+ This is an owner decision added after the report was specified as a draft the person sends. The server stays free of SMTP and of any network call on this path.