@dreamforgestudiollc/emet 0.2.6 → 0.3.1
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.
- package/.env.example +10 -0
- package/CHANGELOG.md +26 -1
- package/README.md +34 -8
- package/areas/emet.md +18 -0
- package/areas/garden.md +18 -0
- package/areas/health.md +18 -0
- package/areas/home.md +18 -0
- package/areas/learning.md +18 -0
- package/areas/state.md +18 -0
- package/docs/DEPLOY.md +32 -1
- package/docs/DEVELOPMENT-PRACTICES.md +26 -0
- package/docs/ERROR-CODES-SPEC.md +43 -0
- package/docs/ERROR-CODES.md +332 -0
- package/docs/GUIDED-SETUP.md +16 -0
- package/docs/PERMISSIONS.md +8 -5
- package/docs/ROADMAP.md +10 -10
- package/docs/SETUP.md +115 -12
- package/package.json +4 -2
- package/server.json +7 -3
- package/src/aleph.js +16 -10
- package/src/annotations.js +8 -3
- package/src/atlas-role.js +8 -3
- package/src/attribution.js +12 -12
- package/src/conformance.js +6 -4
- package/src/database.js +28 -12
- package/src/dispatch.js +33 -16
- package/src/error-codes.js +394 -0
- package/src/error-log.js +273 -0
- package/src/error-report.js +245 -0
- package/src/floor.js +6 -4
- package/src/gaps.js +2 -2
- package/src/gem-check.js +27 -26
- package/src/http-remote.js +2 -1
- package/src/index.js +1 -0
- package/src/invites.js +6 -5
- package/src/layers.js +8 -7
- package/src/mongo-connect.js +5 -0
- package/src/oauth-provider.js +28 -27
- package/src/pages.js +806 -0
- package/src/persons.js +2 -1
- package/src/provenance.js +10 -10
- package/src/rune-dispatch.js +10 -10
- package/src/session-graph.js +16 -15
- package/src/session.js +1 -1
- package/src/setup.js +21 -17
- package/src/startup-pages.js +3 -2
- package/src/startup-payload.js +3 -2
- package/src/subkey-store.js +3 -2
- package/src/tools.js +254 -177
- package/src/validation.js +61 -52
- package/src/version.js +1 -1
- package/templates/AREA.md +35 -0
- package/templates/INDEX.md +7 -6
- package/templates/PROCEDURE.md +1 -1
- package/templates/SEED.md +2 -2
- package/templates/STAGING.md +1 -1
- 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 dreamforgestudio@mail.grokbot.com, the project's report inbox. Set it
|
|
98
|
+
# to your own address to keep reports in house.
|
|
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,32 @@ 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
|
-
##
|
|
8
|
+
## 0.3.1 - 2026-10-21
|
|
9
|
+
|
|
10
|
+
- Changed: `EMET_REPORT_EMAIL` defaults to `dreamforgestudio@mail.grokbot.com`.
|
|
11
|
+
- Added: `scripts/verify-emet.mjs`, also `npm run verify`. Subcommands are `doctor`, `list`, `run`, and `feature`. `--json` prints one object. `--dry-run` skips a call that replaces stored text or hands out access, and says what it would have called. The command uses a temporary directory and the in-memory test database. It does not read `.env`. A tool that needs a service or setting a plain install does not have is reported as a gap. A run whose only problems are gaps exits 3. A failed tool exits 1.
|
|
12
|
+
- Changed: the Official MCP Registry description in `server.json` stays within the registry's 100-character limit and names stable error codes.
|
|
13
|
+
- Added: `docs/features/` is the feature map, one file per feature, including error codes, the error log, and `emet_error_report`. `tests/feature-map.test.js` fails if a registered tool is missing from the map.
|
|
14
|
+
- Added: `docs/DEVELOPMENT-PRACTICES.md`. Docs ship in the same pull request as the feature. A feature is checked by running `verify-emet`, not by tests alone. The feature map stays current. Every pull request gets two independent reviewers who cross-check each other's verdicts.
|
|
15
|
+
|
|
16
|
+
## 0.3.0 - 2026-10-20
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
- 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.
|
|
20
|
+
- 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`.
|
|
21
|
+
- 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.
|
|
22
|
+
- 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.
|
|
23
|
+
- Retired error-code numbers stay reserved. A code removed from the registry is added to `RETIRED_CODES` and is not reused.
|
|
24
|
+
- 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.
|
|
25
|
+
- 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.
|
|
26
|
+
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`.
|
|
27
|
+
ISO 9001 7.5.3 / ISO 13485 4.2.5 document-control wording is unchanged.
|
|
28
|
+
- 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.
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
- 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.
|
|
32
|
+
- 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.
|
|
33
|
+
- 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
34
|
|
|
10
35
|
## 0.2.6 - 2026-10-20
|
|
11
36
|
|
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ EMET is an MCP (Model Context Protocol) memory server, persistent shared memory
|
|
|
10
10
|
|
|
11
11
|
**Website:** <https://dreamforgestudiollc.github.io/EMET/>
|
|
12
12
|
|
|
13
|
-
See also: [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) · [Charter](CHARTER.md)
|
|
13
|
+
See also: [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) · [Charter](CHARTER.md) · [Feature map](docs/features/README.md) · [Development practices](docs/DEVELOPMENT-PRACTICES.md)
|
|
14
14
|
|
|
15
15
|
## What it does
|
|
16
16
|
|
|
@@ -24,7 +24,9 @@ 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
|
-
- **
|
|
27
|
+
- **Error codes and problem reports.** Every error carries a stable `EMET-<AREA>-<NNN>` code. An operational error log keeps 10,000 entries or 90 days, plus daily summaries. The owner-only `emet_error_report` returns the report and an email draft that you send yourself. See [Reporting a problem](#reporting-a-problem).
|
|
28
|
+
- **verify-emet and the feature map.** `npm run verify` runs `scripts/verify-emet.mjs` from a checkout. It starts EMET in a temporary directory on the in-memory test database, with no `.env`, and drives every registered tool. A tool that needs a service a plain install does not have is reported as a gap. A run whose only problems are gaps exits 3. A failed tool exits 1. The map is [docs/features/README.md](docs/features/README.md).
|
|
29
|
+
- **MIT.** Version 0.3.1. EMET is still 0.x: stored document shapes may change before 1.0. Pin a version if you depend on them.
|
|
28
30
|
|
|
29
31
|
The store has one owner, and other people can join only through the optional Guest
|
|
30
32
|
(read-only) and Member (read and write) access, both off by default.
|
|
@@ -43,10 +45,6 @@ EMET is built for document control in environments that work under ISO 9001 and
|
|
|
43
45
|
|
|
44
46
|
## 30-second start
|
|
45
47
|
|
|
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
48
|
- **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
49
|
- **Setup:** [docs/SETUP.md](docs/SETUP.md) — the manual walkthrough: MongoDB, both transports, and the first-run interview.
|
|
52
50
|
- **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 +632,20 @@ knowable the fix is `revise_memory` with a real pointer; where it is not, the ga
|
|
|
634
632
|
fact and the count stops growing from that date. `emet_initialize` carries the counts beside
|
|
635
633
|
`layer_health`.
|
|
636
634
|
|
|
635
|
+
**Topic pages** are views, not records. An area is a controlled document, `areas/<slug>.md`,
|
|
636
|
+
checked against `templates/AREA.md`. It names layers, tags, keywords, document prefixes, an
|
|
637
|
+
optional client list, a staleness window (default 30 days), and a cap. Only the owner creates
|
|
638
|
+
or edits an area. `emet_page` computes the page on every request from current records. Every
|
|
639
|
+
displayed line cites `[mem:<id> · <layer> · <client> · <YYYY-MM-DD>]` or `[doc:<doc_id>@v<version>]`.
|
|
640
|
+
A line with no source is dropped. Superseded and retired records stay out of the current
|
|
641
|
+
sections unless `include_history` is set, and then only under History. The page is not stored,
|
|
642
|
+
not written back, and not returned by `recall`. `emet_page_lint` flags contradictions,
|
|
643
|
+
superseded-but-current claims, unsourced lines, duplicates, broken links, and long-unconfirmed
|
|
644
|
+
statuses. It writes nothing. A Monday `emet_initialize` carries the weekly counts. `STATE.md`
|
|
645
|
+
stays the hand-kept board; `areas/state.md` is the selector for a generated view beside it.
|
|
646
|
+
The shipped examples are EMET, Health, Learning, Home, and Garden. The owner
|
|
647
|
+
writes those files into the store with `write_doc`. Pages are visible to the owner only.
|
|
648
|
+
|
|
637
649
|
What can be guaranteed this way: every write attested, attributed, scrubbed, and every absence
|
|
638
650
|
visible. What cannot be guaranteed without inviting fabrication: every write complete. The
|
|
639
651
|
store does not promise the latter.
|
|
@@ -658,18 +670,22 @@ are in [`docs/GUARDRAILS-AND-MONORAILS.md`](docs/GUARDRAILS-AND-MONORAILS.md).
|
|
|
658
670
|
|
|
659
671
|
## Tools
|
|
660
672
|
|
|
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.
|
|
673
|
+
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
674
|
|
|
663
675
|
<!-- emet-tools -->
|
|
664
676
|
```
|
|
665
677
|
accept_nonconformance
|
|
666
678
|
corpus_recall
|
|
667
679
|
emet_client_approve
|
|
680
|
+
emet_error_report
|
|
668
681
|
emet_floor
|
|
669
682
|
emet_gaps
|
|
670
683
|
emet_initialize
|
|
671
684
|
emet_invite_create
|
|
672
685
|
emet_member_access_create
|
|
686
|
+
emet_page
|
|
687
|
+
emet_page_lint
|
|
688
|
+
emet_pages
|
|
673
689
|
emet_session_close
|
|
674
690
|
emet_session_open
|
|
675
691
|
emet_setup_complete
|
|
@@ -743,7 +759,7 @@ at session *start*, which is the only moment early enough to matter.
|
|
|
743
759
|
|
|
744
760
|
Every tool declares MCP annotations — `readOnlyHint`, `destructiveHint`, `idempotentHint`,
|
|
745
761
|
`openWorldHint` — in one table in `src/annotations.js`, which is also the complete statement of
|
|
746
|
-
what EMET does to a store. **
|
|
762
|
+
what EMET does to a store. **15 of the 34 tools cannot modify anything**; four can replace the
|
|
747
763
|
visible content of a document; `openWorldHint` is false everywhere. The tools reach this
|
|
748
764
|
server's own database and nothing else: no filesystem and no shell. The sign-in server fetches
|
|
749
765
|
a client's metadata document, and only from a public address it has already checked.
|
|
@@ -756,6 +772,16 @@ enforcement: what is actually auto-approved is a host-side setting. See
|
|
|
756
772
|
|
|
757
773
|
---
|
|
758
774
|
|
|
775
|
+
## Reporting a problem
|
|
776
|
+
|
|
777
|
+
`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.
|
|
778
|
+
|
|
779
|
+
Read the report first. The draft is addressed to `EMET_REPORT_EMAIL`. When that variable is unset, the address is `dreamforgestudio@mail.grokbot.com`, the project's report inbox. Set it to your own address to keep reports in house. Set it to an empty string, or to anything other than one plain address, and the tool returns the report and no email.
|
|
780
|
+
|
|
781
|
+
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).
|
|
782
|
+
|
|
783
|
+
---
|
|
784
|
+
|
|
759
785
|
## Tests
|
|
760
786
|
|
|
761
787
|
```
|
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.
|
package/areas/garden.md
ADDED
|
@@ -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.
|
package/areas/health.md
ADDED
|
@@ -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-
|
|
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,26 @@
|
|
|
1
|
+
# Development practices
|
|
2
|
+
|
|
3
|
+
How a change to EMET is specified, checked, and reviewed.
|
|
4
|
+
|
|
5
|
+
## Docs ship with the feature
|
|
6
|
+
|
|
7
|
+
Write the feature page first, from the user's point of view, and land it in the same pull request as the code. The page lives in [docs/features](features/README.md): what the feature is, how a person reaches it, how to drive it, and what goes wrong. A tutorial, a how-to, a reference, and an explanation are different jobs. Do not fold them into one muddy page. The README and the site stay in step with that page when the change is something a user can see.
|
|
8
|
+
|
|
9
|
+
The feature map is part of the tree, so the next session can read it instead of rediscovering the product. `tests/feature-map.test.js` fails if a registered tool is missing from the map. Update the map in the same change that adds or renames a tool.
|
|
10
|
+
|
|
11
|
+
## Verify by running
|
|
12
|
+
|
|
13
|
+
Tests pin behavior. They are not the whole check. `npm run verify` runs [scripts/verify-emet.mjs](../scripts/verify-emet.mjs), which brings EMET up in a temporary directory on the in-memory test database and drives the tools the way a plain install would. A tool that needs a service or a setting that process does not have is reported as a gap. Exit 3 is that report. Exit 1 is a tool that failed. Do not treat 3 as a crash, and do not stub a gap into a pass. A change to a feature is done when `verify-emet` has driven it, not when the unit tests alone are green.
|
|
14
|
+
|
|
15
|
+
Give the command a small, composable surface: `doctor`, `list`, `run`, and `feature`, plus `--json` and `--dry-run` on anything that replaces or hands out access. Errors say what to do instead.
|
|
16
|
+
|
|
17
|
+
## Two reviewers
|
|
18
|
+
|
|
19
|
+
Every pull request gets two independent reviewers. Each one cross-checks the other's verdict against the diff and against a run of the change. A disagreement is resolved in the thread before merge.
|
|
20
|
+
|
|
21
|
+
## Where this came from
|
|
22
|
+
|
|
23
|
+
These practices follow Lauren Tan's *The Complete Guide to pstack*: a verification command you can run, a feature map in the repo, and docs written before the implementation so the code has something to be checked against.
|
|
24
|
+
|
|
25
|
+
- Part 1: <https://x.com/poteto/status/2094457600259842065>
|
|
26
|
+
- Part 2: <https://x.com/poteto/status/2097732320606507506>
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Error codes and the error report
|
|
2
|
+
|
|
3
|
+
This is the behavior EMET 0.3.1 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 `dreamforgestudio@mail.grokbot.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.
|