Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat(topics): topic records, pages, dream planning, brain_topic and o2b topic (#306)

Serg Eroshe06ccee2e41a0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85e26a05..4932350c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **Topics: the `brain_topic` tool, `o2b topic`, and planning in dream.** `brain_topic` and the `o2b topic` verbs list, show and review topics and change them (create, rename, status, goal, assign, unassign, merge, split, link, archive, undo), and let an agent record its own decisions, open questions, log entries and milestones on the topic it works on. A command is stored as your record; a tool call carries the agent's authority unless the agent names yours on your explicit request, which a remote caller cannot, so an agent's goal never replaces the one you wrote and shows as an open question instead. A record names only an item of its own topic. A caller of a remote MCP transport never sees a private topic: it is absent from every list, `show` and `osb://topic/{id}` answer it as an unknown id, and a write that names it is refused the same way. The dream pass plans topics on the view writer only, under a lock, so two machines or two passes never create the same topic: it routes a new record of a project to the topic it clearly belongs to, creates a topic when enough related records of one project (`topics.new_min_records`, default 5) come from at least two sessions (`topics.new_min_sessions`), lists every create and route in its report with the `o2b topic undo` command that takes it back, and never routes or recreates what you undid. Merges and splits are only proposed, and a topic with no news for `topics.quiet_days` (default 30) is offered for a status decision in the digest; nothing changes until you answer. Unticking a done milestone on its page opens it again. Undoing an undo of a private topic's record stays in `private`, private titles, descriptions and goals never route a shared record, a `record` whose `owner` holds no such item (or is neither the topic nor one merged into it) is refused, and a remote caller gets the scope of `list` and `show` fenced like the other topic text. A drafted title of characters outside the Basic Multilingual Plane is cut to fit the record limit instead of never becoming a topic. A view writer move that arrives while a pass plans stops it before it writes, a dream pass whose deadline passed while it waited for the planning lock writes nothing, and a pass that fails midway still lists the topics and routes it wrote, with their undo commands. A split moves an item of a topic merged into the one it names, and refuses an item the topic does not show; an item id a split moved away is not taken again for a new item, and a decision reworded on its page keeps the milestones it serves. When two topics exchange folder names, each keeps its own companion files. A companion move or a conflict copy never deletes a newer version a sync tool delivers under the same name meanwhile; it is kept, and a copy is ingested on the next pass. A folder or symbolic link named like a conflict copy is refused where it is, never moved or read. Editing a private item of a shared topic keeps the new text in `private`, a private record is routed by the private text of a topic, and `o2b topic split --owner` names whose item moves when two merged topics share its id. `brain_topic` refuses a `private` or `removed` value that is not a boolean instead of ignoring it, a dream pass plans topics on its own date and its undo commands name the config it ran with, and a topic counts as active when a topic merged into it or a split into it brings news. A private completion or resolution makes its item private, so a later one written without the flag stays private, and a route you took back from a topic stays blocked after that topic is merged into another. The state digests now carry a `topics` fold hash, so doctor reports machines whose topic folds diverge; a digest from an earlier release has none and is not compared on it. The topics guide is `docs/topics.md`.
+- **`osb://topic/{slug}` is now `osb://rule-topic/{slug}`.** The resource that summarises the signals and the rule of a preference slug moved to its new name, and `osb://topic/{id}` serves topics; the old name still answers a slug for one minor version. Code that names the preference slug says `ruleTopic` now; the `topic` field of signals keeps its name.
+- **Topics in the brain store and the human view (first part).** A topic is one area of work or one personal matter with an id that never changes: its title, description, status, goal, milestones, decisions, open questions, log, links, merges, splits and record assignments are records of the `topics` stream (`topic-create`, `topic-rename`, `topic-status`, `topic-goal`, `decision`, `open-question`, `question-resolved`, `log-entry`, `milestone`, `milestone-done`, `assign`, `unassign`, `merge`, `split`, `link`, `undo`, documented in `FORMAT.md`), folded the same way on every machine, with your records beating an agent's and an agent's beating a decision model's. A rename keeps the id and every reference, an undo voids the record it names and keeps a route you took back from being taken again, a milestone is done only when you mark it or an agent cites evidence, and a personal topic goes to the `private` partition by default. The view writer renders each shared topic to `topics/<date>-<slug>/topic.md` in a fixed section order (title, description, status, goal, milestones, decisions, open questions, the log newest first, related), moves the oldest entries over the page budget to a companion `archive.md`, shows only earned log entries, and moves the folder, your companion files included, when the topic is renamed. Your edits of a topic page become topic records with your authority, so a goal you rewrite stays even when an agent later proposes another, which then shows as an open question. Research reports and source summaries render to `reports/` and `sources/`. A note tool refuses a topic, report or source page of the view and names the tool to use instead; with the view at the vault root, your own notes in folders of those names stay writable. The view writer only ever touches a page of the exact shapes it writes, inside its view folder and never through a symbolic link; a folder at a topic page's name is reported as refused while the rest of the view renders, and a companion file the writer moves is never left in both folders, also when a sync tool replaces it mid-move or Windows refuses to remove it. Undoing an automatic route or taking a record out of a topic blocks that route whether you or an agent wrote the undo.
- **Brain store hardening.** Readers that show log events, or numbers derived from them, to a caller below local reach now withhold events of the `private` partition, and a census test fails on any new log reader that has not been classified. `brain_doctor` names each shard that reads only in part by kind, offset and repair command, and `o2b store shard quarantine|list|release` skips one bad line on this machine without touching the shard (a line of a newer format is never skipped, a pending blob only after seven days and never in `settings`). `o2b store partition leave <partition>` takes a partition off this machine on purpose, and the error that names a lost partition names the verb. A `lane-entry` record keeps the file's text in an optional `raw` field when its fields and text do not reproduce it, so a lane file written as text reads back byte for byte, also after a rollback; the format version does not change.
### Fixed
diff --git a/docs/brain-store.md b/docs/brain-store.md
index 5cac87f7..4b08824b 100644
--- a/docs/brain-store.md
+++ b/docs/brain-store.md
@@ -254,6 +254,11 @@ store into the `view_target` folder:
| `about-me.md` | What the brain knows about you: confirmed rules, grouped by subject |
| `history/<YYYY>-W<ww>.md` | One page per week of what happened, in plain language |
| `decisions.md` | Decisions that were recorded |
+| `topics/<date>-<slug>/topic.md` | One page per shared topic: status, goal, milestones, decisions, open questions, log and related, with an `archive.md` beside it for older entries |
+| `reports/<entry>.md` | One page per research report |
+| `sources/<entry>.md` | One page per ingested source summary |
+
+Topics have their own guide: [topics.md](topics.md).
Each page starts with one HTML comment line that names the store and the
page; there is no frontmatter and there are no Obsidian-only links, so any
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 722c9b7a..74959fdd 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -718,7 +718,8 @@ content as **resources** (added in v0.9.1):
| `osb://digest/latest` | most recent `brain_digest` rendering |
| `osb://status` | Markdown form of the `second_brain_status.brain` block |
| `osb://preference/{id}` | one `pref-` / `ret-` file |
-| `osb://topic/{slug}` | every signal + active/retired pref for a topic |
+| `osb://rule-topic/{slug}` | every signal + active/retired pref for a rule topic (`osb://topic/{slug}` is an alias for one minor version) |
+| `osb://topic/{id}` | one topic's page (see [topics.md](topics.md)) |
| `osb://log/{date}` | one day's `Brain/log/YYYY-MM-DD.md` (a parallel `YYYY-MM-DD.jsonl` sidecar carries the same events as one JSON row per line for machine consumers) |
| `osb://backlinks/{id}` | inverted reference map for `<id>` |
diff --git a/docs/mcp.md b/docs/mcp.md
index dab73aef..a06d27d2 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -445,6 +445,7 @@ flags for a narrower per-process full server.
| `brain_search` | Vault search with optional structured query lanes, explicit focus hints, time ranges, evidence-pack diagnostics, a selectable recall `profile` (`fast \| balanced \| thorough`), an FTS `match_mode` (`all` \| `any`), a pushed `kind` filter (`page` \| `section`) plus SQL pushdown for the promoted `properties` keys (since v1.80.0), and since v1.82.0 an opt-in iterative recall loop (`iterative`, `iterative_token`, `iterative_payload`) whose surviving coverage gaps pause with a plan the caller answers. Write-classified: it persists activation access events by default and the opt-in reinforce, recall-telemetry and query-demand ledgers under `Brain/search/` - ranking state later searches read back. | `query` |
| `brain_changes` | Change probe over the brain store (phase 1 trial, active only when a store is in use): returns the record ids added since an optional watermark (`since`; absent starts from the first record), grouped by partition, stream, scope and topic, plus the watermark to pass next (`truncated: true` when `limit` cut the page, `reset: true` when the watermark came from a replaced index, `warnings` when a catch-up failed), so an agent or hook can see what other agents saved without running a search. Read-only; local reach only. | none (`since`, `limit` optional) |
| `brain_settings` | Shared brain settings, the ones every machine agrees on, named `<block>.<field>` (`dream.candidate_threshold`, `decision_model.enabled`, `guardrails.derived_fact_synthesis`) or by a scalar key (`primary_agent`): `action: get \| list \| set \| unset`. `view.language` (`en`, `ru`, or a regional tag of one) names the language of the human view; it is a store record on every machine, switched or not. A `set` value is a scalar or a list of scalars and goes through the same validator the settings file goes through. Once the machine is switched to the brain store, a write is a `setting-set` or `setting-unset` record with agent authority; a value the operator set (`o2b brain settings set`, human authority) is refused with `human_value_in_force`, never written and outvoted, and while a shared settings shard cannot be read (or is gone since this machine read it) an agent's write is refused with `settings_unreadable`. Before the switch it edits the vault's settings file, where a value that differs from the shipped default counts as the operator's and is refused the same way. A setting that holds a safety or privacy boundary (every `integrity` gate, `notes.read_paths`, `vault.ignore_paths` and `vault.include_paths`, `write_binding.path_prefixes`, the `sessions` capture patterns, the promotion thresholds, the instruction-file ceiling and the trust and owner-scope toggles of `guardrails`, the decision-model opt-out `decision_model.enabled`, the permissions document `permissions.document`) is the operator's alone: an agent's write is refused with `operator_only_setting` in both modes, whether or not the operator set it. A setting of one machine (snapshots, storage, embeddings, decision-model endpoints) is refused with `device_setting` and the machine-config key to set instead. Works on a server with no vault. | `action` (`name` for get/set/unset, `value` for set) |
+| `brain_topic` | Topics (see [topics.md](topics.md)): `action: list \| show \| review` reads (topic heads, one topic with its items and rendered page, proposed merges and quiet topics); `create`, `rename`, `status`, `goal`, `assign`, `unassign`, `merge`, `split`, `link`, `archive` and `undo` record what the user asked, with human authority; `record` adds the agent's own decision, open question, log entry, milestone, resolution or completion, with agent authority. A personal topic is private by default. Below local reach a private topic is absent from every answer, and a write that names one is refused as for an unknown id. Never write topic pages with a note tool. | `action` |
| `brain_recall_feedback` | Record explicit up/down recall feedback for one search result; feeds the deterministic learned-weight fold. | `query`, `result_path`, `verdict` |
| `brain_recall_gate` | Read-only classifier for whether an automatic recall attempt should run; returns `retrieve` plus a stable reason. When the caller passes `scores` AND `match_quality` (the `idf_weighted_coverage` a search outcome reports - the two stand or fall together, and an incomplete pair is refused), also attaches an adequacy verdict (`sufficient` \| `weak` \| `insufficient`), a recommended action (`proceed` \| `re_recall` \| `abstain`), and an optional `escalate` flag. The LEVEL is decided by `match_quality` alone; the scores decide only the usable-result count. Thresholds via `recall_adequacy_sufficient` / `recall_adequacy_weak` / `recall_adequacy_min_results`. Since v1.82.0 a measured call also returns the shared graded surfacing key (`key`, `tier`) beside the binary decision. | `prompt` |
| `brain_context_pack` | Budgeted context slice; pass `lanes: true` to return directives, constraints, and consider lanes. Filtered items include `safety.reasons`. Each item carries a structural `epistemic` status (`observed` \| `derived` \| `hypothesis` \| `plan` \| `unknown`) plus `evidence_refs` derived from existing graph metadata; fields are absent when the status is `unknown`. Takes the same adequacy pair as `brain_recall_gate` under its own spelling, `recall_scores` AND `match_quality`: both or neither, an incomplete pair is refused, and the schema states it as `dependentRequired` keyed on this tool's own scores name. Since v1.91.0 an opt-in `entity_facts_context_pack` config key (default off, env `OPEN_SECOND_BRAIN_ENTITY_FACTS_CONTEXT_PACK`) adds a conditional `entity_facts` section: the canonical-scope entities anchored from the query, at most three, each listing only ids the pack already kept whose bodies anchor it; the key is absent when off, so the default pack stays byte-identical. Since v1.95.0 an opt-in `tail_trim_context_pack` config key (default off, env `OPEN_SECOND_BRAIN_TAIL_TRIM_CONTEXT_PACK`) adds a score-aware tail trim whenever the call carries a query: the top three delivered items are immune, an item whose query-term overlap nearly matches the top delivered score is kept, the rest drop whole with a `tail-trim` skip reason, and the freed budget is offered back to `over-budget` candidates in priority order; the response carries a conditional `tail_trim` block (`dropped`, `kept_by_query_terms`, `rescued`, `tokens_saved`) only when the trim ran, and with the key off the pack is byte-identical. | `max_tokens` |
@@ -886,16 +887,21 @@ come back from `resources/list`:
signals awaiting `dream`. Same data the `second_brain_status`
tool returns under its `brain` field, rendered as markdown.
-Four templated URIs come back from `resources/templates/list`:
+Five templated URIs come back from `resources/templates/list`:
- `osb://preference/{id}` — body of `pref-{id}.md`, with fallback to
`ret-{id}.md` when the active copy is gone. Accepts the bare slug
(`my-rule`) or the prefixed form (`pref-my-rule` / `ret-my-rule`).
-- `osb://topic/{slug}` — synthesised markdown of every signal, the
+- `osb://rule-topic/{slug}` — synthesised markdown of every signal, the
current preference (or retired), the most recent log entries, and a
deterministic **Strongest objection** steelman against the current
preference (a retired/quarantined rule, a recorded negative
- counter-signal, or an unconfirmed-trial caveat) for the topic.
+ counter-signal, or an unconfirmed-trial caveat) for the rule-topic
+ slug. The old name `osb://topic/{slug}` answers the same for one minor
+ version; a value that is a topic id goes to `osb://topic/{id}`.
+- `osb://topic/{id}` — one topic (see [topics.md](topics.md)) by its id,
+ as the page the human view renders for it. Below local reach a private
+ topic answers as an absent one.
- `osb://log/{date}` — body of `Brain/log/<date>.md` (date is
`YYYY-MM-DD`).
- `osb://backlinks/{id}` — inbound references to the given Brain
diff --git a/docs/topics.md b/docs/topics.md
new file mode 100644
index 00000000..4dc57d1c
--- /dev/null
+++ b/docs/topics.md
@@ -0,0 +1,70 @@
+# Topics
+
+A topic is one readable place for one area of work: an initiative, a project, a sub-project or a personal matter. Its page says where things stand (status and goal), what is planned (milestones), what was decided, what is still open, and the few events worth remembering. Agents keep it current; you read it, and you correct it when it is wrong.
+
+This guide covers what a topic is, the page it gets in the human view, how to ask an agent for one, what the dream pass does on its own, and how to take any of that back. It assumes the brain store and the human view are set up (see [brain-store.md](brain-store.md)).
+
+## What a topic is
+
+- **An id that never changes.** A topic is identified by an id (a ULID such as `01KA3Z...`). Its title and the folder of its page are display values: renaming a topic changes them and keeps the id, so every record and every link still points at it.
+- **A scope.** A topic belongs to one project (`project:<name>`) or to the personal scope. Agents see the topics of the project they work in, and other projects' topics only when they ask for them.
+- **A status.** One of Active, Waiting, Blocked, On hold, Done (with the day it was resolved) and Closed.
+- **Records, not a file.** Every change is a record in the brain store: a create, a rename, a status, a goal, a decision, an open question, a log entry, a milestone, an assignment of other material, a merge, a split, a link or an undo. Your records outweigh an agent's, and an agent's outweigh a decision model's, so a change you make is never overwritten by an automatic one. The record kinds are documented in the store's `FORMAT.md`.
+- **Private by default when personal.** A topic in the personal scope is written to the `private` partition unless you ask otherwise, and so is everything recorded on it later. A private topic never appears in the human view, and a remote MCP caller never sees it.
+
+## The page
+
+The view writer renders every shared topic to `topics/<date>-<slug>/topic.md` in the view folder: the day the topic was created and a short form of its title. The page has a fixed order:
+
+1. the title and a one-line description;
+2. the status line, for example `Status: Active`;
+3. the goal;
+4. milestones: open ones first, done ones ticked with their day; a milestone an automatic check thinks is finished shows `looks done, confirm` and stays open until you or an agent with evidence marks it done;
+5. decisions, newest first;
+6. open questions, including a goal an agent proposed after you set yours;
+7. the log, newest first: only corrections, decisions made outside the normal flow, blockers, reframings, rejected approaches (with the reason) and your own notes; routine progress stays in the store;
+8. related: the scope, linked topics, topics merged into this one, and the archive.
+
+Empty sections are left out. When a section grows past the page budget, its oldest done milestones, decisions and log entries move to `archive.md` in the same folder, with the resolved questions; open milestones and open questions always stay on the page.
+
+Edit the page like any note. The view writer reads your edit before its next render and records it with your authority: a new title renames the topic, a status line sets the status, a reworded goal or item replaces it, a ticked or unticked milestone marks it done or open again, a deleted line removes the item, and a line you add under a section becomes a new item there. Your files in a topic folder move with it when the topic is renamed. A note tool (`brain_create_note`, `brain_update_note`) refuses to write a topic page and names the topic tool instead.
+
+Research reports and source summaries get pages too, in `reports/` and `sources/`.
+
+## Asking an agent
+
+Ask in plain words: "start a topic for the move to the new flat with the goal of signing by March", "put this into the store topic", "rename it", "mark it done", "merge these two". The agent uses the `brain_topic` tool. What an agent writes carries its own authority, so it never outweighs what you wrote on the page or with a command: a goal it sets after yours shows as an open question on the page instead. When it acts on your explicit request it may mark the record as yours (`authority: "human"`); a remote MCP caller cannot. Commands you run (`o2b topic ...`) are stored as yours, except `o2b topic record`: it writes agent authority unless you add `--as-human`. An agent also records its own decisions, open questions and log entries on the topic it works on. After a merge two topics can hold an item of the same id; the agent then names the item's `owner`, which must be the topic or one merged into it and must hold that item, or nothing is written. Over a remote MCP transport every topic text the agent gets back, the scope included, is marked as agent-written text.
+
+The same actions are CLI verbs. The guide's commands run as written in the test suite; `<topic>` stands for the id `create` printed and `<record>` for the record id the last command printed:
+
+<!-- doc-test: topics -->
+```sh
+o2b topic create "Brain store" --scope project:o2b --goal "Move machine data out of the vault"
+o2b topic list
+o2b topic record <topic> decision --text "Keep one shard per device and month"
+o2b topic record <topic> log-entry --text "Sync conflicts on pinned.md" --class blocker
+o2b topic record <topic> milestone --text "Store core released" --as-human
+o2b topic status <topic> waiting
+o2b topic rename <topic> --title "Brain store and topics"
+o2b topic show <topic>
+o2b topic review
+o2b topic undo <record>
+o2b topic archive <topic>
+```
+
+`o2b topic --help` lists every verb: `assign` and `unassign` move a record in or out, `merge <topic> --into <topic>` and `split <topic> --into <topic> --items <ids>` combine or separate topics (a split takes only items the topic shows, those of a topic merged into it included; when two merged topics hold an item of the same id, `--owner <topic>` names whose moves), `link <topic> --to <topic>` relates two, and `goal <topic> <goal>` sets the goal. Add `--json` to any verb for the full answer. Agents read the same data through the resource `osb://topic/{id}`.
+
+## What dream does on its own
+
+The dream pass plans topics on the view writer only, and two passes on one machine never create the same topic. Two machines can, in one case: when both claim the view writer role at about the same time and sync takes longer than the one catch-up a fresh claim waits, each may plan once before the other's claim arrives; the brief then proposes merging the two topics. Otherwise:
+
+- **Routes** a new record of a project to the active topic of that project it clearly belongs to. Only shared text decides: a private item, or a title, description or goal you set privately, never pulls a shared record into a topic.
+- **Creates** a topic when enough related records of one project that no topic holds (5 by default, the shared setting `topics.new_min_records`) come from at least two sessions (`topics.new_min_sessions`, default 2). One busy session never makes a topic on its own. The topic gets a drafted title and goal, which you can change.
+- **Proposes** merges of two topics that look like one, and splits of a topic whose material falls into two groups. Nothing proposed is applied: the digest and the dream report list the proposal with the command that applies it.
+- **Asks** about a topic that had no news for 30 days (`topics.quiet_days`): keep it, put it on hold, mark it done or close it. Its status does not change until you answer.
+
+Every create and route is listed in the dream report with the command that undoes it; a pass run with `--config` names that file in the command.
+
+## Undo
+
+`o2b topic undo <record>` takes back one record: an automatic route, a created topic, a decision, a completion. The undo is a record, synced like every other, so every machine honours it, and the dream pass never routes that material to that topic again or recreates a topic you undid. The same holds when an agent undoes a route or takes a record out of a topic for you through `brain_topic`, from this machine or over a remote MCP transport; there your request is stored as the agent's record, since a remote caller cannot write as you, and it still blocks the route. Undoing an undo brings the record back; an undo of a private topic's record stays private, like the topic.
diff --git a/openclaw/index.js b/openclaw/index.js
index 7a05c97c..d82f3407 100644
--- a/openclaw/index.js
+++ b/openclaw/index.js
@@ -2417,7 +2417,7 @@ var init_format_wikilink = __esm(() => {
});
// src/core/store/constants.ts
-var STORE_FORMAT_VERSION = 1, STORE_FORMAT_FILE = "FORMAT.md", STORE_IDENTITY_FILE = "store.json", STORE_PARTITIONS, STORE_STREAMS, LEDGER_STREAM = "ledgers", STORE_BLOBS_DIR = "blobs", STORE_SHARD_EXT = "jsonl", ENVELOPE_FIELDS, BLOB_REF_KEY = "$blob", BLOB_REF_BYTES_KEY = "bytes", COMPACTED_KIND = "compacted", STORE_RECORD_KINDS, STORE_LINE_CAP_BYTES, STORE_BODY_MAX_DEPTH = 64, STORE_BLOB_MAX_BYTES, STORE_ROOT_CONFIG_KEY = "store_root", STORE_ROOT_ENV = "OPEN_SECOND_BRAIN_STORE_ROOT", STORE_DEFAULT_DIR = "store", STORE_STATE_DIR = "stores", STORE_LOCKS_DIR = "locks", STORE_CLOCK_DIR = "clock", SEEN_SHARDS_FILE = "seen-shards.json", AUTHORITY_FIELD = "authority", VAULT_ID_FIELD = "vault_id", AUTHORITIES, PREFERENCE_SET_KIND = "preference-set", PREFERENCE_REMOVE_KIND = "preference-remove", PREFERENCE_EVIDENCE_KIND = "preference-evidence", PINNED_SET_KIND = "pinned-set", PINNED_CLEAR_KIND = "pinned-clear", SETTING_SET_KIND = "setting-set", SETTING_UNSET_KIND = "setting-unset", DEVICE_RETIRE_KIND = "device-retire", STATE_DIGEST_KIND = "state-digest", FOLD_RECORD_KINDS, EVIDENCE_RESULTS, PREFERENCE_COUNTER_FIELDS, SETTING_VIEW_LANGUAGE = "view.language", SETTING_TOPIC_MIN_RECORDS = "topics.new_min_records", SETTING_TOPIC_MIN_SESSIONS = "topics.new_min_sessions", SETTING_KEYS, STATE_DIGEST_FOLDS, DAY_MS, STORE_DUAL_WRITE_CONFIG_KEY = "store_dual_write", STORE_DUAL_WRITE_ENV = "OPEN_SECOND_BRAIN_STORE_DUAL_WRITE", SIGNAL_KIND = "signal", LOG_EVENT_KIND = "log-event", LEDGER_ROW_KIND = "ledger-row", DUAL_WRITE_RECORD_KINDS, DUAL_WRITE_STATUS_FILE = "dual-write.json", STORE_TMP_DIR = "tmp", BLOB_TEMP_PREFIX = ".tmp-";
+var STORE_FORMAT_VERSION = 1, STORE_FORMAT_FILE = "FORMAT.md", STORE_IDENTITY_FILE = "store.json", STORE_PARTITIONS, STORE_STREAMS, LEDGER_STREAM = "ledgers", STORE_BLOBS_DIR = "blobs", STORE_SHARD_EXT = "jsonl", ENVELOPE_FIELDS, BLOB_REF_KEY = "$blob", BLOB_REF_BYTES_KEY = "bytes", COMPACTED_KIND = "compacted", STORE_RECORD_KINDS, STORE_LINE_CAP_BYTES, STORE_BODY_MAX_DEPTH = 64, STORE_BLOB_MAX_BYTES, STORE_ROOT_CONFIG_KEY = "store_root", STORE_ROOT_ENV = "OPEN_SECOND_BRAIN_STORE_ROOT", STORE_DEFAULT_DIR = "store", STORE_STATE_DIR = "stores", STORE_LOCKS_DIR = "locks", STORE_CLOCK_DIR = "clock", SEEN_SHARDS_FILE = "seen-shards.json", AUTHORITY_FIELD = "authority", VAULT_ID_FIELD = "vault_id", AUTHORITIES, PREFERENCE_SET_KIND = "preference-set", PREFERENCE_REMOVE_KIND = "preference-remove", PREFERENCE_EVIDENCE_KIND = "preference-evidence", PINNED_SET_KIND = "pinned-set", PINNED_CLEAR_KIND = "pinned-clear", SETTING_SET_KIND = "setting-set", SETTING_UNSET_KIND = "setting-unset", DEVICE_RETIRE_KIND = "device-retire", STATE_DIGEST_KIND = "state-digest", FOLD_RECORD_KINDS, EVIDENCE_RESULTS, PREFERENCE_COUNTER_FIELDS, SETTING_VIEW_LANGUAGE = "view.language", SETTING_TOPIC_MIN_RECORDS = "topics.new_min_records", SETTING_TOPIC_MIN_SESSIONS = "topics.new_min_sessions", SETTING_TOPIC_QUIET_DAYS = "topics.quiet_days", SETTING_KEYS, STATE_DIGEST_FOLDS, STATE_DIGEST_REQUIRED_FOLDS, DAY_MS, STORE_DUAL_WRITE_CONFIG_KEY = "store_dual_write", STORE_DUAL_WRITE_ENV = "OPEN_SECOND_BRAIN_STORE_DUAL_WRITE", SIGNAL_KIND = "signal", LOG_EVENT_KIND = "log-event", LEDGER_ROW_KIND = "ledger-row", DUAL_WRITE_RECORD_KINDS, DUAL_WRITE_STATUS_FILE = "dual-write.json", STORE_TMP_DIR = "tmp", BLOB_TEMP_PREFIX = ".tmp-";
var init_constants = __esm(() => {
STORE_PARTITIONS = Object.freeze(["shared", "private"]);
STORE_STREAMS = Object.freeze([
@@ -2464,9 +2464,20 @@ var init_constants = __esm(() => {
SETTING_KEYS = Object.freeze([
SETTING_VIEW_LANGUAGE,
SETTING_TOPIC_MIN_RECORDS,
- SETTING_TOPIC_MIN_SESSIONS
+ SETTING_TOPIC_MIN_SESSIONS,
+ SETTING_TOPIC_QUIET_DAYS
+ ]);
+ STATE_DIGEST_FOLDS = Object.freeze([
+ "preferences",
+ "pinned",
+ "settings",
+ "topics"
+ ]);
+ STATE_DIGEST_REQUIRED_FOLDS = Object.freeze([
+ "preferences",
+ "pinned",
+ "settings"
]);
- STATE_DIGEST_FOLDS = Object.freeze(["preferences", "pinned", "settings"]);
DAY_MS = 24 * 60 * 60 * 1000;
DUAL_WRITE_RECORD_KINDS = Object.freeze([
SIGNAL_KIND,
@@ -5171,10 +5182,93 @@ var init_fold_settings = __esm(() => {
fallback: null
},
[SETTING_TOPIC_MIN_RECORDS]: { valid: positiveInt, expected: "a positive integer", fallback: 5 },
- [SETTING_TOPIC_MIN_SESSIONS]: { valid: positiveInt, expected: "a positive integer", fallback: 2 }
+ [SETTING_TOPIC_MIN_SESSIONS]: { valid: positiveInt, expected: "a positive integer", fallback: 2 },
+ [SETTING_TOPIC_QUIET_DAYS]: { valid: positiveInt, expected: "a positive integer", fallback: 30 }
+ });
+});
+
+// src/core/topics/constants.ts
+var TOPIC_CREATE_KIND = "topic-create", TOPIC_RENAME_KIND = "topic-rename", TOPIC_STATUS_KIND = "topic-status", TOPIC_GOAL_KIND = "topic-goal", TOPIC_DECISION_KIND = "decision", TOPIC_QUESTION_KIND = "open-question", TOPIC_QUESTION_RESOLVED_KIND = "question-resolved", TOPIC_LOG_KIND = "log-entry", TOPIC_MILESTONE_KIND = "milestone", TOPIC_MILESTONE_DONE_KIND = "milestone-done", TOPIC_ASSIGN_KIND = "assign", TOPIC_UNASSIGN_KIND = "unassign", TOPIC_MERGE_KIND = "merge", TOPIC_SPLIT_KIND = "split", TOPIC_LINK_KIND = "link", TOPIC_UNDO_KIND = "undo", TOPIC_RECORD_KINDS, TOPIC_ITEM_KINDS, TOPIC_STATUSES, TOPIC_LOG_CLASSES, TOPIC_EARNED_LOG_CLASSES, TOPIC_PAGE_BUDGET;
+var init_constants2 = __esm(() => {
+ TOPIC_RECORD_KINDS = Object.freeze([
+ TOPIC_CREATE_KIND,
+ TOPIC_RENAME_KIND,
+ TOPIC_STATUS_KIND,
+ TOPIC_GOAL_KIND,
+ TOPIC_DECISION_KIND,
+ TOPIC_QUESTION_KIND,
+ TOPIC_QUESTION_RESOLVED_KIND,
+ TOPIC_LOG_KIND,
+ TOPIC_MILESTONE_KIND,
+ TOPIC_MILESTONE_DONE_KIND,
+ TOPIC_ASSIGN_KIND,
+ TOPIC_UNASSIGN_KIND,
+ TOPIC_MERGE_KIND,
+ TOPIC_SPLIT_KIND,
+ TOPIC_LINK_KIND,
+ TOPIC_UNDO_KIND
+ ]);
+ TOPIC_ITEM_KINDS = Object.freeze([
+ TOPIC_DECISION_KIND,
+ TOPIC_QUESTION_KIND,
+ TOPIC_LOG_KIND,
+ TOPIC_MILESTONE_KIND
+ ]);
+ TOPIC_STATUSES = Object.freeze([
+ "active",
+ "waiting",
+ "blocked",
+ "on-hold",
+ "done",
+ "closed"
+ ]);
+ TOPIC_LOG_CLASSES = Object.freeze([
+ "correction",
+ "decision",
+ "blocker",
+ "reframing",
+ "rejected",
+ "note",
+ "routine"
+ ]);
+ TOPIC_EARNED_LOG_CLASSES = new Set([
+ "correction",
+ "decision",
+ "blocker",
+ "reframing",
+ "rejected",
+ "note"
+ ]);
+ TOPIC_PAGE_BUDGET = Object.freeze({
+ doneMilestones: 10,
+ decisions: 25,
+ log: 15
});
});
+// src/core/topics/records.ts
+var init_records = __esm(() => {
+ init_fold();
+ init_ulid();
+ init_constants2();
+});
+
+// src/core/topics/undo-fold.ts
+var init_undo_fold = __esm(() => {
+ init_fold();
+ init_constants2();
+});
+
+// src/core/topics/fold.ts
+var init_fold2 = __esm(() => {
+ init_envelope();
+ init_fold();
+ init_hlc();
+ init_constants2();
+ init_records();
+ init_undo_fold();
+});
+
// src/core/store/shard-quarantine.ts
import { createHash as createHash2 } from "node:crypto";
import { closeSync as closeSync6, readFileSync as readFileSync8, readSync as readSync3, statSync as statSync6 } from "node:fs";
@@ -6174,6 +6268,7 @@ var init_state_digest = __esm(() => {
init_fold_pinned();
init_fold_preferences();
init_fold_settings();
+ init_fold2();
init_hlc();
init_reader();
init_seen_shards();
@@ -8639,6 +8734,7 @@ function appendStoreRecords(store, records, context) {
kind: record.kind,
agent: record.agent !== undefined && record.agent.trim() !== "" ? record.agent : defaultAgent(),
scope: record.scope ?? null,
+ topic: record.topic ?? null,
body: { ...record.body, [VAULT_ID_FIELD]: vaultId }
}));
} catch (err) {
diff --git a/openspec/changes/brain-store-and-topics/design.md b/openspec/changes/brain-store-and-topics/design.md
index d2634d9e..520fccfc 100644
--- a/openspec/changes/brain-store-and-topics/design.md
+++ b/openspec/changes/brain-store-and-topics/design.md
@@ -180,7 +180,7 @@ Only the view writer runs the topic-planning step of dream, under a device-local
A topic created by request on another machine gets a fresh id there. If the planner later sees a near-identical topic, it proposes a merge (`topic_same`) and never merges silently.
-Requested actions come through MCP tools (`brain_topic`, with actions create, assign, rename, status, merge, split, archive, undo) and the matching CLI verbs. Each is recorded as a human record.
+Requested actions come through MCP tools (`brain_topic`, with actions create, assign, rename, status, merge, split, archive, undo) and the matching CLI verbs. A CLI verb is recorded as a human record (the user runs it), except `o2b topic record`, which writes an agent record unless `--as-human`. `brain_topic` writes agent records unless the caller names `human` on the user's explicit request, which is refused below local reach (D18 item 5).
### D10. Decision-model uses
@@ -304,6 +304,51 @@ The inventory for task 2.10 (316 modules reach the legacy tree) raised questions
4. **Private evidence (3.18).** A private `apply-evidence` event never changes a shared preference's status, confidence, evidence timestamps or evidence sections, which dream writes to `shared` for every machine and remote caller; it counts toward a preference that is itself private. Every number derived from evidence that lands in `shared` follows the same rule: a merge copies each private evidence record of the drop as a private record (each copy keeps its source's partition), and its sums count a private use whenever the keep it lands on is private, and the shared and the private copies are written as two store writes, one per partition, since one write lands in one; the merge's log event and audit trail carry the sums of the shared evidence for a shared preference; dream compares a preference's counters against the ones the scan would count, so a shared preference with private uses settles instead of being rewritten every pass. A `preference-evidence` record in `private` no longer makes its preference private (before, the first private use moved the whole preference into `private` on this machine, where every later write followed it). The counters fold the partitions a machine holds, so a local caller on a machine that holds `private` sees its own private uses counted: that is the local view the event may affect, and it is never written back. A caller below local reach is shown the counters a machine that holds only `shared` folds: each preference of the store fold carries both, and the MCP server runs every tool call and resource read of a remote transport in an ambient scope (`store/caller-reach.ts`) that the preference facades and the rebuilt preference pages read, so the MCP tools, the `brain_context` digest, the operator snapshot and the review candidates all answer with the shared counters there. The device-local digest cache is always rendered with nothing withheld, since only local readers are served it; a remote caller gets its own render.
5. **Seen-shards ledger (3.21).** Every read-modify-write of the ledger runs under the device-local lock of the ledger file and re-reads it inside the lock, so a tracking read and a partition leave in two processes never undo each other. The lock guards the ledger alone and takes no other lock inside it, so a reader that holds a store lock may take it; a tracking update waits at most half a second and then skips, which only delays tracking to the next read, a skipped change stays queued in the process, counts as seen in its next listings (so a shard it names is still reported once gone) and is written with its next update, which a listing with nothing new also tries (a change for a partition the machine no longer holds is dropped then, and a partition leave drops its own process's queue for that partition), so a skip delays tracking, it does not drop it; and after a skip behind a lock one holder has kept the whole wait and longer (a crashed process's) the process leaves the ledger alone for ten seconds without waiting, so such a lock costs a hook one wait, not one per listing, while a lock other processes take and release in turn backs nothing off, whatever its directory's stat says (a released lock directory can linger with its old stat on Windows); the leave waits the full lock budget and refuses as before.
+### D16. Topics as built (phase 3, tasks 3.1 to 3.3)
+
+Details the specs leave open, settled for the first part of phase 3:
+
+1. **Identity and envelope.** The topic id is a ULID minted by the writer of the `topic-create`, carried in the envelope `topic` of every topic record (all in the `topics` stream); the first create in fold order fixes the scope (`personal` or `project:<project>`, also the envelope `scope`) and the creation time, and a second create of the same id only offers its title, description and goal to their registers. A non-topic record belongs to the topic its `assign` names, else to the topic its envelope names (`topicOfRecord`).
+2. **Items.** Decisions, open questions, log entries and milestones are list items keyed by an `item` id (the creating record's id when it names none). Each item, its owner topic, a milestone's completion and a question's resolution are registers; `removed: true` is an item's tombstone. A record that names an existing item with another kind is rejected. A log entry carries a `class`; only `routine` stays off the page, and `note` is a line the user wrote into the log section.
+3. **Undo.** An `undo` voids the record it names when its authority is at least that record's, and can itself be undone; an undo cycle (only a forged one) is cut where the walk in canonical record order meets it again, so its outcome is deterministic on every machine. An undo of an `assign` and an `unassign`, by the user or an agent (not by a decision model), record a blocked route, which the dream planning of task 3.4 reads so it never routes that record to that topic again.
+4. **Proposals.** A goal offer that comes after the winning goal and loses to it is a proposal, rendered as an open question attributed to its agent (spec "User rewrites the goal"). A `milestone-done` counts from the user, or from an agent with `evidence`; one from a decision model or from an agent without evidence is a "looks done, confirm" proposal. A model `question-resolved` is a "looks answered" proposal.
+5. **Merges and splits.** A merge resolves the merged topic to its target (`canonical`), applied in fold order of the winning merge records, skipping one that would close a cycle or names a topic that does not exist; the target's page carries both topics' items and names the merged one in its related section, and the merged topic's page is removed. A split moves the listed items (their owner register) and record assignments. Both are written only on the user's confirmation (D9), so they carry `human` authority in practice; the fold applies them by the usual precedence.
+6. **Partitions.** A write is one store operation in one partition (`topics/write.ts`): `private` when asked, when a `topic-create` in it has the personal scope and the caller did not ask for `shared` (spec brain-store "personal-scope topics SHALL default to private"), or when any topic it names lives in `private`, so a private topic's events never land in `shared`. The writer judges this from every partition the machine holds whatever the caller's reach, and refuses when a topics shard cannot be read in full. A topic is private when its first `topic-create` sits in `private`; an item is private when any of its records does. A caller below local reach folds `shared` alone (`topics/read.ts`).
+7. **Private topics stay off the view.** The view renders from `shared` records only (phase 2), so a private topic, an item created in `private`, any record written to `private` and a shared record that carries a `<private>` region never reach a page. An item created in `shared` keeps its shared text on the page after a later edit of it lands in `private`: that edit is not shown, so nothing private is published, but the item does not leave the view; taking it out would be a separate decision. This keeps the phase 2 promise that a phone that syncs only the view sees nothing private, and it means a personal topic is not in the view by default. The spec scenario "User asks for a topic" for a personal matter therefore holds for a personal topic the user asks to keep in `shared`; whether the view should show private topics on a writer that holds `private` (with an opt-in shared setting and private ingestion of their edits) is left to the owner.
+8. **Page layout.** `topics/<YYYY-MM-DD>-<slug>/topic.md`: the topic's creation day (UTC) and a slug of its current title (letters and digits of any script, joined by hyphens, at most 48 code points, `topic` when empty); a second topic that takes the same folder gets the last six characters of its id appended. The id comment line also names the topic (`topic=<id>`). Required sections are the title, the description (a generated placeholder when none), the status line and the related section (which names at least the scope); the goal, milestones, decisions, open questions and log are left out when empty. Decisions and the log are newest first; open milestones come first in the order recorded, then done ones newest first; goal proposals follow the open questions.
+9. **Page budget.** Per section: at most 10 done milestones, 25 decisions and 15 log entries stay on `topic.md`; the oldest over that, and every resolved question, move to `archive.md` in the same folder, linked from the related section. Open milestones and open questions never move, so a topic with more of those than fits is the one case where the page is longer than its budget.
+10. **Retiring pages.** A page in `topics/`, `reports/` or `sources/` that has a render record but is no longer rendered (a rename, a merge, an undone create, a removed report) is removed by the view writer at the start of its pass: an edit it carries and its conflict copies are ingested first, the page leaves its name by one atomic rename (so a racing edit is captured), and the user's companion files of a renamed topic's folder move to the new folder. An edit that renames the topic (its title line) moves the page on the next pass.
+11. **Edits of topic pages.** A changed line of a topic page or its archive maps to the topic record that says the same thing, with `human` authority (`view/topic-edits.ts`): the title, description, status, goal, an item's text (decorations stripped in every view language), a ticked milestone, a deleted item (its tombstone), a deleted goal proposal (an undo of the agent's goal record) and a line added in an item section (a new item). A line this mapping does not own takes the generic phase 2 correction of the view. A done milestone's line key names the record that completed it, so unticking it on the page writes a human `undo` of that record and the milestone is open again.
+12. **Reports and sources.** `reports/<entry>.md` and `sources/<entry>.md` render from the `lane-entry` records of the lanes `reports` and `sources` in `shared`, leaving out removed entries, entries whose fields reserve them as private, records with a `<private>` region and entry ids that are not plain file names. A body line's key is a hash of its text and occurrence, so a correction follows the line while the report keeps it.
+13. **Note-tool refusal.** The note tools' view-folder guard (phase 2) names the topic event tool (`brain_topic`, `o2b topic`) for a path in the view's `topics` folder, and the report and source tools for `reports` and `sources`; at the vault root the guard also owns those three folder names.
+14. **Digests.** The state digests (D6) hash a fourth fold, `topics` (`topicsFingerprint`: every topic, the assignments, blocked routes, voided records and rejected ids). The hash is optional in a digest, so a digest an earlier release of format version 1 published still parses, and two digests are compared on a fold only when both carry it; the format version does not change.
+
+### D17. Topic planning, the topic tool and the CLI as built (phase 3, tasks 3.4 to 3.6)
+
+1. **What planning reads.** The candidates are `signal` records and the log events a person reads (`note`, `decision-record`, `decision-resolved`), with their text, project and session (`topics/candidates.ts`). The project is the record's `project` field (a signal's frontmatter, a log event's body), normalised as every scope key is. The session is the record's `session`, else its `session_ref`, else the device, agent and UTC day that wrote it, so one agent's records of one day on one machine count as one session. A signal a `signal-removed` record forgot is not a candidate.
+2. **Deterministic fallbacks only.** Until the decision-model uses of phase 4, routing and grouping use subject words (letters and digits of any script, four or more code points, a short list of common English words dropped). A record routes to the active topic of its scope whose head (title, description, goal and item texts) shares the most words with it, at least two and a fifth of the record's; a route the user took back is never taken. A record with no project routes only to a personal topic and never makes a topic: personal topics are made on request. A group is grown greedily in record order (a record joins the first group it shares two words with); one of at least `topics.new_min_records` records from at least `topics.new_min_sessions` sessions becomes a topic titled by its three most frequent words (a tie goes to the word its first record says first) with its first record's text as the drafted goal. A record any `assign`, `unassign` or `split` ever named (`touched`, voided ones included) is routed but never grouped again, so a topic the user undid is not recreated from the same records.
+3. **Who and how.** Planning runs on the view writer only (the same view-writer records as the render), under a device-local lock, and reads every held partition inside the lock and refuses on a partial read; the second of two passes therefore sees the first one's topics and assignments and creates nothing twice. Its records are `agent` records of the dreaming agent. A create and its assigns land in `private` when any member is private; a route lands in `private` when the record or the topic is; a private record on a machine without the partition is skipped and counted. The dream pass runs it before the render (`brain/dream-tail.ts`), so the new topic's page is written in the same pass.
+4. **Proposals and prompts.** Two active topics of one scope whose heads (title, description, goal) share half their words (Jaccard) are proposed for a merge; a topic whose own records group into two groups that would each make a topic is proposed for a split; an active topic with no record for `topics.quiet_days` (a new shared setting, default 30) is offered for a status decision. Nothing is written for them: the dream report lists all three, and the markdown digest gains a `## Topics` section with the merges and quiet topics and the command for each, rendered at the caller's reach and absent when there is nothing to ask, so a digest without topics is byte-identical.
+5. **Undo.** `o2b topic undo <record>` (and `brain_topic` `undo`) writes a human `undo` naming a topic record the caller can see; the dream report prints that command for every create and route.
+6. **The topic tool.** `brain_topic` and `o2b topic` share one implementation (`topics/actions.ts`). `o2b topic` writes human records and its `record` verb agent ones; `brain_topic` writes agent records by default, and the caller can name `human` with `authority` except below local reach (D18 item 5). Below local reach the fold holds `shared` only, and every write first resolves the topics it names in that fold, so a private topic answers "no topic with id" exactly as an unknown id does. `show` renders the topic's page with private items for a local caller (`topicPages` with `includePrivate`), never for the view. `osb://topic/{id}` answers the same page and the absent-topic error below local reach.
+7. **Rule topics.** The preference-slug internals of the query and resource layers are named `ruleTopic` (`queryByRuleTopic`, `readRuleTopic` and their renderers); the resource is `osb://rule-topic/{slug}`, and `osb://topic/<value>` serves a topic when the value is a ULID and the rule topic otherwise, as the alias for one minor version. The `brain_query` tool's `topic` argument and the persisted `topic` field of signals keep their names (design D8).
+
+### D18. Topics: review fixes (phase 3)
+
+1. **Paths from records.** The view writer acts on a page path from a record only when it has exactly a shape the renderer writes (`topics/<YYYY-MM-DD>-<slug>/(topic|archive).md`, `reports/<entry>.md`, `sources/<entry>.md`: forward slashes, no `..`, no `\`, no empty segment) and resolves strictly inside the view folder (`view/page-path.ts`). No folder below the view folder, nor the page itself, may be a symbolic link, and the real path of the page's folder must lie inside the real view folder; this check also guards live page writes and both folders of a companion move. Any other path in a `view-render` record is ignored: a device that syncs `shared` can write any record. A Windows device name (`con`, `nul`, ...) is never a retiring page, and a retiring page that is a live page's file under another case (a case-insensitive file system) is not retired.
+2. **Folder slots.** Retiring happens in `view/retire.ts`. A live topic page whose last render record names another topic (the id line on disk decides only for a page rendered before render records named their topic, since a user's edit or a sync merge can change it) is retired first (its edit ingested, its folder's companion files moved to that topic's current folder), then the pages no longer rendered. `view-render` records name the topic of a topic page, so the companions of a page already gone still follow their topic.
+3. **Planning and the writer protocol.** Planning uses the render's gate: the writer releases on a pending request, a writer by its own fresh claim waits until the render settled the claim (`claimSeen`, read only, so the render's own wait is not spent), and the gate is asked again under the planning lock. The lock waits at least 30 seconds, and a pass whose topic records changed between its read and its writes (a lock taken over from a holder that looked stale) writes nothing (`raced`).
+4. **Items per topic.** An item id is its topic's own: the fold keys an item by the topic that first recorded it and the id, and a topic an item was split into finds it by its current owner. A `record` that names an item (an edit, a completion, a resolution) must name an item of that topic of the right kind; below local reach a `record` may not pick a new item id. Unknown `record` fields are refused.
+5. **Authority.** `brain_topic` writes `agent` records unless the caller names `human`, which is refused below local reach; `o2b topic` writes `human` records (the user runs it), and its `record` verb `agent` ones unless `--as-human`. The agent's goal therefore stays a proposal under the user's. A request that reaches `brain_topic` over a remote transport is recorded as an `agent` record: the transport cannot prove the user is behind it. Taking a route back blocks it whoever writes the undo or unassign, the user or an agent; only a decision model's leaves the route open, so an undo through `brain_topic` stops re-routing as `o2b topic undo` does.
+6. **Privacy and delivery.** A shared record that carries a `<private>` region makes its cluster's topic private and is withheld from remote reads of topics; the topic page `show` and `osb://topic/{id}` return is fenced below local reach; an unreadable-shard refusal names no shard below local reach; topic titles and descriptions are one line; review answers and the digest's topic section are empty over a partial read.
+7. **Resources and the view at the vault root.** `osb://topic/<value>` falls back to the rule-topic reader when no topic the caller sees has that id. With the view at the vault root, the note tools refuse only the view's own pages (and their conflict copies and temp files) in `topics/`, `reports/` and `sources/`, and the folders that hold them as containers; a user's own note in those folders stays writable. Report and source ids that differ only in case render one page, and Windows device names none.
+
+8. **PR review follow-ups.** A topic starts `active` without the create claiming the status register, so the first `topic-status` of any authority applies (a later human one still wins). The planner cuts a drafted title to the record limit and checks every create as the fold does before it writes anything of the group. Below local reach every topic text of `list` and `show` is fenced, not only the page. After a merge an item id two owners share is refused as ambiguous until `record` names the `owner`. An undo of an undo is checked by the record it names, so an undone create can be taken back. A line the user adds to a topic page gets an item id derived from its topic, section and text, so the same line in a page and its conflict copy is one item. A private item's words never route a shared record. The view writer never reads a page name that became a symbolic link (it checks each name it reads or captures), moves a companion file only onto no name (a link, then an unlink), honours the pass's time budget while retiring, and takes a retiring page's owner from its last render record before its id line. The dream pass forwards its config path to topic planning and the view render, counts topic writes as a change, and skips planning once its deadline has passed. The folder of a topic never repeats another topic's, whatever a title ends in.
+
+9. **Re-review follow-ups.** An undo is private when the record it names sits in `private` (an undone private create takes its topic out of the fold, so the topic alone cannot tell), so neither a private topic id nor a private record id reaches `shared`. The fold reports, per head field (title, description, goal), whether its winning record is private, and only shared head text and shared items route a shared record. A `record` with an `owner` names an existing item of that owner, and the owner must be the topic or one merged into it; otherwise it is refused as an absent item is. The planner cuts a drafted title in UTF-16 code units, the unit of the record check, after capitalizing and never inside a surrogate pair. Below local reach the scope of `list` and `show` is fenced like the other topic text. A name that is not a regular file (a folder) at a live topic page reports that page as refused and the rest of the pass renders: the disk is read for an owner only when no render record names one. A page is read through `O_NOFOLLOW` and a check of the opened descriptor where the platform has them. A companion move leaves a file in exactly one folder: when the old name holds another version by the time it would be unlinked (a sync tool delivered a newer one), or cannot be unlinked (Windows reports a file another program holds as `EPERM`, the code it also gives for "no hard links"), the new name is taken back.
+
+10. **Second re-review follow-ups.** Planning checks the view writer again from the catch-up read it plans from, so a move that arrives after the gate under the lock read the settings still stops the pass (`not-writer`). The dream pass asks its deadline again under the planning lock, after the read and before the first write, and a pass past it writes nothing (`deferred`). A write that fails after others landed reports `error` with the topics created and records routed before it, each with its undo command, and the dream summary counts them as a change. A `split` request takes only items the topic shows and writes the split of an item of a merged topic under that topic, the item's owner (the fold looks up a split's items by the topic it names); an id two merged owners share needs `owner`. An item id is refused for a new item of a topic only when a split moved that topic's item of the id to another topic: the fold still resolves the id to the moved item. A removed item stays its topic's, so its id can be recorded again. A `decision` record that leaves `serves` out keeps the links the item has, so a decision reworded on its page keeps the milestones it serves, and `"serves": []` clears them. When topics exchange folders, each retiring page moves only the companion names its folder held before any move of the pass. A companion move never unlinks a live name: the source and, when a move is taken back, the new name are each renamed to a temp name first and removed only when they are the version this move checked or placed, so a version a sync tool delivers under either name meanwhile is put back. A conflict-copy name that is not a regular file (a folder, a symbolic link) is refused where it is, and a capture that meets one puts it back under its name without replacing a name that exists. A conflict copy is taken out of its name before it is read, in a render and while retiring, so a copy written again after that read stays for the next pass. A private record routes by the private head text of a topic too, since its assign lands in `private`, and so does any record routed to a private topic; a shared route still uses shared text only. An edit, completion or resolution of an item that has a record in `private` is written to `private`, whatever the caller asks. `o2b topic split` takes `--owner` as `brain_topic` does; a split whose named topic moves no item of its own carries only its records. `brain_topic` refuses a `private` or `removed` that is not a boolean instead of dropping it. A dream pass plans on its own clock when it has one, and its undo commands name the config it ran with. A topic's activity time includes the records of topics merged into it and a split that hands it items or records. An item's privacy counts its completions and resolutions, whose evidence and answer are its text, so a later one written without the flag stays private. A route taken back from a topic is also blocked for the topic it merged into. Companion moves resolve each path once and use path-based calls: the runtime has no descriptor-relative rename or link, so a folder swapped for a symbolic link between the check and the call is not caught. That needs a process with write access to the view folder at that instant, which can already change the user's files directly.
+
## Risks / Trade-offs
- [A fold bug makes machines diverge silently] → state digests with doctor alerts (D6), property tests that shuffle delivery order and duplicate lines, and a rebuild command.
diff --git a/openspec/changes/brain-store-and-topics/tasks.md b/openspec/changes/brain-store-and-topics/tasks.md
index 3930151f..bc5e010f 100644
--- a/openspec/changes/brain-store-and-topics/tasks.md
+++ b/openspec/changes/brain-store-and-topics/tasks.md
@@ -74,14 +74,16 @@ Phases follow design.md D13. Each phase ends in its own release PR, and the vers
## 3. Phase 3: topics, plus reports and sources
-- [ ] 3.1 Implement topic records and folds for the canonical event list in design.md D8, with an immutable `topic_id`. Verify: property tests for order independence, and a rename that keeps every reference.
-- [ ] 3.2 Render `topics/<date>-<slug>/topic.md` through the phase 2 render protocol, with the fixed section order, the page budget and the companion archive. Also render `reports/` and `sources/`. Verify: snapshot tests, including budget overflow.
-- [ ] 3.3 Refuse note-tool writes into the view folder, with a pointer to the topic tools. Verify: a test on `brain_create_note` and `brain_update_note`.
-- [ ] 3.4 Add topic planning to dream, run on the view writer only: route unassigned records, create on N records from at least two sessions, propose merges and splits, prompt on quiet topics, write report entries, and support undo as a synced human record. Verify:
+- [x] 3.1 Implement topic records and folds for the canonical event list in design.md D8, with an immutable `topic_id`. Verify: property tests for order independence, and a rename that keeps every reference. Done: `src/core/topics/`, design D16 items 1 to 6.
+- [x] 3.2 Render `topics/<date>-<slug>/topic.md` through the phase 2 render protocol, with the fixed section order, the page budget and the companion archive. Also render `reports/` and `sources/`. Verify: snapshot tests, including budget overflow. Done: design D16 items 7 to 12.
+- [x] 3.3 Refuse note-tool writes into the view folder, with a pointer to the topic tools. Verify: a test on `brain_create_note` and `brain_update_note`. Done: design D16 item 13.
+- [x] 3.4 Add topic planning to dream, run on the view writer only: route unassigned records, create on N records from at least two sessions, propose merges and splits, prompt on quiet topics, write report entries, and support undo as a synced human record. Verify:
- dream tests for every scenario in `specs/topics/spec.md`;
- a concurrent dream on two machines, and two dream processes on the view writer, each yield exactly one topic per cluster.
-- [ ] 3.5 Add the `brain_topic` MCP tool and the `o2b topic` CLI verbs. Rename the preference-topic internals to `ruleTopic` and the resource to `osb://rule-topic/{slug}`, with an alias for one minor version, and add `osb://topic/{id}`. Verify: MCP contract tests, an alias test and a CHANGELOG note.
-- [ ] 3.6 Write the topics guide in docs: what a topic is, the page schema, how to ask an agent, and undo. Verify: a doc test runs the listed CLI verbs.
+
+ Done: `src/core/topics/plan.ts`, `planning.ts`, design D17.
+- [x] 3.5 Add the `brain_topic` MCP tool and the `o2b topic` CLI verbs. Rename the preference-topic internals to `ruleTopic` and the resource to `osb://rule-topic/{slug}`, with an alias for one minor version, and add `osb://topic/{id}`. Verify: MCP contract tests, an alias test and a CHANGELOG note.
+- [x] 3.6 Write the topics guide in docs: what a topic is, the page schema, how to ask an agent, and undo. Verify: a doc test runs the listed CLI verbs.
- [x] 3.8 Keep a lane page's raw text in its `lane-entry` record (an optional `raw` body field, FORMAT.md), so a store-only machine reads back staged bytes verbatim (OCR F291). Verify: a round-trip test of text without frontmatter and of quoted values. Done in change `store-hardening`.
- [x] 3.9 Make lane entry ids a bijection with legacy paths (every extension, `x.json` vs `x.json.md`, folders that are not lane names), or refuse the names that do not round-trip (OCR F295). Verify: a round-trip test over the lane path table. Done: refused names, design D15 item 1.
- [x] 3.10 Keep the procedural graph and hint counters as device-local state instead of re-appending whole `lane-entry` records on every usage tick (OCR F360). Verify: a usage tick appends no store record, and a migration test moves the counters into the device-local state. Done: design D15 item 2.
diff --git a/src/cli/brain/helpers.ts b/src/cli/brain/helpers.ts
index 03e5b692..d9699bc5 100644
--- a/src/cli/brain/helpers.ts
+++ b/src/cli/brain/helpers.ts
@@ -185,7 +185,7 @@ export function renderUpgradePlanJson(
}
export {
renderQueryPreferenceText,
- renderQueryTopicText,
+ renderQueryRuleTopicText,
renderQueryLogText,
} from "./query-render.ts";
export { diffSummary, readSingleLine, type DiffSummary } from "./rollback-prompt.ts";
diff --git a/src/cli/brain/query-render.ts b/src/cli/brain/query-render.ts
index 483d7abd..5e2e4f83 100644
--- a/src/cli/brain/query-render.ts
+++ b/src/cli/brain/query-render.ts
@@ -1,13 +1,13 @@
/**
* Text renderers for `o2b brain query` results.
*
- * Pure projection of the typed `queryByPreference` / `queryByTopic`
+ * Pure projection of the typed `queryByPreference` / `queryByRuleTopic`
* results plus log-entry arrays into stdout. JSON output uses the
* raw shapes; this module only handles the human-readable variant.
*/
import type { BrainLogEntry } from "../../core/brain/log.ts";
-import { queryByPreference, queryByTopic } from "../../core/brain/query.ts";
+import { queryByPreference, queryByRuleTopic } from "../../core/brain/query.ts";
import { info, ok } from "../output.ts";
export function renderQueryPreferenceText(out: ReturnType<typeof queryByPreference>): void {
@@ -32,7 +32,10 @@ export function renderQueryPreferenceText(out: ReturnType<typeof queryByPreferen
}
}
-export function renderQueryTopicText(out: ReturnType<typeof queryByTopic>, topic: string): void {
+export function renderQueryRuleTopicText(
+ out: ReturnType<typeof queryByRuleTopic>,
+ topic: string,
+): void {
ok(`topic: ${topic}`);
if (out.preference) {
ok(`preference: ${out.preference.id}`);
diff --git a/src/cli/brain/verbs/digest.ts b/src/cli/brain/verbs/digest.ts
index 3c21d0bc..149ff5b7 100644
--- a/src/cli/brain/verbs/digest.ts
+++ b/src/cli/brain/verbs/digest.ts
@@ -47,6 +47,7 @@ export async function cmdBrainDigest(argv: string[]): Promise<number> {
...(untilDate ? { until: untilDate } : {}),
format: flags["json"] ? "json" : "markdown",
linkOutputFormat: resolveLinkOutputFormat(config),
+ ...(config !== undefined ? { configPath: config } : {}),
};
let result;
diff --git a/src/cli/brain/verbs/dream.ts b/src/cli/brain/verbs/dream.ts
index e74224d0..dba9a400 100644
--- a/src/cli/brain/verbs/dream.ts
+++ b/src/cli/brain/verbs/dream.ts
@@ -545,6 +545,7 @@ export async function cmdBrainDream(argv: string[]): Promise<number> {
safeguard: guard(),
...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
...(gates !== null ? { gates } : {}),
+ ...(config !== undefined ? { configPath: config } : {}),
});
} catch (exc) {
if (exc instanceof SafeguardTimeoutError && asJson) {
diff --git a/src/cli/brain/verbs/query.ts b/src/cli/brain/verbs/query.ts
index c10e4bbc..726c8e57 100644
--- a/src/cli/brain/verbs/query.ts
+++ b/src/cli/brain/verbs/query.ts
@@ -3,7 +3,7 @@
* timestamp.
*
* Topic mode is the one surface in this system that ENFORCES per-memory
- * expiry (`filterExpired`, reached only through `queryByTopic`), so it is
+ * expiry (`filterExpired`, reached only through `queryByRuleTopic`), so it is
* also the only one where a point-in-time question is meaningful. Both
* knobs the filter has always taken are exposed here:
*
@@ -20,7 +20,7 @@
import {
queryByLogSince,
queryByPreference,
- queryByTopic,
+ queryByRuleTopic,
BrainNotFoundError,
type QueryByTopicOptions,
} from "../../../core/brain/query.ts";
@@ -32,7 +32,7 @@ import {
parseOptionalIsoDate,
renderQueryLogText,
renderQueryPreferenceText,
- renderQueryTopicText,
+ renderQueryRuleTopicText,
usageError,
} from "../helpers.ts";
import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
@@ -67,7 +67,7 @@ export async function cmdBrainQuery(argv: string[]): Promise<number> {
);
// `--at` moves the clock the expiration filter compares against and
- // `--show-expired` turns that filter off; `queryByTopic` is the only
+ // `--show-expired` turns that filter off; `queryByRuleTopic` is the only
// reader of either. Naming that here beats accepting a flag on
// `--preference` / `--since` that would quietly change nothing.
const atRaw = typeof flags["at"] === "string" ? flags["at"].trim() : null;
@@ -115,11 +115,11 @@ export async function cmdBrainQuery(argv: string[]): Promise<number> {
transportReach: CLI_TRANSPORT_REACH,
...(asOf !== null ? { now: asOf } : {}),
};
- const out = queryByTopic(vault, String(flags["topic"]), topicOptions);
+ const out = queryByRuleTopic(vault, String(flags["topic"]), topicOptions);
if (flags["json"]) {
process.stdout.write(JSON.stringify(out, null, 2) + "\n");
} else {
- renderQueryTopicText(out, String(flags["topic"]));
+ renderQueryRuleTopicText(out, String(flags["topic"]));
}
return 0;
}
diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.ts
index e1a7c084..99c1e3d8 100644
--- a/src/cli/command-manifest.ts
+++ b/src/cli/command-manifest.ts
@@ -1392,6 +1392,101 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
]),
],
),
+ command(
+ "topic",
+ "Topics: list, show and change them by recording topic events",
+ [],
+ [
+ command("list", "List topics, newest first", [
+ flag("scope", "string"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("show", "Show one topic: its head, items and page", [
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("review", "Proposed merges and quiet topics", [
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("create", "Create a topic", [
+ flag("scope", "string"),
+ flag("goal", "string"),
+ flag("description", "string"),
+ flag("private", "boolean"),
+ flag("shared", "boolean"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("rename", "Rename a topic or change its description", [
+ flag("title", "string"),
+ flag("description", "string"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("status", "Change a topic's status", [
+ flag("resolved", "string"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("goal", "Set or clear a topic's goal", [
+ flag("clear", "boolean"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("assign", "Assign a record to a topic", [
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("unassign", "Take a record out of a topic", [
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("merge", "Merge a topic into another", [
+ flag("into", "string"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("split", "Move items or records of a topic to another", [
+ flag("into", "string"),
+ flag("items", "string"),
+ flag("records", "string"),
+ flag("owner", "string"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("link", "Link two topics, or remove the link", [
+ flag("to", "string"),
+ flag("remove", "boolean"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command("archive", "Close a topic", [flag("config", "string"), flag("json", "boolean")]),
+ command("undo", "Undo one topic record", [
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ]),
+ command(
+ "record",
+ "Record a decision, question, log entry, milestone, resolution or completion",
+ [
+ flag("text", "string"),
+ flag("class", "string"),
+ flag("reason", "string"),
+ flag("item", "string"),
+ flag("question", "string"),
+ flag("answer", "string"),
+ flag("milestone", "string"),
+ flag("evidence", "string"),
+ flag("owner", "string"),
+ flag("as-human", "boolean"),
+ flag("config", "string"),
+ flag("json", "boolean"),
+ ],
+ ),
+ ],
+ ),
command(
"discipline",
"Daily logging discipline verbs",
diff --git a/src/cli/json-helpers.ts b/src/cli/json-helpers.ts
index 8710acd7..842de8e9 100644
--- a/src/cli/json-helpers.ts
+++ b/src/cli/json-helpers.ts
@@ -54,6 +54,7 @@ export const COMMANDS_WITH_INTERNAL_JSON: ReadonlySet<string> = new Set([
"state",
"store",
"view",
+ "topic",
"discipline",
"partner",
"decision-model",
diff --git a/src/cli/main.ts b/src/cli/main.ts
index 2b2d041f..e2d08a30 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -59,6 +59,7 @@ import { handleDecisionModelSubcommand } from "./decision-model.ts";
import { handleStateSubcommand } from "./state.ts";
import { handleStoreSubcommand } from "./store.ts";
import { handleViewSubcommand } from "./view.ts";
+import { handleTopicSubcommand } from "./topic.ts";
import { installMcpSignalDrain, type McpSignalDrainHandle } from "./mcp-drain.ts";
import { installMcpFaultGuard } from "./mcp-fault-guard.ts";
import { handleVaultSubcommand } from "./vault.ts";
@@ -1481,6 +1482,7 @@ export async function main(argv: ReadonlyArray<string>): Promise<number> {
command !== "aider" &&
command !== "brain" &&
command !== "vault" &&
+ command !== "topic" &&
// `secrets` has its own two-line help (the env fallback's name read
// is spelled there), so the generic URL stub would only bury it.
command !== "secrets"
@@ -1561,6 +1563,8 @@ async function dispatchCommand(command: string, rest: string[]): Promise<number>
return await handleStoreSubcommand(rest);
case "view":
return await handleViewSubcommand(rest);
+ case "topic":
+ return await handleTopicSubcommand(rest);
case "vault":
return await handleVaultSubcommand(rest);
case "partner":
diff --git a/src/cli/topic.ts b/src/cli/topic.ts
new file mode 100644
index 00000000..8ad6bbad
--- /dev/null
+++ b/src/cli/topic.ts
@@ -0,0 +1,274 @@
+/**
+ * `o2b topic` - topics (design D8, D9; task 3.5), the CLI twin of the
+ * `brain_topic` MCP tool. Every verb runs the same action
+ * (`core/topics/actions.ts`); a change is a topic record, rendered into
+ * the human view by the view writer.
+ *
+ * Verbs: `list [--scope <scope>]`, `show <topic>`, `review`,
+ * `create <title> [--scope <scope>] [--goal <goal>] [--description <text>]
+ * [--private | --shared]`, `rename <topic> [--title <title>]
+ * [--description <text>]`, `status <topic> <status> [--resolved <day>]`,
+ * `goal <topic> <goal> | --clear`, `assign <topic> <record>`,
+ * `unassign <topic> <record>`, `merge <topic> --into <topic>`,
+ * `split <topic> --into <topic> [--items <ids>] [--records <ids>]
+ * [--owner <topic>]`,
+ * `link <topic> --to <topic> [--remove]`, `archive <topic>`,
+ * `undo <record>` and `record <topic> <kind> [--text ...]`. A command is
+ * the user asking, so it carries `human` authority; `record` writes with
+ * `agent` authority unless `--as-human`.
+ */
+
+import { ConfigReadError } from "../core/config.ts";
+import { StoreWriteError } from "../core/store/store-write.ts";
+import { runTopicAction, TopicActionError, type TopicActionInput } from "../core/topics/actions.ts";
+import { TopicWriteError } from "../core/topics/write.ts";
+import { CliError, parseFlags } from "./argparse.ts";
+import { sortedReplacer } from "./helpers.ts";
+
+const USAGE = [
+ "usage: o2b topic list [--scope <scope>]",
+ " o2b topic show <topic>",
+ " o2b topic review",
+ " o2b topic create <title> [--scope project:<p>|personal] [--goal <goal>] [--description <text>] [--private|--shared]",
+ " o2b topic rename <topic> [--title <title>] [--description <text>]",
+ " o2b topic status <topic> <active|waiting|blocked|on-hold|done|closed> [--resolved <YYYY-MM-DD>]",
+ " o2b topic goal <topic> (<goal> | --clear)",
+ " o2b topic assign|unassign <topic> <record>",
+ " o2b topic merge <topic> --into <topic>",
+ " o2b topic split <topic> --into <topic> [--items <id,...>] [--records <id,...>] [--owner <topic>]",
+ " o2b topic link <topic> --to <topic> [--remove]",
+ " o2b topic archive <topic>",
+ " o2b topic undo <record>",
+ " o2b topic record <topic> <decision|open-question|log-entry|milestone|question-resolved|milestone-done> [--text <text>] [--class <class>] [--reason <text>] [--item <id>] [--question <id>] [--answer <text>] [--milestone <id>] [--evidence <text>] [--owner <topic>] [--as-human]",
+ " every verb: [--config <file>] [--json]",
+].join("\n");
+
+const EXIT = Object.freeze({ ok: 0, refused: 1, usage: 2 } as const);
+
+const FLAGS = {
+ config: { type: "string" },
+ json: { type: "boolean" },
+ scope: { type: "string" },
+ goal: { type: "string" },
+ description: { type: "string" },
+ title: { type: "string" },
+ resolved: { type: "string" },
+ into: { type: "string" },
+ to: { type: "string" },
+ items: { type: "string" },
+ records: { type: "string" },
+ remove: { type: "boolean" },
+ clear: { type: "boolean" },
+ private: { type: "boolean" },
+ shared: { type: "boolean" },
+ "as-human": { type: "boolean" },
+ text: { type: "string" },
+ class: { type: "string" },
+ reason: { type: "string" },
+ item: { type: "string" },
+ question: { type: "string" },
+ answer: { type: "string" },
+ milestone: { type: "string" },
+ evidence: { type: "string" },
+ owner: { type: "string" },
+} as const;
+
+/** The CLI flags of every verb, for the command manifest. */
+export const TOPIC_CLI_FLAGS = FLAGS;
+
+type Flags = Record<string, string | boolean | string[] | undefined>;
+
+const str = (flags: Flags, name: string): string | undefined =>
+ typeof flags[name] === "string" ? (flags[name] as string) : undefined;
+
+const list = (value: string | undefined): string[] | undefined =>
+ value === undefined
+ ? undefined
+ : value
+ .split(",")
+ .map((v) => v.trim())
+ .filter(Boolean);
+
+function arg(positional: ReadonlyArray<string>, index: number, name: string): string {
+ const value = positional[index];
+ if (value === undefined) throw new CliError(`missing <${name}>`);
+ return value;
+}
+
+/** The record fields a `record` verb names. */
+function recordFields(flags: Flags): Record<string, unknown> {
+ const out: Record<string, unknown> = {};
+ for (const name of [
+ "text",
+ "class",
+ "reason",
+ "item",
+ "question",
+ "answer",
+ "milestone",
+ "evidence",
+ ]) {
+ const value = str(flags, name);
+ if (value !== undefined) out[name] = value;
+ }
+ return out;
+}
+
+function inputOf(verb: string, positional: ReadonlyArray<string>, flags: Flags): TopicActionInput {
+ const description = str(flags, "description");
+ const optional = description !== undefined ? { description } : {};
+ switch (verb) {
+ case "list":
+ return {
+ action: verb,
+ ...(str(flags, "scope") !== undefined ? { listScope: str(flags, "scope")! } : {}),
+ };
+ case "review":
+ return { action: verb };
+ case "show":
+ case "archive":
+ return { action: verb, topic: arg(positional, 0, "topic") };
+ case "create": {
+ if (flags["private"] === true && flags["shared"] === true) {
+ throw new CliError("--private and --shared exclude each other");
+ }
+ return {
+ action: verb,
+ title: arg(positional, 0, "title"),
+ ...optional,
+ ...(str(flags, "scope") !== undefined ? { scope: str(flags, "scope")! } : {}),
+ ...(str(flags, "goal") !== undefined ? { goal: str(flags, "goal")! } : {}),
+ ...(flags["private"] === true ? { private: true } : {}),
+ ...(flags["shared"] === true ? { private: false } : {}),
+ };
+ }
+ case "rename":
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ ...optional,
+ ...(str(flags, "title") !== undefined ? { title: str(flags, "title")! } : {}),
+ };
+ case "status":
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ status: arg(positional, 1, "status"),
+ ...(str(flags, "resolved") !== undefined ? { resolved: str(flags, "resolved")! } : {}),
+ };
+ case "goal":
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ goal: flags["clear"] === true ? null : arg(positional, 1, "goal"),
+ };
+ case "assign":
+ case "unassign":
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ record: arg(positional, 1, "record"),
+ };
+ case "merge":
+ return { action: verb, topic: arg(positional, 0, "topic"), into: str(flags, "into") ?? "" };
+ case "split": {
+ const items = list(str(flags, "items"));
+ const records = list(str(flags, "records"));
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ into: str(flags, "into") ?? "",
+ ...(items !== undefined ? { items } : {}),
+ ...(records !== undefined ? { records } : {}),
+ ...(str(flags, "owner") !== undefined ? { owner: str(flags, "owner")! } : {}),
+ };
+ }
+ case "link":
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ to: str(flags, "to") ?? "",
+ ...(flags["remove"] === true ? { removed: true } : {}),
+ };
+ case "undo":
+ return { action: verb, record: arg(positional, 0, "record") };
+ case "record":
+ return {
+ action: verb,
+ topic: arg(positional, 0, "topic"),
+ kind: arg(positional, 1, "kind"),
+ fields: recordFields(flags),
+ ...(str(flags, "owner") !== undefined ? { owner: str(flags, "owner")! } : {}),
+ ...(flags["as-human"] === true ? { authority: "human" } : {}),
+ };
+ default:
+ throw new CliError(`unknown topic verb: ${verb}`);
+ }
+}
+
+function render(answer: Record<string, unknown>): string {
+ switch (answer["action"]) {
+ case "list": {
+ const topics = answer["topics"] as Array<Record<string, unknown>>;
+ if (topics.length === 0) return "no topics\n";
+ return topics
+ .map((t) => `${t["id"]} ${t["status"]} ${t["scope"]} ${t["title"]}\n`)
+ .join("");
+ }
+ case "show":
+ return String(answer["page"]);
+ case "review": {
+ if (answer["incomplete"] === true) {
+ return "review incomplete: the topics stream could not be read in full; run `o2b brain doctor`\n";
+ }
+ const merges = answer["merges"] as Array<{ topics: string[] }>;
+ const quiet = answer["quiet"] as Array<{ topic: string; days: number }>;
+ if (merges.length + quiet.length === 0) return "nothing to review\n";
+ return [
+ ...merges.map((m) => `merge? ${m.topics[0]} ${m.topics[1]}\n`),
+ ...quiet.map((q) => `quiet ${q.days} days: ${q.topic}\n`),
+ ].join("");
+ }
+ default:
+ return `${answer["action"]}: topic ${answer["topic"]}, record ${(answer["records"] as string[]).join(", ")}\n`;
+ }
+}
+
+export async function handleTopicSubcommand(argv: ReadonlyArray<string>): Promise<number> {
+ const verb = argv[0];
+ if (verb === undefined || verb === "-h" || verb === "--help") {
+ process.stdout.write(`${USAGE}\n`);
+ return verb === undefined ? EXIT.usage : EXIT.ok;
+ }
+ const rest = argv.slice(1);
+ let json = false;
+ try {
+ const { flags, positional } = parseFlags(rest, FLAGS);
+ json = flags["json"] === true;
+ const input = inputOf(verb, positional, flags);
+ const configPath = str(flags, "config");
+ // A command is the user asking: requested actions carry human authority.
+ const answer = runTopicAction(input, {
+ humanRequest: true,
+ ...(configPath !== undefined ? { configPath } : {}),
+ });
+ process.stdout.write(json ? `${JSON.stringify(answer, sortedReplacer, 2)}\n` : render(answer));
+ // A review over a partial read is not a clean review.
+ return answer["incomplete"] === true ? EXIT.refused : EXIT.ok;
+ } catch (err) {
+ if (err instanceof CliError) {
+ process.stderr.write(`error: ${err.message}\n${USAGE}\n`);
+ return EXIT.usage;
+ }
+ const known =
+ err instanceof TopicActionError ||
+ err instanceof TopicWriteError ||
+ err instanceof StoreWriteError ||
+ err instanceof ConfigReadError;
+ if (!known) throw err;
+ if (json)
+ process.stdout.write(`${JSON.stringify({ ok: false, error: err.message }, null, 2)}\n`);
+ process.stderr.write(`error: ${err.message}\n`);
+ return EXIT.refused;
+ }
+}
diff --git a/src/core/brain/digest-types.ts b/src/core/brain/digest-types.ts
index 9ec583f3..21c1c0c4 100644
--- a/src/core/brain/digest-types.ts
+++ b/src/core/brain/digest-types.ts
@@ -67,6 +67,8 @@ export interface RenderDigestOptions {
* partition are withheld from every section, counts included.
*/
readonly withholdsPrivate?: boolean;
+ /** The machine config whose store the topic section reads (default: the process's). */
+ readonly configPath?: string;
}
export interface RenderDigestResult {
diff --git a/src/core/brain/digest.ts b/src/core/brain/digest.ts
index 1f7fc4bd..85f122a0 100644
--- a/src/core/brain/digest.ts
+++ b/src/core/brain/digest.ts
@@ -35,6 +35,8 @@
* retired entries, the log, or the snapshots.
*/
+import { withPrivateWithheld } from "../store/caller-reach.ts";
+import { readTopicReview, renderTopicReview } from "../topics/review.ts";
import { readerRefView } from "./artifact-ref-view.ts";
import { closedCollectError } from "./maintenance/collect.ts";
import { renderPrefLink, type LinkOutputFormat } from "./wikilink.ts";
@@ -153,8 +155,14 @@ export function renderDigest(vault: string, opts: RenderDigestOptions = {}): Ren
? renderEmptyMarkdown(until)
: renderMarkdown(data, since, until, linkOutputFormat);
const trustSection = renderTrustSection(opts.doctorResult, opts.dreamSummary);
- const content = trustSection ? `${baseMd}\n${trustSection}` : baseMd;
- return Object.freeze({ content, empty });
+ // What the user is asked about topics (merges, quiet topics), read at
+ // the caller's reach; absent when there is nothing to ask.
+ const topicSection = withPrivateWithheld(opts.withholdsPrivate === true, () =>
+ renderTopicReview(readTopicReview(now.getTime(), opts.configPath)),
+ );
+ const sections = [baseMd, trustSection, topicSection].filter((part) => part !== "");
+ const content = sections.join("\n");
+ return Object.freeze({ content, empty: empty && topicSection === "" });
}
/**
diff --git a/src/core/brain/dream-outcome.ts b/src/core/brain/dream-outcome.ts
new file mode 100644
index 00000000..acf40514
--- /dev/null
+++ b/src/core/brain/dream-outcome.ts
@@ -0,0 +1,125 @@
+/**
+ * The decisions a dream pass takes about its own outcome once the plan is
+ * known: whether anything changes at all (the `changed` gate), the
+ * non-fatal warnings it reports, and the retire-sibling projection a
+ * changed run's summary carries. Pure over the plan; split from
+ * `dream.ts`, which sequences them.
+ */
+
+import { resolveNearDuplicateRetireSiblingsEnabled } from "../config.ts";
+import { shouldGateRetireFromConfirmed } from "./dream-apply.ts";
+import type { PlanState, ScanResult } from "./dream-plan.ts";
+import type { RefreshResult } from "./dream-refresh.ts";
+import type { DreamGatedRetireEntry, DreamRunSummary, DreamWarning } from "./dream-types.ts";
+import { READ_ALL_REFS } from "./near-duplicate.ts";
+import { planRetireSiblings, retireSiblingPool } from "./retire-siblings.ts";
+import type { RollupLadderPlan } from "./rollup-ladder.ts";
+
+/**
+ * Attach the retire-sibling projection (near-duplicate defense) to a
+ * changed run's summary. Computed from the completed retire plan, then
+ * reconciled against the retires the confirmed-evidence gate holds back:
+ * the ones the apply step gated, or on a dry run the ones it would gate,
+ * so the dry run and the real run agree. A retiring preference is never
+ * refreshed first, so its scanned frontmatter is what the apply step
+ * reads. The scan is the pass's own reach (a preview scan is already
+ * admitted), hence {@link READ_ALL_REFS}. Off (`enabled`, else the
+ * default config's key), or with nothing to report, the summary is
+ * returned untouched.
+ */
+export function withRetireSiblings(
+ summary: DreamRunSummary,
+ scan: ScanResult,
+ plan: PlanState,
+ opts: {
+ readonly enabled: boolean | undefined;
+ readonly gatedRetires: ReadonlyArray<DreamGatedRetireEntry>;
+ readonly previewGateThreshold: number | undefined;
+ },
+): DreamRunSummary {
+ if (plan.retires.length === 0 || !(opts.enabled ?? resolveNearDuplicateRetireSiblingsEnabled())) {
+ return summary;
+ }
+ const gated = new Set(opts.gatedRetires.map((g) => g.pref_id));
+ if (opts.previewGateThreshold !== undefined) {
+ const byId = new Map(scan.preferences.map((p) => [p.pref.id, p.pref] as const));
+ for (const r of plan.retires) {
+ const existing = byId.get(`pref-${r.slug}`);
+ if (
+ existing !== undefined &&
+ shouldGateRetireFromConfirmed(existing, r.reason, opts.previewGateThreshold)
+ ) {
+ gated.add(existing.id);
+ }
+ }
+ }
+ const siblings = planRetireSiblings(
+ retireSiblingPool(scan.preferences.map((p) => p.pref)),
+ plan.retires.map((r) => ({ id: `pref-${r.slug}`, principle: r.principle, reason: r.reason })),
+ { readable: READ_ALL_REFS, gated },
+ );
+ if (siblings.length === 0) return summary;
+ return Object.freeze({ ...summary, retire_siblings: Object.freeze([...siblings]) });
+}
+
+/**
+ * Non-fatal warnings raised during the run. The non-primary-dream-run
+ * check is the first one: when the caller declares an agent name and it
+ * differs from the vault's declared primary, surface a structured
+ * warning. We do NOT abort — the declaration is observability, not
+ * access control.
+ */
+export function collectWarnings(
+ isNonPrimary: boolean,
+ callerAgent: string,
+ primaryAgent: string | null,
+): DreamWarning[] {
+ if (!isNonPrimary) return [];
+ return [
+ {
+ code: "non-primary-dream-run",
+ message:
+ `dream run from agent '${callerAgent}', but primary is ` +
+ `'${primaryAgent}'. Convention violation, run proceeds.`,
+ },
+ ];
+}
+
+/**
+ * Decide if anything is going to change. We treat any of the following
+ * as a state change:
+ * - a new unconfirmed pref
+ * - a refreshed pref (counters/confidence/status changed)
+ * - a retire
+ * - a same-sign signal noted on an active pref (move + log)
+ * - an inbox signal archived because it left the contradiction window
+ * - a corrupted frontmatter (we want the skip event recorded)
+ * - any pinned-rebut-attempt warning
+ * - a fired rollup-ladder rung (S3)
+ * - a cross-topic rule promotion (t_642bc2b8)
+ */
+export function hasStateChange(
+ plan: PlanState,
+ refresh: RefreshResult,
+ corruptedCount: number,
+ rollupPlan: RollupLadderPlan,
+): boolean {
+ return (
+ plan.newUnconfirmed.length > 0 ||
+ refresh.confirmed.size > 0 ||
+ refresh.updated.size > 0 ||
+ plan.retires.length > 0 ||
+ plan.notedRedundant.length > 0 ||
+ plan.signalsToMove.size > 0 ||
+ plan.signalsToArchive.size > 0 ||
+ plan.retainPinned.length > 0 ||
+ plan.signalsSuppressed.length > 0 ||
+ // v0.10.16: quarantine is a recorded decision (deferred-but-noted),
+ // so a run that produces only quarantine entries is still a
+ // meaningful run from the operator's perspective.
+ plan.quarantined.length > 0 ||
+ plan.crossTopicRules.length > 0 ||
+ rollupPlan.fired ||
+ corruptedCount > 0
+ );
+}
diff --git a/src/core/brain/dream-rollup.ts b/src/core/brain/dream-rollup.ts
new file mode 100644
index 00000000..399c5933
--- /dev/null
+++ b/src/core/brain/dream-rollup.ts
@@ -0,0 +1,68 @@
+/**
+ * The rollup-ladder plan of a dream pass (S3): the count-only ladder over
+ * the run's facts, and the link-candidate manifest it may ask for, built
+ * at most once per run. Split from `dream.ts`, which calls it.
+ */
+
+import { buildLinkCandidateManifest, type LinkCandidateManifest } from "./notes/link-candidates.ts";
+import { gatedOwnerScopeView } from "./owner-scope-view.ts";
+import {
+ planRollupLadder,
+ readRollupLedger,
+ resolveRollupThresholds,
+ type RollupLadderPlan,
+} from "./rollup-ladder.ts";
+import type { BrainConfig } from "./types.ts";
+
+export function buildRollupPlan(
+ vault: string | null,
+ cfg: BrainConfig,
+ factCount: number,
+ runId: string,
+ linkCandidates: () => LinkCandidateManifest,
+): RollupLadderPlan {
+ return planRollupLadder({
+ factCount,
+ ledger: readRollupLedger(vault),
+ thresholds: resolveRollupThresholds(cfg),
+ runId,
+ linkCandidates,
+ });
+}
+
+/**
+ * The link-candidate manifest for this run, walked at most once and only
+ * if something asks for it. Both callers of {@link buildRollupPlan} share
+ * one of these, so a runId collision re-plans off the manifest already
+ * built rather than walking the vault a second time.
+ *
+ * No query: the ladder is count-only by design and never learns which
+ * items it is folding, so ranking the candidates would be inventing a
+ * relevance nothing measured. The manifest says `alphabetical` and names
+ * the total, which is the honest form of that.
+ */
+export function memoizedLinkCandidates(
+ vault: string | null,
+ agentName: string | undefined,
+ readable: ((rel: string) => boolean) | undefined,
+): () => LinkCandidateManifest {
+ let manifest: LinkCandidateManifest | null = null;
+ return () => {
+ if (manifest !== null) return manifest;
+ // No vault: no user notes for a rollup to link to (design D14).
+ if (vault === null) return (manifest = NO_LINK_CANDIDATES);
+ const ownerView = gatedOwnerScopeView(vault, agentName);
+ manifest = buildLinkCandidateManifest(vault, {
+ visible: (rel) => ownerView.visible(rel) && (readable?.(rel) ?? true),
+ });
+ return manifest;
+ };
+}
+
+/** The link manifest of a machine with no vault: no notes, so no candidates. */
+const NO_LINK_CANDIDATES: LinkCandidateManifest = Object.freeze({
+ candidates: Object.freeze([]),
+ total: 0,
+ truncated: false,
+ selection: "alphabetical",
+});
diff --git a/src/core/brain/dream-tail.ts b/src/core/brain/dream-tail.ts
new file mode 100644
index 00000000..ab148efa
--- /dev/null
+++ b/src/core/brain/dream-tail.ts
@@ -0,0 +1,84 @@
+/**
+ * The steps at the tail of a dream pass that belong to the brain store:
+ * topic planning (design D9) and then the render of the human view
+ * (design D7). Both run only where the store is in use, never on a dry
+ * run, and fail open, so a summary on a machine without a store is
+ * byte-identical to before.
+ */
+
+import { describeTopicPlanning, runAutoTopicPlanning } from "../topics/planning.ts";
+import { describeAutoView, runAutoViewPass } from "../view/auto-render.ts";
+import { VIEW_DREAM_BUDGET_MS } from "../view/constants.ts";
+import type { DreamOptions, DreamRunSummary } from "./dream-types.ts";
+
+/**
+ * Plan topics before the render (design D9): on the view writer, route
+ * unassigned records and create topics from recurring clusters; any other
+ * machine plans nothing and its summary names the writer. Fail-open, and
+ * absent when the brain store is not in use here or on a dry run.
+ */
+export function withTopicPass(summary: DreamRunSummary, opts: DreamOptions): DreamRunSummary {
+ if (opts.dryRun === true) return summary;
+ // The run's deadline holds here too, where the store is in use: a pass
+ // whose deadline passed plans nothing and leaves topics to the next one.
+ const safeguard = opts.safeguard;
+ const runAt = opts.now;
+ const report = runAutoTopicPlanning({
+ ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
+ // The run's own clock, when it has one: quiet topics and record times
+ // follow the date the run is for.
+ ...(runAt !== undefined ? { now: () => runAt.getTime() } : {}),
+ ...(safeguard !== undefined
+ ? {
+ mayPlan: () => {
+ try {
+ safeguard.checkpoint();
+ return true;
+ } catch {
+ return false;
+ }
+ },
+ }
+ : {}),
+ });
+ if (report === null) return summary;
+ // Topics created or records routed are writes of this pass.
+ // A pass that failed midway lists what it wrote before the failure.
+ const wrote =
+ (report.status === "planned" || report.status === "error") &&
+ report.created.length + report.routed.length > 0;
+ return {
+ ...summary,
+ ...(wrote ? { changed: true } : {}),
+ topics: { summary: describeTopicPlanning(report), report },
+ };
+}
+
+/**
+ * Render the human view at the end of a pass that wrote (design D7): the
+ * view writer keeps its pages current, any other machine writes none and
+ * its summary names the writer. Bounded by a time budget: pages it does
+ * not reach are deferred to the next pass and counted. Fail-open, and
+ * absent when the brain store is not in use here, so such a summary is
+ * byte-identical to before.
+ */
+export function withViewPass(summary: DreamRunSummary, opts: DreamOptions): DreamRunSummary {
+ if (opts.dryRun === true) return summary;
+ const result = runAutoViewPass({
+ trigger: "dream",
+ budgetMs: opts.viewBudgetMs ?? VIEW_DREAM_BUDGET_MS,
+ ...(opts.configPath !== undefined ? { configPath: opts.configPath } : {}),
+ });
+ if (result === null) return summary;
+ return {
+ ...summary,
+ view: {
+ status: result.status,
+ summary: describeAutoView(result),
+ ...(result.status === "not-writer" ? { writer: result.writer } : {}),
+ ...(result.status === "rendered"
+ ? { deferred: result.pages.filter((p) => p.status === "deferred").length }
+ : {}),
+ },
+ };
+}
diff --git a/src/core/brain/dream-types.ts b/src/core/brain/dream-types.ts
index 9171717f..2f60c630 100644
--- a/src/core/brain/dream-types.ts
+++ b/src/core/brain/dream-types.ts
@@ -10,6 +10,7 @@
* `dream-plan.ts`; this module is only what a CALLER of `dream()` sees.
*/
+import type { TopicPlanningReport } from "../topics/planning.ts";
import type { DreamPhaseSummary } from "./dream-phases.ts";
import type { DreamQuarantinedEntry } from "./dream-plan.ts";
import type { DreamOutcomeRegression } from "./dream-refresh.ts";
@@ -20,6 +21,13 @@ import type { SalienceGateVerdict } from "./salience-gate.ts";
import type { BrainRetiredReason, DreamOpenQuestion } from "./types.ts";
/** The human view render pass at the end of a dream pass. */
+/** The topic-planning step of one dream pass. */
+export interface DreamTopicsOutcome {
+ /** One readable line: what the step did. */
+ readonly summary: string;
+ readonly report: TopicPlanningReport;
+}
+
export interface DreamViewOutcome {
readonly status: string;
/** One readable line: what the pass did. */
@@ -130,6 +138,13 @@ export interface DreamRunSummary {
* machine, and on a dry run.
*/
readonly view?: DreamViewOutcome;
+ /**
+ * The topic-planning step that ran before the render (design D9, task
+ * 3.4): what it created and routed, each with its undo command, and what
+ * it only proposes. Absent when the brain store is not in use on this
+ * machine, and on a dry run.
+ */
+ readonly topics?: DreamTopicsOutcome;
/**
* Sub-operations the dream pass attempted but could not fully
* verify. Empty on every clean run; populated by future
@@ -242,6 +257,11 @@ export interface DreamGateOverrides {
}
export interface DreamOptions {
+ /**
+ * The machine config whose brain store the topic planning and the view
+ * render at the end of the pass use (absent: the process's own).
+ */
+ readonly configPath?: string;
/** Wall clock for the run. Defaults to `new Date()`. */
readonly now?: Date;
/** When true, compute the plan but make no writes. */
diff --git a/src/core/brain/dream.ts b/src/core/brain/dream.ts
index 61e2df3b..6a037615 100644
--- a/src/core/brain/dream.ts
+++ b/src/core/brain/dream.ts
@@ -19,6 +19,9 @@
* - `dream-apply.ts` the plan turned into disk state, in order
* - `dream-report.ts` the run's audit trail in `Brain/log/`
* - `dream-summary.ts` the {@link DreamRunSummary} the caller sees
+ * - `dream-outcome.ts` the `changed` gate, warnings, retire siblings
+ * - `dream-rollup.ts` the rollup-ladder plan and its link manifest
+ * - `dream-tail.ts` topic planning and the human view render
*
* Outputs (high level):
*
@@ -50,10 +53,9 @@
* - dryRun mode returns the planned summary but performs no writes.
*/
+import { withTopicPass, withViewPass } from "./dream-tail.ts";
import { vaultRelativeOf } from "./no-vault.ts";
import { withLogReadPass } from "./log-days.ts";
-import { describeAutoView, runAutoViewPass } from "../view/auto-render.ts";
-import { VIEW_DREAM_BUDGET_MS } from "../view/constants.ts";
import { existsSync } from "node:fs";
import { join } from "node:path";
@@ -63,29 +65,22 @@ import {
gatedRetireSlugs,
plannedSignalArchiveIds,
plannedSignalMoveIds,
- shouldGateRetireFromConfirmed,
type DreamApplyResult,
} from "./dream-apply.ts";
-import { resolveNearDuplicateRetireSiblingsEnabled } from "../config.ts";
import { planAutoRetires } from "./dream-plan-retires.ts";
import { planTopics, topicKeyContentionWarnings } from "./dream-plan-topics.ts";
-import type { PlanState, ScanResult } from "./dream-plan.ts";
+import type { ScanResult } from "./dream-plan.ts";
import {
planCrossTopicRules,
readCrossTopicLedger,
resolveCrossTopicConfig,
} from "./dream-plan-cross-topic.ts";
-import { planRefresh, scanApplyEvidence, type RefreshResult } from "./dream-refresh.ts";
+import { planRefresh, scanApplyEvidence } from "./dream-refresh.ts";
import { writeDreamLog } from "./dream-report.ts";
import { scanBrain } from "./dream-scan.ts";
import { planSignalArchive } from "./signal-archive.ts";
import { buildChangedSummary, buildNoOpSummary } from "./dream-summary.ts";
-import type {
- DreamGatedRetireEntry,
- DreamOptions,
- DreamRunSummary,
- DreamWarning,
-} from "./dream-types.ts";
+import type { DreamOptions, DreamRunSummary, DreamWarning } from "./dream-types.ts";
import { openWorkrun, WORKRUN_PHASE, workrunPath, type WorkrunHandle } from "./dream-workrun.ts";
import { buildIntentReview } from "./intent-review.ts";
import { logShardWikilink } from "./log.ts";
@@ -96,26 +91,17 @@ import {
type ProgressCounter,
} from "./progress.ts";
import { regenerateLessonsQuiet } from "./lessons.ts";
-import { buildLinkCandidateManifest, type LinkCandidateManifest } from "./notes/link-candidates.ts";
-import { gatedOwnerScopeView } from "./owner-scope-view.ts";
import { brainDirsForWrite, collisionCandidateName } from "./paths.ts";
import { isStoreOnly } from "../store/store-only.ts";
import { repairLaneEntryIds } from "../store-migration/lane-id-repair.ts";
import { loadBrainConfig } from "./policy.ts";
import { buildReconcileOutcomes } from "./reconcile-outcomes.ts";
-import {
- planRollupLadder,
- readRollupLedger,
- resolveRollupThresholds,
- type RollupLadderPlan,
-} from "./rollup-ladder.ts";
-import { READ_ALL_REFS } from "./near-duplicate.ts";
-import { planRetireSiblings, retireSiblingPool } from "./retire-siblings.ts";
+import { buildRollupPlan, memoizedLinkCandidates } from "./dream-rollup.ts";
+import { collectWarnings, hasStateChange, withRetireSiblings } from "./dream-outcome.ts";
import { applySalienceGate } from "./salience-gate.ts";
import { withDestructiveSnapshot } from "./snapshot-gate.ts";
import { compactRunStamp, isoDate } from "./time.ts";
import { BRAIN_SNAPSHOT_REASON } from "./types.ts";
-import type { BrainConfig } from "./types.ts";
// ----- Public surface ------------------------------------------------------
@@ -231,7 +217,7 @@ export function dream(vault: string | null, opts: DreamOptions = {}): DreamRunSu
// One read pass for the whole dream: the store-only log is read once
// and shared by every preference's evidence walk (log-days.ts).
return withLogReadPass(() =>
- withViewPass(dreamRun(vault, opts, progress, progressFaults), opts),
+ withViewPass(withTopicPass(dreamRun(vault, opts, progress, progressFaults), opts), opts),
);
} catch (error) {
const reason = progressReasonForError(error);
@@ -252,34 +238,6 @@ function uniqueNoVaultRunId(base: string): string {
throw new Error(`dream: no free run id after ${NO_VAULT_RUN_ID_ATTEMPTS} attempts (${base})`);
}
-/**
- * Render the human view at the end of a pass that wrote (design D7): the
- * view writer keeps its pages current, any other machine writes none and
- * its summary names the writer. Bounded by a time budget: pages it does
- * not reach are deferred to the next pass and counted. Fail-open, and
- * absent when the brain store is not in use here, so such a summary is
- * byte-identical to before.
- */
-function withViewPass(summary: DreamRunSummary, opts: DreamOptions): DreamRunSummary {
- if (opts.dryRun === true) return summary;
- const result = runAutoViewPass({
- trigger: "dream",
- budgetMs: opts.viewBudgetMs ?? VIEW_DREAM_BUDGET_MS,
- });
- if (result === null) return summary;
- return {
- ...summary,
- view: {
- status: result.status,
- summary: describeAutoView(result),
- ...(result.status === "not-writer" ? { writer: result.writer } : {}),
- ...(result.status === "rendered"
- ? { deferred: result.pages.filter((p) => p.status === "deferred").length }
- : {}),
- },
- };
-}
-
/**
* Regenerate the active and lessons digests after a pass. Where they land
* is `compiledDigestPath`'s one rule: `Brain/active.md` and
@@ -670,168 +628,6 @@ function dreamRun(
});
}
-/**
- * Attach the retire-sibling projection (near-duplicate defense) to a
- * changed run's summary. Computed from the completed retire plan, then
- * reconciled against the retires the confirmed-evidence gate holds back:
- * the ones the apply step gated, or on a dry run the ones it would gate,
- * so the dry run and the real run agree. A retiring preference is never
- * refreshed first, so its scanned frontmatter is what the apply step
- * reads. The scan is the pass's own reach (a preview scan is already
- * admitted), hence {@link READ_ALL_REFS}. Off (`enabled`, else the
- * default config's key), or with nothing to report, the summary is
- * returned untouched.
- */
-function withRetireSiblings(
- summary: DreamRunSummary,
- scan: ScanResult,
- plan: PlanState,
- opts: {
- readonly enabled: boolean | undefined;
- readonly gatedRetires: ReadonlyArray<DreamGatedRetireEntry>;
- readonly previewGateThreshold: number | undefined;
- },
-): DreamRunSummary {
- if (plan.retires.length === 0 || !(opts.enabled ?? resolveNearDuplicateRetireSiblingsEnabled())) {
- return summary;
- }
- const gated = new Set(opts.gatedRetires.map((g) => g.pref_id));
- if (opts.previewGateThreshold !== undefined) {
- const byId = new Map(scan.preferences.map((p) => [p.pref.id, p.pref] as const));
- for (const r of plan.retires) {
- const existing = byId.get(`pref-${r.slug}`);
- if (
- existing !== undefined &&
- shouldGateRetireFromConfirmed(existing, r.reason, opts.previewGateThreshold)
- ) {
- gated.add(existing.id);
- }
- }
- }
- const siblings = planRetireSiblings(
- retireSiblingPool(scan.preferences.map((p) => p.pref)),
- plan.retires.map((r) => ({ id: `pref-${r.slug}`, principle: r.principle, reason: r.reason })),
- { readable: READ_ALL_REFS, gated },
- );
- if (siblings.length === 0) return summary;
- return Object.freeze({ ...summary, retire_siblings: Object.freeze([...siblings]) });
-}
-
-/**
- * Non-fatal warnings raised during the run. The non-primary-dream-run
- * check is the first one: when the caller declares an agent name and it
- * differs from the vault's declared primary, surface a structured
- * warning. We do NOT abort — the declaration is observability, not
- * access control.
- */
-function collectWarnings(
- isNonPrimary: boolean,
- callerAgent: string,
- primaryAgent: string | null,
-): DreamWarning[] {
- if (!isNonPrimary) return [];
- return [
- {
- code: "non-primary-dream-run",
- message:
- `dream run from agent '${callerAgent}', but primary is ` +
- `'${primaryAgent}'. Convention violation, run proceeds.`,
- },
- ];
-}
-
-/**
- * Decide if anything is going to change. We treat any of the following
- * as a state change:
- * - a new unconfirmed pref
- * - a refreshed pref (counters/confidence/status changed)
- * - a retire
- * - a same-sign signal noted on an active pref (move + log)
- * - an inbox signal archived because it left the contradiction window
- * - a corrupted frontmatter (we want the skip event recorded)
- * - any pinned-rebut-attempt warning
- * - a fired rollup-ladder rung (S3)
- * - a cross-topic rule promotion (t_642bc2b8)
- */
-function hasStateChange(
- plan: PlanState,
- refresh: RefreshResult,
- corruptedCount: number,
- rollupPlan: RollupLadderPlan,
-): boolean {
- return (
- plan.newUnconfirmed.length > 0 ||
- refresh.confirmed.size > 0 ||
- refresh.updated.size > 0 ||
- plan.retires.length > 0 ||
- plan.notedRedundant.length > 0 ||
- plan.signalsToMove.size > 0 ||
- plan.signalsToArchive.size > 0 ||
- plan.retainPinned.length > 0 ||
- plan.signalsSuppressed.length > 0 ||
- // v0.10.16: quarantine is a recorded decision (deferred-but-noted),
- // so a run that produces only quarantine entries is still a
- // meaningful run from the operator's perspective.
- plan.quarantined.length > 0 ||
- plan.crossTopicRules.length > 0 ||
- rollupPlan.fired ||
- corruptedCount > 0
- );
-}
-
-function buildRollupPlan(
- vault: string | null,
- cfg: BrainConfig,
- factCount: number,
- runId: string,
- linkCandidates: () => LinkCandidateManifest,
-): RollupLadderPlan {
- return planRollupLadder({
- factCount,
- ledger: readRollupLedger(vault),
- thresholds: resolveRollupThresholds(cfg),
- runId,
- linkCandidates,
- });
-}
-
-/**
- * The link-candidate manifest for this run, walked at most once and only
- * if something asks for it. Both callers of {@link buildRollupPlan} share
- * one of these, so a runId collision re-plans off the manifest already
- * built rather than walking the vault a second time.
- *
- * No query: the ladder is count-only by design and never learns which
- * items it is folding, so ranking the candidates would be inventing a
- * relevance nothing measured. The manifest says `alphabetical` and names
- * the total, which is the honest form of that.
- */
-function memoizedLinkCandidates(
- vault: string | null,
- agentName: string | undefined,
- readable: ((rel: string) => boolean) | undefined,
-): () => LinkCandidateManifest {
- let manifest: LinkCandidateManifest | null = null;
- return () => {
- if (manifest !== null) return manifest;
- // No vault: no user notes for a rollup to link to (design D14).
- if (vault === null) return (manifest = NO_LINK_CANDIDATES);
- const ownerView = gatedOwnerScopeView(vault, agentName);
- manifest = buildLinkCandidateManifest(vault, {
- visible: (rel) => ownerView.visible(rel) && (readable?.(rel) ?? true),
- });
- return manifest;
- };
-}
-
-/** The link manifest of a machine with no vault: no notes, so no candidates. */
-const NO_LINK_CANDIDATES: LinkCandidateManifest = Object.freeze({
- candidates: Object.freeze([]),
- total: 0,
- truncated: false,
- selection: "alphabetical",
-});
-
/** What a no-vault run names as its log: the brain log is a store record stream. */
const NO_VAULT_LOG_PATH = "store:log";
diff --git a/src/core/brain/notes/create-note.ts b/src/core/brain/notes/create-note.ts
index 9eecd303..728b5a50 100644
--- a/src/core/brain/notes/create-note.ts
+++ b/src/core/brain/notes/create-note.ts
@@ -480,7 +480,7 @@ export function resolveNoteTarget(vault: string, path: string): ResolvedNoteTarg
// writer's: a page edited there is read back with human authority
// (`core/view/vault-guard.ts`), so a note tool must not write it.
for (const rel of new Set([relPath, landsAt])) {
- const viewRefusal = viewFolderRefusal(vault, rel, "create_note");
+ const viewRefusal = viewFolderRefusal(vault, rel, "the note tools");
if (viewRefusal !== null) throw new CreateNoteError("excluded", viewRefusal);
}
diff --git a/src/core/brain/query.ts b/src/core/brain/query.ts
index 225aebfd..db9b9718 100644
--- a/src/core/brain/query.ts
+++ b/src/core/brain/query.ts
@@ -8,7 +8,7 @@
* - {@link queryByPreference} — one preference (active or retired)
* plus every `apply-evidence` log entry that references it.
*
- * - {@link queryByTopic} — every signal under a topic (active +
+ * - {@link queryByRuleTopic} — every signal under a topic (active +
* processed), the current preference for that topic (active or
* retired), and every log entry mentioning the preference.
*
@@ -234,7 +234,7 @@ export function queryByPreference(vault: string, pref_id: string): QueryByPrefer
* retired), and every log entry mentioning the preference id (active
* or retired form). Unknown topic → empty result with `preference: null`.
*/
-export function queryByTopic(
+export function queryByRuleTopic(
vault: string,
topic: string,
options: QueryByTopicOptions = {},
diff --git a/src/core/derived-store-guard.ts b/src/core/derived-store-guard.ts
index 5de1eec2..bf4e17cb 100644
--- a/src/core/derived-store-guard.ts
+++ b/src/core/derived-store-guard.ts
@@ -48,7 +48,7 @@ export function derivedDirIsSymlinked(base: string, ...segments: readonly string
}
/** Open flags for a derived-file read: never follow a leaf symlink where the platform can refuse one. */
-const READ_NO_FOLLOW_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0);
+export const READ_NO_FOLLOW_FLAGS = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0);
/**
* Outcome of {@link readRegularFileNoFollow}: the file is `absent`, exists but
diff --git a/src/core/search/visibility-surface-registry.ts b/src/core/search/visibility-surface-registry.ts
index 083ebd70..56d909f5 100644
--- a/src/core/search/visibility-surface-registry.ts
+++ b/src/core/search/visibility-surface-registry.ts
@@ -176,7 +176,7 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
kind: K.mcpTool,
category: C.covered,
reason:
- "queryByPreference / queryByTopic (core/brain/query.ts) return Brain records by id, so this " +
+ "queryByPreference / queryByRuleTopic (core/brain/query.ts) return Brain records by id, so this " +
"is root C over reference-shaped rows. The topic mode carries the reach into the SELECTION, " +
"because a topic resolves to exactly one preference and filtering afterwards would report a " +
"topic as having no rule whenever a reserved one sorted first; the signals, the log events " +
@@ -1420,7 +1420,7 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
"reach, named for the resolved page's own derived provenance; local keeps the bytes.",
},
{
- surface: "osb://topic/{slug}",
+ surface: "osb://rule-topic/{slug}",
kind: K.mcpResource,
category: C.covered,
reason:
@@ -1431,6 +1431,16 @@ export const VISIBILITY_SURFACE_REGISTRY: ReadonlyArray<VisibilitySurfaceEntry>
"synthesis is fenced at remote reach, named for the governing rule's derived provenance " +
"(the absent-rule probe, fail closed); local keeps the bytes.",
},
+ {
+ surface: "osb://topic/{id}",
+ kind: K.mcpResource,
+ category: C.covered,
+ reason:
+ "a topic is a store record family with no owner line: its privacy is its partition. A read " +
+ "below local reach folds the shared partition alone, so a private topic answers byte for " +
+ "byte as an absent one (topic ids are ULIDs, not guessable, and still never confirmed), and " +
+ "a private item of a shared topic is left off the page.",
+ },
{
surface: "osb://log/{date}",
kind: K.mcpResource,
diff --git a/src/core/store/FORMAT.md b/src/core/store/FORMAT.md
index 40c3f143..df29e5ef 100644
--- a/src/core/store/FORMAT.md
+++ b/src/core/store/FORMAT.md
@@ -177,6 +177,7 @@ Settings every machine must agree on are records in the `settings` stream of the
- `view.language`: the language tag (for example `en`, `ru` or `pt-BR`) of generated prose in the human view. No default; the renderer decides.
- `topics.new_min_records`: how many related unassigned records start a new topic, a positive integer. Default 5.
- `topics.new_min_sessions`: from how many sessions those records must come, a positive integer. Default 2.
+- `topics.quiet_days`: after how many days without a record an active topic is offered to the user for a status decision, a positive integer. Default 30.
Keys `brain.<block>.<field>` (and `brain.<key>` for a scalar) hold the settings of a vault's legacy `_brain.yaml` that every machine must agree on. The migration from the legacy layout writes only the values the user changed from the shipped default, with `authority` `human`; a value equal to its default is not written, and the key falls back to that default. Their values are the JSON the file held.
@@ -226,7 +227,7 @@ A digest covers an explicit cut: one entry for every shard the publishing machin
"last": "<id of the last verified record>", "pending": <records whose blob has not arrived> }
```
-`pending` is part of the cut because a record whose blob has not arrived cannot be folded yet; two machines that differ only in a delivered blob have different cuts. The digest carries the sha256 of the canonical JSON of the cut, and for each fold (`preferences`, `pinned`, `settings`) the sha256 of the canonical JSON of the fold's resolved state computed from exactly the records in the cut.
+`pending` is part of the cut because a record whose blob has not arrived cannot be folded yet; two machines that differ only in a delivered blob have different cuts. The digest carries the sha256 of the canonical JSON of the cut, and for each fold (`preferences`, `pinned`, `settings`, `topics`) the sha256 of the canonical JSON of the fold's resolved state computed from exactly the records in the cut. The `topics` hash came later: a digest written by an earlier release of format version 1 has none, and two digests are compared on a fold only when both carry it.
- Comparison: only digests whose cuts are identical are compared, each device's latest digest per cut, among the digests of the last 7 days. A fold whose hash differs between two such digests is reported as divergent, with the devices, the partition and the fold.
- Roster: the devices with records in the partition during the last 30 days, minus the devices retired by a `device-retire` record with `authority` `human`. A retired device that writes a record after its retire record is on the roster again. Retire records are read from the `settings` stream of `shared` and apply to every partition.
@@ -253,7 +254,7 @@ Kinds of the mutable-entity folds, with their bodies (fields marked optional may
Kinds of the state digests:
- `device-retire`: `{ "authority": "human", "device": "<device id>", "reason": "<text>" (optional) }`, written to `settings` in `shared`. Takes a device off the digest roster, and out of the devices a removal of the legacy tree waits for. The user writes it (`o2b store device retire`) on a machine other than the one retired; the record's own `device` field is the writing machine, the body's `device` the retired one. A reason that would route the record to `private` is refused, since every machine reads retirements from `shared`. A retired device that writes a record after its retire record is on the roster again and is reported by doctor.
-- `state-digest`: `{ "partition": "shared" | "private", "cut": [<entry>, ...], "cut_hash": "<sha256>", "folds": { "preferences": "<sha256>", "pinned": "<sha256>", "settings": "<sha256>" } }`, written to `digests` in its partition.
+- `state-digest`: `{ "partition": "shared" | "private", "cut": [<entry>, ...], "cut_hash": "<sha256>", "folds": { "preferences": "<sha256>", "pinned": "<sha256>", "settings": "<sha256>", "topics": "<sha256>" (optional) } }`, written to `digests` in its partition.
Kinds written by the dual writes of format version 1 (a trial: while the dual-write setting is on, the release's existing writers also append these records beside their legacy files). Mutable entities reuse the fold kinds above: preference writes and retires are `preference-set` records of the `pref-<slug>` id (a retire sets `status` to `retired`), apply-evidence is `preference-evidence`, and pinned context is `pinned-set` or `pinned-clear`. Pinned context goes to `private` when the writing machine holds that partition and to `shared` when it does not; a text that carries a `<private>` region (or the placeholder a stripped one leaves) or links a private page goes to `private` only. A `pinned-clear` is judged by the text it clears, so it lands where that text's `pinned-set` did. The two partition registers are not merged: a machine that holds `private` writes its sets and clears there, a machine that does not writes them to `shared`, and each partition's register (and its digest) reflects only the records in that partition.
@@ -282,18 +283,39 @@ Kinds of the human view (the readable Markdown pages one device, the view writer
- `view-writer-claim`: `{ "authority": "human", "device": "<device id>" }`, written to `settings` in `shared` by the first machine that creates or migrates the store.
- `view-writer-request`: `{ "authority": "human", "device": "<device id>", "force": <bool> }`, written to `settings` in `shared`: the user asks for the role on that device.
- `view-writer-released`: `{ "request": "<request record id>", "device": "<the releasing writer>", "to": "<device id>" }`, written to `settings` in `shared` by the writer once it has finished any render in progress.
-- `view-render`: `{ "page": "<page path>", "sum": "<sha256 of the page bytes>", "base": "<blob sha256>", "bytes": <length> }`, written to `log` in `shared` after the page holds those bytes. The blob is the canonical JSON of `{ "page", "text", "keys" }`: the page text and, per line, the key of the record it shows (or `null`), the merge base of the next render.
+- `view-render`: `{ "page": "<page path>", "topic": "<topic id>" (optional, for a topic page), "sum": "<sha256 of the page bytes>", "base": "<blob sha256>", "bytes": <length> }`, written to `log` in `shared` after the page holds those bytes. The blob is the canonical JSON of `{ "page", "text", "keys" }`: the page text and, per line, the key of the record it shows (or `null`), the merge base of the next render.
- `view-pass`: `{ "written": 0 }`, written to `log` in `shared` by a writer whose pass found every page of its view folder already as rendered (an idle pass), at most once a day. A pass with no view folder, or with a page it could not write, records none.
- `view-replaced`: `{ "page", "sum", "blob": "<blob sha256>", "bytes", "reason": "edit" | "race" | "conflict-copy" | "foreign" }`, written to `log`: page bytes that were not the writer's own render, kept as a blob of `{ "page", "text" }`. It lands in the partition of the edit's privacy verdict, with the human records the edit produced.
- `view-correction`: `{ "authority", "page", "key", "text" }` or `{ "authority", "page", "key", "hidden": true }`, written to `events`: the user reworded or deleted the line of a page that shows `key`. One register per page and key, resolved by authority, then clock.
- `view-addition`: `{ "authority", "page", "after": "<key>" | null, "text" }`, written to `events`: a line the user added below the line that shows `after`.
-Page paths are relative to the view folder and use `/`. Pages are rendered from `shared` records only; a preference with any record in `private` is left out of every page. A reworded rule line of `about-me.md` is a `preference-set` of the rule's `principle`, a deleted one a `preference-set` that sets `status` to `retired`.
+Page paths are relative to the view folder and use `/`. Pages are rendered from `shared` records only; a preference with any record in `private` is left out of every page, and so is a private topic. A topic page is `topics/<YYYY-MM-DD>-<slug>/topic.md` (the topic's creation day and a slug of its title; a rename moves the folder), with a companion `archive.md` for the entries over the page budget and the resolved questions; its id comment line also names the topic (`topic=<topic id>`). Research reports render to `reports/<entry>.md` and source summaries to `sources/<entry>.md`, from the `lane-entry` records of the lanes `reports` and `sources`. A page in `topics/`, `reports/` or `sources/` the store no longer renders is removed by the view writer, after any edit it carries is ingested, and only when its path has exactly the shape the writer produces (forward slashes, no `..` or `\`, no empty segment, no Windows device name) and resolves inside the view folder, with no symbolic link below the view folder; a render record that names any other path is ignored. An edit of a topic page becomes the topic record that says the same thing, with `authority` `human`. A reworded rule line of `about-me.md` is a `preference-set` of the rule's `principle`, a deleted one a `preference-set` that sets `status` to `retired`.
Ledgers the migration from the legacy layout writes (`ledger-row` records, the same shape): `capture-decisions` (one row per inbound capture the capture bot accepted, rejected or found malformed), `search-feedback` (which search results an agent used, per query) and `search-reinforce` (which vault paths were reinforced by use). Their rows go to `private` when the writing machine holds that partition and to `shared` when it does not; a row that names a private page goes to `private` only.
A `search-reinforce` row is either one reinforcement, `{ "ts": <unix ms>, "paths": ["<vault-relative path>", ...] }`, or a reset, `{ "ts": <unix ms>, "reset": true }`. The ledger is append-only, so a reset is a row too: the reinforcement fold counts only the rows after the newest reset row in fold order, and a reset lands in the partition its writer would put a reinforcement in.
+Kinds of topics (a topic is one area of work or one personal matter with an immutable id; its page in the human view is rendered from these records). Every topic record is written to `topics`, carries `authority` in its body and the topic's id (a ULID) in the envelope's `topic` field; the id never changes, and a rename changes only the title. A list item (a decision, an open question, a log entry, a milestone) is addressed by its `item` id (1 to 64 letters, digits, hyphens and underscores), which is its topic's own: the same id in two topics names two items; a record that creates an item may leave `item` out, and its own record id is the item id then. An item record of the form `{ "authority", "item", "removed": true }` is the item's tombstone.
+
+- `topic-create`: `{ "authority", "title": "<one line>", "scope": "personal" | "project:<project>", "description": "<one line>" | null (optional), "goal": "<text>" | null (optional) }`. The topic exists from its first create in fold order, which fixes its scope and its creation time; its status starts as `active`. The envelope `scope` repeats the topic scope.
+- `topic-rename`: `{ "authority", "title" (optional), "description": "<text>" | null (optional) }`, at least one of the two.
+- `topic-status`: `{ "authority", "status": "active" | "waiting" | "blocked" | "on-hold" | "done" | "closed", "resolved": "<YYYY-MM-DD>" (optional) }`. A `done` status without `resolved` is resolved on the UTC day of the record's clock.
+- `topic-goal`: `{ "authority", "goal": "<text>" | null }`. A goal offer that loses to a stronger authority and comes after the winner is kept as a proposal, shown on the page as an open question attributed to its agent.
+- `decision`: `{ "authority", "item" (optional), "text", "serves": ["<milestone item>", ...] (optional) }`. A record that leaves `serves` out keeps the links the item already has; `"serves": []` clears them.
+- `open-question`: `{ "authority", "item" (optional), "text" }`.
+- `question-resolved`: `{ "authority", "question": "<item>", "answer": "<text>" (optional) }`. One from a decision model only proposes the resolution.
+- `log-entry`: `{ "authority", "item" (optional), "text", "class": "correction" | "decision" | "blocker" | "reframing" | "rejected" | "note" | "routine", "reason": "<text>" (optional) }`. Every class but `routine` is shown on the topic page; routine progress stays in the store.
+- `milestone`: `{ "authority", "item" (optional), "text" }`.
+- `milestone-done`: `{ "authority", "milestone": "<item>", "evidence": "<text>" (optional) }`. It marks the milestone done only with `authority` `human`, or `agent` with `evidence`; any other one only proposes completion.
+- `assign`: `{ "authority", "record": "<record id>" }`: the record belongs to the topic. `unassign` takes it out again.
+- `unassign`: `{ "authority", "record": "<record id>" }`. Unless its `authority` is `model` it also blocks the route: no automatic pass assigns that record to that topic again.
+- `merge`: `{ "authority", "into": "<topic id>" }`: the topic merged into another. It resolves to that topic, whose page carries both topics' items. Merges apply in fold order; one that would close a cycle, or names a topic that does not exist, is ignored.
+- `split`: `{ "authority", "into": "<topic id>", "items": ["<item>", ...] (optional), "records": ["<record id>", ...] (optional) }`: the items and assigned records listed move to the other topic. An item is looked up as the split's topic names it (its own, or one split into it), so an item of a topic merged into another is split by a `split` under the merged topic.
+- `link`: `{ "authority", "to": "<topic id>", "removed": true (optional) }`: the two topics are related; with `removed` the link is gone.
+- `undo`: `{ "authority", "record": "<record id>" }`: the record named is void, as if never written, when the undo's authority is at least that record's. An undo can be undone. An undo of an `assign` whose `authority` is not `model` blocks that route as an `unassign` does.
+
+Topics fold under the rules of every mutable entity: the title, description, goal and status of a topic, each item, the topic that owns an item, a milestone's completion, a question's resolution, a merge, a link and a record's assignment are each one register, resolved by authority, then clock. A record that is not a topic record belongs to the topic its `assign` names, else to the topic its envelope names. A topic is private when its first `topic-create` sits in `private`; every later record of a private topic is written there too, and so is an `undo` of any record that sits in `private` (the undo of an undone private create names a topic that is out of the fold, and still goes there), and an item record, `milestone-done` or `question-resolved` of an item that has a record in `private` (a `milestone-done` or `question-resolved` there counts too). A route taken back from a topic stays blocked for the topic it merged into. A `topic-create` with the personal scope goes to `private` unless its writer asks otherwise.
+
Kinds of attestations (a signed statement of the state one machine measured, made with that machine's signing key):
- `attestation`: `{ "record": { ... } }`, written to `events` in `shared`. The whole signed attestation as its writer produced it: its id (`attest-<UTC instant>`, unique), creation time, signing device, the measured manifest, the store digest, the seal and the signature. An attestation names no page, so it always goes to `shared`, where every machine that verifies it can read it. The key that signed it is never a record: it stays in the signing machine's device-local state, and a verifier needs only its public half. When two records carry the same attestation id, the first in fold order is the attestation and the others are ignored.
diff --git a/src/core/store/constants.ts b/src/core/store/constants.ts
index c88bcde6..ea1e0b75 100644
--- a/src/core/store/constants.ts
+++ b/src/core/store/constants.ts
@@ -204,17 +204,35 @@ export const PREFERENCE_COUNTER_FIELDS = Object.freeze([
export const SETTING_VIEW_LANGUAGE = "view.language";
export const SETTING_TOPIC_MIN_RECORDS = "topics.new_min_records";
export const SETTING_TOPIC_MIN_SESSIONS = "topics.new_min_sessions";
+export const SETTING_TOPIC_QUIET_DAYS = "topics.quiet_days";
export const SETTING_KEYS = Object.freeze([
SETTING_VIEW_LANGUAGE,
SETTING_TOPIC_MIN_RECORDS,
SETTING_TOPIC_MIN_SESSIONS,
+ SETTING_TOPIC_QUIET_DAYS,
] as const);
export type SettingKey = (typeof SETTING_KEYS)[number];
/** The folds a state digest hashes, in the order the digest body lists them. */
-export const STATE_DIGEST_FOLDS = Object.freeze(["preferences", "pinned", "settings"] as const);
+export const STATE_DIGEST_FOLDS = Object.freeze([
+ "preferences",
+ "pinned",
+ "settings",
+ "topics",
+] as const);
export type StateDigestFold = (typeof STATE_DIGEST_FOLDS)[number];
+/**
+ * The folds every digest carries. `topics` came later: a digest an older
+ * release published has no `topics` hash, and a pair of digests is
+ * compared on a fold only when both carry it.
+ */
+export const STATE_DIGEST_REQUIRED_FOLDS: ReadonlyArray<StateDigestFold> = Object.freeze([
+ "preferences",
+ "pinned",
+ "settings",
+]);
+
/** One day in milliseconds, for the day-based windows below. */
export const DAY_MS = 24 * 60 * 60 * 1000;
diff --git a/src/core/store/dual-write.ts b/src/core/store/dual-write.ts
index ef1ca5f5..e5666304 100644
--- a/src/core/store/dual-write.ts
+++ b/src/core/store/dual-write.ts
@@ -90,6 +90,8 @@ export interface DualWriteRecord extends StreamRef {
/** The writing agent; defaults to the configured agent name. */
readonly agent?: string;
readonly scope?: string | null;
+ /** The topic id the record belongs to (the envelope `topic`); `null` or absent: none. */
+ readonly topic?: string | null;
readonly body: RecordBody;
}
@@ -393,6 +395,7 @@ export function appendStoreRecords(
agent:
record.agent !== undefined && record.agent.trim() !== "" ? record.agent : defaultAgent(),
scope: record.scope ?? null,
+ topic: record.topic ?? null,
body: { ...record.body, [VAULT_ID_FIELD]: vaultId },
}),
);
diff --git a/src/core/store/fold-settings.ts b/src/core/store/fold-settings.ts
index 0954f8b9..51568855 100644
--- a/src/core/store/fold-settings.ts
+++ b/src/core/store/fold-settings.ts
@@ -22,6 +22,7 @@ import {
SETTING_SET_KIND,
SETTING_TOPIC_MIN_RECORDS,
SETTING_TOPIC_MIN_SESSIONS,
+ SETTING_TOPIC_QUIET_DAYS,
SETTING_UNSET_KIND,
SETTING_VIEW_LANGUAGE,
type SettingKey,
@@ -61,6 +62,7 @@ export const SETTING_RULES: Readonly<Record<SettingKey, SettingRule>> = Object.f
},
[SETTING_TOPIC_MIN_RECORDS]: { valid: positiveInt, expected: "a positive integer", fallback: 5 },
[SETTING_TOPIC_MIN_SESSIONS]: { valid: positiveInt, expected: "a positive integer", fallback: 2 },
+ [SETTING_TOPIC_QUIET_DAYS]: { valid: positiveInt, expected: "a positive integer", fallback: 30 },
});
function ruleOf(key: string): SettingRule | undefined {
diff --git a/src/core/store/state-digest-compare.ts b/src/core/store/state-digest-compare.ts
index 037d631a..4f78c949 100644
--- a/src/core/store/state-digest-compare.ts
+++ b/src/core/store/state-digest-compare.ts
@@ -26,6 +26,7 @@ import {
DIGEST_ROSTER_WINDOW_DAYS,
DIGEST_SILENCE_DAYS,
STATE_DIGEST_FOLDS,
+ STATE_DIGEST_REQUIRED_FOLDS,
STATE_DIGEST_KIND,
type StateDigestFold,
type StorePartition,
@@ -48,9 +49,18 @@ export function parseDigest(record: StoreRecord): DigestBody | null {
if (typeof body.cut_hash !== "string" || !SHA256_RE.test(body.cut_hash)) return null;
const folds = body.folds as Record<string, unknown> | undefined;
if (typeof folds !== "object" || folds === null) return null;
- for (const fold of STATE_DIGEST_FOLDS) {
+ for (const fold of STATE_DIGEST_REQUIRED_FOLDS) {
if (typeof folds[fold] !== "string" || !SHA256_RE.test(folds[fold] as string)) return null;
}
+ // A fold added later (`topics`) is optional; when present it must be a hash.
+ for (const fold of STATE_DIGEST_FOLDS) {
+ if (
+ folds[fold] !== undefined &&
+ !(typeof folds[fold] === "string" && SHA256_RE.test(folds[fold]))
+ ) {
+ return null;
+ }
+ }
return record.body as unknown as DigestBody;
}
@@ -179,16 +189,20 @@ export function compareDigests(input: CompareDigestsInput): DigestComparison {
const names = [...devices.keys()].toSorted();
comparedCuts.push({ cutHash, devices: names });
for (const fold of STATE_DIGEST_FOLDS) {
- const hashes = new Set(names.map((device) => devices.get(device)!.body.folds[fold]));
- if (hashes.size < 2) continue;
+ // Only the digests that carry the fold (an older release's has no `topics`).
+ const carrying = names.filter(
+ (device) => devices.get(device)!.body.folds[fold] !== undefined,
+ );
+ const hashes = new Set(carrying.map((device) => devices.get(device)!.body.folds[fold]));
+ if (carrying.length < 2 || hashes.size < 2) continue;
findings.push({
kind: "divergent",
partition,
fold,
cutHash,
- devices: names.map((device) => {
+ devices: carrying.map((device) => {
const { record, body } = devices.get(device)!;
- return { device, hash: body.folds[fold], digest: record.id };
+ return { device, hash: body.folds[fold]!, digest: record.id };
}),
});
}
diff --git a/src/core/store/state-digest.ts b/src/core/store/state-digest.ts
index 42e9ed4c..3d382fc1 100644
--- a/src/core/store/state-digest.ts
+++ b/src/core/store/state-digest.ts
@@ -43,6 +43,7 @@ import { compareRecords, type StoreRecord } from "./envelope.ts";
import { foldPinned, pinnedFingerprint } from "./fold-pinned.ts";
import { foldPreferences, preferencesFingerprint } from "./fold-preferences.ts";
import { foldSettings, settingsFingerprint } from "./fold-settings.ts";
+import { foldTopics, topicsFingerprint } from "../topics/fold.ts";
import { parseHlc } from "./hlc.ts";
import { readShard, replacedShards, shardReadGap, type Compaction } from "./reader.ts";
import { SEEN_SHARD_MISSING_REASON, trackSeenShards } from "./seen-shards.ts";
@@ -108,12 +109,15 @@ export interface CutEntry {
/** Fold name to sha256. */
export type FoldHashes = { readonly [F in StateDigestFold]: string };
+/** The fold hashes a parsed digest carries: `topics` is absent in an older release's digest. */
+export type ParsedFoldHashes = Omit<FoldHashes, "topics"> & { readonly topics?: string };
+
/** The body of a `state-digest` record. */
export interface DigestBody {
readonly partition: StorePartition;
readonly cut: ReadonlyArray<CutEntry>;
readonly cut_hash: string;
- readonly folds: FoldHashes;
+ readonly folds: ParsedFoldHashes;
}
function ledgerNames(partitionRoot: string): string[] {
@@ -242,6 +246,7 @@ export function foldHashes(records: ReadonlyArray<StoreRecord>): FoldHashes {
preferences: hash(preferencesFingerprint(foldPreferences(records))),
pinned: hash(pinnedFingerprint(foldPinned(records))),
settings: hash(settingsFingerprint(foldSettings(records))),
+ topics: hash(topicsFingerprint(foldTopics(records))),
};
}
diff --git a/src/core/topics/actions.ts b/src/core/topics/actions.ts
new file mode 100644
index 00000000..1aa814a0
--- /dev/null
+++ b/src/core/topics/actions.ts
@@ -0,0 +1,538 @@
+/**
+ * The topic actions behind the `brain_topic` MCP tool and the `o2b topic`
+ * verbs (design D9; spec `topics` "Topics on request"; task 3.5): one
+ * implementation, so the tool and the CLI cannot disagree.
+ *
+ * Reads (`list`, `show`, `review`) answer at the caller's reach: below
+ * local reach only shared topics exist (`read.ts`), and a write that names
+ * a topic the caller cannot see is refused exactly as one that names no
+ * topic, so neither a private topic's content nor its existence crosses.
+ *
+ * Writes are topic records (`write.ts`). The requested actions (create,
+ * rename, status, goal, assign, unassign, merge, split, link, archive,
+ * undo) carry `human` authority when the user runs them (`o2b topic`) and
+ * `agent` authority through `brain_topic` (design D9, D18). `record` adds
+ * an agent's own decision, open question, log entry, milestone,
+ * resolution or completion, with `agent` authority by default. Every
+ * default can be named instead with `authority` (`human` is refused
+ * below local reach).
+ */
+
+import type { AppendResult } from "../store/appender.ts";
+import type { Authority } from "../store/constants.ts";
+import { SETTING_VIEW_LANGUAGE } from "../store/constants.ts";
+import { sharedSetting } from "./settings.ts";
+import { DELIVERY_TREATMENT, shapeStoredTextForDelivery } from "../brain/delivery-shaping.ts";
+import { viewStrings } from "../view/i18n.ts";
+import { topicPages } from "../view/topic-pages.ts";
+import {
+ TOPIC_ASSIGN_KIND,
+ TOPIC_GOAL_KIND,
+ TOPIC_LINK_KIND,
+ TOPIC_MERGE_KIND,
+ TOPIC_PERSONAL_SCOPE,
+ TOPIC_RENAME_KIND,
+ TOPIC_SPLIT_KIND,
+ TOPIC_STATUS_KIND,
+ TOPIC_UNASSIGN_KIND,
+ TOPIC_UNDO_KIND,
+ type TopicRecordKind,
+} from "./constants.ts";
+import type { TopicFold, TopicState } from "./fold.ts";
+import { reviewTopics } from "./plan.ts";
+import { readTopics, type TopicRead } from "./read.ts";
+import { createTopicEvent, writeTopicEvents, type TopicEvent } from "./write.ts";
+import { privateWithheld } from "../store/caller-reach.ts";
+import { SETTING_TOPIC_QUIET_DAYS } from "../store/constants.ts";
+
+export const TOPIC_ACTIONS = Object.freeze([
+ "list",
+ "show",
+ "review",
+ "create",
+ "rename",
+ "status",
+ "goal",
+ "assign",
+ "unassign",
+ "merge",
+ "split",
+ "link",
+ "archive",
+ "undo",
+ "record",
+] as const);
+export type TopicAction = (typeof TOPIC_ACTIONS)[number];
+
+/** The kinds `record` writes. */
+export const TOPIC_RECORD_ACTION_KINDS = Object.freeze([
+ "decision",
+ "open-question",
+ "log-entry",
+ "milestone",
+ "question-resolved",
+ "milestone-done",
+] as const);
+
+/** A topic action refused before anything was read or written. */
+export class TopicActionError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "TopicActionError";
+ }
+}
+
+export interface TopicActionInput {
+ readonly action: string;
+ readonly topic?: string;
+ readonly title?: string;
+ readonly description?: string | null;
+ readonly goal?: string | null;
+ readonly scope?: string;
+ readonly status?: string;
+ readonly resolved?: string;
+ readonly record?: string;
+ readonly into?: string;
+ readonly to?: string;
+ readonly items?: ReadonlyArray<string>;
+ readonly records?: ReadonlyArray<string>;
+ readonly removed?: boolean;
+ readonly private?: boolean;
+ readonly authority?: string;
+ /** `record`: the kind and its fields. */
+ readonly kind?: string;
+ /** `record`: the topic that owns the named item, when merged topics share its id. */
+ readonly owner?: string;
+ readonly fields?: Readonly<Record<string, unknown>>;
+ /** `list`: the scope to list (default: every topic). */
+ readonly listScope?: string;
+}
+
+export interface TopicActionContext {
+ readonly configPath?: string;
+ readonly agent?: string;
+ readonly now?: () => number;
+ /**
+ * The user is the caller (the `o2b topic` CLI): the requested actions
+ * default to `human` authority. Every other caller (an agent through
+ * `brain_topic`) defaults to `agent` and must name `human` to claim it.
+ */
+ readonly humanRequest?: boolean;
+}
+
+function need(input: TopicActionInput, field: keyof TopicActionInput): string {
+ const value = input[field];
+ if (typeof value !== "string" || value.trim() === "") {
+ throw new TopicActionError(`${input.action}: '${field}' is required`);
+ }
+ return value.trim();
+}
+
+function authorityOf(input: TopicActionInput, fallback: Authority): Authority {
+ if (input.authority === undefined) return fallback;
+ if (input.authority !== "human" && input.authority !== "agent") {
+ throw new TopicActionError("authority must be human or agent");
+ }
+ // A caller below local reach (a remote MCP transport) is never taken to
+ // speak for the user: its records would outweigh the user's own.
+ if (input.authority === "human" && privateWithheld()) {
+ throw new TopicActionError("human authority is refused below local reach");
+ }
+ return input.authority;
+}
+
+/** The fields `record` accepts for each kind; any other field is refused. */
+const RECORD_FIELDS: Readonly<Record<string, ReadonlyArray<string>>> = Object.freeze({
+ decision: ["item", "text", "serves", "removed"],
+ "open-question": ["item", "text", "removed"],
+ "log-entry": ["item", "text", "class", "reason", "removed"],
+ milestone: ["item", "text", "removed"],
+ "question-resolved": ["question", "answer"],
+ "milestone-done": ["milestone", "evidence"],
+});
+
+/** The field of a completion that names its item, and the item's kind. */
+const NAMED_ITEM: Readonly<Record<string, { field: string; kind: string }>> = Object.freeze({
+ "question-resolved": { field: "question", kind: "open-question" },
+ "milestone-done": { field: "milestone", kind: "milestone" },
+});
+
+/**
+ * The topic a `record` event is written under, after its item reference
+ * is checked against the caller's fold: an item named by a completion, or
+ * by an edit, must be an item of that topic of the right kind (a merged
+ * topic's item is written under the topic that owns it). Below local reach
+ * a record may not pick a new item id: the item would collide with one of
+ * a private record the caller cannot see. Every miss gives one message,
+ * so a hidden item and an absent one answer alike.
+ */
+function recordTopic(
+ fold: TopicFold,
+ topic: TopicState,
+ kind: string,
+ fields: Readonly<Record<string, unknown>>,
+ owner: string | undefined,
+): string {
+ for (const key of Object.keys(fields)) {
+ if (!(RECORD_FIELDS[kind] ?? []).includes(key)) {
+ throw new TopicActionError(`record: ${kind} takes no field '${key}'`);
+ }
+ }
+ const named = NAMED_ITEM[kind];
+ const field = named?.field ?? "item";
+ const want = named?.kind ?? kind;
+ const id = fields[field];
+ // `owner` names this topic or one merged into it; any other id (a typo,
+ // an unrelated topic, one the caller cannot see) is refused alike, with
+ // or without an item id.
+ if (owner !== undefined && owner !== topic.id && fold.canonical(owner) !== topic.id) {
+ throw new TopicActionError(
+ `record: owner ${owner} is not this topic or a topic merged into it (${topic.id})`,
+ );
+ }
+ if (id === undefined && named === undefined) return topic.id;
+ if (typeof id !== "string") throw new TopicActionError(`record: ${kind} needs '${field}'`);
+ // After a merge two owners can hold the same item id: `owner` says which.
+ const matches = topic.items.filter(
+ (i) => i.id === id && (owner === undefined || i.owner === owner),
+ );
+ if (matches.length > 1) {
+ throw new TopicActionError(
+ `record: item ${id} is on more than one merged topic; name its owner (${matches.map((i) => i.owner).join(", ")})`,
+ );
+ }
+ const item = matches[0];
+ if (item !== undefined && item.kind === want) return item.owner;
+ // A new item is never picked with `owner`: an owner names an item that exists.
+ if (item === undefined && named === undefined && owner === undefined && !privateWithheld()) {
+ // An id the topic once held still names that item after a split moved it.
+ if (fold.movedAway(topic.id, id)) {
+ throw new TopicActionError(
+ `record: item ${id} of topic ${topic.id} moved to another topic; pick another id`,
+ );
+ }
+ return topic.id;
+ }
+ throw new TopicActionError(`record: no ${want} item ${id} on topic ${topic.id}`);
+}
+
+/**
+ * The `split` records of a request. Each item listed must be one the
+ * topic shows, and it moves by a split written under the topic that owns
+ * it: an item of a topic merged into this one is that topic's own, which
+ * a split of this topic would not find. An id two merged owners share
+ * needs `owner`.
+ */
+function splitEvents(
+ fold: TopicFold,
+ topic: TopicState,
+ input: TopicActionInput,
+ into: string,
+ event: (topic: string, body: Record<string, unknown>) => TopicEvent,
+): TopicEvent[] {
+ const owner = input.owner;
+ if (owner !== undefined && owner !== topic.id && fold.canonical(owner) !== topic.id) {
+ throw new TopicActionError(
+ `split: owner ${owner} is not this topic or a topic merged into it (${topic.id})`,
+ );
+ }
+ const byOwner = new Map<string, string[]>([[topic.id, []]]);
+ for (const id of input.items ?? []) {
+ const matches = topic.items.filter(
+ (i) => i.id === id && (owner === undefined || i.owner === owner),
+ );
+ if (matches.length > 1) {
+ throw new TopicActionError(
+ `split: item ${id} is on more than one merged topic; name its owner (${matches.map((i) => i.owner).join(", ")})`,
+ );
+ }
+ if (matches[0] === undefined) {
+ throw new TopicActionError(`split: no item ${id} on topic ${topic.id}`);
+ }
+ byOwner.set(matches[0].owner, [...(byOwner.get(matches[0].owner) ?? []), id]);
+ }
+ const records = input.records !== undefined ? { records: input.records } : {};
+ const own = byOwner.get(topic.id)!;
+ // The named topic's split comes first and carries the records; a merged
+ // owner's split carries only its items.
+ return [
+ ...(own.length > 0 || input.records !== undefined || byOwner.size === 1
+ ? [
+ event(topic.id, {
+ into,
+ // A merged owner's items go in its own split; an empty list is invalid.
+ ...(own.length > 0 ? { items: own } : {}),
+ ...records,
+ }),
+ ]
+ : []),
+ ...[...byOwner]
+ .filter(([id]) => id !== topic.id)
+ .map(([id, items]) => event(id, { into, items })),
+ ];
+}
+
+/** The fence origin of topic text below local reach. */
+const TOPIC_TEXT_ORIGIN = "stored text: agent-authored (topic records)";
+
+/**
+ * Topic text as the caller of the work running now may be handed it:
+ * agent-written, so fenced below local reach as every other stored text an
+ * agent wrote; as is for a local caller.
+ */
+function delivered<T extends string | null>(text: T): T {
+ if (text === null || !privateWithheld()) return text;
+ return shapeStoredTextForDelivery(text, {
+ treatment: DELIVERY_TREATMENT.fenced,
+ origin: TOPIC_TEXT_ORIGIN,
+ }).text as T;
+}
+
+/** A topic head: what an agent gets for a topic without its body. */
+export function topicHead(topic: TopicState): Record<string, unknown> {
+ return {
+ id: topic.id,
+ title: delivered(topic.title),
+ description: delivered(topic.description),
+ status: topic.status,
+ ...(topic.resolved !== null ? { resolved: topic.resolved } : {}),
+ goal: delivered(topic.goal),
+ scope: delivered(topic.scope),
+ created_at: new Date(topic.createdAt).toISOString(),
+ updated_at: new Date(topic.updatedAt).toISOString(),
+ };
+}
+
+function topicDetail(topic: TopicState): Record<string, unknown> {
+ return {
+ ...topicHead(topic),
+ links: topic.links,
+ goal_proposals: topic.goalProposals.map((p) => ({
+ agent: p.agent,
+ goal: delivered(p.goal),
+ record: p.record,
+ })),
+ items: topic.items.map((i) => ({
+ id: i.id,
+ owner: i.owner,
+ kind: i.kind,
+ text: delivered(i.text),
+ ...(i.logClass !== undefined ? { class: i.logClass } : {}),
+ ...(i.reason !== undefined ? { reason: delivered(i.reason) } : {}),
+ ...(i.serves !== undefined ? { serves: i.serves } : {}),
+ authority: i.author.authority,
+ agent: i.author.agent,
+ created_at: new Date(i.createdAt).toISOString(),
+ ...(i.done !== undefined ? { done: new Date(i.done.at).toISOString() } : {}),
+ ...(i.doneProposed !== undefined ? { looks_done: true } : {}),
+ ...(i.resolved !== undefined ? { resolved: new Date(i.resolved.at).toISOString() } : {}),
+ })),
+ };
+}
+
+/** The topic `id` names after merges, if the caller can see it. */
+function visibleTopic(read: TopicRead, id: string): TopicState {
+ const canonical = read.fold.canonical(id);
+ const topic = canonical === null ? undefined : read.fold.topics.get(canonical);
+ if (topic === undefined) throw new TopicActionError(`no topic with id ${id}`);
+ return topic;
+}
+
+function shownMarkdown(read: TopicRead, topic: TopicState, configPath?: string): string {
+ const lang = sharedSetting(SETTING_VIEW_LANGUAGE, configPath);
+ const strings = viewStrings(typeof lang === "string" ? lang : null);
+ // A local caller sees its private topics too; below local reach the
+ // fold already holds none.
+ const pages = topicPages(read.storeId ?? "", read.fold, strings, {
+ includePrivate: !privateWithheld(),
+ });
+ const page = pages.find((p) => p.topic === topic.id && p.page.endsWith("/topic.md"));
+ const text = page === undefined ? "" : `${page.lines.map((l) => l.text).join("\n")}\n`;
+ // Topic text is written by agents: below local reach it is delivered
+ // fenced, as every other stored text that agents wrote.
+ if (!privateWithheld()) return text;
+ return shapeStoredTextForDelivery(text, {
+ treatment: DELIVERY_TREATMENT.fenced,
+ origin: TOPIC_TEXT_ORIGIN,
+ }).text;
+}
+
+function quietDays(configPath?: string): number {
+ return sharedSetting(SETTING_TOPIC_QUIET_DAYS, configPath) as number;
+}
+
+function listJson(fold: TopicFold, scope: string | undefined): Record<string, unknown>[] {
+ return [...fold.topics.values()]
+ .filter((t) => t.mergedInto === null && (scope === undefined || t.scope === scope))
+ .toSorted((a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : 1))
+ .map(topicHead);
+}
+
+/** The events of a write action, against what the caller can see. */
+function eventsOf(
+ input: TopicActionInput,
+ read: TopicRead,
+ now: number,
+ humanRequest: boolean,
+): TopicEvent[] {
+ const human = authorityOf(input, humanRequest ? "human" : "agent");
+ const event = (
+ kind: TopicRecordKind,
+ topic: string,
+ body: Record<string, unknown>,
+ ): TopicEvent => ({
+ kind,
+ topic,
+ authority: human,
+ body,
+ });
+ const topicId = (): string => visibleTopic(read, need(input, "topic")).id;
+ switch (input.action) {
+ case "create":
+ return [
+ createTopicEvent({
+ title: need(input, "title"),
+ scope: input.scope ?? TOPIC_PERSONAL_SCOPE,
+ authority: human,
+ ...(input.description !== undefined ? { description: input.description } : {}),
+ ...(input.goal !== undefined ? { goal: input.goal } : {}),
+ now,
+ }),
+ ];
+ case "rename":
+ return [
+ event(TOPIC_RENAME_KIND, topicId(), {
+ ...(input.title !== undefined ? { title: input.title } : {}),
+ ...(input.description !== undefined ? { description: input.description } : {}),
+ }),
+ ];
+ case "status":
+ return [
+ event(TOPIC_STATUS_KIND, topicId(), {
+ status: need(input, "status"),
+ ...(input.resolved !== undefined ? { resolved: input.resolved } : {}),
+ }),
+ ];
+ case "archive":
+ return [event(TOPIC_STATUS_KIND, topicId(), { status: "closed" })];
+ case "goal":
+ return [event(TOPIC_GOAL_KIND, topicId(), { goal: input.goal ?? null })];
+ case "assign":
+ return [event(TOPIC_ASSIGN_KIND, topicId(), { record: need(input, "record") })];
+ case "unassign":
+ return [event(TOPIC_UNASSIGN_KIND, topicId(), { record: need(input, "record") })];
+ case "merge": {
+ const into = visibleTopic(read, need(input, "into")).id;
+ return [event(TOPIC_MERGE_KIND, topicId(), { into })];
+ }
+ case "split": {
+ const into = visibleTopic(read, need(input, "into")).id;
+ const topic = visibleTopic(read, need(input, "topic"));
+ return splitEvents(read.fold, topic, input, into, (t, body) =>
+ event(TOPIC_SPLIT_KIND, t, body),
+ );
+ }
+ case "link": {
+ const to = visibleTopic(read, need(input, "to")).id;
+ return [
+ event(TOPIC_LINK_KIND, topicId(), {
+ to,
+ ...(input.removed === true ? { removed: true } : {}),
+ }),
+ ];
+ }
+ case "undo": {
+ const record = need(input, "record");
+ const topic = read.recordTopics.get(record);
+ // An undo names a topic record the caller can see; any other id is
+ // "no such record". Its topic may be gone (an undone create): undoing
+ // that undo brings the topic back.
+ if (topic === undefined) {
+ throw new TopicActionError(`no topic record with id ${record}`);
+ }
+ return [event(TOPIC_UNDO_KIND, topic, { record })];
+ }
+ case "record": {
+ const kind = need(input, "kind");
+ if (!(TOPIC_RECORD_ACTION_KINDS as ReadonlyArray<string>).includes(kind)) {
+ throw new TopicActionError(
+ `record: kind must be one of ${TOPIC_RECORD_ACTION_KINDS.join(", ")}`,
+ );
+ }
+ const fields = input.fields ?? {};
+ return [
+ {
+ kind: kind as TopicRecordKind,
+ topic: recordTopic(
+ read.fold,
+ visibleTopic(read, need(input, "topic")),
+ kind,
+ fields,
+ input.owner,
+ ),
+ authority: authorityOf(input, "agent"),
+ body: { ...fields },
+ },
+ ];
+ }
+ default:
+ throw new TopicActionError(`unknown action: ${input.action}`);
+ }
+}
+
+/** Run one topic action and return its JSON answer. */
+export function runTopicAction(
+ input: TopicActionInput,
+ context: TopicActionContext = {},
+): Record<string, unknown> {
+ if (!(TOPIC_ACTIONS as ReadonlyArray<string>).includes(input.action)) {
+ throw new TopicActionError(`action must be one of ${TOPIC_ACTIONS.join(", ")}`);
+ }
+ const now = (context.now ?? Date.now)();
+ const read = readTopics(context.configPath);
+ switch (input.action) {
+ case "list":
+ return { action: "list", topics: listJson(read.fold, input.listScope) };
+ case "show": {
+ const topic = visibleTopic(read, need(input, "topic"));
+ return {
+ action: "show",
+ topic: topicDetail(topic),
+ page: shownMarkdown(read, topic, context.configPath),
+ };
+ }
+ case "review": {
+ // A fold over a partial read may miss topics: no proposal is made from it.
+ if (read.unreadable.length > 0) {
+ return {
+ action: "review",
+ incomplete: true,
+ merges: [],
+ quiet: [],
+ ...(privateWithheld() ? {} : { unreadable: read.unreadable }),
+ };
+ }
+ const review = reviewTopics(read.fold, now, quietDays(context.configPath));
+ return {
+ action: "review",
+ merges: review.merges.map((m) => ({ topics: m.topics, score: m.score })),
+ quiet: review.quiet,
+ };
+ }
+ }
+ const events = eventsOf(input, read, now, context.humanRequest === true);
+ const written: AppendResult[] = writeTopicEvents(
+ events.map((e) => (context.agent !== undefined ? { ...e, agent: context.agent } : e)),
+ {
+ ...(context.configPath !== undefined ? { configPath: context.configPath } : {}),
+ ...(input.private !== undefined ? { private: input.private } : {}),
+ },
+ );
+ return {
+ action: input.action,
+ // A split answers the topic it names, also when a merged owner's split comes first.
+ topic:
+ input.action === "split" ? visibleTopic(read, need(input, "topic")).id : events[0]!.topic,
+ records: written.map((w) => w.record.id),
+ };
+}
diff --git a/src/core/topics/candidates.ts b/src/core/topics/candidates.ts
new file mode 100644
index 00000000..30df1908
--- /dev/null
+++ b/src/core/topics/candidates.ts
@@ -0,0 +1,128 @@
+/**
+ * The records topic planning groups into topics (design D9; task 3.4):
+ * captured signals and the log events a person would read (notes and
+ * decisions), each with its text, its project, its session and whether
+ * it is private.
+ *
+ * - **Project.** The `project` the record names (a signal's frontmatter,
+ * a log event's body), normalised as every scope key is
+ * (`scope-key.ts`); `null` when it names none.
+ * - **Session.** The `session` the record names, else its `session_ref`,
+ * else the device, agent and UTC day that wrote it: records of one
+ * agent on one machine on one day count as one session, so a single
+ * busy session never makes a topic on its own (spec "One busy session
+ * does not make a topic").
+ *
+ * A signal a `signal-removed` record forgot is left out. Pure.
+ */
+
+import { scopeFromFrontmatter } from "../scope-key.ts";
+import { LOG_EVENT_KIND, SIGNAL_KIND } from "../store/constants.ts";
+import type { StoreRecord } from "../store/envelope.ts";
+import { SIGNAL_REMOVED_KIND } from "../store/fold-signals.ts";
+import { parseHlc } from "../store/hlc.ts";
+import { valueCarriesPrivateRegion } from "../store/private-region.ts";
+
+/** Log event types whose text a person would read on a topic. */
+const READABLE_EVENTS: Readonly<Record<string, ReadonlyArray<string>>> = Object.freeze({
+ note: ["text"],
+ "decision-record": ["chosen", "decision"],
+ "decision-resolved": ["choice"],
+});
+
+export interface TopicCandidate {
+ readonly id: string;
+ readonly text: string;
+ /** The project the record names, or `null`. */
+ readonly project: string | null;
+ readonly session: string;
+ /** Physical clock of the record, in ms. */
+ readonly at: number;
+ readonly private: boolean;
+ /** The envelope `topic` the record was written under, or `null`. */
+ readonly topic: string | null;
+}
+
+function str(value: unknown): string | null {
+ return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+function obj(value: unknown): Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : {};
+}
+
+function fallbackSession(record: StoreRecord, at: number): string {
+ return `${record.device}/${record.agent}/${new Date(at).toISOString().slice(0, 10)}`;
+}
+
+function candidateOf(record: StoreRecord, isPrivate: boolean): TopicCandidate | null {
+ const at = parseHlc(record.hlc)!.physical;
+ let text: string | null = null;
+ let meta: Record<string, unknown> = {};
+ if (record.kind === SIGNAL_KIND) {
+ meta = obj(record.body["frontmatter"]);
+ text = str(meta["principle"]) ?? str(record.body["raw"]);
+ } else if (record.kind === LOG_EVENT_KIND) {
+ const type = String(record.body["event_type"]);
+ // Own keys only: `constructor` or `toString` must not resolve to Object's.
+ if (!Object.hasOwn(READABLE_EVENTS, type)) return null;
+ const fields = READABLE_EVENTS[type]!;
+ meta = obj(record.body["body"]);
+ text = fields.map((f) => str(meta[f])).find((t) => t !== null) ?? null;
+ }
+ if (text === null) return null;
+ const scope = scopeFromFrontmatter(meta);
+ return {
+ id: record.id,
+ text,
+ project: scope.project,
+ session: scope.session ?? str(meta["session_ref"]) ?? fallbackSession(record, at),
+ at,
+ private: isPrivate,
+ topic: record.topic,
+ };
+}
+
+/** The candidates among `records`; `privateIds` names those of the `private` partition. */
+export function topicCandidates(
+ records: ReadonlyArray<StoreRecord>,
+ privateIds: ReadonlySet<string>,
+): TopicCandidate[] {
+ const removed = new Set(
+ records.filter((r) => r.kind === SIGNAL_REMOVED_KIND).map((r) => String(r.body["signal"])),
+ );
+ const out: TopicCandidate[] = [];
+ for (const record of records) {
+ if (record.kind === SIGNAL_KIND && removed.has(String(record.body["id"]))) continue;
+ // A shared record that carries a `<private>` region (a legacy or
+ // foreign writer) counts as private: its text must not seed a shared topic.
+ const isPrivate = privateIds.has(record.id) || valueCarriesPrivateRegion(record.body);
+ const candidate = candidateOf(record, isPrivate);
+ if (candidate !== null) out.push(candidate);
+ }
+ return out;
+}
+
+/** Common words of no use for telling subjects apart. */
+const STOPWORDS: ReadonlySet<string> = new Set(
+ (
+ "about after again also always because been before being both could does doing done each " +
+ "even every from have having here into just like made make many more most much must never " +
+ "only other over same should since some such than that their them then there these they " +
+ "this those through under until very want were what when where which while will with " +
+ "within without would your"
+ ).split(" "),
+);
+
+/** The distinct words of `text` that can tell subjects apart, in any script. */
+export function subjectTokens(text: string): Set<string> {
+ return new Set(
+ text
+ .normalize("NFC")
+ .toLowerCase()
+ .split(/[^\p{L}\p{N}]+/u)
+ .filter((w) => [...w].length >= 4 && !STOPWORDS.has(w)),
+ );
+}
diff --git a/src/core/topics/constants.ts b/src/core/topics/constants.ts
new file mode 100644
index 00000000..b9499622
--- /dev/null
+++ b/src/core/topics/constants.ts
@@ -0,0 +1,122 @@
+/**
+ * Names of topics (design D8, spec `topics`): the one place that spells
+ * the topic record kinds, their statuses, log classes and scopes, so the
+ * fold, the writers, the view and the format document cannot drift apart.
+ *
+ * A topic is a record family with an immutable id (a ULID): every topic
+ * record carries that id in the envelope's `topic` field and is written to
+ * the `topics` stream. Display values (the title, the folder name of its
+ * page) change; the id never does.
+ */
+
+/** The stream every topic record is written to. */
+export const TOPIC_STREAM = "topics" as const;
+
+export const TOPIC_CREATE_KIND = "topic-create";
+export const TOPIC_RENAME_KIND = "topic-rename";
+export const TOPIC_STATUS_KIND = "topic-status";
+export const TOPIC_GOAL_KIND = "topic-goal";
+export const TOPIC_DECISION_KIND = "decision";
+export const TOPIC_QUESTION_KIND = "open-question";
+export const TOPIC_QUESTION_RESOLVED_KIND = "question-resolved";
+export const TOPIC_LOG_KIND = "log-entry";
+export const TOPIC_MILESTONE_KIND = "milestone";
+export const TOPIC_MILESTONE_DONE_KIND = "milestone-done";
+export const TOPIC_ASSIGN_KIND = "assign";
+export const TOPIC_UNASSIGN_KIND = "unassign";
+export const TOPIC_MERGE_KIND = "merge";
+export const TOPIC_SPLIT_KIND = "split";
+export const TOPIC_LINK_KIND = "link";
+export const TOPIC_UNDO_KIND = "undo";
+
+/** The canonical topic event list of design D8, in its order; FORMAT.md documents each. */
+export const TOPIC_RECORD_KINDS = Object.freeze([
+ TOPIC_CREATE_KIND,
+ TOPIC_RENAME_KIND,
+ TOPIC_STATUS_KIND,
+ TOPIC_GOAL_KIND,
+ TOPIC_DECISION_KIND,
+ TOPIC_QUESTION_KIND,
+ TOPIC_QUESTION_RESOLVED_KIND,
+ TOPIC_LOG_KIND,
+ TOPIC_MILESTONE_KIND,
+ TOPIC_MILESTONE_DONE_KIND,
+ TOPIC_ASSIGN_KIND,
+ TOPIC_UNASSIGN_KIND,
+ TOPIC_MERGE_KIND,
+ TOPIC_SPLIT_KIND,
+ TOPIC_LINK_KIND,
+ TOPIC_UNDO_KIND,
+] as const);
+export type TopicRecordKind = (typeof TOPIC_RECORD_KINDS)[number];
+
+/** The four kinds that carry a list item of a topic page. */
+export const TOPIC_ITEM_KINDS = Object.freeze([
+ TOPIC_DECISION_KIND,
+ TOPIC_QUESTION_KIND,
+ TOPIC_LOG_KIND,
+ TOPIC_MILESTONE_KIND,
+] as const);
+export type TopicItemKind = (typeof TOPIC_ITEM_KINDS)[number];
+
+/**
+ * Topic statuses as records spell them; the page shows each in the view
+ * language (`Active`, `Waiting`, `Blocked`, `On hold`, `Done`, `Closed`
+ * in English).
+ */
+export const TOPIC_STATUSES = Object.freeze([
+ "active",
+ "waiting",
+ "blocked",
+ "on-hold",
+ "done",
+ "closed",
+] as const);
+export type TopicStatus = (typeof TOPIC_STATUSES)[number];
+
+/** The status of a new topic. */
+export const TOPIC_DEFAULT_STATUS: TopicStatus = "active";
+
+/**
+ * Classes of a `log-entry`. Only the earned ones reach the topic page
+ * (spec "Log entries are earned"); `routine` progress stays in the store.
+ * `note` is a line the user wrote into the log section of the page.
+ */
+export const TOPIC_LOG_CLASSES = Object.freeze([
+ "correction",
+ "decision",
+ "blocker",
+ "reframing",
+ "rejected",
+ "note",
+ "routine",
+] as const);
+export type TopicLogClass = (typeof TOPIC_LOG_CLASSES)[number];
+
+/** The log classes the topic page shows. */
+export const TOPIC_EARNED_LOG_CLASSES: ReadonlySet<TopicLogClass> = new Set([
+ "correction",
+ "decision",
+ "blocker",
+ "reframing",
+ "rejected",
+ "note",
+]);
+
+/** The scope of a topic that belongs to no project. */
+export const TOPIC_PERSONAL_SCOPE = "personal";
+
+/** Prefix of a project scope: `project:<project>`. */
+export const TOPIC_PROJECT_SCOPE_PREFIX = "project:";
+
+/**
+ * The page budget of `topic.md` (spec "Page stays scannable"): at most
+ * this many entries of each section stay on the page. The oldest done
+ * milestones, decisions and log entries over it move to the companion
+ * archive page; open milestones and open questions never move.
+ */
+export const TOPIC_PAGE_BUDGET = Object.freeze({
+ doneMilestones: 10,
+ decisions: 25,
+ log: 15,
+});
diff --git a/src/core/topics/fold.ts b/src/core/topics/fold.ts
new file mode 100644
index 00000000..abbffc37
--- /dev/null
+++ b/src/core/topics/fold.ts
@@ -0,0 +1,685 @@
+/**
+ * The topic fold (design D4, D8; task 3.1): every topic, its fields, its
+ * list items, links, merges and record assignments, folded from topic
+ * records in any delivery order.
+ *
+ * Pure: no I/O, no clock, no model call. The same set of records folds to
+ * the same state on every machine (`prepareRecords` gives one canonical
+ * order), whatever order the shards arrived in and however often a line
+ * was delivered.
+ *
+ * Rules:
+ *
+ * - **Identity.** A topic is its id, the envelope `topic` of its records.
+ * It exists once a `topic-create` for that id is folded; its scope and
+ * creation time are those of the first create in fold order and never
+ * change. It starts active: the create offers no status, so an agent's
+ * status change applies to a topic the user created. A rename changes only the title (and description): every
+ * record keeps naming the same id, so no reference moves.
+ * - **Registers.** The title, description, goal and status of a topic,
+ * each list item, an item's owner, a milestone's completion, a
+ * question's resolution, a merge, a link and a record's assignment are
+ * each one register, resolved by authority, then clock (`RegisterSet`).
+ * An item record with `removed: true`, an `unassign` and a link with
+ * `removed: true` are tombstones.
+ * - **Proposals.** A goal offer that loses to a stronger authority and
+ * comes later than the winner is kept as a proposal (spec "User
+ * rewrites the goal": the page shows it as an open question). A
+ * `milestone-done` counts only from the user, or from an agent that
+ * cites `evidence`; any other one (a decision model, an agent without
+ * evidence) only proposes completion. A `question-resolved` from a
+ * decision model only proposes the resolution.
+ * - **Undo.** An `undo` voids the record it names, provided its authority
+ * is at least that record's; an undo can itself be undone. A voided
+ * record is folded as if it had never been written. An undo of an
+ * `assign` and an `unassign`, by the user or an agent (not by a decision
+ * model), also block that route, so a later automatic pass does not
+ * route the record to that topic again.
+ * - **Merges.** A merged topic resolves to the topic it merged into
+ * ({@link TopicFold.canonical}); its items show on that topic. Merges
+ * apply in fold order of their winning records, and one that would
+ * close a cycle, or names a topic that does not exist, is ignored.
+ * - **Splits.** A split moves the items and the record assignments it
+ * lists to another topic (the item's owner register, the assignment
+ * register).
+ *
+ * A record of a topic kind whose body is malformed is not applied and is
+ * reported in `rejected`.
+ */
+
+import { compareCodeUnits } from "../store/compare.ts";
+import { compareRecords, type StoreRecord } from "../store/envelope.ts";
+import {
+ prepareRecords,
+ recordAuthority,
+ RegisterSet,
+ TOMBSTONE,
+ type RegisterEntry,
+ type RejectedRecord,
+} from "../store/fold.ts";
+import type { Authority } from "../store/constants.ts";
+import { parseHlc } from "../store/hlc.ts";
+import {
+ TOPIC_ASSIGN_KIND,
+ TOPIC_CREATE_KIND,
+ TOPIC_DEFAULT_STATUS,
+ TOPIC_GOAL_KIND,
+ TOPIC_LINK_KIND,
+ TOPIC_MERGE_KIND,
+ TOPIC_MILESTONE_DONE_KIND,
+ TOPIC_QUESTION_RESOLVED_KIND,
+ TOPIC_RENAME_KIND,
+ TOPIC_SPLIT_KIND,
+ TOPIC_STATUS_KIND,
+ TOPIC_UNASSIGN_KIND,
+ TOPIC_UNDO_KIND,
+ type TopicItemKind,
+ type TopicLogClass,
+ type TopicStatus,
+} from "./constants.ts";
+import { isTopicItemKind, isTopicRecordKind, topicBodyRejection } from "./records.ts";
+import { voidedRecords } from "./undo-fold.ts";
+
+/** Who wrote a record, for attribution on the page. */
+export interface TopicAuthor {
+ readonly record: string;
+ readonly agent: string;
+ readonly authority: Authority;
+ /** Physical clock of the record, in ms. */
+ readonly at: number;
+}
+
+export interface TopicItem {
+ readonly id: string;
+ readonly kind: TopicItemKind;
+ /** The topic that owns the item now (before merges resolve; see {@link TopicFold.canonical}). */
+ readonly owner: string;
+ readonly text: string;
+ readonly logClass?: TopicLogClass;
+ readonly reason?: string;
+ readonly serves?: ReadonlyArray<string>;
+ /** The record whose value is shown. */
+ readonly author: TopicAuthor;
+ /** When the item was first recorded, in ms. */
+ readonly createdAt: number;
+ /** A milestone marked done by the user, or by an agent that cited evidence. */
+ readonly done?: TopicAuthor & { readonly evidence: string | null };
+ /** A completion proposed without that standing (spec: "looks done, confirm"). */
+ readonly doneProposed?: TopicAuthor;
+ readonly resolved?: TopicAuthor & { readonly answer: string | null };
+ readonly resolveProposed?: TopicAuthor;
+ /** Whether any record of the item, its completions and resolutions included, sits in `private`. */
+ readonly private: boolean;
+}
+
+export interface GoalProposal extends TopicAuthor {
+ readonly goal: string;
+}
+
+export interface TopicState {
+ readonly id: string;
+ readonly title: string;
+ readonly description: string | null;
+ readonly goal: string | null;
+ readonly goalProposals: ReadonlyArray<GoalProposal>;
+ readonly status: TopicStatus;
+ /** `YYYY-MM-DD` the topic was resolved, for `done` (the record's day when none was given). */
+ readonly resolved: string | null;
+ readonly scope: string;
+ /** Physical clock of the first `topic-create`, in ms. */
+ readonly createdAt: number;
+ /** Physical clock of the latest record of the topic, in ms. */
+ readonly updatedAt: number;
+ /** The topic this one merged into, or `null`. */
+ readonly mergedInto: string | null;
+ /** Topics linked to this one, in id order. */
+ readonly links: ReadonlyArray<string>;
+ /** Items this topic owns, merged topics' items included, in fold order of their first record. */
+ readonly items: ReadonlyArray<TopicItem>;
+ /** Whether the topic's first `topic-create` sits in the `private` partition. */
+ readonly private: boolean;
+ /**
+ * Per head field, whether the record whose value is shown sits in the
+ * `private` partition: a shared topic can carry a private rename or goal.
+ */
+ readonly privateFields: Readonly<Record<TopicHeadField, boolean>>;
+}
+
+/** The head fields of a topic whose winning record can be private on its own. */
+export type TopicHeadField = "title" | "description" | "goal";
+
+export interface TopicFold {
+ /** Every existing topic by id, merged ones included. */
+ readonly topics: ReadonlyMap<string, TopicState>;
+ /** The topic `id` resolves to after merges, or `null` when it does not exist. */
+ canonical(id: string): string | null;
+ /**
+ * Explicit assignments: record id to the canonical topic it was assigned
+ * to, or `null` when it was unassigned (or its topic no longer exists).
+ */
+ readonly assignments: ReadonlyMap<string, string | null>;
+ /**
+ * Routes the user took back: `<record id>\u0000<topic id>`, each also
+ * under the topic its topic merged into.
+ */
+ readonly blockedRoutes: ReadonlySet<string>;
+ /** Records an `undo` voided. */
+ readonly voided: ReadonlySet<string>;
+ /**
+ * Whether `topic` first recorded an item `item` that a split has since
+ * moved to another topic: the id still names that item there, so a new
+ * item of `topic` must take another id. A removed item stays the
+ * topic's, and its id can be recorded again.
+ */
+ movedAway(topic: string, item: string): boolean;
+ /**
+ * Records any `assign`, `unassign` or `split` named, voided ones
+ * included: material a topic once held. Automatic planning routes such a
+ * record but never builds a new topic from it, so a topic the user undid
+ * is not created again from the same records.
+ */
+ readonly touched: ReadonlySet<string>;
+ readonly rejected: ReadonlyArray<RejectedRecord>;
+}
+
+export interface FoldTopicsOptions {
+ /** Ids of the records that sit in the `private` partition. */
+ readonly privateIds?: ReadonlySet<string>;
+}
+
+/** The key of a blocked route. */
+export function routeKey(record: string, topic: string): string {
+ return `${record}\u0000${topic}`;
+}
+
+function physical(record: StoreRecord): number {
+ return parseHlc(record.hlc)!.physical;
+}
+
+function authorOf(record: StoreRecord): TopicAuthor {
+ return {
+ record: record.id,
+ agent: record.agent,
+ authority: recordAuthority(record)!,
+ at: physical(record),
+ };
+}
+
+function dayOf(ms: number): string {
+ return new Date(ms).toISOString().slice(0, 10);
+}
+
+interface ItemValue {
+ readonly kind: TopicItemKind;
+ readonly text: string;
+ readonly logClass?: TopicLogClass;
+ readonly reason?: string;
+ readonly serves?: ReadonlyArray<string>;
+}
+
+interface Registers {
+ readonly title: RegisterSet<string>;
+ readonly description: RegisterSet<string | null>;
+ readonly goal: RegisterSet<string | null>;
+ readonly status: RegisterSet<{ status: TopicStatus; resolved: string | null }>;
+ readonly merge: RegisterSet<string>;
+ readonly link: RegisterSet<true>;
+ readonly item: RegisterSet<ItemValue>;
+ readonly owner: RegisterSet<string>;
+ readonly done: RegisterSet<string | null>;
+ readonly resolved: RegisterSet<string | null>;
+ readonly assign: RegisterSet<string>;
+}
+
+function newRegisters(): Registers {
+ return {
+ title: new RegisterSet(),
+ description: new RegisterSet(),
+ goal: new RegisterSet(),
+ status: new RegisterSet(),
+ merge: new RegisterSet(),
+ link: new RegisterSet(),
+ item: new RegisterSet(),
+ owner: new RegisterSet(),
+ done: new RegisterSet(),
+ resolved: new RegisterSet(),
+ assign: new RegisterSet(),
+ };
+}
+
+function entry<V>(record: StoreRecord, value: V | typeof TOMBSTONE): RegisterEntry<V> {
+ return { record, authority: recordAuthority(record)!, value };
+}
+
+function linkKey(a: string, b: string): string {
+ return a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+}
+
+interface Scratch {
+ readonly regs: Registers;
+ readonly creates: Map<string, StoreRecord>;
+ /** Item register key (`<first topic>\u0000<item id>`) to the item's first record. */
+ readonly itemFirst: Map<string, StoreRecord>;
+ /** Item id to its register keys, in the order they were first seen. */
+ readonly itemKeys: Map<string, string[]>;
+ readonly itemRecords: Map<string, string[]>;
+ readonly doneProposals: Map<string, StoreRecord>;
+ readonly resolveProposals: Map<string, StoreRecord>;
+ readonly updated: Map<string, number>;
+ readonly blocked: Set<string>;
+ readonly rejected: RejectedRecord[];
+}
+
+/**
+ * The register key of item `item` as topic `topic` names it: an item id
+ * is a topic's own, never global, so two topics that pick the same token
+ * hold two items. The key is the topic that first recorded the item and
+ * the id; a topic the item was split into finds it by its current owner.
+ * `null` when the topic holds no such item yet.
+ */
+function itemKeyFor(s: Scratch, topic: string, item: string): string | null {
+ const own = `${topic}\u0000${item}`;
+ if (s.itemFirst.has(own)) return own;
+ return (s.itemKeys.get(item) ?? []).find((k) => s.regs.owner.get(k)?.value === topic) ?? null;
+}
+
+function applyItem(s: Scratch, record: StoreRecord): void {
+ const kind = record.kind as TopicItemKind;
+ const id = typeof record.body["item"] === "string" ? record.body["item"] : record.id;
+ const known = itemKeyFor(s, record.topic!, id);
+ const item = known ?? `${record.topic!}\u0000${id}`;
+ const first = s.itemFirst.get(item);
+ if (first !== undefined && first.kind !== kind) {
+ s.rejected.push({ id: record.id, kind, reason: `item ${id} is a ${first.kind}` });
+ return;
+ }
+ if (first === undefined) {
+ s.itemFirst.set(item, record);
+ s.itemKeys.set(id, [...(s.itemKeys.get(id) ?? []), item]);
+ s.regs.owner.offer(item, entry(record, record.topic!));
+ }
+ s.itemRecords.set(item, [...(s.itemRecords.get(item) ?? []), record.id]);
+ if (record.body["removed"] === true) {
+ s.regs.item.offer(item, entry<ItemValue>(record, TOMBSTONE));
+ return;
+ }
+ const body = record.body;
+ // A decision record that leaves `serves` out (a reworded page line)
+ // keeps the links the item has; `"serves": []` clears them.
+ const prior = s.regs.item.get(item);
+ const serves = Array.isArray(body["serves"])
+ ? (body["serves"] as string[])
+ : prior !== undefined && !prior.removed
+ ? prior.value!.serves
+ : undefined;
+ const value: ItemValue = {
+ kind,
+ text: body["text"] as string,
+ ...(typeof body["class"] === "string" ? { logClass: body["class"] as TopicLogClass } : {}),
+ ...(typeof body["reason"] === "string" ? { reason: body["reason"] } : {}),
+ ...(serves !== undefined ? { serves } : {}),
+ };
+ s.regs.item.offer(item, entry(record, value));
+}
+
+function applyRecord(s: Scratch, record: StoreRecord): void {
+ const topic = record.topic!;
+ const body = record.body;
+ const authority = recordAuthority(record)!;
+ s.updated.set(topic, Math.max(s.updated.get(topic) ?? 0, physical(record)));
+ if (isTopicItemKind(record.kind)) {
+ applyItem(s, record);
+ return;
+ }
+ switch (record.kind) {
+ case TOPIC_CREATE_KIND:
+ if (!s.creates.has(topic)) s.creates.set(topic, record);
+ s.regs.title.offer(topic, entry(record, body["title"] as string));
+ if (body["description"] !== undefined) {
+ s.regs.description.offer(topic, entry(record, body["description"] as string | null));
+ }
+ if (body["goal"] !== undefined) {
+ s.regs.goal.offer(topic, entry(record, body["goal"] as string | null));
+ }
+ return;
+ case TOPIC_RENAME_KIND:
+ if (body["title"] !== undefined)
+ s.regs.title.offer(topic, entry(record, body["title"] as string));
+ if (body["description"] !== undefined) {
+ s.regs.description.offer(topic, entry(record, body["description"] as string | null));
+ }
+ return;
+ case TOPIC_STATUS_KIND: {
+ const status = body["status"] as TopicStatus;
+ const resolved =
+ status === "done"
+ ? ((body["resolved"] as string | undefined) ?? dayOf(physical(record)))
+ : null;
+ s.regs.status.offer(topic, entry(record, { status, resolved }));
+ return;
+ }
+ case TOPIC_GOAL_KIND:
+ s.regs.goal.offer(topic, entry(record, body["goal"] as string | null));
+ return;
+ case TOPIC_MILESTONE_DONE_KIND: {
+ const id = body["milestone"] as string;
+ const milestone = itemKeyFor(s, topic, id) ?? `${topic}\u0000${id}`;
+ const evidence = typeof body["evidence"] === "string" ? body["evidence"] : null;
+ // A completion counts for the item's privacy: its evidence is its text.
+ s.itemRecords.set(milestone, [...(s.itemRecords.get(milestone) ?? []), record.id]);
+ if (authority === "human" || (authority === "agent" && evidence !== null)) {
+ s.regs.done.offer(milestone, entry(record, evidence));
+ } else {
+ s.doneProposals.set(milestone, record);
+ }
+ return;
+ }
+ case TOPIC_QUESTION_RESOLVED_KIND: {
+ const id = body["question"] as string;
+ const question = itemKeyFor(s, topic, id) ?? `${topic}\u0000${id}`;
+ const answer = typeof body["answer"] === "string" ? body["answer"] : null;
+ // A resolution counts for the item's privacy: its answer is its text.
+ s.itemRecords.set(question, [...(s.itemRecords.get(question) ?? []), record.id]);
+ if (authority === "model") s.resolveProposals.set(question, record);
+ else s.regs.resolved.offer(question, entry(record, answer));
+ return;
+ }
+ case TOPIC_ASSIGN_KIND:
+ s.regs.assign.offer(body["record"] as string, entry(record, topic));
+ return;
+ case TOPIC_UNASSIGN_KIND:
+ s.regs.assign.offer(body["record"] as string, entry<string>(record, TOMBSTONE));
+ // Taking a route back is the signal, whoever writes it: only a
+ // decision model's unassign leaves the route open.
+ if (authority !== "model") s.blocked.add(routeKey(body["record"] as string, topic));
+ return;
+ case TOPIC_MERGE_KIND:
+ s.regs.merge.offer(topic, entry(record, body["into"] as string));
+ return;
+ case TOPIC_SPLIT_KIND:
+ // The topic that receives items or records has news too.
+ s.updated.set(
+ body["into"] as string,
+ Math.max(s.updated.get(body["into"] as string) ?? 0, physical(record)),
+ );
+ for (const id of (body["items"] as string[] | undefined) ?? []) {
+ const item = itemKeyFor(s, topic, id);
+ if (item !== null) s.regs.owner.offer(item, entry(record, body["into"] as string));
+ }
+ for (const id of (body["records"] as string[] | undefined) ?? []) {
+ s.regs.assign.offer(id, entry(record, body["into"] as string));
+ }
+ return;
+ case TOPIC_LINK_KIND:
+ s.regs.link.offer(
+ linkKey(topic, body["to"] as string),
+ entry<true>(record, body["removed"] === true ? TOMBSTONE : true),
+ );
+ return;
+ }
+}
+
+/** Fold topic records (any order, duplicates allowed); records of other kinds are ignored. */
+export function foldTopics(
+ input: Iterable<StoreRecord>,
+ options: FoldTopicsOptions = {},
+): TopicFold {
+ const privateIds = options.privateIds ?? new Set<string>();
+ const { records } = prepareRecords(input);
+ const s: Scratch = {
+ regs: newRegisters(),
+ creates: new Map(),
+ itemFirst: new Map(),
+ itemKeys: new Map(),
+ itemRecords: new Map(),
+ doneProposals: new Map(),
+ resolveProposals: new Map(),
+ updated: new Map(),
+ blocked: new Set(),
+ rejected: [],
+ };
+ const valid: StoreRecord[] = [];
+ for (const record of records) {
+ if (!isTopicRecordKind(record.kind)) continue;
+ const reason = topicBodyRejection(record.kind, record.topic, record.body);
+ if (reason === null) valid.push(record);
+ else s.rejected.push({ id: record.id, kind: record.kind, reason });
+ }
+ const voided = voidedRecords(valid);
+ const routeUndone = new Set(
+ valid
+ .filter(
+ (u) => u.kind === TOPIC_UNDO_KIND && !voided.has(u.id) && u.body["authority"] !== "model",
+ )
+ .map((u) => u.body["record"] as string),
+ );
+ for (const record of valid) {
+ if (voided.has(record.id)) {
+ // A route taken back (by the user or an agent, never by a decision
+ // model): no automatic pass routes it there again.
+ if (record.kind === TOPIC_ASSIGN_KIND && routeUndone.has(record.id)) {
+ s.blocked.add(routeKey(record.body["record"] as string, record.topic!));
+ }
+ continue;
+ }
+ if (record.kind !== TOPIC_UNDO_KIND) applyRecord(s, record);
+ }
+ const touched = new Set<string>();
+ for (const record of valid) {
+ if (record.kind === TOPIC_ASSIGN_KIND || record.kind === TOPIC_UNASSIGN_KIND) {
+ touched.add(record.body["record"] as string);
+ } else if (record.kind === TOPIC_SPLIT_KIND) {
+ for (const id of (record.body["records"] as string[] | undefined) ?? []) touched.add(id);
+ }
+ }
+ return { ...assemble(s, voided, privateIds), touched };
+}
+
+function canonicalResolver(s: Scratch): (id: string) => string | null {
+ const edges = new Map<string, string>();
+ const winners = s.regs.merge
+ .keys()
+ .map((source) => ({ source, state: s.regs.merge.get(source)! }))
+ .filter(({ state }) => !state.removed)
+ .toSorted((a, b) => compareRecords(a.state.winner.record, b.state.winner.record));
+ const resolve = (id: string): string => {
+ let at = id;
+ const seen = new Set<string>();
+ while (edges.has(at) && !seen.has(at)) {
+ seen.add(at);
+ at = edges.get(at)!;
+ }
+ return at;
+ };
+ for (const { source, state } of winners) {
+ const into = state.value!;
+ if (!s.creates.has(source) || !s.creates.has(into)) continue;
+ if (resolve(into) === source) continue; // would close a cycle
+ edges.set(source, into);
+ }
+ return (id) => (s.creates.has(id) ? resolve(id) : null);
+}
+
+function goalProposals(s: Scratch, topic: string): GoalProposal[] {
+ const state = s.regs.goal.get(topic);
+ if (state === undefined) return [];
+ const winnerAt = state.history.indexOf(state.winner);
+ const out: GoalProposal[] = [];
+ for (const offer of state.history.slice(winnerAt + 1)) {
+ const goal = offer.value;
+ if (typeof goal !== "string" || goal === state.value) continue;
+ if (out.some((p) => p.goal === goal)) continue;
+ out.push({ ...authorOf(offer.record), goal });
+ }
+ return out;
+}
+
+function buildItem(
+ s: Scratch,
+ key: string,
+ owner: string,
+ privateIds: ReadonlySet<string>,
+): TopicItem | null {
+ const id = key.slice(key.indexOf("\u0000") + 1);
+ const state = s.regs.item.get(key);
+ if (state === undefined || state.removed) return null;
+ const value = state.value!;
+ const first = s.itemFirst.get(key)!;
+ const done = s.regs.done.get(key);
+ const resolved = s.regs.resolved.get(key);
+ const proposedDone = s.doneProposals.get(key);
+ const proposedResolve = s.resolveProposals.get(key);
+ const isMilestone = value.kind === "milestone";
+ const isQuestion = value.kind === "open-question";
+ return {
+ id,
+ kind: value.kind,
+ owner,
+ text: value.text,
+ ...(value.logClass !== undefined ? { logClass: value.logClass } : {}),
+ ...(value.reason !== undefined ? { reason: value.reason } : {}),
+ ...(value.serves !== undefined ? { serves: value.serves } : {}),
+ author: authorOf(state.winner.record),
+ createdAt: physical(first),
+ ...(isMilestone && done !== undefined
+ ? { done: { ...authorOf(done.winner.record), evidence: done.value } }
+ : {}),
+ ...(isMilestone && done === undefined && proposedDone !== undefined
+ ? { doneProposed: authorOf(proposedDone) }
+ : {}),
+ ...(isQuestion && resolved !== undefined
+ ? { resolved: { ...authorOf(resolved.winner.record), answer: resolved.value } }
+ : {}),
+ ...(isQuestion && resolved === undefined && proposedResolve !== undefined
+ ? { resolveProposed: authorOf(proposedResolve) }
+ : {}),
+ private: (s.itemRecords.get(key) ?? []).some((r) => privateIds.has(r)),
+ };
+}
+
+/**
+ * The routes taken back, each also under the topic its topic resolves to
+ * now: a route back from a topic later merged away still keeps the record
+ * from the topic that shows the merged one's material.
+ */
+function blockedThroughMerges(
+ blocked: ReadonlySet<string>,
+ canonical: (id: string) => string | null,
+): Set<string> {
+ const out = new Set(blocked);
+ for (const key of blocked) {
+ const [record, topic] = key.split("\u0000") as [string, string];
+ const home = canonical(topic);
+ if (home !== null && home !== topic) out.add(routeKey(record, home));
+ }
+ return out;
+}
+
+function assemble(
+ s: Scratch,
+ voided: Set<string>,
+ privateIds: ReadonlySet<string>,
+): Omit<TopicFold, "touched"> {
+ const canonical = canonicalResolver(s);
+ const items = new Map<string, TopicItem[]>();
+ // A topic's activity includes that of the topics merged into it, whose
+ // items it shows (an edit of such an item is written under its owner).
+ const activity = new Map<string, number>();
+ for (const [id, create] of s.creates) {
+ const home = canonical(id)!;
+ const at = s.updated.get(id) ?? physical(create);
+ activity.set(home, Math.max(activity.get(home) ?? 0, at));
+ }
+ const ordered = [...s.itemFirst.entries()].toSorted(([, a], [, b]) => compareRecords(a, b));
+ for (const [id] of ordered) {
+ const owner = s.regs.owner.get(id)!.value!;
+ const home = canonical(owner);
+ if (home === null) continue;
+ const item = buildItem(s, id, owner, privateIds);
+ if (item !== null) items.set(home, [...(items.get(home) ?? []), item]);
+ }
+ const links = new Map<string, string[]>();
+ for (const key of s.regs.link.keys()) {
+ if (s.regs.link.get(key)!.removed) continue;
+ const [a, b] = key.split("\u0000") as [string, string];
+ if (!s.creates.has(a) || !s.creates.has(b)) continue;
+ links.set(a, [...(links.get(a) ?? []), b]);
+ links.set(b, [...(links.get(b) ?? []), a]);
+ }
+ const topics = new Map<string, TopicState>();
+ const winnerPrivate = (reg: RegisterSet<unknown>, id: string): boolean => {
+ const state = reg.get(id);
+ return state !== undefined && privateIds.has(state.winner.record.id);
+ };
+ for (const [id, create] of s.creates) {
+ // A topic starts active; the create does not claim the status, so the
+ // first `topic-status` of any authority applies (a later human one wins).
+ const status = s.regs.status.get(id)?.value ?? { status: TOPIC_DEFAULT_STATUS, resolved: null };
+ const home = canonical(id)!;
+ topics.set(id, {
+ id,
+ title: s.regs.title.get(id)!.value!,
+ description: s.regs.description.get(id)?.value ?? null,
+ goal: s.regs.goal.get(id)?.value ?? null,
+ goalProposals: goalProposals(s, id),
+ status: status.status,
+ resolved: status.resolved,
+ scope: create.body["scope"] as string,
+ createdAt: physical(create),
+ updatedAt: home === id ? activity.get(id)! : (s.updated.get(id) ?? physical(create)),
+ mergedInto: home === id ? null : home,
+ links: (links.get(id) ?? []).toSorted(),
+ items: home === id ? (items.get(id) ?? []) : [],
+ private: privateIds.has(create.id),
+ privateFields: {
+ title: winnerPrivate(s.regs.title, id),
+ description: winnerPrivate(s.regs.description, id),
+ goal: winnerPrivate(s.regs.goal, id),
+ },
+ });
+ }
+ const assignments = new Map<string, string | null>();
+ for (const record of s.regs.assign.keys()) {
+ const state = s.regs.assign.get(record)!;
+ assignments.set(record, state.removed ? null : canonical(state.value!));
+ }
+ return {
+ topics,
+ canonical,
+ assignments,
+ blockedRoutes: blockedThroughMerges(s.blocked, canonical),
+ voided,
+ movedAway: (topic, item) => {
+ const key = `${topic}\u0000${item}`;
+ return s.itemFirst.has(key) && s.regs.owner.get(key)?.value !== topic;
+ },
+ rejected: s.rejected,
+ };
+}
+
+/**
+ * The canonical topic a record belongs to: its explicit assignment, else
+ * the topic its envelope names; `null` when neither names an existing
+ * topic. A topic record itself belongs to the topic it names.
+ */
+export function topicOfRecord(fold: TopicFold, record: StoreRecord): string | null {
+ if (!isTopicRecordKind(record.kind)) {
+ if (fold.assignments.has(record.id)) return fold.assignments.get(record.id)!;
+ }
+ return record.topic === null ? null : fold.canonical(record.topic);
+}
+
+/**
+ * The resolved state of a topic fold as plain JSON, for the state digests
+ * (design D6): two machines whose cuts hold the same topic records give
+ * the same fingerprint.
+ */
+export function topicsFingerprint(fold: TopicFold): unknown {
+ return {
+ topics: [...fold.topics.values()].toSorted((a, b) => compareCodeUnits(a.id, b.id)),
+ assignments: [...fold.assignments].toSorted(([a], [b]) => compareCodeUnits(a, b)),
+ blocked: [...fold.blockedRoutes].toSorted(compareCodeUnits),
+ voided: [...fold.voided].toSorted(compareCodeUnits),
+ rejected: fold.rejected.map((r) => r.id),
+ };
+}
diff --git a/src/core/topics/plan.ts b/src/core/topics/plan.ts
new file mode 100644
index 00000000..5492f52e
--- /dev/null
+++ b/src/core/topics/plan.ts
@@ -0,0 +1,288 @@
+/**
+ * Topic planning (design D9; spec `topics` "Automatic grouping during
+ * dream", "Merges and splits are proposed", "Topic status lifecycle";
+ * task 3.4): the pure decision of what the dream pass does with the
+ * records no topic holds yet. No I/O and no model call: the same fold and
+ * candidates give the same plan on every machine, and the deterministic
+ * fallbacks of design D10 are the whole rule here.
+ *
+ * - **Route.** An unassigned record of a project goes to the active
+ * topic of that project whose head (title, description, goal and item
+ * texts) shares the most subject words with it: at least two words and
+ * a fifth of the record's, the earlier topic on a tie. A route the user
+ * took back (`blockedRoutes`) is never taken again. A record with no
+ * project goes only to a personal topic.
+ * - **Create.** The records of one project that no topic holds and none
+ * ever held (`touched`) are grouped by shared subject words; a group of
+ * at least `minRecords` records from at least `minSessions` sessions
+ * becomes a topic, titled by its most frequent words, its goal drafted
+ * from its first record, and every record of it assigned. Records with
+ * no project never make a topic on their own; a personal topic is made
+ * on request.
+ * - **Propose.** Two active topics of one scope whose heads share half
+ * their words are proposed for a merge; a topic whose records fall into
+ * two groups that would each make a topic is proposed for a split.
+ * Nothing proposed is applied.
+ * - **Ask.** An active topic with no record for `quietDays` is offered to
+ * the user for a status decision; its status does not change.
+ */
+
+import { compareCodeUnits } from "../store/compare.ts";
+import { DAY_MS } from "../store/constants.ts";
+import { TOPIC_PERSONAL_SCOPE, TOPIC_PROJECT_SCOPE_PREFIX } from "./constants.ts";
+import { subjectTokens, type TopicCandidate } from "./candidates.ts";
+import { TOPIC_TITLE_MAX } from "./records.ts";
+import { routeKey, type TopicFold, type TopicHeadField, type TopicState } from "./fold.ts";
+
+/** At least this many shared subject words route a record or join it to a group. */
+const MIN_SHARED = 2;
+/** And at least this share of the record's words. */
+const MIN_ROUTE_SHARE = 0.2;
+/** Two topic heads that share this much (Jaccard) are proposed for a merge. */
+const MERGE_JACCARD = 0.5;
+/** Words in a drafted title. */
+const TITLE_WORDS = 3;
+/** Longest drafted goal, in characters. */
+const GOAL_MAX = 200;
+
+export interface PlanSettings {
+ readonly minRecords: number;
+ readonly minSessions: number;
+ readonly quietDays: number;
+}
+
+export interface PlannedRoute {
+ readonly record: string;
+ readonly topic: string;
+ readonly private: boolean;
+}
+
+export interface PlannedCreate {
+ readonly title: string;
+ readonly goal: string;
+ readonly scope: string;
+ readonly private: boolean;
+ /** Record ids the topic is made from, in record order. */
+ readonly members: ReadonlyArray<string>;
+ readonly sessions: number;
+}
+
+export interface MergeProposal {
+ readonly topics: readonly [string, string];
+ readonly score: number;
+}
+
+export interface SplitProposal {
+ readonly topic: string;
+ readonly groups: ReadonlyArray<ReadonlyArray<string>>;
+}
+
+export interface QuietPrompt {
+ readonly topic: string;
+ readonly days: number;
+}
+
+export interface TopicReview {
+ readonly merges: ReadonlyArray<MergeProposal>;
+ readonly quiet: ReadonlyArray<QuietPrompt>;
+}
+
+export interface TopicPlan extends TopicReview {
+ readonly routes: ReadonlyArray<PlannedRoute>;
+ readonly creates: ReadonlyArray<PlannedCreate>;
+ readonly splits: ReadonlyArray<SplitProposal>;
+}
+
+const isActive = (t: TopicState): boolean => t.mergedInto === null && t.status === "active";
+
+/**
+ * The subject words of a topic's head. Private text decides only a route
+ * that lands in `private` (a private record, or a private topic): a
+ * private item, or a title, description or goal whose winning record is
+ * private, would otherwise let private words pull a shared record into a
+ * topic by a shared assign.
+ */
+function headTokens(topic: TopicState, withPrivate: boolean): Set<string> {
+ const field = (name: TopicHeadField, value: string | null): string =>
+ topic.privateFields[name] && !withPrivate ? "" : (value ?? "");
+ const parts = [
+ field("title", topic.title),
+ field("description", topic.description),
+ field("goal", topic.goal),
+ ...topic.items.filter((i) => withPrivate || !i.private).map((i) => i.text),
+ ];
+ return subjectTokens(parts.join(" "));
+}
+
+function shared(a: ReadonlySet<string>, b: ReadonlySet<string>): number {
+ let n = 0;
+ for (const w of a) if (b.has(w)) n++;
+ return n;
+}
+
+function scopeOf(candidate: TopicCandidate): string {
+ return candidate.project === null
+ ? TOPIC_PERSONAL_SCOPE
+ : `${TOPIC_PROJECT_SCOPE_PREFIX}${candidate.project}`;
+}
+
+/** The canonical topic that holds `candidate`, or `null`. */
+function holder(fold: TopicFold, candidate: TopicCandidate): string | null {
+ if (fold.assignments.has(candidate.id)) return fold.assignments.get(candidate.id)!;
+ return candidate.topic === null ? null : fold.canonical(candidate.topic);
+}
+
+function bestTopic(
+ fold: TopicFold,
+ candidate: TopicCandidate,
+ topics: ReadonlyArray<{ topic: TopicState; tokens: Set<string>; all: Set<string> }>,
+): string | null {
+ const words = subjectTokens(candidate.text);
+ if (words.size === 0) return null;
+ let best: { id: string; score: number } | null = null;
+ for (const { topic, tokens, all } of topics) {
+ if (topic.scope !== scopeOf(candidate)) continue;
+ if (fold.blockedRoutes.has(routeKey(candidate.id, topic.id))) continue;
+ // Such a route is written to `private`: private words may decide it.
+ const n = shared(words, candidate.private || topic.private ? all : tokens);
+ if (n < MIN_SHARED || n / words.size < MIN_ROUTE_SHARE) continue;
+ if (best === null || n > best.score) best = { id: topic.id, score: n };
+ }
+ return best?.id ?? null;
+}
+
+interface Group {
+ readonly members: TopicCandidate[];
+ readonly words: Map<string, number>;
+}
+
+/** Greedy grouping by shared subject words, in record order: deterministic. */
+function groups(candidates: ReadonlyArray<TopicCandidate>): Group[] {
+ const out: Group[] = [];
+ for (const candidate of candidates) {
+ const words = subjectTokens(candidate.text);
+ const home = out.find((g) => shared(words, new Set(g.words.keys())) >= MIN_SHARED);
+ const group = home ?? { members: [], words: new Map<string, number>() };
+ if (home === undefined) out.push(group);
+ group.members.push(candidate);
+ for (const w of words) group.words.set(w, (group.words.get(w) ?? 0) + 1);
+ }
+ return out;
+}
+
+function qualifies(group: Group, settings: PlanSettings): boolean {
+ return (
+ group.members.length >= settings.minRecords &&
+ new Set(group.members.map((m) => m.session)).size >= settings.minSessions
+ );
+}
+
+/** The group's most frequent words, a tie going to the word its first record says first. */
+function draftTitle(group: Group): string {
+ const first = [...subjectTokens(group.members[0]!.text)];
+ const rank = (w: string): number => (first.includes(w) ? first.indexOf(w) : first.length);
+ const words = [...group.words]
+ .toSorted(([a, na], [b, nb]) => nb - na || rank(a) - rank(b) || compareCodeUnits(a, b))
+ .slice(0, TITLE_WORDS)
+ .map(([w]) => w);
+ // A word of a script written without spaces can be a whole sentence:
+ // the title is cut to the longest a record may carry, in the unit the
+ // record check counts (UTF-16 code units), after the capital letter
+ // (which can grow: "ß" becomes "SS"), never inside a surrogate pair.
+ const joined = words.join(" ");
+ const [lead = ""] = joined;
+ return clampUnits(lead.toUpperCase() + joined.slice(lead.length), TOPIC_TITLE_MAX).trim();
+}
+
+/** `text` cut to at most `max` UTF-16 code units, never splitting a surrogate pair. */
+function clampUnits(text: string, max: number): string {
+ if (text.length <= max) return text;
+ const code = text.charCodeAt(max - 1);
+ const end = code >= 0xd800 && code <= 0xdbff ? max - 1 : max;
+ return text.slice(0, end);
+}
+
+function draftGoal(group: Group): string {
+ const text = group.members[0]!.text.replaceAll(/\s+/g, " ").trim();
+ return [...text].length <= GOAL_MAX ? text : `${[...text].slice(0, GOAL_MAX - 3).join("")}...`;
+}
+
+const byRecordOrder = (a: TopicCandidate, b: TopicCandidate): number =>
+ a.at - b.at || compareCodeUnits(a.id, b.id);
+
+/** Merge proposals and quiet-topic prompts: what the brief and digest ask the user. */
+export function reviewTopics(fold: TopicFold, nowMs: number, quietDays: number): TopicReview {
+ const active = [...fold.topics.values()]
+ .filter(isActive)
+ .toSorted((a, b) => compareCodeUnits(a.id, b.id));
+ const merges: MergeProposal[] = [];
+ const heads = active.map((topic) => ({
+ topic,
+ tokens: subjectTokens([topic.title, topic.description ?? "", topic.goal ?? ""].join(" ")),
+ }));
+ for (let i = 0; i < heads.length; i++) {
+ for (let j = i + 1; j < heads.length; j++) {
+ const a = heads[i]!;
+ const b = heads[j]!;
+ if (a.topic.scope !== b.topic.scope) continue;
+ const n = shared(a.tokens, b.tokens);
+ const union = a.tokens.size + b.tokens.size - n;
+ const score = union === 0 ? 0 : n / union;
+ if (score >= MERGE_JACCARD) merges.push({ topics: [a.topic.id, b.topic.id], score });
+ }
+ }
+ const quiet = active
+ .map((t) => ({ topic: t.id, days: Math.floor((nowMs - t.updatedAt) / DAY_MS) }))
+ .filter((q) => q.days >= quietDays);
+ return { merges, quiet };
+}
+
+/** The plan for `candidates` against `fold`. */
+export function planTopics(
+ fold: TopicFold,
+ candidates: ReadonlyArray<TopicCandidate>,
+ settings: PlanSettings,
+ nowMs: number,
+): TopicPlan {
+ const ordered = candidates.toSorted(byRecordOrder);
+ const active = [...fold.topics.values()]
+ .filter(isActive)
+ .toSorted((a, b) => a.createdAt - b.createdAt || compareCodeUnits(a.id, b.id))
+ .map((topic) => ({ topic, tokens: headTokens(topic, false), all: headTokens(topic, true) }));
+ const routes: PlannedRoute[] = [];
+ const free: TopicCandidate[] = [];
+ for (const candidate of ordered) {
+ if (holder(fold, candidate) !== null) continue;
+ const topic = bestTopic(fold, candidate, active);
+ if (topic !== null) {
+ const target = fold.topics.get(topic)!;
+ routes.push({ record: candidate.id, topic, private: candidate.private || target.private });
+ } else if (candidate.project !== null && !fold.touched.has(candidate.id)) {
+ free.push(candidate);
+ }
+ }
+ const creates: PlannedCreate[] = [];
+ const projects = [...new Set(free.map((c) => c.project!))].toSorted(compareCodeUnits);
+ for (const project of projects) {
+ for (const group of groups(free.filter((c) => c.project === project))) {
+ if (!qualifies(group, settings)) continue;
+ creates.push({
+ title: draftTitle(group),
+ goal: draftGoal(group),
+ scope: `${TOPIC_PROJECT_SCOPE_PREFIX}${project}`,
+ private: group.members.some((m) => m.private),
+ members: group.members.map((m) => m.id),
+ sessions: new Set(group.members.map((m) => m.session)).size,
+ });
+ }
+ }
+ const splits: SplitProposal[] = [];
+ for (const { topic } of active) {
+ const members = ordered.filter((c) => holder(fold, c) === topic.id);
+ const parts = groups(members).filter((g) => qualifies(g, settings));
+ if (parts.length >= 2) {
+ splits.push({ topic: topic.id, groups: parts.map((g) => g.members.map((m) => m.id)) });
+ }
+ }
+ return { routes, creates, splits, ...reviewTopics(fold, nowMs, settings.quietDays) };
+}
diff --git a/src/core/topics/planning.ts b/src/core/topics/planning.ts
new file mode 100644
index 00000000..202f364e
--- /dev/null
+++ b/src/core/topics/planning.ts
@@ -0,0 +1,418 @@
+/**
+ * The topic-planning step of dream (design D9; task 3.4): only the view
+ * writer runs it, under a device-local exclusive lock, so neither two
+ * machines nor two processes on the writer create the same topic twice.
+ *
+ * A pass:
+ *
+ * 1. reads the view writer records; any other machine stops here and its
+ * report names the writer (spec "Two machines run dream at once");
+ * 2. takes the planning lock, then reads every partition this machine
+ * holds (and stops when a shard could not be read in full: a plan
+ * over a partial read could make a topic that already exists, or
+ * when that read names another view writer, or the pass's deadline
+ * passed while it waited for the lock);
+ * 3. plans (`plan.ts`) and appends, as `agent` records of its own agent:
+ * a `topic-create` per new topic with an `assign` per record, and an
+ * `assign` per route. A record lands in `private` when its topic is
+ * private or the record it assigns is; a private one on a machine
+ * without that partition is skipped and reported.
+ *
+ * Every create and route is listed in the report with the command that
+ * undoes it, also when a later write of the pass fails; the undo is a human `undo` record every machine honours.
+ * Merges, splits and quiet topics are only listed. Reading inside the lock
+ * is what makes a second pass see the first one's topics and assign
+ * nothing twice.
+ */
+
+import { join } from "node:path";
+
+import { readDeviceId, resolveAgentName } from "../config.ts";
+import { appendRecord } from "../store/appender.ts";
+import {
+ SETTING_TOPIC_MIN_RECORDS,
+ SETTING_TOPIC_MIN_SESSIONS,
+ SETTING_TOPIC_QUIET_DAYS,
+ type StorePartition,
+} from "../store/constants.ts";
+import { foldSettings, settingValue } from "../store/fold-settings.ts";
+import { withLocalLock } from "../store/local-lock.ts";
+import { inspectStore, openStore, type StoreHandle } from "../store/store-open.ts";
+import { resolveConfiguredStoreRoot } from "../store/store-paths.ts";
+import { newUlid } from "../store/ulid.ts";
+import { catchUp, catchUpSettings, partitionRecords } from "../view/catch-up.ts";
+import { VIEW_STATE_DIR } from "../view/constants.ts";
+import { foldViewWriter } from "../view/writer-fold.ts";
+import { claimSeen, releaseIfRequested } from "../view/writer.ts";
+import { resolveLockWaitBudgetMs } from "../brain/sync-lockfile.ts";
+import { readStreamRecords } from "../store/read/stream-read.ts";
+import { TOPIC_ASSIGN_KIND, TOPIC_CREATE_KIND, TOPIC_STREAM } from "./constants.ts";
+import { topicCandidates } from "./candidates.ts";
+import { topicBodyRejection } from "./records.ts";
+import { foldTopics } from "./fold.ts";
+import { planTopics, type MergeProposal, type QuietPrompt, type SplitProposal } from "./plan.ts";
+
+/** The command that undoes one automatic topic record. */
+export const TOPIC_UNDO_COMMAND = "o2b topic undo";
+
+/** Device-local lock target of the planning step. */
+const PLAN_LOCK = "topic-plan";
+
+export interface CreatedTopic {
+ readonly topic: string;
+ readonly title: string;
+ readonly record: string;
+ readonly members: number;
+ readonly undo: string;
+}
+
+export interface RoutedRecord {
+ readonly record: string;
+ readonly topic: string;
+ readonly assign: string;
+ readonly undo: string;
+}
+
+export type TopicPlanningReport =
+ | { readonly status: "no-writer" }
+ | { readonly status: "not-writer"; readonly writer: string }
+ | { readonly status: "released"; readonly to: string }
+ | { readonly status: "waiting-for-claim" }
+ | { readonly status: "raced" }
+ | { readonly status: "incomplete-read"; readonly shards: ReadonlyArray<string> }
+ /** The pass's deadline passed while it waited for the planning lock: nothing was written. */
+ | { readonly status: "deferred" }
+ | TopicPlanningError
+ | {
+ readonly status: "planned";
+ readonly created: ReadonlyArray<CreatedTopic>;
+ readonly routed: ReadonlyArray<RoutedRecord>;
+ readonly merges: ReadonlyArray<MergeProposal>;
+ readonly splits: ReadonlyArray<SplitProposal>;
+ readonly quiet: ReadonlyArray<QuietPrompt>;
+ /** Planned records skipped: private ones on a machine without `private`. */
+ readonly skipped: number;
+ /** Planned topics not created because their record would not be valid. */
+ readonly invalid: number;
+ };
+
+/**
+ * A pass that failed. A write that failed after others landed keeps them
+ * in `created` and `routed`, each with its undo command: they are in the
+ * store, and the report must still name them.
+ */
+export interface TopicPlanningError {
+ readonly status: "error";
+ readonly error: string;
+ readonly created: ReadonlyArray<CreatedTopic>;
+ readonly routed: ReadonlyArray<RoutedRecord>;
+}
+
+export interface TopicPlanningOptions {
+ readonly agent: string;
+ /** Wall clock (default `Date.now`). */
+ readonly now?: () => number;
+ /**
+ * The config file the pass was run with, named in every undo command
+ * it reports so the command acts on the same store.
+ */
+ readonly configPath?: string;
+ /**
+ * Asked under the planning lock, after the read and before the first
+ * write: `false` writes nothing (`deferred`), so a pass whose deadline
+ * passed while it waited for the lock leaves topics to the next one.
+ */
+ readonly mayPlan?: () => boolean;
+}
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+/** A word for a POSIX shell, single-quoted unless it needs no quoting. */
+function shellWord(value: string): string {
+ return /^[A-Za-z0-9_./:=@%+,-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function undoOf(record: string, configPath: string | undefined): string {
+ const config = configPath === undefined ? "" : ` --config ${shellWord(configPath)}`;
+ return `${TOPIC_UNDO_COMMAND} ${record}${config}`;
+}
+
+/**
+ * How long a pass waits for another pass's planning lock: longer than the
+ * store's default, since the holder reads the whole store before it writes.
+ */
+const PLAN_LOCK_WAIT_MS = 30_000;
+
+/** The device-local lock target of the planning step. */
+export function topicPlanLockTarget(store: StoreHandle): string {
+ return join(store.deviceStateDir, VIEW_STATE_DIR, PLAN_LOCK);
+}
+
+type WriterGate =
+ | { readonly ok: true }
+ | { readonly ok: false; readonly report: TopicPlanningReport };
+
+/**
+ * The render's writer protocol (design D7), for planning: only the view
+ * writer plans; a writer whose role a request moves hands it over
+ * instead; and a writer by its own fresh claim waits until the render
+ * has settled the claim, so a rival claim with a lower clock has one
+ * catch-up to arrive before this machine creates a topic.
+ */
+function writerGate(store: StoreHandle, options: TopicPlanningOptions): WriterGate {
+ const settings = catchUpSettings(store, options.now);
+ if (settings === null) {
+ return { ok: false, report: { status: "incomplete-read", shards: ["shared/settings"] } };
+ }
+ const state = foldViewWriter(settings);
+ if (state.writer === null) return { ok: false, report: { status: "no-writer" } };
+ if (state.writer !== store.device) {
+ return { ok: false, report: { status: "not-writer", writer: state.writer } };
+ }
+ const to = releaseIfRequested(store, state, {
+ agent: options.agent,
+ ...(options.now !== undefined ? { now: options.now } : {}),
+ });
+ if (to !== null) return { ok: false, report: { status: "released", to } };
+ if (!claimSeen(store, state)) return { ok: false, report: { status: "waiting-for-claim" } };
+ return { ok: true };
+}
+
+/** One planning pass on this machine. */
+export function runTopicPlanning(
+ store: StoreHandle,
+ options: TopicPlanningOptions,
+): TopicPlanningReport {
+ const clock = options.now ?? Date.now;
+ const before = writerGate(store, options);
+ if (!before.ok) return before.report;
+ const wait = Math.max(resolveLockWaitBudgetMs(), PLAN_LOCK_WAIT_MS);
+ return withLocalLock(
+ topicPlanLockTarget(store),
+ () => {
+ // Asked again under the lock: the role may have moved while this
+ // pass waited, and no plan starts after a release.
+ const under = writerGate(store, options);
+ if (!under.ok) return under.report;
+ return planUnderLock(store, options, clock);
+ },
+ wait,
+ );
+}
+
+/** The ids of every topic record this machine holds now: the fence a plan is written behind. */
+function topicRecordIds(store: StoreHandle): string {
+ const ids: string[] = [];
+ for (const partition of store.partitions) {
+ for (const record of readStreamRecords(store.root, partition, { stream: TOPIC_STREAM })
+ .records) {
+ ids.push(record.id);
+ }
+ }
+ return ids.toSorted().join(",");
+}
+
+function planUnderLock(
+ store: StoreHandle,
+ options: TopicPlanningOptions,
+ clock: () => number,
+): TopicPlanningReport {
+ const fence = topicRecordIds(store);
+ const read = catchUp(store, options.now);
+ if (read.unreadable.length > 0) {
+ return { status: "incomplete-read", shards: read.unreadable.map((s) => s.path) };
+ }
+ // The writer as this read reports it: a move that arrived after the gate
+ // above read the settings still stops the pass before it plans.
+ const writer = foldViewWriter(partitionRecords(read, "shared")).writer;
+ if (writer === null) return { status: "no-writer" };
+ if (writer !== store.device) return { status: "not-writer", writer };
+ const privateIds = new Set(partitionRecords(read, "private").map((r) => r.id));
+ const records = [...read.records.values()].flat();
+ const fold = foldTopics(records, { privateIds });
+ const shared = foldSettings(partitionRecords(read, "shared"));
+ const plan = planTopics(
+ fold,
+ topicCandidates(records, privateIds),
+ {
+ minRecords: settingValue(shared, SETTING_TOPIC_MIN_RECORDS) as number,
+ minSessions: settingValue(shared, SETTING_TOPIC_MIN_SESSIONS) as number,
+ quietDays: settingValue(shared, SETTING_TOPIC_QUIET_DAYS) as number,
+ },
+ clock(),
+ );
+ // A lock taken over from a holder that looked stale (a paused process)
+ // lets two passes plan at once: a pass whose topic records changed since
+ // it read them writes nothing, and the next pass plans again.
+ if (topicRecordIds(store) !== fence) return { status: "raced" };
+ if (options.mayPlan !== undefined && !options.mayPlan()) return { status: "deferred" };
+ let skipped = 0;
+ let invalid = 0;
+ const append = (
+ isPrivate: boolean,
+ kind: string,
+ topic: string,
+ body: Record<string, unknown>,
+ scope: string | null = null,
+ ): string | null => {
+ const partition: StorePartition = isPrivate ? "private" : "shared";
+ if (!store.partitions.has(partition)) {
+ skipped += 1;
+ return null;
+ }
+ return appendRecord(
+ store,
+ {
+ partition,
+ stream: TOPIC_STREAM,
+ kind,
+ agent: options.agent,
+ scope,
+ topic,
+ body: { authority: "agent", ...body },
+ },
+ options.now !== undefined ? { now: options.now } : {},
+ ).record.id;
+ };
+ const created: Array<Mutable<CreatedTopic>> = [];
+ const routed: RoutedRecord[] = [];
+ try {
+ writePlan();
+ } catch (err) {
+ // What landed before the failure stays listed, with its undo command.
+ return { status: "error", error: errorText(err), created, routed };
+ }
+ return {
+ status: "planned",
+ created,
+ routed,
+ merges: plan.merges,
+ splits: plan.splits,
+ quiet: plan.quiet,
+ skipped,
+ invalid,
+ };
+
+ function writePlan(): void {
+ for (const plannedTopic of plan.creates) {
+ const topic = newUlid(clock());
+ const body = {
+ title: plannedTopic.title,
+ scope: plannedTopic.scope,
+ goal: plannedTopic.goal,
+ };
+ // Checked as the fold checks it: a create the fold would reject (a
+ // scope too long for a record) is never written, nor are its assigns,
+ // so its records stay free for a later pass.
+ if (topicBodyRejection(TOPIC_CREATE_KIND, topic, { authority: "agent", ...body }) !== null) {
+ invalid += 1;
+ continue;
+ }
+ const record = append(
+ plannedTopic.private,
+ TOPIC_CREATE_KIND,
+ topic,
+ body,
+ plannedTopic.scope,
+ );
+ if (record === null) continue;
+ // Listed as soon as it lands; `members` counts the assigns written.
+ const entry = {
+ topic,
+ title: plannedTopic.title,
+ record,
+ members: 0,
+ undo: undoOf(record, options.configPath),
+ };
+ created.push(entry);
+ for (const member of plannedTopic.members) {
+ if (append(plannedTopic.private, TOPIC_ASSIGN_KIND, topic, { record: member }) !== null) {
+ entry.members += 1;
+ }
+ }
+ }
+ for (const route of plan.routes) {
+ const assign = append(route.private, TOPIC_ASSIGN_KIND, route.topic, {
+ record: route.record,
+ });
+ if (assign !== null)
+ routed.push({ ...route, assign, undo: undoOf(assign, options.configPath) });
+ }
+ }
+}
+
+function errorText(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * {@link runTopicPlanning} for the store and device the machine config
+ * names, as the dream pass runs it: `null` when this machine uses no
+ * store or has no device id. Fail-open: an error is returned, never thrown.
+ */
+export function runAutoTopicPlanning(
+ options: {
+ readonly configPath?: string;
+ readonly now?: () => number;
+ /**
+ * Asked once the store is known to be in use, right before planning:
+ * `false` plans nothing and answers `null` (a dream pass past its
+ * deadline). Asked again under the planning lock, before the first
+ * write (`deferred`).
+ */
+ readonly mayPlan?: () => boolean;
+ } = {},
+): TopicPlanningReport | null {
+ try {
+ const { root } = resolveConfiguredStoreRoot(options.configPath);
+ if (inspectStore(root) === null) return null;
+ const device = readDeviceId(options.configPath);
+ if (device === null) return null;
+ if (options.mayPlan !== undefined && !options.mayPlan()) return null;
+ const store = openStore({ root, device });
+ return runTopicPlanning(store, {
+ agent: resolveAgentName(options.configPath),
+ ...(options.now !== undefined ? { now: options.now } : {}),
+ ...(options.configPath !== undefined ? { configPath: options.configPath } : {}),
+ ...(options.mayPlan !== undefined ? { mayPlan: options.mayPlan } : {}),
+ });
+ } catch (err) {
+ return { status: "error", error: errorText(err), created: [], routed: [] };
+ }
+}
+
+/** One line for the dream report. */
+export function describeTopicPlanning(
+ report: NonNullable<ReturnType<typeof runAutoTopicPlanning>>,
+): string {
+ switch (report.status) {
+ case "no-writer":
+ return "no machine plans topics yet (no view writer)";
+ case "not-writer":
+ return `this machine plans no topics; the view writer is ${report.writer}`;
+ case "incomplete-read":
+ return "topics were not planned: some shards could not be read";
+ case "released":
+ return `topics were not planned: the view writer role moved to ${report.to}`;
+ case "waiting-for-claim":
+ return "this machine just took the view writer role; it plans topics from its next pass";
+ case "raced":
+ return "topics were not planned: another pass wrote topic records meanwhile";
+ case "deferred":
+ return "topics were not planned: the pass ran out of time while it waited for the planning lock";
+ case "error": {
+ const done = report.created.length + report.routed.length;
+ const landed =
+ done > 0
+ ? ` (${report.created.length} topic(s) created and ${report.routed.length} record(s) routed before it)`
+ : "";
+ return `topics could not be planned: ${report.error}${landed}`;
+ }
+ case "planned":
+ return (
+ `${report.created.length} topic(s) created, ${report.routed.length} record(s) routed, ` +
+ `${report.merges.length} merge and ${report.splits.length} split proposal(s), ` +
+ `${report.quiet.length} quiet topic(s)`
+ );
+ }
+}
diff --git a/src/core/topics/read.ts b/src/core/topics/read.ts
new file mode 100644
index 00000000..a6688bd0
--- /dev/null
+++ b/src/core/topics/read.ts
@@ -0,0 +1,93 @@
+/**
+ * Read the topics of the configured store (task 3.1): the `topics` stream
+ * of every partition this machine holds, folded once (`fold.ts`), each
+ * topic and item tagged with whether it is private.
+ *
+ * Reach (design D3, task 3.17): a caller below local reach (a remote MCP
+ * transport, `caller-reach.ts`) is answered from the `shared` partition
+ * alone, so a private topic, a private item of a shared topic, and an
+ * undo, rename or assignment written to `private` read for it as if they
+ * did not exist; it folds exactly what a machine that holds only `shared`
+ * folds. Every other caller folds every partition this machine holds.
+ *
+ * A shard that could not be read, was read only in part, or is gone since
+ * this machine read it is named in `unreadable`: its records are unknown,
+ * not absent, so a caller that decides something from the fold (the
+ * writer's privacy of a topic, the dream's routing) refuses on any.
+ * Nothing is written.
+ */
+
+import { privateWithheld } from "../store/caller-reach.ts";
+import { valueCarriesPrivateRegion } from "../store/private-region.ts";
+import type { StorePartition } from "../store/constants.ts";
+import type { StoreRecord } from "../store/envelope.ts";
+import { configuredStore } from "../store/read/store-entities.ts";
+import { readStreamRecords } from "../store/read/stream-read.ts";
+import type { StoreInspection } from "../store/store-open.ts";
+import { TOPIC_STREAM } from "./constants.ts";
+import { foldTopics, type TopicFold } from "./fold.ts";
+
+export interface TopicRead {
+ readonly fold: TopicFold;
+ /** Partition-relative paths (`<partition>/<shard>`) of shards not read in full. */
+ readonly unreadable: ReadonlyArray<string>;
+ /** The partitions the fold read. */
+ readonly partitions: ReadonlySet<StorePartition>;
+ /** The topic each topic record read names (record id to topic id). */
+ readonly recordTopics: ReadonlyMap<string, string>;
+ /** Ids of the topic records read from the `private` partition. */
+ readonly privateRecords: ReadonlySet<string>;
+ /** The store id, `null` without a store. */
+ readonly storeId: string | null;
+}
+
+const EMPTY: TopicRead = Object.freeze({
+ fold: foldTopics([]),
+ unreadable: [],
+ partitions: new Set<StorePartition>(),
+ recordTopics: new Map<string, string>(),
+ privateRecords: new Set<string>(),
+ storeId: null,
+});
+
+/** The partitions a read for the caller of the work running now may fold. */
+function readablePartitions(store: StoreInspection): StorePartition[] {
+ const held = [...store.partitions];
+ return privateWithheld() ? held.filter((p) => p === "shared") : held;
+}
+
+/** Fold the topics of `store`, for the caller of the work running now. */
+export function readTopicsOf(store: StoreInspection): TopicRead {
+ const records: StoreRecord[] = [];
+ const privateIds = new Set<string>();
+ const unreadable: string[] = [];
+ const partitions = readablePartitions(store);
+ for (const partition of partitions) {
+ const read = readStreamRecords(store.root, partition, { stream: TOPIC_STREAM });
+ for (const record of read.records) {
+ // Below local reach a shared record that carries a `<private>` region
+ // is withheld, as every reader withholds it.
+ if (privateWithheld() && valueCarriesPrivateRegion(record.body)) continue;
+ records.push(record);
+ if (partition === "private") privateIds.add(record.id);
+ }
+ unreadable.push(...read.unreadable.map((rel) => `${partition}/${rel}`));
+ }
+ const recordTopics = new Map<string, string>();
+ for (const record of records)
+ if (record.topic !== null) recordTopics.set(record.id, record.topic);
+ return {
+ fold: foldTopics(records, { privateIds }),
+ unreadable,
+ partitions: new Set(partitions),
+ recordTopics,
+ privateRecords: privateIds,
+ storeId: store.storeId,
+ };
+}
+
+/** {@link readTopicsOf} for the store the machine config at `configPath` names; empty without one. */
+export function readTopics(configPath?: string): TopicRead {
+ const store = configuredStore(configPath);
+ return store === null ? EMPTY : readTopicsOf(store);
+}
diff --git a/src/core/topics/records.ts b/src/core/topics/records.ts
new file mode 100644
index 00000000..8903b843
--- /dev/null
+++ b/src/core/topics/records.ts
@@ -0,0 +1,189 @@
+/**
+ * Shapes of the topic records (design D8, FORMAT.md "Topics"): what a
+ * valid body of each kind holds, checked the same way by the fold (a
+ * record that fails is not applied and is reported) and by the writers (a
+ * record that fails is never written).
+ *
+ * Every topic record carries `authority` in its body and the id of its
+ * topic in the envelope's `topic` field. A list item (a decision, an open
+ * question, a log entry, a milestone) is addressed by its `item` id; a
+ * record that creates one may leave `item` out, and its own record id is
+ * the item id then. An item record with `removed: true` is the item's
+ * tombstone.
+ */
+
+import { isAuthority } from "../store/fold.ts";
+import { isUlid } from "../store/ulid.ts";
+import {
+ TOPIC_ASSIGN_KIND,
+ TOPIC_CREATE_KIND,
+ TOPIC_DECISION_KIND,
+ TOPIC_GOAL_KIND,
+ TOPIC_ITEM_KINDS,
+ TOPIC_LINK_KIND,
+ TOPIC_LOG_CLASSES,
+ TOPIC_LOG_KIND,
+ TOPIC_MERGE_KIND,
+ TOPIC_MILESTONE_DONE_KIND,
+ TOPIC_PERSONAL_SCOPE,
+ TOPIC_PROJECT_SCOPE_PREFIX,
+ TOPIC_QUESTION_RESOLVED_KIND,
+ TOPIC_RECORD_KINDS,
+ TOPIC_RENAME_KIND,
+ TOPIC_SPLIT_KIND,
+ TOPIC_STATUS_KIND,
+ TOPIC_STATUSES,
+ TOPIC_UNASSIGN_KIND,
+ TOPIC_UNDO_KIND,
+ type TopicItemKind,
+ type TopicRecordKind,
+} from "./constants.ts";
+
+/** Longest title, in characters. */
+export const TOPIC_TITLE_MAX = 200;
+/** Longest text of any other field, in characters. */
+export const TOPIC_TEXT_MAX = 4000;
+
+/** An item id: a ULID, or any short token a writer chose. */
+const ITEM_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function isTopicRecordKind(kind: string): kind is TopicRecordKind {
+ return (TOPIC_RECORD_KINDS as ReadonlyArray<string>).includes(kind);
+}
+
+export function isTopicItemKind(kind: string): kind is TopicItemKind {
+ return (TOPIC_ITEM_KINDS as ReadonlyArray<string>).includes(kind);
+}
+
+export function isItemId(value: unknown): value is string {
+ return typeof value === "string" && ITEM_ID_RE.test(value);
+}
+
+/** A topic scope: `personal`, or `project:<project>` (one line, at most 200 characters). */
+export function isTopicScope(value: unknown): value is string {
+ if (value === TOPIC_PERSONAL_SCOPE) return true;
+ return (
+ typeof value === "string" &&
+ value.length <= 200 &&
+ value.startsWith(TOPIC_PROJECT_SCOPE_PREFIX) &&
+ value.slice(TOPIC_PROJECT_SCOPE_PREFIX.length).trim() !== "" &&
+ !/[\r\n]/.test(value)
+ );
+}
+
+function text(value: unknown, max = TOPIC_TEXT_MAX): value is string {
+ return typeof value === "string" && value.trim() !== "" && value.length <= max;
+}
+
+function textOrNull(value: unknown): boolean {
+ return value === null || text(value);
+}
+
+/** A one-line text: a title or a description, never a line break that opens a new block. */
+function line(value: unknown, max = TOPIC_TEXT_MAX): value is string {
+ return text(value, max) && !/[\r\n]/.test(value);
+}
+
+function lineOrNull(value: unknown): boolean {
+ return value === null || line(value);
+}
+
+function idList(value: unknown, valid: (v: unknown) => boolean): boolean {
+ return Array.isArray(value) && value.length > 0 && value.every(valid);
+}
+
+type Body = Readonly<Record<string, unknown>>;
+
+function itemRejection(kind: TopicItemKind, body: Body): string | null {
+ if (body["removed"] === true) return isItemId(body["item"]) ? null : "a removal needs an item id";
+ if (body["item"] !== undefined && !isItemId(body["item"])) return "invalid item id";
+ if (!text(body["text"])) return "text must be a non-empty string";
+ if (kind === TOPIC_LOG_KIND) {
+ const cls = body["class"];
+ if (typeof cls !== "string" || !(TOPIC_LOG_CLASSES as ReadonlyArray<string>).includes(cls)) {
+ return `class must be one of ${TOPIC_LOG_CLASSES.join(", ")}`;
+ }
+ if (body["reason"] !== undefined && !text(body["reason"])) return "invalid reason";
+ }
+ if (kind === TOPIC_DECISION_KIND && body["serves"] !== undefined) {
+ // An empty list clears the links; a record without `serves` keeps them.
+ const serves = body["serves"];
+ if (!(Array.isArray(serves) && (serves.length === 0 || idList(serves, isItemId)))) {
+ return "serves must list item ids";
+ }
+ }
+ return null;
+}
+
+/**
+ * Why a topic record of `kind`, for the topic `topic` (the envelope
+ * field), with `body` cannot be applied, or `null` when it can.
+ */
+export function topicBodyRejection(kind: string, topic: string | null, body: Body): string | null {
+ if (!isTopicRecordKind(kind)) return `not a topic record kind: ${kind}`;
+ if (topic === null || !isUlid(topic)) return "the envelope topic must be a topic id";
+ if (!isAuthority(body["authority"])) return "missing or invalid authority";
+ if (isTopicItemKind(kind)) return itemRejection(kind, body);
+ switch (kind) {
+ case TOPIC_CREATE_KIND:
+ if (!line(body["title"], TOPIC_TITLE_MAX)) return "title must be a non-empty single line";
+ if (!isTopicScope(body["scope"])) return "scope must be personal or project:<project>";
+ if (body["description"] !== undefined && !lineOrNull(body["description"])) {
+ return "description must be a single line or null";
+ }
+ if (body["goal"] !== undefined && !textOrNull(body["goal"])) return "invalid goal";
+ return null;
+ case TOPIC_RENAME_KIND:
+ if (body["title"] === undefined && body["description"] === undefined) {
+ return "a rename needs a title or a description";
+ }
+ if (body["title"] !== undefined && !line(body["title"], TOPIC_TITLE_MAX)) {
+ return "title must be a non-empty single line";
+ }
+ if (body["description"] !== undefined && !lineOrNull(body["description"])) {
+ return "description must be a single line or null";
+ }
+ return null;
+ case TOPIC_STATUS_KIND:
+ if (!(TOPIC_STATUSES as ReadonlyArray<unknown>).includes(body["status"])) {
+ return `status must be one of ${TOPIC_STATUSES.join(", ")}`;
+ }
+ if (
+ body["resolved"] !== undefined &&
+ !(typeof body["resolved"] === "string" && DAY_RE.test(body["resolved"]))
+ ) {
+ return "resolved must be a YYYY-MM-DD day";
+ }
+ return null;
+ case TOPIC_GOAL_KIND:
+ return textOrNull(body["goal"]) ? null : "goal must be a non-empty string or null";
+ case TOPIC_QUESTION_RESOLVED_KIND:
+ if (!isItemId(body["question"])) return "question must be an item id";
+ return body["answer"] === undefined || text(body["answer"]) ? null : "invalid answer";
+ case TOPIC_MILESTONE_DONE_KIND:
+ if (!isItemId(body["milestone"])) return "milestone must be an item id";
+ return body["evidence"] === undefined || text(body["evidence"]) ? null : "invalid evidence";
+ case TOPIC_ASSIGN_KIND:
+ case TOPIC_UNASSIGN_KIND:
+ case TOPIC_UNDO_KIND:
+ return isUlid(body["record"]) ? null : "record must be a record id";
+ case TOPIC_MERGE_KIND:
+ if (!isUlid(body["into"])) return "into must be a topic id";
+ return body["into"] === topic ? "a topic cannot merge into itself" : null;
+ case TOPIC_SPLIT_KIND:
+ if (!isUlid(body["into"]) || body["into"] === topic) return "into must be another topic id";
+ if (body["items"] === undefined && body["records"] === undefined) {
+ return "a split needs items or records";
+ }
+ if (body["items"] !== undefined && !idList(body["items"], isItemId)) return "invalid items";
+ if (body["records"] !== undefined && !idList(body["records"], isUlid))
+ return "invalid records";
+ return null;
+ case TOPIC_LINK_KIND:
+ if (!isUlid(body["to"]) || body["to"] === topic) return "to must be another topic id";
+ return body["removed"] === undefined || body["removed"] === true ? null : "invalid removed";
+ default:
+ return `not a topic record kind: ${kind}`;
+ }
+}
diff --git a/src/core/topics/review.ts b/src/core/topics/review.ts
new file mode 100644
index 00000000..09643a61
--- /dev/null
+++ b/src/core/topics/review.ts
@@ -0,0 +1,59 @@
+/**
+ * What the brief and the digest ask the user about topics (spec `topics`
+ * "Quiet topic", "Two topics look the same"; task 3.4): the merge
+ * proposals and the quiet topics of the configured store, read for the
+ * caller of the work running now (a caller below local reach is asked
+ * only about shared topics), and their Markdown section. Nothing is
+ * written: a proposal is applied only when the user confirms it with the
+ * topic tool.
+ */
+
+import { SETTING_TOPIC_QUIET_DAYS } from "../store/constants.ts";
+import { settingValue } from "../store/fold-settings.ts";
+import { sharedSettingsOf } from "./settings.ts";
+import { configuredStore } from "../store/read/store-entities.ts";
+import { reviewTopics, type TopicReview } from "./plan.ts";
+import { readTopicsOf } from "./read.ts";
+import type { TopicFold } from "./fold.ts";
+import { plainText } from "../view/pages.ts";
+
+export interface TopicReviewRead {
+ readonly review: TopicReview;
+ readonly fold: TopicFold;
+}
+
+/** The review of the store the machine config at `configPath` names; `null` without one. */
+export function readTopicReview(nowMs: number, configPath?: string): TopicReviewRead | null {
+ const store = configuredStore(configPath);
+ if (store === null || !store.partitions.has("shared")) return null;
+ const { fold, unreadable } = readTopicsOf(store);
+ // A fold over a partial read may miss topics: nothing is asked from it.
+ if (unreadable.length > 0) return null;
+ const quietDays = settingValue(sharedSettingsOf(store), SETTING_TOPIC_QUIET_DAYS) as number;
+ return { review: reviewTopics(fold, nowMs, quietDays), fold };
+}
+
+/** The `## Topics` section of a digest or brief; empty when there is nothing to ask. */
+export function renderTopicReview(read: TopicReviewRead | null): string {
+ if (read === null) return "";
+ const { review, fold } = read;
+ if (review.merges.length === 0 && review.quiet.length === 0) return "";
+ // One line per title: a title is caller text and must not open a new block.
+ const title = (id: string): string => plainText(fold.topics.get(id)?.title ?? id);
+ const lines = ["## Topics", ""];
+ for (const merge of review.merges) {
+ const [a, b] = merge.topics;
+ lines.push(
+ `- These topics look like one: "${title(a)}" and "${title(b)}". To merge them: ` +
+ `\`o2b topic merge ${b} --into ${a}\`.`,
+ );
+ }
+ for (const quiet of review.quiet) {
+ lines.push(
+ `- "${title(quiet.topic)}" has had no news for ${quiet.days} days. Keep it, put it on hold, ` +
+ `mark it done or close it: \`o2b topic status ${quiet.topic} <active|on-hold|done|closed>\`.`,
+ );
+ }
+ lines.push("");
+ return lines.join("\n");
+}
diff --git a/src/core/topics/settings.ts b/src/core/topics/settings.ts
new file mode 100644
index 00000000..4de677e7
--- /dev/null
+++ b/src/core/topics/settings.ts
@@ -0,0 +1,22 @@
+/**
+ * The shared settings topics read (`view.language`, the thresholds of
+ * planning), from the `settings` stream of the configured store's
+ * `shared` partition: one reader, so the topic tool, the digest's topic
+ * section and the page render of `show` cannot disagree on a value.
+ */
+
+import { foldSettings, settingValue, type SettingsFold } from "../store/fold-settings.ts";
+import { configuredStore } from "../store/read/store-entities.ts";
+import { readStreamRecords } from "../store/read/stream-read.ts";
+import type { StoreInspection } from "../store/store-open.ts";
+
+/** The settings fold of `store` (its defaults when it has no `shared` partition). */
+export function sharedSettingsOf(store: StoreInspection | null): SettingsFold {
+ if (store === null || !store.partitions.has("shared")) return foldSettings([]);
+ return foldSettings(readStreamRecords(store.root, "shared", { stream: "settings" }).records);
+}
+
+/** The value of `key` in the configured store's shared settings, else its default. */
+export function sharedSetting(key: string, configPath?: string): unknown {
+ return settingValue(sharedSettingsOf(configuredStore(configPath)), key);
+}
diff --git a/src/core/topics/undo-fold.ts b/src/core/topics/undo-fold.ts
new file mode 100644
index 00000000..612bfd22
--- /dev/null
+++ b/src/core/topics/undo-fold.ts
@@ -0,0 +1,43 @@
+/**
+ * Undo resolution of the topic fold (design D8): which topic records an
+ * effective `undo` voids. Split from `fold.ts`; pure, like the fold.
+ */
+
+import type { StoreRecord } from "../store/envelope.ts";
+import { authorityRank, recordAuthority } from "../store/fold.ts";
+import { TOPIC_UNDO_KIND } from "./constants.ts";
+
+/**
+ * Records voided by an effective undo. An undo cycle (only a forged one)
+ * is cut where the walk meets it again: the record it meets counts as not
+ * voided there, so the outcome depends only on the canonical record order
+ * and is the same on every machine.
+ */
+export function voidedRecords(records: ReadonlyArray<StoreRecord>): Set<string> {
+ const byId = new Map(records.map((r) => [r.id, r]));
+ const undoers = new Map<string, StoreRecord[]>();
+ for (const r of records) {
+ if (r.kind !== TOPIC_UNDO_KIND) continue;
+ const target = r.body["record"] as string;
+ undoers.set(target, [...(undoers.get(target) ?? []), r]);
+ }
+ const memo = new Map<string, boolean>();
+ const visiting = new Set<string>();
+ const isVoided = (id: string): boolean => {
+ const known = memo.get(id);
+ if (known !== undefined) return known;
+ if (visiting.has(id)) return false;
+ visiting.add(id);
+ const target = byId.get(id);
+ const rank = target === undefined ? 0 : authorityRank(recordAuthority(target)!);
+ const result = (undoers.get(id) ?? []).some(
+ (u) => authorityRank(recordAuthority(u)!) >= rank && !isVoided(u.id),
+ );
+ visiting.delete(id);
+ memo.set(id, result);
+ return result;
+ };
+ const out = new Set<string>();
+ for (const r of records) if (isVoided(r.id)) out.add(r.id);
+ return out;
+}
diff --git a/src/core/topics/write.ts b/src/core/topics/write.ts
new file mode 100644
index 00000000..179fa7d4
--- /dev/null
+++ b/src/core/topics/write.ts
@@ -0,0 +1,217 @@
+/**
+ * The write path of topics (spec `topics` "Topic events as the write
+ * path"; task 3.1): an agent, a command or the dream pass changes a topic
+ * only by appending topic records to its own shard of the `topics` stream.
+ * Nothing here writes a view page; the view writer renders pages from
+ * these records.
+ *
+ * One call is one store operation (`store-write.ts`): every record lands
+ * in one partition, and it is `private` when
+ *
+ * - the caller asks for it (`private: true`),
+ * - a `topic-create` in the batch has the personal scope and the caller
+ * did not say otherwise (spec brain-store "personal-scope topics SHALL
+ * default to private"),
+ * - any topic the batch names already lives in `private` (records never
+ * move between partitions, so a private topic's events stay there),
+ * - an event edits, completes or resolves an item that has a record in
+ * `private` (a private item on a shared topic: its new text or state
+ * stays private too),
+ * - an `undo` in the batch names a record that sits in `private` (an
+ * undone create takes its topic out of the fold, so the topic alone
+ * cannot tell; the undo of that undo still names the private topic),
+ * - or the store's own backstop (a `<private>` region in a body) says so.
+ *
+ * Topics have no legacy form, so the records go to the store whether or
+ * not this machine has switched; a machine without a store refuses with
+ * the store's reason and remedy. Every record is checked against the shape
+ * the fold applies (`records.ts`) before anything is written, and every
+ * topic a record names must exist or be created in the same call.
+ */
+
+import type { AppendResult } from "../store/appender.ts";
+import { privateWithheld, withPrivateShown } from "../store/caller-reach.ts";
+import { AUTHORITY_FIELD, type Authority } from "../store/constants.ts";
+import type { DualWriteContext, DualWriteRecord } from "../store/dual-write.ts";
+import { storeWrite } from "../store/store-write.ts";
+import { newUlid } from "../store/ulid.ts";
+import {
+ TOPIC_CREATE_KIND,
+ TOPIC_LINK_KIND,
+ TOPIC_MERGE_KIND,
+ TOPIC_MILESTONE_DONE_KIND,
+ TOPIC_QUESTION_RESOLVED_KIND,
+ TOPIC_PERSONAL_SCOPE,
+ TOPIC_SPLIT_KIND,
+ TOPIC_STREAM,
+ TOPIC_UNDO_KIND,
+ type TopicRecordKind,
+} from "./constants.ts";
+import { readTopics, type TopicRead } from "./read.ts";
+import { isTopicItemKind, topicBodyRejection } from "./records.ts";
+
+/** One topic record to write. */
+export interface TopicEvent {
+ readonly kind: TopicRecordKind;
+ /** The topic id (the envelope `topic`). */
+ readonly topic: string;
+ readonly authority: Authority;
+ /** The body without `authority`. */
+ readonly body: Readonly<Record<string, unknown>>;
+ /** The writing agent; defaults to the configured agent name. */
+ readonly agent?: string;
+}
+
+export type TopicWriteFailure = "invalid" | "unknown-topic" | "unreadable";
+
+/** A topic write refused before anything was written. */
+export class TopicWriteError extends Error {
+ readonly reason: TopicWriteFailure;
+ constructor(reason: TopicWriteFailure, message: string) {
+ super(message);
+ this.name = "TopicWriteError";
+ this.reason = reason;
+ }
+}
+
+export interface WriteTopicOptions extends DualWriteContext {
+ /** Force the partition: `true` private, `false` shared unless a named topic is private. */
+ readonly private?: boolean;
+}
+
+/** A fresh topic id. */
+export function newTopicId(nowMs: number = Date.now()): string {
+ return newUlid(nowMs);
+}
+
+/** The `topic-create` event of a new topic, with a fresh id. */
+export function createTopicEvent(input: {
+ readonly title: string;
+ readonly scope: string;
+ readonly authority: Authority;
+ readonly description?: string | null;
+ readonly goal?: string | null;
+ readonly agent?: string;
+ readonly now?: number;
+}): TopicEvent {
+ return {
+ kind: TOPIC_CREATE_KIND,
+ topic: newTopicId(input.now),
+ authority: input.authority,
+ body: {
+ title: input.title.trim(),
+ scope: input.scope,
+ ...(input.description !== undefined ? { description: input.description } : {}),
+ ...(input.goal !== undefined ? { goal: input.goal } : {}),
+ },
+ ...(input.agent !== undefined ? { agent: input.agent } : {}),
+ };
+}
+
+/** Topic ids an event names besides its own topic. */
+function namedTopics(event: TopicEvent): string[] {
+ switch (event.kind) {
+ case TOPIC_MERGE_KIND:
+ case TOPIC_SPLIT_KIND:
+ return [event.body["into"] as string];
+ case TOPIC_LINK_KIND:
+ return [event.body["to"] as string];
+ default:
+ return [];
+ }
+}
+
+/**
+ * Whether an undo names a record that sits in `private`: its topic may be
+ * out of the fold (an undone create), and nothing that names a private
+ * topic or a private record may land in `shared`.
+ */
+function undoesPrivate(read: TopicRead, event: TopicEvent): boolean {
+ return read.privateRecords.has(event.body["record"] as string);
+}
+
+/** Whether an event changes an item that has a record in `private`. */
+function touchesPrivateItem(read: TopicRead, event: TopicEvent): boolean {
+ const body = event.body;
+ const id = isTopicItemKind(event.kind)
+ ? body["item"]
+ : event.kind === TOPIC_MILESTONE_DONE_KIND
+ ? body["milestone"]
+ : event.kind === TOPIC_QUESTION_RESOLVED_KIND
+ ? body["question"]
+ : undefined;
+ if (typeof id !== "string") return false;
+ const home = read.fold.canonical(event.topic);
+ const topic = home === null ? undefined : read.fold.topics.get(home);
+ return topic?.items.some((i) => i.id === id && i.owner === event.topic && i.private) === true;
+}
+
+/** The store record of one event, after its shape is checked. */
+function recordOf(event: TopicEvent): DualWriteRecord {
+ const body = { ...event.body, [AUTHORITY_FIELD]: event.authority };
+ const reason = topicBodyRejection(event.kind, event.topic, body);
+ if (reason !== null) {
+ throw new TopicWriteError("invalid", `${event.kind} for topic ${event.topic}: ${reason}`);
+ }
+ return {
+ stream: TOPIC_STREAM,
+ kind: event.kind,
+ topic: event.topic,
+ ...(event.agent !== undefined ? { agent: event.agent } : {}),
+ ...(event.kind === TOPIC_CREATE_KIND ? { scope: event.body["scope"] as string } : {}),
+ body,
+ };
+}
+
+/**
+ * Append `events` as one store operation. Throws {@link TopicWriteError}
+ * for an invalid event, a topic that does not exist, or a topic shard this
+ * machine cannot read in full (the privacy of the topics named cannot be
+ * judged then), and `StoreWriteError` when the store refuses the write.
+ */
+export function writeTopicEvents(
+ events: ReadonlyArray<TopicEvent>,
+ options: WriteTopicOptions = {},
+): AppendResult[] {
+ if (events.length === 0) return [];
+ const records = events.map(recordOf);
+ // The writer judges privacy from every partition this machine holds,
+ // whatever the caller's reach: a remote caller's event for a private
+ // topic still belongs in `private`.
+ const read = withPrivateShown(() => readTopics(options.configPath));
+ if (read.unreadable.length > 0) {
+ // Below local reach the shards are not named: they may be private ones.
+ const named = privateWithheld() ? "" : ` (${read.unreadable.join(", ")})`;
+ throw new TopicWriteError(
+ "unreadable",
+ `the topics stream cannot be read in full${named}; run ` +
+ "`o2b brain doctor` and retry once sync has delivered it",
+ );
+ }
+ const created = new Map(
+ events.filter((e) => e.kind === TOPIC_CREATE_KIND).map((e) => [e.topic, e] as const),
+ );
+ for (const event of events) {
+ // An undo is checked by the record it names, whose topic may be gone.
+ if (
+ event.kind === TOPIC_UNDO_KIND &&
+ read.recordTopics.get(event.body["record"] as string) === event.topic
+ ) {
+ continue;
+ }
+ for (const id of [event.topic, ...namedTopics(event)]) {
+ if (!created.has(id) && !read.fold.topics.has(id)) {
+ throw new TopicWriteError("unknown-topic", `${event.kind}: no topic with id ${id}`);
+ }
+ }
+ }
+ const personal = [...created.values()].some((e) => e.body["scope"] === TOPIC_PERSONAL_SCOPE);
+ const named = events.flatMap((e) => [e.topic, ...namedTopics(e)]);
+ const isPrivate =
+ options.private === true ||
+ (options.private === undefined && personal) ||
+ named.some((id) => read.fold.topics.get(id)?.private === true) ||
+ events.some((e) => e.kind === TOPIC_UNDO_KIND && undoesPrivate(read, e)) ||
+ events.some((e) => touchesPrivateItem(read, e));
+ return storeWrite(() => records.map((r) => (isPrivate ? { ...r, private: true } : r)), options);
+}
diff --git a/src/core/view/auto-render.ts b/src/core/view/auto-render.ts
index 36974288..74467370 100644
--- a/src/core/view/auto-render.ts
+++ b/src/core/view/auto-render.ts
@@ -153,8 +153,10 @@ export function describeAutoView(result: AutoViewResult): string {
case "rendered": {
const written = result.pages.filter((p) => p.status === "written").length;
const deferred = result.pages.filter((p) => p.status === "deferred").length;
+ const removed = result.pages.filter((p) => p.status === "removed").length;
return (
- `rendered ${result.pages.length} page(s), ${written} changed` +
+ `rendered ${result.pages.length - removed} page(s), ${written} changed` +
+ (removed > 0 ? `, ${removed} removed` : "") +
(deferred > 0 ? `, ${deferred} deferred to the next pass` : "")
);
}
@@ -185,7 +187,9 @@ export function autoViewAudit(result: AutoViewResult): [boolean, Record<string,
const failed =
result.status === "rendered"
? result.pages
- .filter((p) => p.status !== "written" && p.status !== "unchanged")
+ .filter(
+ (p) => p.status !== "written" && p.status !== "unchanged" && p.status !== "removed",
+ )
.map((p) => ({
page: p.page,
status: p.status,
diff --git a/src/core/view/constants.ts b/src/core/view/constants.ts
index 32aa7305..a403072b 100644
--- a/src/core/view/constants.ts
+++ b/src/core/view/constants.ts
@@ -27,6 +27,33 @@ export const VIEW_DECISIONS_PAGE = "decisions.md";
/** Folder of the weekly history pages, `history/<YYYY>-W<ww>.md`. */
export const VIEW_HISTORY_DIR = "history";
+/** Folder of the topic pages, `topics/<YYYY-MM-DD>-<slug>/topic.md`. */
+export const VIEW_TOPICS_DIR = "topics";
+
+/** The page of one topic, in its folder. */
+export const VIEW_TOPIC_PAGE = "topic.md";
+
+/** The companion archive of a topic page, in the same folder. */
+export const VIEW_TOPIC_ARCHIVE_PAGE = "archive.md";
+
+/** Folder of the research report pages, `reports/<entry>.md`. */
+export const VIEW_REPORTS_DIR = "reports";
+
+/** Folder of the source summary pages, `sources/<entry>.md`. */
+export const VIEW_SOURCES_DIR = "sources";
+
+/**
+ * Folders whose pages come and go with their records (a topic renamed,
+ * merged or undone, a report removed): a page there that the store no
+ * longer renders is removed by the view writer, after any edit it carries
+ * is ingested.
+ */
+export const VIEW_RETIRING_DIRS = Object.freeze([
+ VIEW_TOPICS_DIR,
+ VIEW_REPORTS_DIR,
+ VIEW_SOURCES_DIR,
+]);
+
/** Extension of every view page. */
export const VIEW_PAGE_EXT = ".md";
diff --git a/src/core/view/corrections.ts b/src/core/view/corrections.ts
index 6d979351..ed6eb145 100644
--- a/src/core/view/corrections.ts
+++ b/src/core/view/corrections.ts
@@ -13,7 +13,11 @@
* - any other generated line reworded: a `view-correction` of that line's
* key with the user's text; deleted: a `view-correction` that hides it;
* - a line the user added: a `view-addition` placed after the nearest
- * generated line above it.
+ * generated line above it;
+ * - a line of a topic page (keyed `t:<topic id>:...`): the topic record
+ * that says the same thing (`topic-edits.ts`), so the edit lands on
+ * the topic and follows it through a rename; a topic line that module
+ * does not map takes the generic correction above.
*
* The id comment line and blank layout lines are never mapped. The next
* render folds the corrections back in (see {@link applyCorrections}), so
@@ -22,18 +26,15 @@
*/
import { AUTHORITY_FIELD, PREFERENCE_SET_KIND } from "../store/constants.ts";
-import type { RecordBody, StoreRecord } from "../store/envelope.ts";
+import type { StoreRecord } from "../store/envelope.ts";
import { prepareRecords, recordAuthority, RegisterSet, TOMBSTONE } from "../store/fold.ts";
import { VIEW_ABOUT_ME_PAGE, VIEW_ADDITION_KIND, VIEW_CORRECTION_KIND } from "./constants.ts";
+import type { EditRecord } from "./edit-record.ts";
import { alignable, diffLines } from "./line-diff.ts";
import { ID_LINE_KEY, type PageLine, type PageModel } from "./pages.ts";
+import { topicAddition, topicCorrection } from "./topic-edits.ts";
-/** A record an edit produces, before the caller picks its partition. */
-export interface EditRecord {
- readonly stream: "events";
- readonly kind: string;
- readonly body: RecordBody;
-}
+export type { EditRecord } from "./edit-record.ts";
/** Retired status a deleted rule line sets. */
const RETIRED = "retired";
@@ -158,7 +159,7 @@ export function applyCorrections(
for (const add of byAnchor.get(null) ?? []) {
emit({ key: `${ADDITION_KEY_PREFIX}${add.id}`, text: add.text });
}
- return { page: model.page, lines };
+ return { ...model, lines };
}
function correction(page: string, key: string, text: string | null): EditRecord {
@@ -190,6 +191,21 @@ function addition(page: string, after: string | null, text: string): EditRecord
};
}
+/** The records of one changed keyed line: a topic record when it maps, else a correction. */
+function correctionRecords(
+ page: string,
+ key: string,
+ before: string,
+ text: string | null,
+): EditRecord[] {
+ return topicCorrection(key, before, text) ?? [correction(page, key, text)];
+}
+
+/** The records of one added line: a topic item when its anchor is in one, else an addition. */
+function additionRecords(page: string, anchor: string | null, text: string): EditRecord[] {
+ return topicAddition(anchor, text) ?? [addition(page, anchor, text)];
+}
+
/** The key of the nearest keyed line at or above `index`, the id line excluded. */
function anchorAt(keys: ReadonlyArray<string | null>, index: number): string | null {
for (let i = index; i >= 0; i--) {
@@ -229,21 +245,24 @@ export function editRecords(
continue;
}
if (key === null) {
- if (text.trim() !== "") out.push(addition(page, anchor, text));
+ if (text.trim() !== "") out.push(...additionRecords(page, anchor, text));
continue;
}
// A line cleared down to its list marker is emptied too.
const emptied = text.replace(BARE_LIST_MARKER_RE, "").trim() === "";
- out.push(correction(page, key, emptied ? null : text));
+ const before = base[hunk.baseStart + p]!;
+ out.push(...correctionRecords(page, key, before, emptied ? null : text));
anchor = key;
}
for (let p = paired; p < baseLen; p++) {
const key = baseKeys[hunk.baseStart + p] ?? null;
- if (key !== null && key !== ID_LINE_KEY) out.push(correction(page, key, null));
+ if (key !== null && key !== ID_LINE_KEY) {
+ out.push(...correctionRecords(page, key, base[hunk.baseStart + p]!, null));
+ }
}
for (let p = paired; p < otherLen; p++) {
const text = edited[hunk.otherStart + p]!.trimEnd();
- if (text.trim() !== "") out.push(addition(page, anchor, text));
+ if (text.trim() !== "") out.push(...additionRecords(page, anchor, text));
}
}
return out;
@@ -276,6 +295,8 @@ export function reviewedEdits(
function isDeletion(record: EditRecord): boolean {
if (record.kind === VIEW_CORRECTION_KIND) return record.body["hidden"] === true;
+ // A topic item's tombstone, or an undo of a goal proposal.
+ if (record.stream === "topics") return record.body["removed"] === true || record.kind === "undo";
const fields = record.body["fields"] as Record<string, unknown> | undefined;
return record.kind === PREFERENCE_SET_KIND && fields?.["status"] === RETIRED;
}
diff --git a/src/core/view/edit-record.ts b/src/core/view/edit-record.ts
new file mode 100644
index 00000000..aeb1a0d0
--- /dev/null
+++ b/src/core/view/edit-record.ts
@@ -0,0 +1,16 @@
+/**
+ * A record that a human edit of a view page produces, before the ingest
+ * picks its partition (`view-records.ts`). A leaf module: the edit
+ * mappers of every page family (`corrections.ts`, `topic-edits.ts`) build
+ * it and the ingest writes it.
+ */
+
+import type { RecordBody } from "../store/envelope.ts";
+
+export interface EditRecord {
+ readonly stream: "events" | "topics";
+ readonly kind: string;
+ readonly body: RecordBody;
+ /** The topic id a topic record belongs to (the envelope `topic`). */
+ readonly topic?: string;
+}
diff --git a/src/core/view/i18n.ts b/src/core/view/i18n.ts
index ad10a19f..de87e758 100644
--- a/src/core/view/i18n.ts
+++ b/src/core/view/i18n.ts
@@ -9,6 +9,11 @@
* primary subtag, so `pt-BR` would use a `pt` table.
*/
+import type { TopicLogClass, TopicStatus } from "../topics/constants.ts";
+
+/** Log classes a topic page shows (every class but `routine`). */
+export type EarnedLogClass = Exclude<TopicLogClass, "routine">;
+
export interface ViewStrings {
readonly aboutTitle: string;
readonly aboutIntro: string;
@@ -25,6 +30,37 @@ export interface ViewStrings {
readonly historyRetired: (text: string) => string;
/** Monday first, as ISO weeks count. */
readonly weekdays: ReadonlyArray<string>;
+ readonly topicStatus: Readonly<Record<TopicStatus, string>>;
+ /** The status line of a topic page; `resolved` for a done topic. */
+ readonly statusLine: (label: string, resolved: string | null) => string;
+ /** The label before the status on its line, as {@link statusLine} writes it. */
+ readonly statusLabel: string;
+ readonly topicNoDescription: string;
+ readonly topicGoal: string;
+ readonly topicMilestones: string;
+ readonly topicDecisions: string;
+ readonly topicQuestions: string;
+ readonly topicResolvedQuestions: string;
+ readonly topicLog: string;
+ readonly topicRelated: string;
+ readonly milestoneDone: (day: string) => string;
+ readonly milestoneLooksDone: string;
+ readonly questionLooksAnswered: string;
+ readonly questionAnswer: (answer: string) => string;
+ readonly goalProposal: (agent: string, goal: string) => string;
+ readonly serves: (list: string) => string;
+ readonly logClass: Readonly<Record<EarnedLogClass, string>>;
+ readonly because: (reason: string) => string;
+ readonly scopePersonal: string;
+ readonly scopeProject: (project: string) => string;
+ readonly mergedFrom: (title: string) => string;
+ readonly archiveLink: string;
+ readonly archiveTitle: (title: string) => string;
+ readonly archiveIntro: string;
+ readonly archiveBack: string;
+ readonly reportIntro: (day: string) => string;
+ readonly sourceTitle: (source: string) => string;
+ readonly sourceIntro: (day: string) => string;
}
const EN: ViewStrings = {
@@ -44,6 +80,50 @@ const EN: ViewStrings = {
historyRule: (text) => `New rule: ${text}`,
historyRetired: (text) => `You retired a rule: ${text}`,
weekdays: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
+ topicStatus: {
+ active: "Active",
+ waiting: "Waiting",
+ blocked: "Blocked",
+ "on-hold": "On hold",
+ done: "Done",
+ closed: "Closed",
+ },
+ statusLine: (label, resolved) =>
+ resolved === null ? `Status: ${label}` : `Status: ${label} (resolved ${resolved})`,
+ statusLabel: "Status",
+ topicNoDescription: "No description yet.",
+ topicGoal: "Goal",
+ topicMilestones: "Milestones",
+ topicDecisions: "Decisions",
+ topicQuestions: "Open questions",
+ topicResolvedQuestions: "Resolved questions",
+ topicLog: "Log",
+ topicRelated: "Related",
+ milestoneDone: (day) => `done ${day}`,
+ milestoneLooksDone: "looks done, confirm",
+ questionLooksAnswered: "looks answered, confirm",
+ questionAnswer: (answer) => `answer: ${answer}`,
+ goalProposal: (agent, goal) => `Goal proposed by ${agent}: ${goal}`,
+ serves: (list) => `serves: ${list}`,
+ logClass: {
+ correction: "correction",
+ decision: "decision",
+ blocker: "blocker",
+ reframing: "reframing",
+ rejected: "rejected approach",
+ note: "note",
+ },
+ because: (reason) => `because ${reason}`,
+ scopePersonal: "Personal matter",
+ scopeProject: (project) => `Project: ${project}`,
+ mergedFrom: (title) => `Merged from: ${title}`,
+ archiveLink: "Older entries",
+ archiveTitle: (title) => `${title}: archive`,
+ archiveIntro: "Entries that moved off the topic page, newest first.",
+ archiveBack: "Back to the topic",
+ reportIntro: (day) => `Research report of ${day}.`,
+ sourceTitle: (source) => `Source: ${source}`,
+ sourceIntro: (day) => `Summary of a source, updated ${day}.`,
};
const RU: ViewStrings = {
@@ -63,6 +143,50 @@ const RU: ViewStrings = {
historyRule: (text) => `Новое правило: ${text}`,
historyRetired: (text) => `Вы сняли правило: ${text}`,
weekdays: ["Понедельник", "Вторник", "Среда", "Четверг", "Пятница", "Суббота", "Воскресенье"],
+ topicStatus: {
+ active: "Активна",
+ waiting: "Ожидает",
+ blocked: "Заблокирована",
+ "on-hold": "Отложена",
+ done: "Готова",
+ closed: "Закрыта",
+ },
+ statusLine: (label, resolved) =>
+ resolved === null ? `Статус: ${label}` : `Статус: ${label} (решена ${resolved})`,
+ statusLabel: "Статус",
+ topicNoDescription: "Описания пока нет.",
+ topicGoal: "Цель",
+ topicMilestones: "Вехи",
+ topicDecisions: "Решения",
+ topicQuestions: "Открытые вопросы",
+ topicResolvedQuestions: "Решённые вопросы",
+ topicLog: "Журнал",
+ topicRelated: "Связанное",
+ milestoneDone: (day) => `готово ${day}`,
+ milestoneLooksDone: "похоже, готово, подтвердите",
+ questionLooksAnswered: "похоже, есть ответ, подтвердите",
+ questionAnswer: (answer) => `ответ: ${answer}`,
+ goalProposal: (agent, goal) => `Цель, предложенная ${agent}: ${goal}`,
+ serves: (list) => `служит: ${list}`,
+ logClass: {
+ correction: "исправление",
+ decision: "решение",
+ blocker: "блокер",
+ reframing: "переосмысление",
+ rejected: "отвергнутый подход",
+ note: "заметка",
+ },
+ because: (reason) => `потому что ${reason}`,
+ scopePersonal: "Личное дело",
+ scopeProject: (project) => `Проект: ${project}`,
+ mergedFrom: (title) => `Объединена из: ${title}`,
+ archiveLink: "Старые записи",
+ archiveTitle: (title) => `${title}: архив`,
+ archiveIntro: "Записи, ушедшие со страницы темы, сначала новые.",
+ archiveBack: "Назад к теме",
+ reportIntro: (day) => `Исследовательский отчёт от ${day}.`,
+ sourceTitle: (source) => `Источник: ${source}`,
+ sourceIntro: (day) => `Сводка источника, обновлена ${day}.`,
};
const TABLES: Readonly<Record<string, ViewStrings>> = { en: EN, ru: RU };
@@ -78,6 +202,11 @@ export function isViewLanguage(tag: string): boolean {
return Object.hasOwn(TABLES, tag.split("-")[0]!.toLowerCase());
}
+/** The strings of every language the view has, English first. */
+export function allViewStrings(): ReadonlyArray<ViewStrings> {
+ return Object.values(TABLES);
+}
+
/** The strings for language tag `tag` (`null`: English). */
export function viewStrings(tag: string | null): ViewStrings {
const primary = (tag ?? "en").split("-")[0]!.toLowerCase();
diff --git a/src/core/view/lane-view-pages.ts b/src/core/view/lane-view-pages.ts
new file mode 100644
index 00000000..eb75e09d
--- /dev/null
+++ b/src/core/view/lane-view-pages.ts
@@ -0,0 +1,143 @@
+/**
+ * Report and source pages of the human view (design D7 "Pages"; spec
+ * brain-store "Report stored"; task 3.2): `reports/<entry>.md` for every
+ * research report and `sources/<entry>.md` for every ingested source
+ * summary, rendered from their `lane-entry` records (the lanes `reports`
+ * and `sources`) in the `shared` partition.
+ *
+ * A page shows the entry's title, one generated line (in the view
+ * language) with its day, and the entry's Markdown body as written, with
+ * Obsidian-only links turned into their plain text. A body line's key is
+ * a hash of its text and its occurrence, so a correction the user makes
+ * to a line follows it while the report keeps that line, and lapses when
+ * a rewrite of the report drops it.
+ *
+ * Left out: a removed entry, one whose fields reserve it as private, one
+ * whose record carries a `<private>` region, and an entry id that is not
+ * a plain file name.
+ */
+
+import { sha256Hex } from "../integrity/digest.ts";
+import {
+ foldLaneEntries,
+ LANE_ENTRY_KIND,
+ LANE_ENTRY_REMOVE_KIND,
+ type LaneEntryValue,
+} from "../store/lane-records.ts";
+import type { StoreRecord } from "../store/envelope.ts";
+import { isPrivateFrontmatter } from "../store/private-page.ts";
+import { valueCarriesPrivateRegion } from "../store/private-region.ts";
+import { compareCodeUnits } from "../store/compare.ts";
+import { VIEW_PAGE_EXT, VIEW_REPORTS_DIR, VIEW_SOURCES_DIR } from "./constants.ts";
+import type { ViewStrings } from "./i18n.ts";
+import { RESERVED_DEVICE_NAME_RE } from "./page-path.ts";
+import { idLine, plainText, type PageLine, type PageModel } from "./pages.ts";
+
+/** The lanes whose entries the view renders, and their folder. */
+const LANES = Object.freeze([
+ { lane: "reports", dir: VIEW_REPORTS_DIR },
+ { lane: "sources", dir: VIEW_SOURCES_DIR },
+] as const);
+
+/** An entry id that is a plain file name: dot-separated runs of letters, digits, `_` and `-`. */
+const ENTRY_RE = /^(?=.{1,128}$)[A-Za-z0-9][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/;
+
+const WIKILINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+const BLANK: PageLine = { key: null, text: "" };
+
+function field(value: LaneEntryValue, name: string): string | null {
+ const v = value.fields[name];
+ return typeof v === "string" && v.trim() !== "" ? v.trim() : null;
+}
+
+/** A body line with its Obsidian-only links written as plain text. */
+function plainLine(line: string): string {
+ return line
+ .replaceAll(WIKILINK_RE, (_all, target: string, alias: string | undefined) =>
+ (alias ?? target).trim(),
+ )
+ .trimEnd();
+}
+
+function bodyLines(prefix: string, text: string, title: string): PageLine[] {
+ const raw = text.replaceAll(/\r\n?/g, "\n").split("\n").map(plainLine);
+ // The body's own title heading is the page title already.
+ const first = raw.findIndex((l) => l.trim() !== "");
+ if (first >= 0 && raw[first]!.replace(/^#+\s*/, "").trim() === title) raw.splice(0, first + 1);
+ while (raw.length > 0 && raw[0]!.trim() === "") raw.shift();
+ while (raw.length > 0 && raw.at(-1)!.trim() === "") raw.pop();
+ const seen = new Map<string, number>();
+ return raw.map((line) => {
+ if (line.trim() === "") return BLANK;
+ const hash = sha256Hex(line).slice(0, 12);
+ const n = (seen.get(hash) ?? 0) + 1;
+ seen.set(hash, n);
+ return { key: `${prefix}:${hash}:${n}`, text: line };
+ });
+}
+
+function entryPage(
+ storeId: string,
+ dir: string,
+ lane: string,
+ value: LaneEntryValue,
+ strings: ViewStrings,
+): PageModel {
+ const page = `${dir}/${value.entry}${VIEW_PAGE_EXT}`;
+ const prefix = `e:${lane}:${value.entry}`;
+ const isReport = lane === "reports";
+ const title = isReport
+ ? (field(value, "title") ?? value.entry)
+ : strings.sourceTitle(plainText(field(value, "source_path") ?? value.entry));
+ const day =
+ (isReport ? field(value, "report_date") : field(value, "updated_at"))?.slice(0, 10) ?? null;
+ const lines: PageLine[] = [
+ idLine(storeId, page),
+ BLANK,
+ { key: `${prefix}:title`, text: `# ${plainText(title)}` },
+ ];
+ if (day !== null) {
+ lines.push(BLANK, {
+ key: `${prefix}:intro`,
+ text: isReport ? strings.reportIntro(day) : strings.sourceIntro(day),
+ });
+ }
+ const body = bodyLines(prefix, value.text, plainText(field(value, "title") ?? ""));
+ if (body.length > 0) lines.push(BLANK, ...body);
+ return { page, lines };
+}
+
+/** The report and source pages the `shared` records render to, in page order. */
+export function lanePages(
+ storeId: string,
+ shared: ReadonlyArray<StoreRecord>,
+ strings: ViewStrings,
+): PageModel[] {
+ const usable = shared.filter(
+ (r) =>
+ (r.kind === LANE_ENTRY_KIND || r.kind === LANE_ENTRY_REMOVE_KIND) &&
+ !valueCarriesPrivateRegion(r.body),
+ );
+ const fold = foldLaneEntries(usable);
+ const pages: PageModel[] = [];
+ for (const { lane, dir } of LANES) {
+ for (const state of fold.entries.values()) {
+ const value = state.value;
+ if (value === null || value.lane !== lane || !ENTRY_RE.test(value.entry)) continue;
+ if (RESERVED_DEVICE_NAME_RE.test(value.entry) || isPrivateFrontmatter(value.fields)) continue;
+ pages.push(entryPage(storeId, dir, lane, value, strings));
+ }
+ }
+ // Two ids that differ only in case are one file on a case-insensitive
+ // file system: the first in code unit order keeps the page, on every
+ // machine, and the other renders none.
+ const seen = new Set<string>();
+ return pages
+ .toSorted((a, b) => compareCodeUnits(a.page, b.page))
+ .filter((p) => {
+ const folded = p.page.toLowerCase();
+ if (seen.has(folded)) return false;
+ seen.add(folded);
+ return true;
+ });
+}
diff --git a/src/core/view/page-io.ts b/src/core/view/page-io.ts
index e797cb8c..1d971c61 100644
--- a/src/core/view/page-io.ts
+++ b/src/core/view/page-io.ts
@@ -29,25 +29,72 @@
import { randomBytes } from "node:crypto";
import {
closeSync,
+ constants as fsConstants,
+ copyFileSync,
+ existsSync,
+ lstatSync,
+ fstatSync,
fsyncSync,
linkSync,
mkdirSync,
openSync,
readdirSync,
readFileSync,
+ readlinkSync,
renameSync,
+ rmdirSync,
+ symlinkSync,
unlinkSync,
writeSync,
} from "node:fs";
+import type { Stats } from "node:fs";
import { basename, dirname, join } from "node:path";
+import { READ_NO_FOLLOW_FLAGS } from "../derived-store-guard.ts";
import { NO_LINK_CODES } from "../store/blobs.ts";
import { VIEW_PAGE_EXT, VIEW_TEMP_PREFIX } from "./constants.ts";
+/** A page name that is not a regular file (a symbolic link, a folder): never read through. */
+export class NotAPageFileError extends Error {
+ readonly code = "ENOTPAGE";
+ constructor(path: string) {
+ super(`not a regular file, left alone: ${path}`);
+ this.name = "NotAPageFileError";
+ }
+}
+
+/** Open errors of `O_NOFOLLOW` on a symbolic link (`EMLINK` on FreeBSD). */
+const LINK_REFUSED_CODES: ReadonlySet<string> = new Set(["ELOOP", "EMLINK"]);
+
+/**
+ * The bytes of the regular file at `path`, never following a symbolic
+ * link: a sync tool or another process may put a link under a page name
+ * after the path was checked. The `lstat` check refuses a link on every
+ * platform; where the platform has `O_NOFOLLOW` the open refuses one too,
+ * and the opened descriptor is checked again, so a link or a folder
+ * swapped in between is never read through.
+ */
+function readRegular(path: string): Buffer {
+ if (!lstatSync(path).isFile()) throw new NotAPageFileError(path);
+ let fd: number;
+ try {
+ fd = openSync(path, READ_NO_FOLLOW_FLAGS);
+ } catch (err) {
+ if (LINK_REFUSED_CODES.has(errnoCode(err) ?? "")) throw new NotAPageFileError(path);
+ throw err;
+ }
+ try {
+ if (!fstatSync(fd).isFile()) throw new NotAPageFileError(path);
+ return readFileSync(fd);
+ } finally {
+ closeSync(fd);
+ }
+}
+
/** The bytes of a page, or `null` when it does not exist. */
export function readPage(path: string): Buffer | null {
try {
- return readFileSync(path);
+ return readRegular(path);
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
if (code === "ENOENT" || code === "ENOTDIR") return null;
@@ -148,7 +195,7 @@ export function replacePage(
let replaced: Buffer | null = null;
if (captured) {
try {
- replaced = readFileSync(away);
+ replaced = readRegular(away);
} catch (err) {
// Unreadable right now (an antivirus or indexer holds it): the page
// goes back under its name, never left away.
@@ -206,6 +253,63 @@ function restore(away: string, path: string): void {
removeQuietly(away);
}
+/** A page taken out of its name, its bytes captured, until the caller settles it. */
+export interface CapturedPage {
+ readonly bytes: Buffer;
+ /** Remove the captured file, once its bytes are stored or known to be the writer's own. */
+ readonly discard: () => void;
+ /** Put the page back under its name (a new page under that name is newer and kept). */
+ readonly restore: () => void;
+}
+
+/**
+ * Take the page at `path` away from its name for removal: one atomic
+ * rename captures exactly the bytes on disk at that instant, an edit a
+ * sync tool delivered a moment before included. `null` when there is no
+ * page. The captured file keeps a temp name until the caller discards or
+ * restores it, so a crash in between leaves it recoverable.
+ */
+export function capturePage(path: string): CapturedPage | null {
+ const away = tempName(dirname(path), "old");
+ try {
+ renameSync(path, away);
+ } catch (err) {
+ if (errnoCode(err) === "ENOENT" || errnoCode(err) === "ENOTDIR") return null;
+ throw err;
+ }
+ let bytes: Buffer;
+ try {
+ bytes = readRegular(away);
+ } catch (err) {
+ if (err instanceof NotAPageFileError) putBackOther(away, path);
+ else restore(away, path);
+ throw err;
+ }
+ return { bytes, discard: () => removeQuietly(away), restore: () => restore(away, path) };
+}
+
+/**
+ * Put a captured name that is not a regular file (a folder, a symbolic
+ * link) back under its name, never replacing a name that exists now: a
+ * link is made again (which fails on an existing name) and never followed,
+ * a folder is renamed back (a rename never replaces a file or a non-empty
+ * folder), and anything else only while the name is free. When it cannot
+ * go back it stays under its temp name, nothing lost.
+ */
+function putBackOther(away: string, path: string): void {
+ try {
+ const stat = lstatSync(away);
+ if (stat.isSymbolicLink()) {
+ symlinkSync(readlinkSync(away), path);
+ removeQuietly(away);
+ } else if (stat.isDirectory() || lstatOrNull(path) === null) {
+ renameSync(away, path);
+ }
+ } catch {
+ // kept under the temp name
+ }
+}
+
/** Syncthing: `.sync-conflict-<YYYYMMDD>-<HHMMSS>-<device id prefix>`. */
const SYNCTHING_COPY_RE = /^\.sync-conflict-\d{8}-\d{6}-[a-z0-9]{7}$/;
/** Dropbox, Nextcloud and similar: ` (<who>conflicted copy <date ...>)`. */
@@ -240,7 +344,139 @@ export function conflictCopies(path: string): string[] {
.map((name) => join(dir, name));
}
-/** Remove a conflict copy once its content is in the store. */
-export function removeCopy(path: string): void {
- removeQuietly(path);
+/**
+ * Move what the user keeps in a topic folder (companion files beside the
+ * writer's pages) into the folder the topic moved to, when a rename moved
+ * its page. `skip` names the writer's own pages; temp files and names the
+ * new folder already has stay where they are; `only`, when given, limits
+ * the move to those names. Best effort: a file that cannot move stays in
+ * the old folder, which is then kept.
+ */
+export function moveCompanions(
+ fromDir: string,
+ toDir: string,
+ skip: ReadonlySet<string>,
+ only?: ReadonlySet<string>,
+): void {
+ for (const name of listCompanions(fromDir, skip)) {
+ if (only !== undefined && !only.has(name)) continue;
+ try {
+ mkdirSync(toDir, { recursive: true });
+ moveNoReplace(join(fromDir, name), join(toDir, name));
+ } catch {
+ // left in the old folder
+ }
+ }
+}
+
+/** The companion names in `dir` (none when it cannot be read): every name but `skip` and temp files. */
+export function listCompanions(dir: string, skip: ReadonlySet<string>): string[] {
+ try {
+ return readdirSync(dir).filter((n) => !skip.has(n) && !n.startsWith(VIEW_TEMP_PREFIX));
+ } catch {
+ return [];
+ }
+}
+
+/** Whether two stats are one version of one file: same file, same size, same modification time. */
+function sameVersion(a: Stats, b: Stats | null): boolean {
+ return (
+ b !== null && a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs
+ );
+}
+
+function lstatOrNull(path: string): Stats | null {
+ try {
+ return lstatSync(path);
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Move `from` to `to` without ever replacing a `to` that exists, even one
+ * a sync tool creates in the same instant: a file is linked to its new
+ * name (which fails on an existing name) and then unlinked, or, where the
+ * file system has no hard links, copied exclusively; a folder is renamed
+ * only onto no name (a rename may replace an empty folder, never a file
+ * or a non-empty folder). A symbolic link is left where it is.
+ *
+ * A move that cannot finish is taken back: when the old name holds another
+ * version by the time it would be removed (a sync tool delivered a newer
+ * one), or cannot be removed (Windows reports a file another program
+ * holds as `EPERM`, the same code as "no hard links"), the new name is
+ * taken back and the file stays where it was. Neither name is ever
+ * unlinked live: each is first renamed to a temp name, and only the
+ * version checked is removed there, so a version a sync tool delivers
+ * under either name meanwhile is put back, never deleted. One case is
+ * left: a file another program holds open against deletion can be linked
+ * but neither name can then be removed, so it stays under both names
+ * until that program lets go.
+ */
+function moveNoReplace(from: string, to: string): void {
+ const stat = lstatSync(from);
+ if (stat.isSymbolicLink()) return;
+ if (stat.isDirectory()) {
+ if (existsSync(to)) return;
+ renameSync(from, to);
+ return;
+ }
+ // The version this move put under the new name: the source itself for a
+ // link, the copy as written otherwise.
+ let placed = stat;
+ try {
+ linkSync(from, to);
+ } catch (err) {
+ const code = errnoCode(err);
+ if (code === undefined || !NO_LINK_CODES.has(code)) throw err;
+ copyFileSync(from, to, fsConstants.COPYFILE_EXCL);
+ placed = lstatSync(to);
+ }
+ const now = lstatOrNull(from);
+ if (now === null) return; // gone meanwhile: the new name holds the only copy
+ if (!sameVersion(stat, now)) {
+ removeIfVersion(to, placed);
+ return;
+ }
+ const away = tempName(dirname(from), "move");
+ try {
+ renameSync(from, away);
+ } catch (err) {
+ if (errnoCode(err) === "ENOENT") return; // gone meanwhile, as above
+ removeIfVersion(to, placed);
+ throw err;
+ }
+ if (sameVersion(stat, lstatOrNull(away))) {
+ removeQuietly(away);
+ return;
+ }
+ // A newer version took the old name between the check and the rename:
+ // it goes back under that name, and the move is taken back.
+ restore(away, from);
+ removeIfVersion(to, placed);
+}
+
+/**
+ * Remove `path` only while it is still the version `ours` (the name this
+ * move created): it is renamed to a temp name first and checked there, so
+ * a file a sync tool put under the name meanwhile is put back, not removed.
+ */
+function removeIfVersion(path: string, ours: Stats): void {
+ const away = tempName(dirname(path), "back");
+ try {
+ renameSync(path, away);
+ } catch {
+ return; // gone already
+ }
+ if (sameVersion(ours, lstatOrNull(away))) removeQuietly(away);
+ else restore(away, path);
+}
+
+/** Remove a page folder once nothing is left in it; a folder with anything in it stays. */
+export function removeEmptyFolder(dir: string): void {
+ try {
+ rmdirSync(dir);
+ } catch {
+ // not empty, or already gone
+ }
}
diff --git a/src/core/view/page-path.ts b/src/core/view/page-path.ts
new file mode 100644
index 00000000..ed4d462d
--- /dev/null
+++ b/src/core/view/page-path.ts
@@ -0,0 +1,103 @@
+/**
+ * The only page paths the view writer ever touches on disk (review
+ * finding: a forged `view-render` record). A page path comes from store
+ * records any device that syncs `shared` can write, so it is checked
+ * twice before any file operation:
+ *
+ * 1. against the exact shape the renderer produces for its folders
+ * (`topics/<YYYY-MM-DD>-<slug>/topic.md` and `archive.md`,
+ * `reports/<entry>.md`, `sources/<entry>.md`): forward slashes only,
+ * no `..`, no backslash, no empty segment, no drive or root;
+ * 2. by resolving it under the view folder and requiring the result to
+ * stay strictly inside that folder, on the host's own path rules, as
+ * text and on disk (no symbolic link below the view folder, and the
+ * real path of the page's folder inside the real view folder).
+ *
+ * A path that fails either check is never read, captured, ingested,
+ * moved or removed.
+ */
+
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { VIEW_REPORTS_DIR, VIEW_SOURCES_DIR, VIEW_TOPICS_DIR } from "./constants.ts";
+
+/** A topic folder: the creation day and a slug of letters and digits of any script, hyphen-joined. */
+const TOPIC_FOLDER_RE = /^\d{4}-\d{2}-\d{2}-[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u;
+const TOPIC_PAGE_RE = /^(?:topic|archive)\.md$/;
+/** A report or source entry file: the lane entry id the renderer accepts, then `.md`. */
+const ENTRY_PAGE_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*\.md$/;
+/** Names Windows reserves for devices, refused with any extension. */
+export const RESERVED_DEVICE_NAME_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+
+/** Whether `page` has the exact shape of a page the renderer writes in a retiring folder. */
+export function isRetiringPageShape(page: string): boolean {
+ if (page.includes("\\") || page.includes("\u0000")) return false;
+ const parts = page.split("/");
+ if (parts.some((p) => p === "" || p === "." || p === "..")) return false;
+ if (parts[0] === VIEW_TOPICS_DIR) {
+ return parts.length === 3 && TOPIC_FOLDER_RE.test(parts[1]!) && TOPIC_PAGE_RE.test(parts[2]!);
+ }
+ if (parts[0] === VIEW_REPORTS_DIR || parts[0] === VIEW_SOURCES_DIR) {
+ return (
+ parts.length === 2 &&
+ parts[1]!.length <= 140 &&
+ ENTRY_PAGE_RE.test(parts[1]!) &&
+ !RESERVED_DEVICE_NAME_RE.test(parts[1]!)
+ );
+ }
+ return false;
+}
+
+function inside(root: string, path: string): boolean {
+ const rel = relative(root, path);
+ return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/** Whether `path` exists and is a symbolic link (or, on Windows, a junction). */
+function isLink(path: string): boolean | null {
+ try {
+ return lstatSync(path).isSymbolicLink();
+ } catch {
+ return null; // absent: nothing below it exists either
+ }
+}
+
+/**
+ * The file of view page `page` under the view folder `target`, or `null`
+ * when it would resolve to the folder itself or outside it, as text or on
+ * disk: no folder below the view folder, nor the page itself, may be a
+ * symbolic link, and the real path of the page's folder must stay inside
+ * the real path of the view folder. The view folder itself may be a link.
+ */
+export function pageFileInside(target: string, page: string): string | null {
+ const root = resolve(target);
+ const file = resolve(root, ...page.split("/"));
+ if (!inside(root, file)) return null;
+ let at = root;
+ for (const part of relative(root, file).split(sep)) {
+ at = join(at, part);
+ const link = isLink(at);
+ if (link === null) break;
+ if (link) return null;
+ }
+ let realRoot: string;
+ try {
+ realRoot = realpathSync(root);
+ } catch {
+ return file; // no view folder yet: nothing below it can be a link
+ }
+ let folder = dirname(file);
+ while (folder !== root && isLink(folder) === null) folder = dirname(folder);
+ if (folder === root) return file;
+ try {
+ return inside(realRoot, realpathSync(folder)) ? file : null;
+ } catch {
+ return null;
+ }
+}
+
+/** The file of a page in a retiring folder, when both checks pass; `null` otherwise. */
+export function retiringPageFile(target: string, page: string): string | null {
+ return isRetiringPageShape(page) ? pageFileInside(target, page) : null;
+}
diff --git a/src/core/view/pages.ts b/src/core/view/pages.ts
index 52a1f133..5ea2909f 100644
--- a/src/core/view/pages.ts
+++ b/src/core/view/pages.ts
@@ -55,6 +55,8 @@ export interface PageLine {
export interface PageModel {
readonly page: string;
readonly lines: ReadonlyArray<PageLine>;
+ /** The topic a topic page or archive shows. */
+ readonly topic?: string;
}
/** Key of the id comment line; never mapped to a record. */
diff --git a/src/core/view/render.ts b/src/core/view/render.ts
index eaaf555c..5ec755e6 100644
--- a/src/core/view/render.ts
+++ b/src/core/view/render.ts
@@ -22,19 +22,22 @@
* the replacement and capturing the bytes it replaces; a racing
* edit in those bytes is ingested and the page rendered again;
* d. writes the render record with the new merge base;
- * 4. writes a `view-pass` heartbeat when it wrote nothing for a day.
+ * 4. before the pages, removes the pages of a retiring folder (topics,
+ * reports, sources) the store no longer renders (a renamed, merged or
+ * undone topic, a removed report), ingesting any edit they carry
+ * first, and moves a renamed topic's companion files to its new
+ * folder;
+ * 5. writes a `view-pass` heartbeat when it wrote nothing for a day.
*
* A missing or empty page is never read as an edit (deleting a page does
* not retire every rule on it); it is rendered again.
*/
-import { join } from "node:path";
-
import { PartitionUnavailableError } from "../store/appender.ts";
import { SETTING_VIEW_LANGUAGE } from "../store/constants.ts";
import { foldSettings, settingValue } from "../store/fold-settings.ts";
import { withLocalLock } from "../store/local-lock.ts";
-import { textCarriesPrivateRegion } from "../store/private-region.ts";
+import { textCarriesPrivateRegion, valueCarriesPrivateRegion } from "../store/private-region.ts";
import type { StoreHandle } from "../store/store-open.ts";
import {
catchUp,
@@ -43,11 +46,20 @@ import {
withOwnRecord,
type ViewCatchUp,
} from "./catch-up.ts";
+import { foldTopics } from "../topics/fold.ts";
import { VIEW_RENDER_ATTEMPTS } from "./constants.ts";
import { applyCorrections, foldCorrections, pageLines, reviewedEdits } from "./corrections.ts";
import { viewStrings } from "./i18n.ts";
import { matchLines, mergeLines } from "./line-diff.ts";
-import { conflictCopies, readPage, removeCopy, replacePage, type ReplaceHooks } from "./page-io.ts";
+import { lanePages } from "./lane-view-pages.ts";
+import {
+ capturePage,
+ conflictCopies,
+ NotAPageFileError,
+ readPage,
+ replacePage,
+ type ReplaceHooks,
+} from "./page-io.ts";
import {
aboutMePage,
confirmedPreferences,
@@ -76,6 +88,9 @@ import {
} from "./view-records.ts";
import { claimSettled, releaseIfRequested, renderLockTarget } from "./writer.ts";
import { readPageStats, sameStat, statPage, writePageStats, type PageStats } from "./page-stats.ts";
+import { pageFileInside } from "./page-path.ts";
+import { retirePages, type RetireContext } from "./retire.ts";
+import { topicPages } from "./topic-pages.ts";
import { foldViewWriter } from "./writer-fold.ts";
export interface ViewPassOptions extends RecordOptions {
@@ -93,7 +108,14 @@ export interface ViewPassOptions extends RecordOptions {
/** What happened to one page. */
export interface PageReport {
readonly page: string;
- readonly status: "written" | "unchanged" | "refused" | "busy" | "base-pending" | "deferred";
+ readonly status:
+ | "written"
+ | "unchanged"
+ | "removed"
+ | "refused"
+ | "busy"
+ | "base-pending"
+ | "deferred";
/** Human records written from edits of this page. */
readonly ingested: number;
readonly detail?: string;
@@ -117,10 +139,15 @@ export function buildPages(store: StoreHandle, read: ViewCatchUp): Map<string, P
const prefs = confirmedPreferences(all);
const entries = viewEntries(shared, all);
const corrections = foldCorrections(shared);
+ // Topic records that carry a `<private>` region stay off the pages, as
+ // every other record family's do.
+ const topics = foldTopics(shared.filter((r) => !valueCarriesPrivateRegion(r.body)));
const models = [
aboutMePage(store.storeId, prefs, strings),
decisionsPage(store.storeId, entries, strings),
...historyPages(store.storeId, entries, strings),
+ ...topicPages(store.storeId, topics, strings),
+ ...lanePages(store.storeId, shared, strings),
];
return new Map(models.map((m) => [m.page, applyCorrections(m, corrections)]));
}
@@ -228,13 +255,23 @@ function renderPageNow(ctx: PageContext, page: string, path: string): PageReport
privateEdit = done.isPrivate;
}
for (const copy of conflictCopies(path)) {
- const bytes = readPage(copy);
- if (hasContent(bytes) && !own.has(bytesSum(bytes))) {
- const done = ingest(ctx, page, base, bytes.toString("utf8"), "conflict-copy");
- ingested += done.records;
- privateEdit ||= done.isPrivate;
+ // A name that is not a regular file (a folder, a link) is refused
+ // where it is. A copy is taken out of its name before it is read: one
+ // a sync tool writes again meanwhile is left for the next pass.
+ readPage(copy);
+ const captured = capturePage(copy);
+ if (captured === null) continue;
+ try {
+ if (hasContent(captured.bytes) && !own.has(bytesSum(captured.bytes))) {
+ const done = ingest(ctx, page, base, captured.bytes.toString("utf8"), "conflict-copy");
+ ingested += done.records;
+ privateEdit ||= done.isPrivate;
+ }
+ } catch (err) {
+ captured.restore();
+ throw err;
}
- removeCopy(copy);
+ captured.discard();
}
const model = modelOf(ctx, page);
if (model === undefined) return { page, status: "unchanged", ingested };
@@ -250,6 +287,7 @@ function renderPageNow(ctx: PageContext, page: string, path: string): PageReport
const bytes = Buffer.from(text, "utf8");
const intent = {
page,
+ ...(model.topic !== undefined ? { topic: model.topic } : {}),
sum: bytesSum(bytes),
base: writeBase(ctx.store, page, { text, keys }),
bytes: bytes.length,
@@ -289,7 +327,13 @@ function renderPageNow(ctx: PageContext, page: string, path: string): PageReport
/** Write the render records a dead pass left only as intents. */
function recoverIntents(ctx: PageContext, target: string): void {
for (const intent of pendingIntents(ctx.store)) {
- const disk = readPage(join(target, ...intent.page.split("/")));
+ const path = pageFileInside(target, intent.page);
+ let disk: Buffer | null = null;
+ try {
+ disk = path === null ? null : readPage(path);
+ } catch (err) {
+ if (!(err instanceof NotAPageFileError)) throw err;
+ }
const recorded = ownSums(ctx.read, intent.page).has(intent.sum);
if (disk !== null && bytesSum(disk) === intent.sum && !recorded) {
writeRender(ctx.store, intent, ctx.options);
@@ -306,27 +350,54 @@ function renderPages(ctx: PageContext, target: string): PageReport[] {
recoverIntents(ctx, target);
const reports: PageReport[] = [];
ctx.models ??= buildPages(ctx.store, ctx.read);
+ const retire: RetireContext = {
+ store: ctx.store,
+ read: () => ctx.read,
+ models: () => (ctx.models ??= buildPages(ctx.store, ctx.read)),
+ stats: ctx.stats,
+ ingest: (page, base, text, reason) => ingest(ctx, page, base, text, reason).records,
+ };
+ reports.push(...retirePages(retire, target, pageFailure, ctx.options.shouldStop));
+ ctx.models ??= buildPages(ctx.store, ctx.read);
+ // The page list of this pass: an ingest may rebuild the models, and a
+ // page it renamed is retired by the next pass.
for (const page of ctx.models.keys()) {
if (ctx.options.shouldStop?.() === true) {
reports.push({ page, status: "deferred", ingested: 0, detail: "the time budget ran out" });
continue;
}
+ // A page whose folder is a link (or leads out of the view) is never written.
+ const path = pageFileInside(target, page);
+ if (path === null) {
+ reports.push({
+ page,
+ status: "refused",
+ ingested: 0,
+ detail: "the page path leaves the view",
+ });
+ continue;
+ }
try {
- reports.push(renderOnePage(ctx, page, join(target, ...page.split("/"))));
+ reports.push(renderOnePage(ctx, page, path));
} catch (err) {
- if (err instanceof PartitionUnavailableError) {
- reports.push({ page, status: "refused", ingested: 0, detail: err.message });
- } else if (PAGE_BUSY_CODES.has((err as NodeJS.ErrnoException).code ?? "")) {
- // Windows refuses to rename a page another program holds open.
- reports.push({ page, status: "busy", ingested: 0, detail: (err as Error).message });
- } else {
- throw err;
- }
+ reports.push(pageFailure(page, err));
}
}
return reports;
}
+/** The report of a page whose render or removal failed for a reason a later pass may not have. */
+function pageFailure(page: string, err: unknown): PageReport {
+ if (err instanceof PartitionUnavailableError || err instanceof NotAPageFileError) {
+ return { page, status: "refused", ingested: 0, detail: err.message };
+ }
+ if (PAGE_BUSY_CODES.has((err as NodeJS.ErrnoException).code ?? "")) {
+ // Windows refuses to rename a page another program holds open.
+ return { page, status: "busy", ingested: 0, detail: (err as Error).message };
+ }
+ throw err;
+}
+
/** One render pass on this machine. */
export function runViewPass(store: StoreHandle, options: ViewPassOptions): ViewPassReport {
// The writer records first: a machine that is not the writer reads
diff --git a/src/core/view/retire.ts b/src/core/view/retire.ts
new file mode 100644
index 00000000..880d070e
--- /dev/null
+++ b/src/core/view/retire.ts
@@ -0,0 +1,322 @@
+/**
+ * Pages that leave the view (task 3.2, design D16 item 10): a topic
+ * renamed, merged or undone, a report removed, or a topic folder another
+ * topic now takes. Split from `render.ts`, which calls it before it
+ * renders the pages of a pass.
+ *
+ * Two kinds of page leave:
+ *
+ * - a page of a retiring folder (`topics/`, `reports/`, `sources/`) a
+ * render record names and the store no longer renders;
+ * - a page the store still renders whose file on disk names another
+ * topic in its id line: the folder slot passed from one topic to
+ * another (a rename, or a topic with an earlier clock that synced in
+ * late), so the old topic's page and the user's files in its folder
+ * belong elsewhere now.
+ *
+ * Either way an edit the page carries, and every conflict copy of it, is
+ * ingested first, as before a render; the page leaves its name by one
+ * atomic rename, so an edit that lands right before it is captured too;
+ * and the user's companion files of a topic folder follow the topic to
+ * its current folder. A topic page whose file is already gone (a pass
+ * that died after removing it) still has its companions moved, by the
+ * topic its last render record names.
+ *
+ * Every page path comes from store records any device can write, so it
+ * passes the exact shape check and the inside-the-view check of
+ * `page-path.ts` before any file operation; any other path is ignored.
+ */
+
+import { statSync } from "node:fs";
+import { basename, dirname } from "node:path";
+
+import { compareCodeUnits } from "../store/compare.ts";
+import type { StoreHandle } from "../store/store-open.ts";
+import type { ViewCatchUp } from "./catch-up.ts";
+import {
+ VIEW_RENDER_KIND,
+ VIEW_RETIRING_DIRS,
+ VIEW_TOPIC_ARCHIVE_PAGE,
+ VIEW_TOPIC_PAGE,
+} from "./constants.ts";
+import { pageLines } from "./corrections.ts";
+import { pageFileInside, retiringPageFile } from "./page-path.ts";
+import {
+ capturePage,
+ conflictCopies,
+ listCompanions,
+ moveCompanions,
+ NotAPageFileError,
+ readPage,
+ removeEmptyFolder,
+} from "./page-io.ts";
+import type { PageStats } from "./page-stats.ts";
+import type { PageModel } from "./pages.ts";
+import { topicOfIdLine } from "./topic-pages.ts";
+import {
+ bytesSum,
+ lastRender,
+ loadBase,
+ ownSums,
+ type RenderBase,
+ type ReplacedReason,
+} from "./view-records.ts";
+
+/** What retiring needs from the render pass it runs in. */
+export interface RetireContext {
+ readonly store: StoreHandle;
+ /** The pass's current read (an ingest replaces it). */
+ read(): ViewCatchUp;
+ /** The pages the store renders now (rebuilt after an ingest). */
+ models(): ReadonlyMap<string, PageModel>;
+ readonly stats: PageStats;
+ /** Store a version that is not the writer's own render; returns the records written. */
+ ingest(page: string, base: RenderBase | null, text: string, reason: ReplacedReason): number;
+}
+
+/** What happened to one page that left. */
+export interface RetireReport {
+ readonly page: string;
+ readonly status: "removed" | "base-pending" | "deferred";
+ readonly ingested: number;
+ readonly detail?: string;
+}
+
+const COMPANION_SKIP: ReadonlySet<string> = new Set([VIEW_TOPIC_PAGE, VIEW_TOPIC_ARCHIVE_PAGE]);
+
+function hasContent(bytes: Buffer | null): bytes is Buffer {
+ return bytes !== null && pageLines(bytes.toString("utf8")).some((l) => l.trim() !== "");
+}
+
+const archiveFirst = (page: string): number => (basename(page) === VIEW_TOPIC_ARCHIVE_PAGE ? 0 : 1);
+
+function byFolder(a: string, b: string): number {
+ return compareCodeUnits(dirname(a), dirname(b)) || archiveFirst(a) - archiveFirst(b);
+}
+
+/** The folder a topic's page lives in now, from the models of this pass. */
+function currentTopicFolder(ctx: RetireContext, topic: string | null): string | null {
+ if (topic === null) return null;
+ for (const model of ctx.models().values()) {
+ if (model.topic === topic && basename(model.page) === VIEW_TOPIC_PAGE)
+ return dirname(model.page);
+ }
+ return null;
+}
+
+/** The topic the last render record of `page` names, or `null`. */
+function renderedTopic(ctx: RetireContext, page: string): string | null {
+ const topic = lastRender(ctx.read(), page)?.record.body["topic"];
+ return typeof topic === "string" ? topic : null;
+}
+
+function moveFolderCompanions(
+ ctx: RetireContext,
+ target: string,
+ page: string,
+ topic: string | null,
+ only?: ReadonlySet<string>,
+): void {
+ const moved = currentTopicFolder(ctx, topic);
+ if (moved === null || moved === dirname(page)) return;
+ const to = pageFileInside(target, `${moved}/${VIEW_TOPIC_PAGE}`);
+ const from = pageFileInside(target, page);
+ if (to === null || from === null) return;
+ moveCompanions(dirname(from), dirname(to), COMPANION_SKIP, only);
+}
+
+/**
+ * The companion names in the folder of each page, read before anything
+ * moves: when topics exchange folders, a folder receives another topic's
+ * files before its own leave, and only the names it held at the start
+ * are its topic's.
+ */
+function companionsAtStart(target: string, pages: ReadonlyArray<string>): Map<string, Set<string>> {
+ const out = new Map<string, Set<string>>();
+ for (const page of pages) {
+ const path = pageFileInside(target, page);
+ if (path !== null) out.set(page, new Set(listCompanions(dirname(path), COMPANION_SKIP)));
+ }
+ return out;
+}
+
+/** Take one page out of the view; `null` when there was nothing to take. */
+function retireOne(
+ ctx: RetireContext,
+ target: string,
+ page: string,
+ path: string,
+ options: { readonly keepFolder: boolean; readonly companions?: ReadonlySet<string> },
+): RetireReport | null {
+ const copies = conflictCopies(path);
+ if (readPage(path) === null && copies.length === 0) {
+ // The page went before its companions did (a pass that died between).
+ if (basename(page) === VIEW_TOPIC_PAGE) {
+ moveFolderCompanions(ctx, target, page, renderedTopic(ctx, page), options.companions);
+ if (!options.keepFolder) removeEmptyFolder(dirname(path));
+ }
+ return null;
+ }
+ const last = lastRender(ctx.read(), page);
+ const base = last === null ? null : loadBase(ctx.store, last);
+ if (last !== null && base === null) {
+ return { page, status: "base-pending", ingested: 0, detail: "the merge base has not synced" };
+ }
+ const own = ownSums(ctx.read(), page);
+ let ingested = 0;
+ for (const copy of copies) {
+ // A name that is not a regular file (a folder, a link) is refused
+ // where it is. A copy is taken out of its name before it is read, as
+ // the page is: one a sync tool writes again meanwhile is left for the
+ // next pass, never removed.
+ readPage(copy);
+ const captured = capturePage(copy);
+ if (captured === null) continue;
+ try {
+ if (hasContent(captured.bytes) && !own.has(bytesSum(captured.bytes))) {
+ ingested += ctx.ingest(page, base, captured.bytes.toString("utf8"), "conflict-copy");
+ }
+ } catch (err) {
+ captured.restore();
+ throw err;
+ }
+ captured.discard();
+ }
+ const captured = capturePage(path);
+ if (captured !== null) {
+ try {
+ if (hasContent(captured.bytes) && !own.has(bytesSum(captured.bytes))) {
+ const text = captured.bytes.toString("utf8");
+ ingested += ctx.ingest(page, base, text, base ? "edit" : "foreign");
+ }
+ } catch (err) {
+ captured.restore();
+ throw err;
+ }
+ captured.discard();
+ if (basename(page) === VIEW_TOPIC_PAGE) {
+ const firstLine = pageLines(captured.bytes.toString("utf8"))[0] ?? "";
+ // The writer's own render record says whose page it was; the id line,
+ // which a user can edit, decides only when that record names none.
+ const owner = renderedTopic(ctx, page) ?? topicOfIdLine(firstLine);
+ moveFolderCompanions(ctx, target, page, owner, options.companions);
+ }
+ }
+ if (!options.keepFolder) removeEmptyFolder(dirname(path));
+ ctx.stats.delete(page);
+ return { page, status: "removed", ingested };
+}
+
+/**
+ * The topic the id line of the page file at `path` names, or `null`. A
+ * name that is not a regular file (a folder, a link) names no owner: the
+ * render of that page reports it as refused, and the rest of the pass goes on.
+ */
+function ownerOnDisk(path: string): string | null {
+ let disk: Buffer | null;
+ try {
+ disk = readPage(path);
+ } catch (err) {
+ if (err instanceof NotAPageFileError) return null;
+ throw err;
+ }
+ return disk === null ? null : topicOfIdLine(pageLines(disk.toString("utf8"))[0] ?? "");
+}
+
+/**
+ * Live topic pages whose file is another topic's: the slot passed to a new
+ * topic. Whose a page is comes from the writer's own last render record of
+ * it; the id line on disk, which a user's edit or a sync merge can change,
+ * decides only for a page rendered before render records named a topic.
+ */
+function foreignPages(ctx: RetireContext, target: string): string[] {
+ const out: string[] = [];
+ for (const model of ctx.models().values()) {
+ if (model.topic === undefined) continue;
+ const path = pageFileInside(target, model.page);
+ if (path === null) continue;
+ // A page already gone still names, in its last render record, whose
+ // folder this was: that topic's files must still leave it. The disk
+ // is read only when no render record says it.
+ const owner = renderedTopic(ctx, model.page) ?? ownerOnDisk(path);
+ if (owner !== null && owner !== model.topic) out.push(model.page);
+ }
+ return out.toSorted(byFolder);
+}
+
+/** Whether `a` and `b` are one file on disk (a case-insensitive file system, or a link). */
+function sameFile(a: string, b: string): boolean {
+ try {
+ const sa = statSync(a);
+ const sb = statSync(b);
+ return sa.dev === sb.dev && sa.ino === sb.ino;
+ } catch {
+ return false;
+ }
+}
+
+/** Pages a render record names in a retiring folder that the store no longer renders. */
+function retiredPages(ctx: RetireContext, target: string): string[] {
+ const live = ctx.models();
+ const livePaths = new Map<string, string>();
+ for (const page of live.keys()) {
+ const file = pageFileInside(target, page);
+ if (file !== null) livePaths.set(page.toLowerCase(), file);
+ }
+ const out = new Set<string>();
+ for (const records of ctx.read().records.values()) {
+ for (const record of records) {
+ const page = record.body["page"];
+ if (record.kind !== VIEW_RENDER_KIND || typeof page !== "string" || live.has(page)) continue;
+ if (!VIEW_RETIRING_DIRS.some((dir) => page.startsWith(`${dir}/`))) continue;
+ const file = retiringPageFile(target, page);
+ if (file === null) continue;
+ // On a case-insensitive file system a page whose path differs from a
+ // live page's only in case is that live page's file: never retired.
+ const twin = livePaths.get(page.toLowerCase());
+ if (twin !== undefined && sameFile(file, twin)) continue;
+ out.add(page);
+ }
+ }
+ return [...out].toSorted(byFolder);
+}
+
+/**
+ * Retire every page that left the view, in the order that keeps a
+ * user's files with the right topic: first the pages whose folder slot
+ * another topic took (their companions move out before anything moves
+ * in), then the pages no longer rendered. `onFailure` turns an error of
+ * one page into its report; the other pages still retire.
+ */
+export function retirePages<R>(
+ ctx: RetireContext,
+ target: string,
+ onFailure: (page: string, err: unknown) => R,
+ shouldStop?: () => boolean,
+): Array<RetireReport | R> {
+ const reports: Array<RetireReport | R> = [];
+ const foreign = foreignPages(ctx, target);
+ const companions = companionsAtStart(target, foreign);
+ const run = (page: string, keepFolder: boolean): void => {
+ const path = keepFolder ? pageFileInside(target, page) : retiringPageFile(target, page);
+ if (path === null) return;
+ // The pass's time budget holds here too: the rest wait for a later pass.
+ if (shouldStop?.() === true) {
+ reports.push({ page, status: "deferred", ingested: 0, detail: "the time budget ran out" });
+ return;
+ }
+ try {
+ const own = companions.get(page);
+ const report = retireOne(ctx, target, page, path, {
+ keepFolder,
+ ...(own !== undefined ? { companions: own } : {}),
+ });
+ if (report !== null) reports.push(report);
+ } catch (err) {
+ reports.push(onFailure(page, err));
+ }
+ };
+ for (const page of foreign) run(page, true);
+ for (const page of retiredPages(ctx, target)) run(page, false);
+ return reports;
+}
diff --git a/src/core/view/topic-edits.ts b/src/core/view/topic-edits.ts
new file mode 100644
index 00000000..f90b6762
--- /dev/null
+++ b/src/core/view/topic-edits.ts
@@ -0,0 +1,291 @@
+/**
+ * Human edits of topic pages as topic records (spec `topics` "Human edits
+ * win"; task 3.2). A line of `topic.md` or `archive.md` carries a key
+ * `t:<topic id>:<what>` (`topic-pages.ts`); an edit of that line becomes
+ * the topic record that says the same thing, with `human` authority, so
+ * it beats every agent and decision-model record on that item and moves
+ * with the topic through a rename:
+ *
+ * - the title line: `topic-rename` of the title; the description line:
+ * `topic-rename` of the description (deleted: cleared);
+ * - the status line: `topic-status`, when the text names a status in any
+ * language the view has (a done date in brackets is kept);
+ * - the goal line: `topic-goal` (deleted: cleared);
+ * - a milestone, decision, open question or log line reworded: the
+ * item's record with the new text (a milestone ticked `[x]` also gets a
+ * `milestone-done`); deleted: the item's tombstone;
+ * - a goal proposal deleted: an `undo` of the agent's goal record;
+ * reworded: the user's own goal;
+ * - a line added under a section heading or item: a new item of that
+ * section (a line added to the log is a `note`), whose id comes from its
+ * topic, section and text, so one line added twice is one item.
+ *
+ * Generated decorations (the list marker, a checkbox, the done or "looks
+ * done" marker, the date and class of a log line, "serves" and answer
+ * tails) are stripped in every language before the text is stored. Any
+ * other line (headings, the related section, a status that names no
+ * status) is not mapped here: `null` sends it to the generic correction
+ * of the view (`corrections.ts`).
+ */
+
+import { sha256Hex } from "../integrity/digest.ts";
+import { TOPIC_STATUSES, type TopicItemKind, type TopicStatus } from "../topics/constants.ts";
+import { topicBodyRejection } from "../topics/records.ts";
+import type { EditRecord } from "./edit-record.ts";
+import { allViewStrings } from "./i18n.ts";
+
+const KEY_RE = /^t:([0-9A-HJKMNP-TV-Z]{26}):(.+)$/;
+const LIST_MARKER_RE = /^\s*(?:[-*+]|\d+[.)])\s+/;
+const CHECKBOX_RE = /^\[( |x|X)\]\s*/;
+const DAY = "\\d{4}-\\d{2}-\\d{2}";
+
+const escape = (text: string): string => text.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** A pattern from a template: each hole is the source text of its group. */
+function template(text: string, holes: ReadonlyArray<string>): string {
+ let out = escape(text);
+ holes.forEach((hole, i) => {
+ out = out.replace(String.fromCharCode(i + 1), hole);
+ });
+ return out;
+}
+
+const STRINGS = allViewStrings();
+const alt = (parts: ReadonlyArray<string>): string => parts.join("|");
+
+const MILESTONE_TAIL_RE = new RegExp(
+ `\\s*\\((?:${alt(STRINGS.flatMap((s) => [template(s.milestoneDone("\u0001"), [DAY]), escape(s.milestoneLooksDone)]))})\\)\\s*$`,
+);
+const DECISION_TAIL_RE = new RegExp(
+ `\\s*\\((?:${alt(STRINGS.map((s) => template(s.serves("\u0001"), [".*"])))})\\)\\s*$`,
+);
+const QUESTION_TAIL_RE = new RegExp(
+ `\\s*\\((?:${alt(STRINGS.flatMap((s) => [template(s.questionAnswer("\u0001"), [".*"]), escape(s.questionLooksAnswered)]))})\\)\\s*$`,
+);
+const LOG_HEAD_RE = new RegExp(
+ `^${DAY},\\s*(?:${alt(STRINGS.flatMap((s) => Object.values(s.logClass).map(escape)))}):\\s*`,
+ "i",
+);
+const BECAUSE_RE = new RegExp(
+ `,\\s*(?:${alt(STRINGS.map((s) => template(s.because("\u0001"), ["(.+)"])))})$`,
+);
+const GOAL_PROPOSAL_RE = new RegExp(
+ `^(?:${alt(STRINGS.map((s) => template(s.goalProposal("\u0001", "\u0002"), [".+?", "(.+)"])))})$`,
+);
+
+function human(topic: string, kind: string, body: Record<string, unknown>): EditRecord | null {
+ const full = { authority: "human", ...body };
+ return topicBodyRejection(kind, topic, full) === null
+ ? { stream: "topics", kind, topic, body: full }
+ : null;
+}
+
+function bare(text: string): string {
+ return text.replace(LIST_MARKER_RE, "").trim();
+}
+
+/** The status a status line names, in any view language, with its done day. */
+function parseStatus(text: string): { status: TopicStatus; resolved?: string } | null {
+ for (const s of STRINGS) {
+ const match = new RegExp(
+ `^${escape(s.statusLabel)}\\s*:\\s*(.+?)\\s*(?:\\((.*)\\))?\\s*$`,
+ "i",
+ ).exec(text.trim());
+ if (match === null) continue;
+ const label = match[1]!.toLowerCase();
+ for (const other of STRINGS) {
+ const status = TOPIC_STATUSES.find((st) => other.topicStatus[st].toLowerCase() === label);
+ if (status === undefined) continue;
+ const day = new RegExp(DAY).exec(match[2] ?? "")?.[0];
+ return status === "done" && day !== undefined ? { status, resolved: day } : { status };
+ }
+ }
+ return null;
+}
+
+function milestoneParts(line: string): { checked: boolean; text: string } {
+ const rest = bare(line);
+ const box = CHECKBOX_RE.exec(rest);
+ const text = (box === null ? rest : rest.slice(box[0].length))
+ .replace(MILESTONE_TAIL_RE, "")
+ .trim();
+ return { checked: box !== null && box[1] !== " ", text };
+}
+
+function itemText(kind: TopicItemKind, line: string): { text: string; reason?: string } {
+ const rest = bare(line);
+ switch (kind) {
+ case "decision":
+ return { text: rest.replace(DECISION_TAIL_RE, "").trim() };
+ case "open-question":
+ return { text: rest.replace(QUESTION_TAIL_RE, "").trim() };
+ case "log-entry": {
+ const text = rest.replace(LOG_HEAD_RE, "");
+ const because = BECAUSE_RE.exec(text);
+ return because === null
+ ? { text: text.trim() }
+ : {
+ text: text.slice(0, because.index).trim(),
+ reason: because.slice(1).find(Boolean)!.trim(),
+ };
+ }
+ case "milestone":
+ return { text: milestoneParts(line).text };
+ }
+}
+
+const ITEM_KEYS: Readonly<Record<string, TopicItemKind>> = {
+ d: "decision",
+ q: "open-question",
+ l: "log-entry",
+ m: "milestone",
+ mx: "milestone",
+};
+
+function itemCorrection(
+ topic: string,
+ kind: TopicItemKind,
+ rest: string,
+ before: string,
+ after: string | null,
+): EditRecord[] | null {
+ const parts = rest.split(":");
+ const item = parts.at(-1)!;
+ const logClass = kind === "log-entry" ? parts[0] : undefined;
+ // `mx:<done record>:<item>`: a done milestone, and the record that completed it.
+ const doneRecord = kind === "milestone" && parts.length === 2 ? parts[0] : undefined;
+ if (after === null)
+ return [human(topic, kind, { item, removed: true })].filter((r) => r !== null);
+ const now = itemText(kind, after);
+ const was = itemText(kind, before);
+ const out: Array<EditRecord | null> = [];
+ if (now.text !== was.text || now.reason !== was.reason) {
+ out.push(
+ human(topic, kind, {
+ item,
+ text: now.text,
+ ...(logClass !== undefined ? { class: logClass } : {}),
+ ...(now.reason !== undefined ? { reason: now.reason } : {}),
+ }),
+ );
+ }
+ if (kind === "milestone") {
+ const wasDone = milestoneParts(before).checked;
+ const isDone = milestoneParts(after).checked;
+ if (isDone && !wasDone) out.push(human(topic, "milestone-done", { milestone: item }));
+ // Unticked: the user takes the completion back.
+ if (wasDone && !isDone && doneRecord !== undefined) {
+ out.push(human(topic, "undo", { record: doneRecord }));
+ }
+ }
+ if (out.some((r) => r === null)) return null;
+ return out as EditRecord[];
+}
+
+function one(record: EditRecord | null): EditRecord[] | null {
+ return record === null ? null : [record];
+}
+
+/**
+ * The topic records for the keyed line `key`, reworded from `before` to
+ * `after` or deleted (`after` null); `null` when the key is not a topic
+ * line this module maps, or the new text does not make a valid record.
+ */
+export function topicCorrection(
+ key: string,
+ before: string,
+ after: string | null,
+): EditRecord[] | null {
+ const match = KEY_RE.exec(key);
+ if (match === null) return null;
+ const [, topic, what] = match as unknown as [string, string, string];
+ const [head, ...tail] = what.split(":");
+ const rest = tail.join(":");
+ switch (head) {
+ case "title": {
+ // A deleted title is rendered again; the topic keeps its name.
+ if (after === null) return [];
+ return one(human(topic, "topic-rename", { title: after.replace(/^#+\s*/, "").trim() }));
+ }
+ case "desc": {
+ if (after === null) return one(human(topic, "topic-rename", { description: null }));
+ const text = after.trim();
+ if (STRINGS.some((s) => s.topicNoDescription === text)) return [];
+ return one(human(topic, "topic-rename", { description: text }));
+ }
+ case "status": {
+ if (after === null) return [];
+ const parsed = parseStatus(after);
+ return parsed === null ? null : one(human(topic, "topic-status", parsed));
+ }
+ case "goal":
+ return one(human(topic, "topic-goal", { goal: after === null ? null : after.trim() }));
+ case "gp": {
+ if (after === null) return one(human(topic, "undo", { record: rest }));
+ const proposal = GOAL_PROPOSAL_RE.exec(bare(after));
+ const goal = proposal === null ? bare(after) : proposal.slice(1).find(Boolean)!.trim();
+ return one(human(topic, "topic-goal", { goal }));
+ }
+ default: {
+ const kind = ITEM_KEYS[head!];
+ return kind === undefined ? null : itemCorrection(topic, kind, rest, before, after);
+ }
+ }
+}
+
+/** The section an anchor key sits in, as the kind of item a line added there becomes. */
+function sectionOf(what: string): TopicItemKind | null {
+ const [head, ...tail] = what.split(":");
+ const name = head === "a" && tail[0] === "h" ? tail[1] : head === "h" ? tail[0] : null;
+ if (name !== null) {
+ const bySection: Readonly<Record<string, TopicItemKind>> = {
+ milestones: "milestone",
+ decisions: "decision",
+ questions: "open-question",
+ resolved: "open-question",
+ log: "log-entry",
+ };
+ return bySection[name ?? ""] ?? null;
+ }
+ if (head === "gp") return "open-question";
+ return ITEM_KEYS[head!] ?? null;
+}
+
+/**
+ * The item id of a line the user added: derived from the topic, the
+ * section and the text, so the same line added in two copies of a page (a
+ * sync tool's conflict copy beside the page) is one item, not two.
+ */
+function additionId(topic: string, kind: TopicItemKind, text: string): string {
+ return `u${sha256Hex(`${topic}\u0000${kind}\u0000${text}`).slice(0, 24)}`;
+}
+
+/**
+ * The topic records for a line the user added below the keyed line
+ * `anchor`; `null` when the anchor is not inside an item section of a
+ * topic page.
+ */
+export function topicAddition(anchor: string | null, line: string): EditRecord[] | null {
+ const match = anchor === null ? null : KEY_RE.exec(anchor);
+ if (match === null) return null;
+ const [, topic, what] = match as unknown as [string, string, string];
+ const kind = sectionOf(what);
+ if (kind === null) return null;
+ if (kind === "milestone") {
+ const { checked, text } = milestoneParts(line);
+ const item = additionId(topic, kind, text);
+ const records = [
+ human(topic, kind, { item, text }),
+ ...(checked ? [human(topic, "milestone-done", { milestone: item })] : []),
+ ];
+ return records.some((r) => r === null) ? null : (records as EditRecord[]);
+ }
+ const { text, reason } = itemText(kind, line);
+ const record = human(topic, kind, {
+ item: additionId(topic, kind, text),
+ text,
+ ...(kind === "log-entry" ? { class: "note" } : {}),
+ ...(reason !== undefined ? { reason } : {}),
+ });
+ return record === null ? null : [record];
+}
diff --git a/src/core/view/topic-pages.ts b/src/core/view/topic-pages.ts
new file mode 100644
index 00000000..0f4a2323
--- /dev/null
+++ b/src/core/view/topic-pages.ts
@@ -0,0 +1,391 @@
+/**
+ * Topic pages of the human view (design D7, D8; spec `topics` "Topic
+ * page"; task 3.2): one folder per topic, `topics/<YYYY-MM-DD>-<slug>/`,
+ * holding `topic.md` and, when the page budget overflows or questions are
+ * resolved, the companion `archive.md`. Pure: the pages are a function of
+ * the topic fold (`../topics/fold.ts`) and the view language.
+ *
+ * `topic.md`, in a fixed section order: the title, the one-line
+ * description, the status line, the goal, milestones, decisions, open
+ * questions, the log (newest first) and the related section. The goal,
+ * milestones, decisions, open questions and log are left out when empty;
+ * the title, description, status and related section are always there
+ * (related names at least the topic's scope).
+ *
+ * - Milestones: open ones in the order they were recorded, then done
+ * ones, newest done first. A completion proposed without standing (a
+ * decision model, an agent with no evidence) shows as "looks done,
+ * confirm" and the milestone stays open.
+ * - Decisions: newest first, each with the milestones it serves.
+ * - Open questions: unresolved questions, then the goal proposals that
+ * lost to the user's goal, attributed to their agent.
+ * - Log: earned entries only (`TOPIC_EARNED_LOG_CLASSES`), newest first.
+ * - Related: the scope, linked topics as relative links, topics merged
+ * into this one, and the archive link.
+ *
+ * Page budget (`TOPIC_PAGE_BUDGET`): the oldest done milestones, decisions
+ * and log entries over their section's budget move to `archive.md`, with
+ * the resolved questions. Open milestones and open questions never move.
+ *
+ * The folder is the UTC day of the topic's creation and a slug of its
+ * current title, so a rename moves the page (the renderer retires the old
+ * folder). Two topics that take the same folder are told apart by the
+ * tail of their id. Every line carries a key `t:<topic id>:...` naming
+ * what it shows, so an edit maps back to a topic record (`topic-edits.ts`).
+ */
+
+import { compareCodeUnits } from "../store/compare.ts";
+import {
+ TOPIC_EARNED_LOG_CLASSES,
+ TOPIC_PAGE_BUDGET,
+ TOPIC_PERSONAL_SCOPE,
+ TOPIC_PROJECT_SCOPE_PREFIX,
+} from "../topics/constants.ts";
+import type { TopicFold, TopicItem, TopicState } from "../topics/fold.ts";
+import { VIEW_TOPIC_ARCHIVE_PAGE, VIEW_TOPIC_PAGE, VIEW_TOPICS_DIR } from "./constants.ts";
+import type { EarnedLogClass, ViewStrings } from "./i18n.ts";
+import { ID_LINE_KEY, plainText, type PageLine, type PageModel } from "./pages.ts";
+
+/** Longest slug of a topic folder, in code points. */
+const SLUG_MAX = 48;
+
+const BLANK: PageLine = { key: null, text: "" };
+
+/** The slug of a title: lowercase letters and digits of any script, joined by hyphens. */
+export function topicSlug(title: string): string {
+ const words = title
+ .normalize("NFC")
+ .toLowerCase()
+ .split(/[^\p{L}\p{N}]+/u)
+ .filter(Boolean);
+ const slug = [...words.join("-")].slice(0, SLUG_MAX).join("").replace(/-+$/, "");
+ return slug === "" ? "topic" : slug;
+}
+
+function dayOf(ms: number): string {
+ return new Date(ms).toISOString().slice(0, 10);
+}
+
+/** What a render may show beyond the view's own rule. */
+export interface TopicPageOptions {
+ /**
+ * Show private topics and items too: for a local caller's read of one
+ * topic (the topic tool, `osb://topic/{id}`), never for the view.
+ */
+ readonly includePrivate?: boolean;
+}
+
+/** The topics a page is rendered for: existing, not merged away, not private. */
+export function renderedTopics(fold: TopicFold, options: TopicPageOptions = {}): TopicState[] {
+ return [...fold.topics.values()]
+ .filter((t) => t.mergedInto === null && (options.includePrivate === true || !t.private))
+ .toSorted((a, b) => a.createdAt - b.createdAt || compareCodeUnits(a.id, b.id));
+}
+
+/** The view folder of each rendered topic, relative to the view: `topics/<day>-<slug>`. */
+export function topicFolders(fold: TopicFold, options: TopicPageOptions = {}): Map<string, string> {
+ const out = new Map<string, string>();
+ const taken = new Set<string>();
+ for (const topic of renderedTopics(fold, options)) {
+ const base = `${VIEW_TOPICS_DIR}/${dayOf(topic.createdAt)}-${topicSlug(topic.title)}`;
+ // The base, else the base and the tail of the id, else a counter on
+ // that: a folder another topic holds (a title that already ends in such
+ // a tail) is never shared.
+ let folder = taken.has(base) ? `${base}-${topic.id.slice(-6).toLowerCase()}` : base;
+ for (let n = 2; taken.has(folder); n++)
+ folder = `${base}-${topic.id.slice(-6).toLowerCase()}-${n}`;
+ taken.add(folder);
+ out.set(topic.id, folder);
+ }
+ return out;
+}
+
+/** The id comment line of a topic page: the store, the page and the topic. */
+function topicIdLine(storeId: string, page: string, topic: string): PageLine {
+ return {
+ key: ID_LINE_KEY,
+ text: `<!-- open-second-brain-view store=${storeId} page=${page} topic=${topic} -->`,
+ };
+}
+
+/** The topic id an id comment line names, or `null`. */
+export function topicOfIdLine(line: string): string | null {
+ const match = /^<!-- open-second-brain-view .*\btopic=([0-9A-HJKMNP-TV-Z]{26})\b/.exec(line);
+ return match === null ? null : match[1]!;
+}
+
+interface Sections {
+ readonly milestonesOpen: TopicItem[];
+ readonly milestonesDone: TopicItem[];
+ readonly milestonesArchived: TopicItem[];
+ readonly decisions: TopicItem[];
+ readonly decisionsArchived: TopicItem[];
+ readonly questions: TopicItem[];
+ readonly resolved: TopicItem[];
+ readonly log: TopicItem[];
+ readonly logArchived: TopicItem[];
+}
+
+const newestFirst = (a: TopicItem, b: TopicItem): number => b.createdAt - a.createdAt;
+
+function sections(topic: TopicState, includePrivate: boolean): Sections {
+ const shown = topic.items.filter((i) => includePrivate || !i.private);
+ const milestones = shown.filter((i) => i.kind === "milestone");
+ const done = milestones
+ .filter((i) => i.done !== undefined)
+ .toSorted((a, b) => b.done!.at - a.done!.at);
+ const decisions = shown
+ .filter((i) => i.kind === "decision")
+ .toReversed()
+ .toSorted(newestFirst);
+ const questions = shown.filter((i) => i.kind === "open-question");
+ const log = shown
+ .filter((i) => i.kind === "log-entry" && TOPIC_EARNED_LOG_CLASSES.has(i.logClass!))
+ .toReversed()
+ .toSorted(newestFirst);
+ return {
+ milestonesOpen: milestones.filter((i) => i.done === undefined),
+ milestonesDone: done.slice(0, TOPIC_PAGE_BUDGET.doneMilestones),
+ milestonesArchived: done.slice(TOPIC_PAGE_BUDGET.doneMilestones),
+ decisions: decisions.slice(0, TOPIC_PAGE_BUDGET.decisions),
+ decisionsArchived: decisions.slice(TOPIC_PAGE_BUDGET.decisions),
+ questions: questions.filter((i) => i.resolved === undefined),
+ resolved: questions
+ .filter((i) => i.resolved !== undefined)
+ .toSorted((a, b) => b.resolved!.at - a.resolved!.at),
+ log: log.slice(0, TOPIC_PAGE_BUDGET.log),
+ logArchived: log.slice(TOPIC_PAGE_BUDGET.log),
+ };
+}
+
+function hasArchive(s: Sections): boolean {
+ return (
+ s.milestonesArchived.length +
+ s.decisionsArchived.length +
+ s.resolved.length +
+ s.logArchived.length >
+ 0
+ );
+}
+
+interface LineContext {
+ readonly includePrivate: boolean;
+ readonly topic: TopicState;
+ readonly strings: ViewStrings;
+ readonly key: (rest: string) => string;
+}
+
+/**
+ * The key of an item line: under the topic that owns the item, not the
+ * page's topic, since an item id is its owner's own and a merged topic's
+ * items show on the page it merged into (an edit lands on the owner).
+ */
+function itemKey(item: TopicItem, rest: string): string {
+ return `t:${item.owner}:${rest}`;
+}
+
+function milestoneLine(c: LineContext, item: TopicItem): PageLine {
+ const text = plainText(item.text);
+ const line =
+ item.done !== undefined
+ ? `- [x] ${text} (${c.strings.milestoneDone(dayOf(item.done.at))})`
+ : item.doneProposed !== undefined
+ ? `- [ ] ${text} (${c.strings.milestoneLooksDone})`
+ : `- [ ] ${text}`;
+ // A done milestone's key names the record that completed it, so
+ // unticking the line can undo exactly that record.
+ const key = item.done !== undefined ? `mx:${item.done.record}:${item.id}` : `m:${item.id}`;
+ return { key: itemKey(item, key), text: line };
+}
+
+function decisionLine(c: LineContext, item: TopicItem): PageLine {
+ const served = (item.serves ?? []).flatMap((id) => {
+ const milestone = c.topic.items.find(
+ (i) => i.id === id && i.kind === "milestone" && !i.private,
+ );
+ return milestone === undefined ? [] : [plainText(milestone.text)];
+ });
+ const serves = served.length > 0 ? ` (${c.strings.serves(served.join("; "))})` : "";
+ return { key: itemKey(item, `d:${item.id}`), text: `- ${plainText(item.text)}${serves}` };
+}
+
+function questionLine(c: LineContext, item: TopicItem): PageLine {
+ const text = plainText(item.text);
+ if (item.resolved !== undefined) {
+ const answer = item.resolved.answer;
+ const tail = answer === null ? "" : ` (${c.strings.questionAnswer(plainText(answer))})`;
+ return { key: itemKey(item, `q:${item.id}`), text: `- ${text}${tail}` };
+ }
+ const tail = item.resolveProposed !== undefined ? ` (${c.strings.questionLooksAnswered})` : "";
+ return { key: itemKey(item, `q:${item.id}`), text: `- ${text}${tail}` };
+}
+
+function logLine(c: LineContext, item: TopicItem): PageLine {
+ const cls = item.logClass as EarnedLogClass;
+ const reason = item.reason !== undefined ? `, ${c.strings.because(plainText(item.reason))}` : "";
+ return {
+ key: itemKey(item, `l:${cls}:${item.id}`),
+ text: `- ${dayOf(item.createdAt)}, ${c.strings.logClass[cls]}: ${plainText(item.text)}${reason}`,
+ };
+}
+
+function section(
+ lines: PageLine[],
+ key: string,
+ heading: string,
+ body: ReadonlyArray<PageLine>,
+): void {
+ if (body.length === 0) return;
+ lines.push(BLANK, { key, text: `## ${heading}` }, BLANK, ...body);
+}
+
+function relatedLines(
+ c: LineContext,
+ fold: TopicFold,
+ folders: ReadonlyMap<string, string>,
+ archive: boolean,
+): PageLine[] {
+ const { topic, strings } = c;
+ const scope =
+ topic.scope === TOPIC_PERSONAL_SCOPE
+ ? strings.scopePersonal
+ : strings.scopeProject(plainText(topic.scope.slice(TOPIC_PROJECT_SCOPE_PREFIX.length)));
+ const out: PageLine[] = [{ key: c.key("scope"), text: `- ${scope}` }];
+ const linked = new Set(topic.links.map((id) => fold.canonical(id)).filter((id) => id !== null));
+ linked.delete(topic.id);
+ for (const id of [...linked].toSorted()) {
+ const folder = folders.get(id!);
+ const other = fold.topics.get(id!);
+ if (folder === undefined || other === undefined) continue;
+ out.push({
+ key: c.key(`link:${id}`),
+ text: `- [${plainText(other.title)}](../${folder.split("/").at(-1)}/${VIEW_TOPIC_PAGE})`,
+ });
+ }
+ for (const merged of [...fold.topics.values()]
+ .filter((t) => t.mergedInto === topic.id && (c.includePrivate || !t.private))
+ .toSorted((a, b) => compareCodeUnits(a.id, b.id))) {
+ out.push({
+ key: c.key(`merged:${merged.id}`),
+ text: `- ${strings.mergedFrom(plainText(merged.title))}`,
+ });
+ }
+ if (archive) {
+ out.push({
+ key: c.key("archive"),
+ text: `- [${strings.archiveLink}](${VIEW_TOPIC_ARCHIVE_PAGE})`,
+ });
+ }
+ return out;
+}
+
+function topicPage(
+ storeId: string,
+ fold: TopicFold,
+ topic: TopicState,
+ folders: ReadonlyMap<string, string>,
+ strings: ViewStrings,
+ includePrivate: boolean,
+): PageModel[] {
+ const folder = folders.get(topic.id)!;
+ const page = `${folder}/${VIEW_TOPIC_PAGE}`;
+ const c: LineContext = { includePrivate, topic, strings, key: (rest) => `t:${topic.id}:${rest}` };
+ const s = sections(topic, includePrivate);
+ const archive = hasArchive(s);
+ const lines: PageLine[] = [topicIdLine(storeId, page, topic.id), BLANK];
+ lines.push({ key: c.key("title"), text: `# ${plainText(topic.title)}` }, BLANK);
+ const description = topic.description === null ? "" : plainText(topic.description);
+ lines.push({
+ key: c.key("desc"),
+ text: description === "" ? strings.topicNoDescription : description,
+ });
+ lines.push(BLANK, {
+ key: c.key("status"),
+ text: strings.statusLine(
+ strings.topicStatus[topic.status],
+ topic.status === "done" ? topic.resolved : null,
+ ),
+ });
+ const goal = topic.goal === null ? "" : plainText(topic.goal);
+ section(
+ lines,
+ c.key("h:goal"),
+ strings.topicGoal,
+ goal === "" ? [] : [{ key: c.key("goal"), text: goal }],
+ );
+ section(lines, c.key("h:milestones"), strings.topicMilestones, [
+ ...s.milestonesOpen.map((i) => milestoneLine(c, i)),
+ ...s.milestonesDone.map((i) => milestoneLine(c, i)),
+ ]);
+ section(
+ lines,
+ c.key("h:decisions"),
+ strings.topicDecisions,
+ s.decisions.map((i) => decisionLine(c, i)),
+ );
+ section(lines, c.key("h:questions"), strings.topicQuestions, [
+ ...s.questions.map((i) => questionLine(c, i)),
+ ...topic.goalProposals.map((p) => ({
+ key: c.key(`gp:${p.record}`),
+ text: `- ${strings.goalProposal(plainText(p.agent), plainText(p.goal))}`,
+ })),
+ ]);
+ section(
+ lines,
+ c.key("h:log"),
+ strings.topicLog,
+ s.log.map((i) => logLine(c, i)),
+ );
+ section(lines, c.key("h:related"), strings.topicRelated, relatedLines(c, fold, folders, archive));
+ const pages: PageModel[] = [{ page, lines, topic: topic.id }];
+ if (archive) pages.push(archivePage(storeId, folder, c, s));
+ return pages;
+}
+
+function archivePage(storeId: string, folder: string, c: LineContext, s: Sections): PageModel {
+ const page = `${folder}/${VIEW_TOPIC_ARCHIVE_PAGE}`;
+ const { strings, topic } = c;
+ const lines: PageLine[] = [topicIdLine(storeId, page, topic.id), BLANK];
+ lines.push({ key: c.key("a:title"), text: `# ${strings.archiveTitle(plainText(topic.title))}` });
+ lines.push(BLANK, { key: c.key("a:intro"), text: strings.archiveIntro });
+ lines.push(BLANK, { key: c.key("a:back"), text: `[${strings.archiveBack}](${VIEW_TOPIC_PAGE})` });
+ section(
+ lines,
+ c.key("a:h:milestones"),
+ strings.topicMilestones,
+ s.milestonesArchived.map((i) => milestoneLine(c, i)),
+ );
+ section(
+ lines,
+ c.key("a:h:decisions"),
+ strings.topicDecisions,
+ s.decisionsArchived.map((i) => decisionLine(c, i)),
+ );
+ section(
+ lines,
+ c.key("a:h:resolved"),
+ strings.topicResolvedQuestions,
+ s.resolved.map((i) => questionLine(c, i)),
+ );
+ section(
+ lines,
+ c.key("a:h:log"),
+ strings.topicLog,
+ s.logArchived.map((i) => logLine(c, i)),
+ );
+ return { page, lines, topic: topic.id };
+}
+
+/** Every topic page and archive the fold renders to. */
+export function topicPages(
+ storeId: string,
+ fold: TopicFold,
+ strings: ViewStrings,
+ options: TopicPageOptions = {},
+): PageModel[] {
+ const folders = topicFolders(fold, options);
+ const includePrivate = options.includePrivate === true;
+ return renderedTopics(fold, options).flatMap((topic) =>
+ topicPage(storeId, fold, topic, folders, strings, includePrivate),
+ );
+}
diff --git a/src/core/view/vault-guard.ts b/src/core/view/vault-guard.ts
index 5c2cce80..6e3abe87 100644
--- a/src/core/view/vault-guard.ts
+++ b/src/core/view/vault-guard.ts
@@ -14,7 +14,12 @@
*
* When the view folder is the vault root itself, only the names the view
* writer owns are refused: its pages, their sync-conflict copies, its
- * temp files and the history folder.
+ * temp files and its folders (history, topics, reports, sources).
+ *
+ * A topic page is never written by a note tool (spec `topics` "Direct
+ * page write is refused"): the refusal for a path in the topics folder
+ * names the topic event tool to use instead, and one in the reports or
+ * sources folder names the tool that writes those.
*/
import { realpathSync } from "node:fs";
@@ -26,8 +31,12 @@ import {
VIEW_DECISIONS_PAGE,
VIEW_HISTORY_DIR,
VIEW_PAGE_EXT,
+ VIEW_REPORTS_DIR,
+ VIEW_SOURCES_DIR,
VIEW_TEMP_PREFIX,
+ VIEW_TOPICS_DIR,
} from "./constants.ts";
+import { isRetiringPageShape } from "./page-path.ts";
import { configuredViewTargetDir } from "./target.ts";
/**
@@ -81,6 +90,58 @@ const PAGE_STEMS = [VIEW_ABOUT_ME_PAGE, VIEW_DECISIONS_PAGE].map((page) =>
page.slice(0, -VIEW_PAGE_EXT.length),
);
+/** The view writer's folders. */
+const VIEW_DIRS: ReadonlySet<string> = new Set([
+ VIEW_HISTORY_DIR,
+ VIEW_TOPICS_DIR,
+ VIEW_REPORTS_DIR,
+ VIEW_SOURCES_DIR,
+]);
+
+/** What to use instead of a note tool, per view folder. */
+const INSTEAD: Readonly<Record<string, string>> = Object.freeze({
+ [VIEW_TOPICS_DIR]:
+ "a topic page is rendered from topic events: record them with the `brain_topic` tool " +
+ "(or the `o2b topic` command) instead",
+ [VIEW_REPORTS_DIR]:
+ "a report page is rendered from the report: write it with `brain_research_report` instead",
+ [VIEW_SOURCES_DIR]:
+ "a source page is rendered from the source summary: write it with `brain_ingest_source` instead",
+});
+
+/** Folders a user's own notes may share with a view at the vault root. */
+const SHARED_ROOT_DIRS: ReadonlySet<string> = new Set([
+ VIEW_TOPICS_DIR,
+ VIEW_REPORTS_DIR,
+ VIEW_SOURCES_DIR,
+]);
+
+/** A sync tool's conflict-copy suffix after a page's stem, as `page-io.ts` recognises it. */
+const COPY_SUFFIX_RE = /(?:\.sync-conflict-[^/]*| \([^)/]*conflicted copy[^)/]*\))(\.md)$/i;
+
+/**
+ * Whether `path`, under a top folder a view at the vault root shares with
+ * the user's notes (`topics/`, `reports/`, `sources/`), is the view's: a
+ * page the renderer writes, a sync tool's conflict copy of one, a writer
+ * temp file in a topic folder, or (with `container`) the shared folder or
+ * a topic folder itself. A user's own `topics/plan.md` stays theirs.
+ */
+function isSharedRootViewPath(path: string, container: boolean): boolean {
+ const parts = path.split("/");
+ if (parts.length === 1) return container;
+ const name = parts.at(-1)!;
+ if (name.startsWith(VIEW_TEMP_PREFIX)) return true;
+ if (isRetiringPageShape(path) || isRetiringPageShape(path.replace(COPY_SUFFIX_RE, "$1"))) {
+ return true;
+ }
+ return (
+ container &&
+ parts[0] === VIEW_TOPICS_DIR &&
+ parts.length === 2 &&
+ isRetiringPageShape(`${path}/topic.md`)
+ );
+}
+
/** Whether a top-level name at the vault root is one the view writer owns. */
function isViewName(name: string): boolean {
if (name.startsWith(VIEW_TEMP_PREFIX) || name === VIEW_HISTORY_DIR) return true;
@@ -106,6 +167,7 @@ export function isInViewFolder(
const view = fold(viewRel);
if (view === "" || view === ".") {
const top = path.split("/")[0] ?? "";
+ if (SHARED_ROOT_DIRS.has(top)) return isSharedRootViewPath(path, opts.container === true);
return isViewName(top);
}
if (path === view || path.startsWith(`${view}/`)) return true;
@@ -134,5 +196,16 @@ export function viewFolderRefusal(
}
const viewRel = inVault(vault, dir);
if (viewRel === null || !isInViewFolder(viewRel, relPath, opts)) return null;
- return `the human view folder is written by the view writer only, not via ${surface}: ${relPath}`;
+ const refusal = `the human view folder is written by the view writer only, not via ${surface}: ${relPath}`;
+ const instead = INSTEAD[viewFolderOf(viewRel, relPath) ?? ""];
+ return instead === undefined ? refusal : `${refusal}; ${instead}`;
+}
+
+/** The view folder (`topics`, `history`, ...) a vault-relative path inside the view sits in. */
+function viewFolderOf(viewRel: string, relPath: string): string | null {
+ const path = fold(posix.normalize(relPath)).replace(/\/+$/, "");
+ const view = fold(viewRel);
+ const inside = view === "" || view === "." ? path : path.slice(view.length + 1);
+ const top = inside.split("/")[0] ?? "";
+ return inside.includes("/") && VIEW_DIRS.has(top) ? top : null;
}
diff --git a/src/core/view/view-records.ts b/src/core/view/view-records.ts
index 1154441f..97af9192 100644
--- a/src/core/view/view-records.ts
+++ b/src/core/view/view-records.ts
@@ -3,7 +3,7 @@
* records with their merge base, replaced page versions, ingested human
* edits, the idle heartbeat and the device-local render intents.
*
- * - `view-render` `{ page, sum, base, bytes }` (`log`, `shared`): the page
+ * - `view-render` `{ page, topic?, sum, base, bytes }` (`log`, `shared`): the page
* now holds the bytes whose sha256 is `sum`; `base` names the blob that
* keeps that text and the key of each line, the base of the next
* three-way merge. Written only after the page is in place.
@@ -58,7 +58,7 @@ import {
VIEW_REPLACED_KIND,
VIEW_STATE_DIR,
} from "./constants.ts";
-import type { EditRecord } from "./corrections.ts";
+import type { EditRecord } from "./edit-record.ts";
import { allRecords, type ViewCatchUp } from "./catch-up.ts";
/** The merge base a render record names. */
@@ -192,7 +192,14 @@ export function ingestVersion(
for (const edit of edits) {
appendRecord(
store,
- { partition, stream: edit.stream, kind: edit.kind, agent: options.agent, body: edit.body },
+ {
+ partition,
+ stream: edit.stream,
+ kind: edit.kind,
+ agent: options.agent,
+ ...(edit.topic !== undefined ? { topic: edit.topic } : {}),
+ body: edit.body,
+ },
now,
);
}
@@ -222,7 +229,13 @@ export function writeRender(
stream: "log",
kind: VIEW_RENDER_KIND,
agent: options.agent,
- body: { page: intent.page, sum: intent.sum, base: intent.base, bytes: intent.bytes },
+ body: {
+ page: intent.page,
+ ...(intent.topic !== undefined ? { topic: intent.topic } : {}),
+ sum: intent.sum,
+ base: intent.base,
+ bytes: intent.bytes,
+ },
},
options.now !== undefined ? { now: options.now } : {},
).record;
@@ -254,6 +267,8 @@ export function heartbeat(store: StoreHandle, read: ViewCatchUp, options: Record
/** A page about to be put in place, kept device-local until its render record is written. */
export interface RenderIntent {
readonly page: string;
+ /** The topic a topic page or archive shows. */
+ readonly topic?: string;
readonly sum: string;
readonly base: string;
readonly bytes: number;
diff --git a/src/core/view/writer.ts b/src/core/view/writer.ts
index ce8e9337..580e1534 100644
--- a/src/core/view/writer.ts
+++ b/src/core/view/writer.ts
@@ -171,6 +171,22 @@ function claimSeenPath(store: StoreHandle): string {
return join(store.deviceStateDir, VIEW_STATE_DIR, VIEW_CLAIM_SEEN_FILE);
}
+/**
+ * Whether {@link claimSettled} has already answered `true` for this
+ * device's current claim, without noting anything: for a step that must
+ * wait for the writer's settled claim but must not spend the render's own
+ * wait (topic planning runs before the render in a dream pass).
+ */
+export function claimSeen(store: StoreHandle, state: ViewWriterState): boolean {
+ if (state.via !== "claim" || state.since === null) return true;
+ try {
+ const seen = JSON.parse(readFileSync(claimSeenPath(store), "utf8")) as { claim?: unknown };
+ return seen.claim === state.since.id;
+ } catch {
+ return false;
+ }
+}
+
/**
* Whether this device, holding the role through its own claim, has
* already caught up once since it first saw that: the first call for a
diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.ts
index f4593d1f..f0b90d8d 100644
--- a/src/mcp/brain-tools.ts
+++ b/src/mcp/brain-tools.ts
@@ -40,6 +40,7 @@ import { SYNTHESIS_TOOLS } from "./brain/synthesis-tools.ts";
import { GENERATION_TOOLS } from "./brain/generation-tools.ts";
import { CALENDAR_TOOLS } from "./brain/calendar-tools.ts";
import { PLEDGE_TOOLS } from "./brain/pledge-tools.ts";
+import { TOPIC_TOOLS } from "./brain/topic-tools.ts";
import { MEMORY_BRIDGE_TOOLS } from "./brain/memory-bridge-tools.ts";
import { LIFECYCLE_TOOLS } from "./brain/lifecycle-tools.ts";
import { LIFECYCLE_FILE_TOOLS } from "./brain/lifecycle-file-tools.ts";
@@ -97,6 +98,8 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
...RECEIPT_TOOLS,
// Brain store change probe (design D5): new record ids since a watermark.
...CHANGES_TOOLS,
+ // Topics (design D8, D9): read and change topics by recording topic events.
+ ...TOPIC_TOOLS,
// Shared brain settings (design D4, D14 item 3): get, list, set, unset.
...SETTINGS_TOOLS,
]);
diff --git a/src/mcp/brain/brief-view-tools.ts b/src/mcp/brain/brief-view-tools.ts
index 5c73d2b9..6fd62ee8 100644
--- a/src/mcp/brain/brief-view-tools.ts
+++ b/src/mcp/brain/brief-view-tools.ts
@@ -223,6 +223,7 @@ export async function toolBrainDigest(
...(agentScope !== undefined ? { agentScope } : {}),
...(readable !== undefined ? { readable } : {}),
...(restricted ? { withholdsPrivate: true } : {}),
+ ...(ctx.configPath ? { configPath: ctx.configPath } : {}),
});
const result = renderFor(format, readableAtContextReachOrUndefined(ctx));
diff --git a/src/mcp/brain/dream-tools.ts b/src/mcp/brain/dream-tools.ts
index de5c6390..7a1566a1 100644
--- a/src/mcp/brain/dream-tools.ts
+++ b/src/mcp/brain/dream-tools.ts
@@ -387,6 +387,7 @@ export async function toolBrainDream(
...(agent ? { agentName: agent } : {}),
...(gates !== undefined ? { gates } : {}),
...(onProgress ? { onProgress } : {}),
+ ...(ctx.configPath ? { configPath: ctx.configPath } : {}),
});
const changeList = dreamChangeList(summary);
// A retire-sibling pair names two preferences; it is kept only when the
diff --git a/src/mcp/brain/query-tools.ts b/src/mcp/brain/query-tools.ts
index 50b9924e..715e274c 100644
--- a/src/mcp/brain/query-tools.ts
+++ b/src/mcp/brain/query-tools.ts
@@ -10,7 +10,7 @@ import {
BrainNotFoundError,
queryByLogSince,
queryByPreference,
- queryByTopic,
+ queryByRuleTopic,
} from "../../core/brain/query.ts";
import { parseIsoUtc } from "../../core/brain/health/iso-time.ts";
import { queryAgentSources } from "../../core/brain/agent-source/query.ts";
@@ -79,7 +79,7 @@ const AS_OF_FORMS = "an ISO-8601 instant or YYYY-MM-DD date";
/**
* The as-of instant the expiration filter is evaluated against.
*
- * `queryByTopic` has taken a `now` option since C5 and this handler
+ * `queryByRuleTopic` has taken a `now` option since C5 and this handler
* dropped it, so an agent could ask to SEE lapsed memories
* (`show_expired`) but never to ask what the brain held at an instant.
* Only topic mode runs that filter, so an `at` supplied beside
@@ -244,7 +244,7 @@ async function toolBrainQuery(
// expiration_date; show_expired re-includes them for audit, and
// `at` moves the clock that filter compares against.
const showExpired = coerceBoolOptional(args, "show_expired") ?? false;
- const res = queryByTopic(ctx.vault, topic, {
+ const res = queryByRuleTopic(ctx.vault, topic, {
showExpired,
transportReach: contextReach(ctx),
...(asOf !== null ? { now: asOf } : {}),
diff --git a/src/mcp/brain/topic-tools.ts b/src/mcp/brain/topic-tools.ts
new file mode 100644
index 00000000..6f94f9d0
--- /dev/null
+++ b/src/mcp/brain/topic-tools.ts
@@ -0,0 +1,223 @@
+/**
+ * `brain_topic` (design D9, spec `topics` "Topics on request"; task 3.5):
+ * the MCP twin of `o2b topic`. Agents change a topic only through this
+ * tool, by recording topic events; topic pages in the human view are
+ * rendered from them by the view writer and are never written by a note
+ * tool.
+ *
+ * Reads (`list`, `show`, `review`) and every write answer at the caller's
+ * reach: the server runs a remote call with the `private` partition
+ * withheld, so a private topic is absent from every list, its id answers
+ * "no topic" to `show` and to every write that names it, and no count or
+ * proposal mentions it. The work lives in `core/topics/actions.ts`.
+ */
+
+import { StoreWriteError } from "../../core/store/store-write.ts";
+import {
+ runTopicAction,
+ TOPIC_ACTIONS,
+ TOPIC_RECORD_ACTION_KINDS,
+ TopicActionError,
+ type TopicActionInput,
+} from "../../core/topics/actions.ts";
+import { TOPIC_STATUSES } from "../../core/topics/constants.ts";
+import { TopicWriteError } from "../../core/topics/write.ts";
+import { coerceStr, unknownOperationError } from "../coerce.ts";
+import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
+import { INVALID_PARAMS, MCPError } from "../protocol.ts";
+import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
+
+const TOOL = "brain_topic";
+
+function optString(args: Record<string, unknown>, key: string): string | undefined {
+ const value = args[key];
+ if (value === undefined || value === null) return undefined;
+ if (typeof value !== "string")
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: '${key}' must be a string`);
+ return value;
+}
+
+function optNullable(args: Record<string, unknown>, key: string): string | null | undefined {
+ return args[key] === null ? null : optString(args, key);
+}
+
+function optBool(args: Record<string, unknown>, key: string): boolean | undefined {
+ const value = args[key];
+ if (value === undefined || value === null) return undefined;
+ // Never dropped: a `private: "true"` that fell away would write to `shared`.
+ if (typeof value !== "boolean")
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: '${key}' must be a boolean`);
+ return value;
+}
+
+function optList(args: Record<string, unknown>, key: string): string[] | undefined {
+ const value = args[key];
+ if (value === undefined) return undefined;
+ if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: '${key}' must be a list of strings`);
+ }
+ return value as string[];
+}
+
+function inputOf(args: Record<string, unknown>, action: string): TopicActionInput {
+ const fields = args["fields"];
+ if (
+ fields !== undefined &&
+ (typeof fields !== "object" || fields === null || Array.isArray(fields))
+ ) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: 'fields' must be an object`);
+ }
+ const strings = [
+ "topic",
+ "title",
+ "scope",
+ "status",
+ "resolved",
+ "record",
+ "into",
+ "to",
+ "authority",
+ "kind",
+ "owner",
+ ];
+ const input: Record<string, unknown> = { action };
+ for (const key of strings) {
+ const value = optString(args, key);
+ if (value !== undefined) input[key] = value;
+ }
+ for (const key of ["description", "goal"]) {
+ const value = optNullable(args, key);
+ if (value !== undefined) input[key] = value;
+ }
+ for (const key of ["items", "records"]) {
+ const value = optList(args, key);
+ if (value !== undefined) input[key] = value;
+ }
+ for (const key of ["removed", "private"]) {
+ const value = optBool(args, key);
+ if (value !== undefined) input[key] = value;
+ }
+ if (fields !== undefined) input["fields"] = fields;
+ const listScope = optString(args, "list_scope");
+ if (listScope !== undefined) input["listScope"] = listScope;
+ return input as unknown as TopicActionInput;
+}
+
+/** The agent a record is written under: the token's agent, else the server's. */
+function agentOf(ctx: ServerContext): string | undefined {
+ return ctx.requestIdentity?.via === "token" ? ctx.requestIdentity.agent : ctx.agentName;
+}
+
+function toolBrainTopic(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Record<string, unknown> {
+ const action = coerceStr(args, "action", true)!;
+ if (!(TOPIC_ACTIONS as ReadonlyArray<string>).includes(action)) {
+ throw unknownOperationError(`${TOOL}: 'action' must be one of ${TOPIC_ACTIONS.join(", ")}`);
+ }
+ try {
+ return runTopicAction(inputOf(args, action), {
+ ...(ctx.configPath !== null ? { configPath: ctx.configPath } : {}),
+ ...(agentOf(ctx) !== undefined ? { agent: agentOf(ctx)! } : {}),
+ });
+ } catch (err) {
+ if (err instanceof TopicActionError || err instanceof TopicWriteError) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`, {
+ code: err instanceof TopicWriteError ? `topic_${err.reason}` : "topic_invalid",
+ });
+ }
+ if (err instanceof StoreWriteError) {
+ throw new MCPError(INVALID_PARAMS, `${TOOL}: ${err.message}`, {
+ code: `store_${err.reason}`,
+ });
+ }
+ throw err;
+ }
+}
+
+export const TOPIC_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
+ {
+ name: TOOL,
+ kind: "write",
+ description:
+ "Topics: list, show, review; create, rename, status, goal, assign, unassign, merge, split, link, archive, undo; record adds your decision, question, log entry or milestone. Writes are yours (agent); pass authority human when the user asked (local only). Undo blocks re-routing. Never edit topic pages.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ action: { type: "string", enum: [...TOPIC_ACTIONS], description: "Action to perform." },
+ topic: {
+ type: "string",
+ description: "Topic id (a ULID) for every action but list, review and create.",
+ },
+ title: { type: "string", maxLength: 200, description: "Title for create and rename." },
+ description: {
+ type: ["string", "null"],
+ description: "One-line description for create and rename (null clears it).",
+ },
+ goal: {
+ type: ["string", "null"],
+ description: "Goal for create and goal (null clears it).",
+ },
+ scope: {
+ type: "string",
+ description:
+ "create: `project:<project>` or `personal` (default). A personal topic is private unless private is false.",
+ },
+ list_scope: { type: "string", description: "list: only topics of this scope." },
+ status: {
+ type: "string",
+ enum: [...TOPIC_STATUSES],
+ description: "status: the new status.",
+ },
+ resolved: { type: "string", description: "status done: the resolved day (YYYY-MM-DD)." },
+ record: {
+ type: "string",
+ description: "assign, unassign: a record id; undo: the topic record to undo.",
+ },
+ into: { type: "string", description: "merge, split: the target topic id." },
+ to: { type: "string", description: "link: the other topic id." },
+ items: {
+ type: "array",
+ items: { type: "string" },
+ description: "split: item ids to move.",
+ },
+ records: {
+ type: "array",
+ items: { type: "string" },
+ description: "split: record ids to move.",
+ },
+ removed: { type: "boolean", description: "link: remove the link." },
+ private: {
+ type: "boolean",
+ description: "Write to the private partition (true) or shared (false).",
+ },
+ authority: {
+ type: "string",
+ enum: ["human", "agent"],
+ description:
+ "human: the user explicitly asked for this (refused from a remote transport, where a request stays an agent record). Default agent.",
+ },
+ owner: {
+ type: "string",
+ description:
+ "record, split: the topic that owns the named item, when merged topics share its id.",
+ },
+ kind: {
+ type: "string",
+ enum: [...TOPIC_RECORD_ACTION_KINDS],
+ description: "record: the kind of event.",
+ },
+ fields: {
+ type: "object",
+ description:
+ "record: the event's fields, as FORMAT.md documents them (for example { text, class } for a log-entry, { milestone, evidence } for milestone-done).",
+ },
+ },
+ required: ["action"],
+ additionalProperties: false,
+ },
+ previewBudget: MCP_PREVIEW_BUDGET,
+ handler: toolBrainTopic,
+ },
+]);
diff --git a/src/mcp/resources-digest-readers.ts b/src/mcp/resources-digest-readers.ts
index 63ba77d9..46bce2e9 100644
--- a/src/mcp/resources-digest-readers.ts
+++ b/src/mcp/resources-digest-readers.ts
@@ -114,6 +114,7 @@ export function readLessons(ctx: ResourceContext, uri: string, view: RequestView
: renderLessonsForReader(ctx.vault, {
readable: view.refs.visible,
...(view.refs.withholdsPrivate === true ? { withholdsPrivate: true } : {}),
+ ...(ctx.configPath ? { configPath: ctx.configPath } : {}),
}).document;
return { uri, mimeType: MIME_MARKDOWN, text: delivery.shape(text, LESSONS_REL) };
}
@@ -164,7 +165,7 @@ export function readStatus(ctx: ResourceContext, uri: string): ResourceContent {
* Render the topic-query result as a compact markdown document. Kept
* here (not in `query.ts`) because the markdown shape is a
* resource-surface concern; callers that want the structured form can
- * still invoke `queryByTopic` directly.
+ * still invoke `queryByRuleTopic` directly.
*/
export function renderStatusMarkdown(s: BrainStatusSnapshot): string {
const lines: string[] = [];
diff --git a/src/mcp/resources-record-readers.ts b/src/mcp/resources-record-readers.ts
index ef389826..70a0fd42 100644
--- a/src/mcp/resources-record-readers.ts
+++ b/src/mcp/resources-record-readers.ts
@@ -19,7 +19,7 @@ import {
validateSlug,
BRAIN_PREFERENCES_REL,
} from "../core/brain/paths.ts";
-import { BrainNotFoundError, queryByPreference, queryByTopic } from "../core/brain/query.ts";
+import { BrainNotFoundError, queryByPreference, queryByRuleTopic } from "../core/brain/query.ts";
import { type ArtifactRefView } from "../core/brain/artifact-ref-view.ts";
import { logEntriesAtReach, recordRefs } from "../core/brain/log-events-at-reach.ts";
import {
@@ -117,7 +117,7 @@ export function readPreference(
};
}
-export function readTopic(
+export function readRuleTopic(
ctx: ResourceContext,
uri: string,
rawSlug: string,
@@ -133,7 +133,7 @@ export function readTopic(
// to one preference and several may carry it, so filtering afterwards
// would report the topic as having no rule whenever another owner's
// preference happened to sort first.
- result = queryByTopic(ctx.vault, rawSlug, {
+ result = queryByRuleTopic(ctx.vault, rawSlug, {
ownerScope: view.ownerScope,
transportReach: view.reach,
});
@@ -165,19 +165,19 @@ export function readTopic(
const preferenceRel = result.preference
? deliveryRelForBrainArtifact(ctx.vault, result.preference.id)
: `${BRAIN_PREFERENCES_REL}/pref-${rawSlug}.md`;
- const objection = topicObjectionSection(ctx.vault, scoped);
+ const objection = ruleTopicObjectionSection(ctx.vault, scoped);
let text: string;
if (objection.rel === null) {
// The block quotes the governing preference itself (or no page at
// all): one document, one probe. The trailing newline keeps the
// unfenced bytes identical to the pre-shaping document.
text = delivery.shape(
- `${renderTopicMarkdown(rawSlug, scoped)}\n${objection.text}\n`,
+ `${renderRuleTopicMarkdown(rawSlug, scoped)}\n${objection.text}\n`,
preferenceRel,
);
} else {
text =
- `${delivery.shape(renderTopicMarkdown(rawSlug, scoped), preferenceRel)}\n` +
+ `${delivery.shape(renderRuleTopicMarkdown(rawSlug, scoped), preferenceRel)}\n` +
`${delivery.shape(objection.text, objection.rel)}\n`;
}
return { uri, mimeType: MIME_MARKDOWN, text };
@@ -257,7 +257,10 @@ export function shardAtReach(
return [head.trimEnd(), ...blocks].join(LOG_BLOCK_SEPARATOR) + "\n";
}
-export function renderTopicMarkdown(slug: string, result: ReturnType<typeof queryByTopic>): string {
+export function renderRuleTopicMarkdown(
+ slug: string,
+ result: ReturnType<typeof queryByRuleTopic>,
+): string {
const lines: string[] = [];
lines.push(`# Brain topic: ${slug}`);
lines.push("");
@@ -311,11 +314,11 @@ export function renderTopicMarkdown(slug: string, result: ReturnType<typeof quer
* the document's treatment, which brain_query's signal payloads shape
* at the same page.
*/
-export function topicObjectionSection(
+export function ruleTopicObjectionSection(
vault: string,
- result: ReturnType<typeof queryByTopic>,
+ result: ReturnType<typeof queryByRuleTopic>,
): { readonly text: string; readonly rel: string | null } {
- const sentence = buildTopicObjection(vault, result);
+ const sentence = buildRuleTopicObjection(vault, result);
const text = `## Strongest objection\n\n- ${sentence.sentence}`;
return { text, rel: sentence.rel };
}
@@ -328,9 +331,9 @@ export function topicObjectionSection(
* objection" sentence when none applies. The rel names the page the
* sentence quotes, for the section renderer to probe.
*/
-export function buildTopicObjection(
+export function buildRuleTopicObjection(
vault: string,
- result: ReturnType<typeof queryByTopic>,
+ result: ReturnType<typeof queryByRuleTopic>,
): { readonly sentence: string; readonly rel: string | null } {
const pref = result.preference;
if (pref && pref.id.startsWith("ret-")) {
diff --git a/src/mcp/resources-shared.ts b/src/mcp/resources-shared.ts
index 9fbe1321..2fe39943 100644
--- a/src/mcp/resources-shared.ts
+++ b/src/mcp/resources-shared.ts
@@ -5,6 +5,7 @@
* the markdown MIME type. Split from `resources.ts`.
*/
+import { isUlid } from "../core/store/ulid.ts";
import { readFileSync } from "node:fs";
import { BrainNotFoundError } from "../core/brain/query.ts";
import { gatedOwnerScopeView } from "../core/brain/owner-scope-view.ts";
@@ -41,6 +42,8 @@ export interface ResourceContext {
* anything, which resolves to the narrowest rather than the widest.
*/
readonly reach?: TransportReach;
+ /** The machine config the server runs under (the store, the device). */
+ readonly configPath?: string | null;
}
export interface ResourceDescriptor {
@@ -80,7 +83,7 @@ export function requestView(ctx: ResourceContext): RequestView {
*
* `refs` is the ANDed decision every reference-shaped filter asks.
* `ownerScope` is separate because two readers push ownership into their
- * SELECTION rather than filtering afterwards - `queryByTopic` and
+ * SELECTION rather than filtering afterwards - `queryByRuleTopic` and
* `buildBacklinkIndex` both take a scope - and that argument is the owner
* rule's alone. The reserved-token rule has no selection-side form; it is
* asked over the rows those selections return.
@@ -131,7 +134,8 @@ export type Parsed =
| { readonly kind: "digestLatest" }
| { readonly kind: "status" }
| { readonly kind: "preference"; readonly id: string }
- | { readonly kind: "topic"; readonly slug: string }
+ | { readonly kind: "ruleTopic"; readonly slug: string; readonly alias: boolean }
+ | { readonly kind: "topic"; readonly id: string }
| { readonly kind: "log"; readonly date: string }
| { readonly kind: "backlinks"; readonly id: string };
@@ -159,8 +163,15 @@ export function parseUri(uri: string): Parsed {
if (head === "preference" && parts.length === 2) {
return { kind: "preference", id: parts[1]! };
}
+ if (head === "rule-topic" && parts.length === 2) {
+ return { kind: "ruleTopic", slug: parts[1]!, alias: false };
+ }
if (head === "topic" && parts.length === 2) {
- return { kind: "topic", slug: parts[1]! };
+ // A topic id is a ULID; anything else is a rule-topic slug through the
+ // old name, kept as an alias for one minor version (design D8).
+ return isUlid(parts[1]!)
+ ? { kind: "topic", id: parts[1]! }
+ : { kind: "ruleTopic", slug: parts[1]!, alias: true };
}
if (head === "log" && parts.length === 2) {
return { kind: "log", date: parts[1]! };
diff --git a/src/mcp/resources-topic-readers.ts b/src/mcp/resources-topic-readers.ts
new file mode 100644
index 00000000..46698207
--- /dev/null
+++ b/src/mcp/resources-topic-readers.ts
@@ -0,0 +1,40 @@
+/**
+ * The topic reader of the `osb://` surface (task 3.5): `osb://topic/{id}`
+ * answers one topic (design D8) by its id, as the page the human view
+ * renders for it.
+ *
+ * Reach: a caller below local reach folds the `shared` partition alone,
+ * so a private topic answers exactly as an absent one, and its existence
+ * does not cross. An id the caller sees no topic for falls back to the
+ * rule-topic reader (the alias of one minor version), as for any value. A
+ * local caller also sees its private topics, which the human view never
+ * shows.
+ */
+
+import { resolvedTransportReach, TRANSPORT_REACH } from "../core/graph/transport-reach.ts";
+import { withPrivateWithheld } from "../core/store/caller-reach.ts";
+import { runTopicAction, TopicActionError } from "../core/topics/actions.ts";
+import { MIME_MARKDOWN, type ResourceContent, type ResourceContext } from "./resources-shared.ts";
+
+/**
+ * The topic page for `id`, or `null` when the caller sees no topic with
+ * that id (absent, or private below local reach). Fenced below local
+ * reach, as all agent-written stored text is.
+ */
+export function readTopicById(
+ ctx: ResourceContext,
+ uri: string,
+ id: string,
+): ResourceContent | null {
+ const remote = resolvedTransportReach(ctx.reach) !== TRANSPORT_REACH.local;
+ const configPath = ctx.configPath ?? undefined;
+ try {
+ const shown = withPrivateWithheld(remote, () =>
+ runTopicAction({ action: "show", topic: id }, configPath !== undefined ? { configPath } : {}),
+ );
+ return { uri, mimeType: MIME_MARKDOWN, text: String(shown["page"]) };
+ } catch (err) {
+ if (err instanceof TopicActionError) return null;
+ throw err;
+ }
+}
diff --git a/src/mcp/resources.ts b/src/mcp/resources.ts
index f30e249a..9ce26d22 100644
--- a/src/mcp/resources.ts
+++ b/src/mcp/resources.ts
@@ -10,9 +10,13 @@
* osb://preference/{id} — Brain/preferences/pref-{id}.md OR
* Brain/retired/ret-{id}.md when the
* preferences/ copy is gone
- * osb://topic/{slug} — synthesized markdown summary of every
+ * osb://rule-topic/{slug} — synthesized markdown summary of every
* signal + the current pref / retired
- * for the topic slug
+ * for the rule-topic slug (the old name
+ * osb://topic/{slug} is an alias for one
+ * minor version)
+ * osb://topic/{id} — one topic (design D8) by its id, as
+ * its rendered page
* osb://log/{date} — Brain/log/<date>.md as-is
*
* The first two are concrete resources (returned by `resources/list`).
@@ -71,8 +75,9 @@ import {
readLessons,
readStatus,
} from "./resources-digest-readers.ts";
-import { readLog, readPreference, readTopic } from "./resources-record-readers.ts";
+import { readLog, readPreference, readRuleTopic } from "./resources-record-readers.ts";
import { readBacklinks } from "./resources-backlink-readers.ts";
+import { readTopicById } from "./resources-topic-readers.ts";
export type {
ResourceContext,
@@ -120,10 +125,17 @@ const TEMPLATES: ReadonlyArray<ResourceTemplateDescriptor> = [
mimeType: MIME_MARKDOWN,
},
{
- uriTemplate: "osb://topic/{slug}",
- name: "Brain topic summary",
+ uriTemplate: "osb://rule-topic/{slug}",
+ name: "Brain rule-topic summary",
description:
- "Markdown synthesis of every signal (active + processed), the current preference (or retired), the most recent log mentions, and a deterministic 'Strongest objection' steelman against the current preference for the topic slug.",
+ "Markdown synthesis of every signal (active + processed), the current preference (or retired), the most recent log mentions, and a deterministic 'Strongest objection' steelman against the current preference for the rule-topic slug. The old name osb://topic/{slug} still answers for one minor version.",
+ mimeType: MIME_MARKDOWN,
+ },
+ {
+ uriTemplate: "osb://topic/{id}",
+ name: "Brain topic",
+ description:
+ "One topic by its id (a ULID): the page the human view renders for it (status, goal, milestones, decisions, open questions, log, related), as Markdown.",
mimeType: MIME_MARKDOWN,
},
{
@@ -162,8 +174,14 @@ export function readResource(ctx: ResourceContext, uri: string): ResourceContent
return readStatus(ctx, uri);
case "preference":
return readPreference(ctx, uri, parsed.id, requestView(ctx));
+ case "ruleTopic":
+ return readRuleTopic(ctx, uri, parsed.slug, requestView(ctx));
case "topic":
- return readTopic(ctx, uri, parsed.slug, requestView(ctx));
+ // A ULID-shaped value that names no topic the caller sees is still a
+ // rule-topic slug through the old name.
+ return (
+ readTopicById(ctx, uri, parsed.id) ?? readRuleTopic(ctx, uri, parsed.id, requestView(ctx))
+ );
case "log":
return readLog(ctx, uri, parsed.date, requestView(ctx));
case "backlinks":
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 48aa56d8..21ddfafe 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -617,6 +617,7 @@ export class MCPServer {
vault: this.vault,
agentName: this.contextFor(identity).agentName,
reach: this.reach,
+ configPath: this.configPath,
},
uri,
);
diff --git a/tests/cli/brain-query-as-of.test.ts b/tests/cli/brain-query-as-of.test.ts
index 50bf4d40..b2bfb3f4 100644
--- a/tests/cli/brain-query-as-of.test.ts
+++ b/tests/cli/brain-query-as-of.test.ts
@@ -3,9 +3,9 @@
* task J).
*
* The expiry filter has taken an as-of instant since C5 - `filterExpired`
- * defaults `now` to the wall clock and `queryByTopic` threads a `now`
+ * defaults `now` to the wall clock and `queryByRuleTopic` threads a `now`
* option straight into it - and no surface ever passed one. The CLI
- * called `queryByTopic(vault, topic)` with no options object at all, so
+ * called `queryByRuleTopic(vault, topic)` with no options object at all, so
* "what did the brain hold as of last month" was unaskable from the one
* surface that enforces expiry, and `--show-expired` (which MCP has had
* since C5) did not exist on the CLI either.
diff --git a/tests/cli/topic-cli.test.ts b/tests/cli/topic-cli.test.ts
new file mode 100644
index 00000000..eddc0882
--- /dev/null
+++ b/tests/cli/topic-cli.test.ts
@@ -0,0 +1,148 @@
+/**
+ * The `o2b topic` verbs the guide does not run (review fix of task 3.5):
+ * `goal` (and `--clear`), `assign`, `unassign`, `merge --into`,
+ * `split --into --items` and `link --to` (and `--remove`), each through
+ * the real CLI in a child process against a fresh store, its effect read
+ * back with `show --json`. A command is the user asking, so every record
+ * it writes carries human authority.
+ */
+import { afterAll, beforeAll, describe, expect, setDefaultTimeout, test } from "bun:test";
+import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { readPartition } from "../../src/core/store/state-digest.ts";
+import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
+
+setDefaultTimeout(CLI_SPAWN_BUDGET_MS * 4);
+
+const CLI_ENTRY = resolve(import.meta.dir, "..", "..", "src", "cli", "main.ts");
+let parent: string;
+let env: Record<string, string>;
+
+beforeAll(() => {
+ parent = mkdtempSync(join(tmpdir(), "o2b-topic-cli-"));
+ const config = join(parent, "config.yaml");
+ writeFileSync(config, "");
+ env = {
+ OPEN_SECOND_BRAIN_CONFIG: config,
+ OPEN_SECOND_BRAIN_STORE_ROOT: join(parent, "store"),
+ O2B_DEVICE_ID: "laptop",
+ HOME: join(parent, "home"),
+ XDG_STATE_HOME: join(parent, "state"),
+ LOCALAPPDATA: join(parent, "state"),
+ VAULT_DIR: "",
+ };
+ expect(cli(["store", "init"]).code).toBe(0);
+});
+afterAll(() => rmSync(parent, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }));
+
+function cli(args: ReadonlyArray<string>): { code: number; out: string } {
+ const child = Bun.spawnSync([process.execPath, CLI_ENTRY, ...args], {
+ env: { ...process.env, ...env },
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ timeout: CLI_SPAWN_BUDGET_MS,
+ });
+ return { code: child.exitCode ?? -1, out: `${child.stdout}${child.stderr}` };
+}
+
+function json(args: ReadonlyArray<string>): Record<string, unknown> {
+ const result = cli([...args, "--json"]);
+ expect({ args, code: result.code }).toEqual({ args, code: 0 });
+ return JSON.parse(result.out) as Record<string, unknown>;
+}
+
+const create = (title: string): string =>
+ json(["topic", "create", title, "--scope", "project:o2b"])["topic"] as string;
+const show = (topic: string): Record<string, unknown> =>
+ json(["topic", "show", topic])["topic"] as Record<string, unknown>;
+const itemTexts = (topic: string): string[] =>
+ (show(topic)["items"] as Array<{ text: string }>).map((i) => i.text);
+
+describe("o2b topic verbs", () => {
+ test("goal, assign, unassign, link, split and merge do what their flags say", () => {
+ const store = create("Store");
+ const docs = create("Docs");
+
+ json(["topic", "goal", store, "Ship phase 3"]);
+ expect(show(store)["goal"]).toBe("Ship phase 3");
+ json(["topic", "goal", store, "--clear"]);
+ expect(show(store)["goal"]).toBeNull();
+
+ const record = "01KA0000000000000000000009";
+ json(["topic", "assign", store, record]);
+ json(["topic", "unassign", store, record]);
+
+ json(["topic", "link", store, "--to", docs]);
+ expect(show(docs)["links"]).toEqual([store]);
+ json(["topic", "link", store, "--to", docs, "--remove"]);
+ expect(show(docs)["links"]).toEqual([]);
+
+ json(["topic", "record", store, "decision", "--text", "Keep JSONL", "--item", "d1"]);
+ json(["topic", "record", store, "decision", "--text", "Write the guide", "--item", "d2"]);
+ json(["topic", "split", store, "--into", docs, "--items", "d2"]);
+ const texts = (topic: string) =>
+ (show(topic)["items"] as Array<{ text: string }>).map((i) => i.text);
+ expect(texts(store)).toEqual(["Keep JSONL"]);
+ expect(texts(docs)).toEqual(["Write the guide"]);
+
+ json(["topic", "merge", docs, "--into", store]);
+ expect(show(docs)["id"]).toBe(store);
+ expect(texts(store).toSorted()).toEqual(["Keep JSONL", "Write the guide"]);
+
+ const authorities = readPartition(join(parent, "store", "shared"))
+ .filter((s) => s.stream === "topics")
+ .flatMap((s) => s.records)
+ .map((r) => [r.kind, r.body["authority"]]);
+ expect(
+ authorities.filter(([kind]) => kind !== "decision").every(([, a]) => a === "human"),
+ ).toBe(true);
+ expect(authorities.filter(([kind]) => kind === "decision").map(([, a]) => a)).toEqual([
+ "agent",
+ "agent",
+ ]);
+ });
+
+ test("split --owner names which merged topic's item moves when two share its id", () => {
+ const one = create("Owner one");
+ const two = create("Owner two");
+ const dest = create("Owner dest");
+ json(["topic", "record", one, "milestone", "--text", "One's", "--item", "m1"]);
+ json(["topic", "record", two, "milestone", "--text", "Two's", "--item", "m1"]);
+ json(["topic", "merge", one, "--into", two]);
+ const ambiguous = cli(["topic", "split", two, "--into", dest, "--items", "m1"]);
+ expect(ambiguous.code).not.toBe(0);
+ expect(ambiguous.out).toContain("name its owner");
+ json(["topic", "split", two, "--into", dest, "--items", "m1", "--owner", one]);
+ expect(itemTexts(dest)).toEqual(["One's"]);
+ expect(itemTexts(two)).toEqual(["Two's"]);
+ });
+
+ test("a verb without the flag it needs is refused with a usage error", () => {
+ const store = create("Lonely");
+ expect(cli(["topic", "merge", store]).code).toBe(1);
+ expect(cli(["topic", "goal", store]).code).toBe(2);
+ });
+});
+
+describe("o2b topic help and an incomplete review", () => {
+ test("topic --help prints the topic usage", () => {
+ const result = cli(["topic", "--help"]);
+ expect(result.code).toBe(0);
+ expect(result.out).toContain("usage: o2b topic list");
+ });
+
+ test("a review over a partly unreadable topics shard says so and exits non-zero", () => {
+ const store = create("Broken soon");
+ void store;
+ const dir = join(parent, "store", "shared", "topics", "laptop");
+ const shard = join(dir, readdirSync(dir)[0]!);
+ const lines = readFileSync(shard, "utf8").split("\n");
+ writeFileSync(shard, [lines[0], "{broken", ...lines.slice(1)].join("\n"));
+ const result = cli(["topic", "review"]);
+ expect(result.code).toBe(1);
+ expect(result.out).toContain("review incomplete");
+ });
+});
diff --git a/tests/contract/serve-with-correction.test.ts b/tests/contract/serve-with-correction.test.ts
index 16a501ef..f0ec786b 100644
--- a/tests/contract/serve-with-correction.test.ts
+++ b/tests/contract/serve-with-correction.test.ts
@@ -20,7 +20,7 @@ import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { brainDirs } from "../../src/core/brain/paths.ts";
-import { queryByTopic } from "../../src/core/brain/query.ts";
+import { queryByRuleTopic } from "../../src/core/brain/query.ts";
import { correct } from "../../src/core/brain/lifecycle/correction.ts";
import { appendClaimEvent, readClaimEvents } from "../../src/core/brain/truth/store.ts";
import { computeTruthStateWithConflicts } from "../../src/core/brain/truth/conflicts.ts";
@@ -138,7 +138,7 @@ describe("serve-with-correction contract", () => {
expect(event).toBeDefined();
expect(event!.validFrom).toBe(CORRECTION_TS);
- const out = queryByTopic(vault, "deploy-timeout");
+ const out = queryByRuleTopic(vault, "deploy-timeout");
expect(out.preference?.id).toBe("pref-old");
});
@@ -148,7 +148,7 @@ describe("serve-with-correction contract", () => {
rmSync(join(brainDirs(vault).preferences, "pref-new.md"));
- const out = queryByTopic(vault, "deploy-timeout");
+ const out = queryByRuleTopic(vault, "deploy-timeout");
expect(out.preference).toBeNull();
});
@@ -161,7 +161,7 @@ describe("serve-with-correction contract", () => {
expect(retirement.reasonCode).toBe("tombstone");
expect(retirement.validUntil).toBeNull();
- const out = queryByTopic(vault, "deploy-timeout");
+ const out = queryByRuleTopic(vault, "deploy-timeout");
expect(out.preference).toBeNull();
});
diff --git a/tests/core/architecture/content-class-census.test.ts b/tests/core/architecture/content-class-census.test.ts
index e693dbf9..a5c8fb74 100644
--- a/tests/core/architecture/content-class-census.test.ts
+++ b/tests/core/architecture/content-class-census.test.ts
@@ -67,7 +67,7 @@
* which is how the per-collection shape looks when it is done right).
*/
-import { describe, expect, test } from "bun:test";
+import { describe, setDefaultTimeout, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";
@@ -269,6 +269,16 @@ const PAGE_CARRYING_SITES: ReadonlyArray<string> = Object.freeze([
const ENTRIES = Object.values(EGRESS_SITES);
+/**
+ * Every test here scans the whole source tree, some of them more than
+ * once; that walk grows with the tree and takes several seconds on a
+ * loaded runner, past bun's 5 s default. One budget for the file, the
+ * one its slowest tests already carried, so no test depends on an idle
+ * machine.
+ */
+const CENSUS_SCAN_BUDGET_MS = 20_000;
+setDefaultTimeout(CENSUS_SCAN_BUDGET_MS);
+
describe("content-class egress census", () => {
test("the derived population is the named page-carrying sites, as an equality", () => {
expect([...POPULATION].toSorted()).toEqual([...PAGE_CARRYING_SITES].toSorted());
@@ -292,7 +302,7 @@ describe("content-class egress census", () => {
// carries its own budget instead of riding the default.
test("every page-carrying site applies the class filter", () => {
expect(classFilterCensus(SOURCE_TREE)).toEqual([]);
- }, 20000);
+ });
test("the pack verb's delegated filter is really there", () => {
// The one hop the census credits. If the selection step's block scan
@@ -343,7 +353,7 @@ describe("the content-class census cannot pass by finding nothing", () => {
// census names it - a blinded detector or a vacuous census shows here.
expect(isPageCarryingRedactor(intruder.text)).toBe(true);
expect(classFilterCensus([...SOURCE_TREE, intruder])).toContain(intruder.path);
- }, 20000);
+ });
test("removing the seam from a real verb is reported by name", () => {
for (const path of [
@@ -358,7 +368,7 @@ describe("the content-class census cannot pass by finding nothing", () => {
const tree = SOURCE_TREE.map((f) => (f.path === path ? { path, text: stripped } : f));
expect(classFilterCensus(tree)).toContain(path);
}
- }, 20000);
+ });
test("removing the transcript naming from `brain export` is reported by name", () => {
// The transcript branch's duty is refuse-or-name, never silently
diff --git a/tests/core/architecture/visibility-surface-census.test.ts b/tests/core/architecture/visibility-surface-census.test.ts
index 81ebcbe1..2a88a846 100644
--- a/tests/core/architecture/visibility-surface-census.test.ts
+++ b/tests/core/architecture/visibility-surface-census.test.ts
@@ -226,7 +226,7 @@ const NOTE_CONTENT_PRODUCERS: ReadonlyArray<ProducerRule> = Object.freeze([
identifiers: ["buildConceptCluster"],
},
{ specifierIncludes: "/brain/portability/sources.ts", identifiers: ["aggregateSources"] },
- { specifierIncludes: "/brain/query.ts", identifiers: ["queryByPreference", "queryByTopic"] },
+ { specifierIncludes: "/brain/query.ts", identifiers: ["queryByPreference", "queryByRuleTopic"] },
{ specifierIncludes: "/brain/pref-audit.ts", identifiers: ["readPrefAudit"] },
{
specifierIncludes: "/brain/link-graph/bridge-discovery.ts",
@@ -663,7 +663,7 @@ function reasonProblems(entries: ReadonlyArray<VisibilitySurfaceEntry>): {
*/
const MCP_TOOL_POPULATION_SIZE = 89;
/** Measured: MCP resources + templates. */
-const MCP_RESOURCE_POPULATION_SIZE = 8;
+const MCP_RESOURCE_POPULATION_SIZE = 9;
/**
* Measured: hand-enumerated CLI verb mirrors. 20 -> 21: `brain attest`
* (delivery trust) joins as the CLI mirror of `brain_attestations`; the
@@ -818,7 +818,8 @@ describe("visibility surface census", () => {
"osb://log/{date}",
"osb://preference/{id}",
"osb://preferences/active",
- "osb://topic/{slug}",
+ "osb://rule-topic/{slug}",
+ "osb://topic/{id}",
]);
expect(byCategory(VISIBILITY_SURFACE_CATEGORY.excluded)).toEqual(["osb://status"]);
});
diff --git a/tests/core/brain.query.test.ts b/tests/core/brain.query.test.ts
index 64544f74..93e6f435 100644
--- a/tests/core/brain.query.test.ts
+++ b/tests/core/brain.query.test.ts
@@ -23,7 +23,7 @@ import {
BrainNotFoundError,
queryByLogSince,
queryByPreference,
- queryByTopic,
+ queryByRuleTopic,
} from "../../src/core/brain/query.ts";
let tmp: string;
@@ -164,7 +164,7 @@ describe("queryByPreference", () => {
});
});
-describe("queryByTopic", () => {
+describe("queryByRuleTopic", () => {
test("collects active and processed signals plus the active preference", () => {
// Two signals — one active, one already processed.
writeSignal(tmp, {
@@ -211,7 +211,7 @@ describe("queryByTopic", () => {
},
});
- const res = queryByTopic(tmp, "no-internal-abbrev");
+ const res = queryByRuleTopic(tmp, "no-internal-abbrev");
expect(res.signals).toHaveLength(2);
expect(res.signals.map((s) => s.id)).toEqual([
"sig-2026-05-13-no-internal-abbrev",
@@ -228,7 +228,7 @@ describe("queryByTopic", () => {
now: new Date("2026-08-12T05:00:00Z"),
retired_by: "[[Brain/log/2026-08-12]]",
});
- const res = queryByTopic(tmp, "orphan");
+ const res = queryByRuleTopic(tmp, "orphan");
expect(res.preference?.id).toBe("ret-orphan");
expect(res.signals).toEqual([]);
});
@@ -243,16 +243,16 @@ describe("queryByTopic", () => {
writePreference(tmp, { ...basePref("alpha"), slug: "alpha", topic: "shared-topic" });
writePreference(tmp, { ...basePref("middle"), slug: "middle", topic: "shared-topic" });
- const r1 = queryByTopic(tmp, "shared-topic");
- const r2 = queryByTopic(tmp, "shared-topic");
- const r3 = queryByTopic(tmp, "shared-topic");
+ const r1 = queryByRuleTopic(tmp, "shared-topic");
+ const r2 = queryByRuleTopic(tmp, "shared-topic");
+ const r3 = queryByRuleTopic(tmp, "shared-topic");
expect(r1.preference?.id).toBe("pref-alpha");
expect(r2.preference?.id).toBe("pref-alpha");
expect(r3.preference?.id).toBe("pref-alpha");
});
test("unknown topic returns null preference and empty signals/events", () => {
- const res = queryByTopic(tmp, "never-existed");
+ const res = queryByRuleTopic(tmp, "never-existed");
expect(res.signals).toEqual([]);
expect(res.preference).toBeNull();
expect(res.all_log_events).toEqual([]);
diff --git a/tests/core/brain/coupling-surfaces.test.ts b/tests/core/brain/coupling-surfaces.test.ts
index 185fbd67..4ce714b3 100644
--- a/tests/core/brain/coupling-surfaces.test.ts
+++ b/tests/core/brain/coupling-surfaces.test.ts
@@ -6,7 +6,7 @@
* through `couplingVerdict`: the record appears only beside its
* resolved, readable chain-tip correction and is dropped fail-closed
* otherwise - a withheld correction takes its predecessor with it. The
- * surfaces covered here are recall by topic (`queryByTopic`), the
+ * surfaces covered here are recall by topic (`queryByRuleTopic`), the
* context pack, the active.md digest and the dream scan.
*
* Today's exclusion wiring is pinned too: a tombstoned retired record
@@ -23,7 +23,7 @@ import { join } from "node:path";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
-import { queryByTopic } from "../../../src/core/brain/query.ts";
+import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { packContext } from "../../../src/core/brain/context-pack.ts";
import { renderActive } from "../../../src/core/brain/active.ts";
import { scanBrain } from "../../../src/core/brain/dream-scan.ts";
@@ -106,21 +106,21 @@ describe("recall by topic", () => {
writePreferencePage("pref-new", "alpha-v2");
writeRetired("ret-old", { topic: "alpha", supersededBy: "pref-new" });
- const out = queryByTopic(vault, "alpha");
+ const out = queryByRuleTopic(vault, "alpha");
expect(out.preference?.id).toBe("ret-old");
});
test("a retired record whose correction is unresolved is dropped fail-closed", () => {
writeRetired("ret-dangling", { topic: "beta", supersededBy: "pref-ghost" });
- const out = queryByTopic(vault, "beta");
+ const out = queryByRuleTopic(vault, "beta");
expect(out.preference).toBeNull();
});
test("a retired record with no successor pointer keeps today's behavior", () => {
writeRetired("ret-plain", { topic: "gamma" });
- const out = queryByTopic(vault, "gamma");
+ const out = queryByRuleTopic(vault, "gamma");
expect(out.preference?.id).toBe("ret-plain");
});
@@ -128,7 +128,7 @@ describe("recall by topic", () => {
writePreferencePage("pref-new", "delta-v2");
writeRetired("ret-dead", { topic: "delta", supersededBy: "pref-new", tombstoned: true });
- const out = queryByTopic(vault, "delta");
+ const out = queryByRuleTopic(vault, "delta");
expect(out.preference).toBeNull();
});
@@ -136,7 +136,7 @@ describe("recall by topic", () => {
writePreferencePage("pref-new", "alpha-v2");
writeRetired("ret-old", { topic: "alpha", supersededBy: "pref-new" });
- const out = queryByTopic(vault, "alpha-v2");
+ const out = queryByRuleTopic(vault, "alpha-v2");
expect(out.preference?.id).toBe("pref-new");
});
});
diff --git a/tests/core/brain/decisions/record.test.ts b/tests/core/brain/decisions/record.test.ts
index 8c8f9bb6..34cb250b 100644
--- a/tests/core/brain/decisions/record.test.ts
+++ b/tests/core/brain/decisions/record.test.ts
@@ -7,7 +7,7 @@ import { parseFrontmatter } from "../../../../src/core/vault.ts";
import { readLogDay } from "../../../../src/core/brain/log-jsonl.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../../src/core/brain/types.ts";
import { listObligations } from "../../../../src/core/brain/obligations.ts";
-import { queryByTopic } from "../../../../src/core/brain/query.ts";
+import { queryByRuleTopic } from "../../../../src/core/brain/query.ts";
import {
DECISION_TYPE,
DecisionError,
@@ -218,7 +218,7 @@ describe("rating and rationale (B2)", () => {
test("rated decisions do not pollute signal/preference recall", () => {
recordDecision(vault, baseInput({ title: "deploy runtime choice", chosen: "Bun", rating: 5 }));
- const recall = queryByTopic(vault, "deploy");
+ const recall = queryByRuleTopic(vault, "deploy");
expect(recall.signals.length).toBe(0);
expect(recall.preference).toBeNull();
});
diff --git a/tests/core/brain/dream-expiration-filter.test.ts b/tests/core/brain/dream-expiration-filter.test.ts
index 7ea4834c..b035e56d 100644
--- a/tests/core/brain/dream-expiration-filter.test.ts
+++ b/tests/core/brain/dream-expiration-filter.test.ts
@@ -3,7 +3,7 @@
*
* The ambient TTL stamps `expiration_date = created + N` on extracted
* signals; the query read path drops a signal past that date from recall
- * (`filterExpired`, reached only through `queryByTopic`). The dream pass
+ * (`filterExpired`, reached only through `queryByRuleTopic`). The dream pass
* read the same files with no such filter, so a transient fact whose TTL
* lapsed inside the contradiction window was still clustered, still
* counted toward the candidate threshold, and finally consolidated into a
diff --git a/tests/core/brain/expiration-set.test.ts b/tests/core/brain/expiration-set.test.ts
index c36a063e..bac42df7 100644
--- a/tests/core/brain/expiration-set.test.ts
+++ b/tests/core/brain/expiration-set.test.ts
@@ -41,7 +41,7 @@ import {
ExpirationValueError,
setExpiration,
} from "../../../src/core/brain/expiration-set.ts";
-import { queryByTopic } from "../../../src/core/brain/query.ts";
+import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { resolveAppendShardId } from "../../../src/core/brain/ledger-shards.ts";
import { logShardJsonlPath } from "../../../src/core/brain/paths.ts";
import { writePreference } from "../../../src/core/brain/preference.ts";
@@ -269,15 +269,17 @@ describe("what an expiration is FOR", () => {
seedPreference();
setExpiration(vault, signalId, "2026-07-15");
- const live = queryByTopic(vault, "staging-endpoint", { now: new Date("2026-07-15T12:00:00Z") });
+ const live = queryByRuleTopic(vault, "staging-endpoint", {
+ now: new Date("2026-07-15T12:00:00Z"),
+ });
expect(live.signals.map((s) => s.id)).toContain(signalId);
- const lapsed = queryByTopic(vault, "staging-endpoint", {
+ const lapsed = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2026-07-16T00:00:01Z"),
});
expect(lapsed.signals.map((s) => s.id)).not.toContain(signalId);
- const audited = queryByTopic(vault, "staging-endpoint", {
+ const audited = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2026-07-16T00:00:01Z"),
showExpired: true,
});
@@ -288,7 +290,7 @@ describe("what an expiration is FOR", () => {
const signalId = seedSignal();
setExpiration(vault, signalId, "2026-07-15");
setExpiration(vault, signalId, EXPIRATION_CLEAR);
- const after = queryByTopic(vault, "staging-endpoint", {
+ const after = queryByRuleTopic(vault, "staging-endpoint", {
now: new Date("2027-01-01T00:00:00Z"),
});
expect(after.signals.map((s) => s.id)).toContain(signalId);
diff --git a/tests/core/brain/preference-expiration.test.ts b/tests/core/brain/preference-expiration.test.ts
index 6803bff1..e251ae68 100644
--- a/tests/core/brain/preference-expiration.test.ts
+++ b/tests/core/brain/preference-expiration.test.ts
@@ -19,7 +19,7 @@ import {
type WritePreferenceInput,
} from "../../../src/core/brain/preference.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
-import { queryByTopic } from "../../../src/core/brain/query.ts";
+import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { BRAIN_CONFIDENCE, BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";
let vault: string;
@@ -81,7 +81,7 @@ describe("writePreference — expiration_date frontmatter", () => {
});
});
-describe("queryByTopic — default drops expired, showExpired re-includes", () => {
+describe("queryByRuleTopic — default drops expired, showExpired re-includes", () => {
const now = new Date("2026-08-01T00:00:00Z");
function seedExpiredPreference(): void {
@@ -100,27 +100,27 @@ describe("queryByTopic — default drops expired, showExpired re-includes", () =
test("default query drops a preference past its expiration_date", () => {
seedExpiredPreference();
- const res = queryByTopic(vault, "deploy", { now });
+ const res = queryByRuleTopic(vault, "deploy", { now });
expect(res.preference).toBeNull();
});
test("showExpired: true re-includes the expired preference (audit path)", () => {
seedExpiredPreference();
- const res = queryByTopic(vault, "deploy", { now, showExpired: true });
+ const res = queryByRuleTopic(vault, "deploy", { now, showExpired: true });
expect(res.preference).not.toBeNull();
expect(res.preference?.id).toBe("pref-expired-rule");
});
test("a still-live preference is returned by the default query", () => {
writePreference(vault, basePref("live-rule", { expiration_date: "2026-12-31" }));
- const res = queryByTopic(vault, "deploy", { now });
+ const res = queryByRuleTopic(vault, "deploy", { now });
expect(res.preference?.id).toBe("pref-live-rule");
});
test("an expired preference is FILTERED, not moved to Brain/retired/ (audit trail preserved)", () => {
seedExpiredPreference();
// A read that drops the expired preference must not touch disk.
- queryByTopic(vault, "deploy", { now });
+ queryByRuleTopic(vault, "deploy", { now });
expect(existsSync(join(vault, "Brain", "preferences", "pref-expired-rule.md"))).toBe(true);
expect(existsSync(join(vault, "Brain", "retired", "ret-expired-rule.md"))).toBe(false);
});
diff --git a/tests/core/brain/signal-expiration.test.ts b/tests/core/brain/signal-expiration.test.ts
index a2a132e4..7357ac21 100644
--- a/tests/core/brain/signal-expiration.test.ts
+++ b/tests/core/brain/signal-expiration.test.ts
@@ -13,7 +13,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { parseSignal, writeSignal, type WriteSignalInput } from "../../../src/core/brain/signal.ts";
-import { queryByTopic } from "../../../src/core/brain/query.ts";
+import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { filterExpired } from "../../../src/core/brain/expiration.ts";
let vault: string;
@@ -63,7 +63,7 @@ describe("writeSignal — expiration_date frontmatter", () => {
});
});
-describe("queryByTopic — default drops expired signals, showExpired re-includes", () => {
+describe("queryByRuleTopic — default drops expired signals, showExpired re-includes", () => {
const now = new Date("2026-08-01T00:00:00Z");
function seed(): void {
@@ -74,7 +74,7 @@ describe("queryByTopic — default drops expired signals, showExpired re-include
test("default query drops signals past their expiration_date", () => {
seed();
- const res = queryByTopic(vault, "deploy", { now });
+ const res = queryByRuleTopic(vault, "deploy", { now });
const principles = res.signals.map((s) => s.principle).sort();
// The expired one is dropped; the live one and the never-expiring one stay.
expect(principles).toEqual(["Principle for live-sig", "Principle for no-expiry-sig"]);
@@ -82,13 +82,13 @@ describe("queryByTopic — default drops expired signals, showExpired re-include
test("showExpired: true re-includes the expired signal (audit path)", () => {
seed();
- const res = queryByTopic(vault, "deploy", { now, showExpired: true });
+ const res = queryByRuleTopic(vault, "deploy", { now, showExpired: true });
expect(res.signals.length).toBe(3);
});
test("an expired signal is FILTERED, not deleted from the inbox", () => {
const res = writeSignal(vault, baseSignal("expired-sig", { expiration_date: "2026-07-15" }));
- queryByTopic(vault, "deploy", { now });
+ queryByRuleTopic(vault, "deploy", { now });
expect(existsSync(res.path)).toBe(true);
});
@@ -107,11 +107,13 @@ describe("queryByTopic — default drops expired signals, showExpired re-include
expect(parsed.source_type).toBe("extracted");
expect(filterExpired([parsed], { now: new Date("2026-07-15T09:29:59Z") }).length).toBe(1);
expect(filterExpired([parsed], { now: new Date("2026-07-15T09:30:01Z") }).length).toBe(0);
- const query = queryByTopic(vault, "deploy", { now: new Date("2026-08-01T00:00:00Z") });
+ const query = queryByRuleTopic(vault, "deploy", { now: new Date("2026-08-01T00:00:00Z") });
expect(query.signals.length).toBe(0);
expect(
- queryByTopic(vault, "deploy", { now: new Date("2026-08-01T00:00:00Z"), showExpired: true })
- .signals.length,
+ queryByRuleTopic(vault, "deploy", {
+ now: new Date("2026-08-01T00:00:00Z"),
+ showExpired: true,
+ }).signals.length,
).toBe(1);
});
});
diff --git a/tests/core/brain/signal-retire.test.ts b/tests/core/brain/signal-retire.test.ts
index 63319150..950a01fa 100644
--- a/tests/core/brain/signal-retire.test.ts
+++ b/tests/core/brain/signal-retire.test.ts
@@ -19,7 +19,7 @@ import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { parseFrontmatter } from "../../../src/core/vault.ts";
import { parseSignal, writeSignal } from "../../../src/core/brain/signal.ts";
-import { queryByTopic, readAllLogEntries } from "../../../src/core/brain/query.ts";
+import { queryByRuleTopic, readAllLogEntries } from "../../../src/core/brain/query.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../src/core/brain/types.ts";
import {
InvalidSignalIdError,
@@ -95,12 +95,12 @@ describe("retireSignal", () => {
test("the retired signal is excluded from dream intake but stays readable", () => {
const id = seedSignal("fact-url", "fact-url-topic");
// Before retirement the dream-intake surface (inbox + processed) sees it.
- expect(queryByTopic(vault, "fact-url-topic").signals.map((s) => s.id)).toContain(id);
+ expect(queryByRuleTopic(vault, "fact-url-topic").signals.map((s) => s.id)).toContain(id);
const res = retireSignal(vault, id, { reason: "no longer relevant", now: NOW });
// The dream signal-collection surface no longer sees it.
- expect(queryByTopic(vault, "fact-url-topic").signals.map((s) => s.id)).not.toContain(id);
+ expect(queryByRuleTopic(vault, "fact-url-topic").signals.map((s) => s.id)).not.toContain(id);
// But it remains readable in the retired directory.
const reread = parseSignal(res.path);
expect(reread.id).toBe(id);
diff --git a/tests/core/brain/store-readers/reader-parity.test.ts b/tests/core/brain/store-readers/reader-parity.test.ts
index df1dafcf..f506f71c 100644
--- a/tests/core/brain/store-readers/reader-parity.test.ts
+++ b/tests/core/brain/store-readers/reader-parity.test.ts
@@ -36,7 +36,7 @@ import { loadPreference } from "../../../../src/core/brain/preference.ts";
import {
queryByLogSince,
queryByPreference,
- queryByTopic,
+ queryByRuleTopic,
readAllLogEntries,
} from "../../../../src/core/brain/query.ts";
import { vaultAgentSourceProvider as vaultProvider } from "../../../../src/core/brain/agent-source/vault-provider.ts";
@@ -181,7 +181,7 @@ const READERS: ReadonlyArray<Reader> = [
},
{
name: "query by topic",
- read: (env) => queryByTopic(env.vault, "tabs", { now: FIXTURE_NOW }),
+ read: (env) => queryByRuleTopic(env.vault, "tabs", { now: FIXTURE_NOW }),
holdsData: mentions(FIXTURE.confirmed, FIXTURE.activeSignals[0]!),
},
{
diff --git a/tests/core/install/tool-ceiling.test.ts b/tests/core/install/tool-ceiling.test.ts
index 6b6cf42a..2dda80d6 100644
--- a/tests/core/install/tool-ceiling.test.ts
+++ b/tests/core/install/tool-ceiling.test.ts
@@ -354,8 +354,8 @@ describe("the capability report states the ceiling it runs under", () => {
// wave added brain_attestations (121); the agent-presence wave added
// brain_skill_rewrite_status (122); the brain-store wave added
// brain_changes (123); the shared-settings change added brain_settings
- // (124).
- expect(evaluated.available_tool_count).toBe(124);
+ // (124); topics added brain_topic (125).
+ expect(evaluated.available_tool_count).toBe(125);
expect(evaluated.advertised_tool_count).toBe(7);
});
});
diff --git a/tests/core/store/fixtures/fold-records.ts b/tests/core/store/fixtures/fold-records.ts
index a582c7d1..68c44788 100644
--- a/tests/core/store/fixtures/fold-records.ts
+++ b/tests/core/store/fixtures/fold-records.ts
@@ -59,6 +59,7 @@ export interface RecSpec {
readonly body: RecordBody;
readonly agent?: string;
readonly id?: string;
+ readonly topic?: string | null;
readonly rng?: () => number;
}
@@ -70,6 +71,7 @@ export function rec(spec: RecSpec): StoreRecord {
agent: spec.agent ?? "agent-1",
kind: spec.kind,
body: spec.body,
+ topic: spec.topic ?? null,
id: spec.id ?? seededUlid(spec.rng ?? fallbackRng, spec.physical),
});
}
diff --git a/tests/core/store/state-digest.test.ts b/tests/core/store/state-digest.test.ts
index f26d0aa2..4d36a075 100644
--- a/tests/core/store/state-digest.test.ts
+++ b/tests/core/store/state-digest.test.ts
@@ -152,6 +152,56 @@ describe("state digests", () => {
}
});
+ test("a topic fold difference is reported; an older release's digest without topics is not compared on it", () => {
+ const a = tmp.open("dev-a");
+ const b = tmp.open("dev-b");
+ const c = tmp.open("dev-c");
+ seedPreferences(a, b, NOW - 60_000);
+ appendRecord(
+ a,
+ {
+ partition: "shared",
+ stream: "topics",
+ kind: "topic-create",
+ agent: "agent-1",
+ topic: "01KA0000000000000000000000",
+ body: { authority: "human", title: "Store", scope: "project:o2b" },
+ },
+ { now: at(NOW - 30_000) },
+ );
+ const good = publishStateDigest(a, { partition: "shared", agent: "doctor", now: at(NOW) });
+ const digest = (store: StoreHandle, body: RecordBody, ms: number) =>
+ appendRecord(
+ store,
+ { partition: "shared", stream: "digests", kind: "state-digest", agent: "doctor", body },
+ { now: at(ms) },
+ );
+ const { topics: _dropped, ...older } = good.body.folds;
+ digest(c, { ...good.body, folds: older }, NOW + 3);
+ const bad = digest(
+ b,
+ { ...good.body, folds: { ...good.body.folds, topics: "0".repeat(64) } },
+ NOW + 5,
+ );
+ const report = checkStateDigests(a, { now: at(NOW + 10) });
+ expect(report.findings.filter((f) => f.kind === "divergent")).toEqual([
+ {
+ kind: "divergent",
+ partition: "shared",
+ fold: "topics",
+ cutHash: good.body.cut_hash,
+ devices: [
+ {
+ device: "dev-a",
+ hash: good.body.folds.topics!,
+ digest: good.published ? good.append.record.id : "",
+ },
+ { device: "dev-b", hash: "0".repeat(64), digest: bad.record.id },
+ ],
+ },
+ ]);
+ });
+
test("an offline device is reported as silent, never as divergent, and does not stall the others", () => {
const a = tmp.open("dev-a");
const b = tmp.open("dev-b");
diff --git a/tests/core/surface/skill-attach-decision.test.ts b/tests/core/surface/skill-attach-decision.test.ts
index b95a93c6..46de4d86 100644
--- a/tests/core/surface/skill-attach-decision.test.ts
+++ b/tests/core/surface/skill-attach-decision.test.ts
@@ -463,7 +463,10 @@ test("stage 2 gets only the time that remains", async () => {
provider,
});
expect(seen).toHaveLength(2);
- expect(seen[0]).toBe(3000);
+ // Stage 1 gets the whole budget, less the moment the call itself took to
+ // start: a slow runner hands the provider 2999, not 3000.
+ expect(seen[0]!).toBeLessThanOrEqual(3000);
+ expect(seen[0]!).toBeGreaterThan(3000 - 55);
expect(seen[1]!).toBeLessThanOrEqual(3000 - 55);
expect(seen[1]!).toBeGreaterThan(SKILLS_STAGE2_MIN_REMAINING_MS);
});
diff --git a/tests/core/topics/dream-topics.test.ts b/tests/core/topics/dream-topics.test.ts
new file mode 100644
index 00000000..da822444
--- /dev/null
+++ b/tests/core/topics/dream-topics.test.ts
@@ -0,0 +1,155 @@
+/**
+ * The dream pass runs topic planning before its render (task 3.4): on the
+ * view writer the summary lists the topic it created with the command
+ * that undoes it, and the render that follows writes the topic's page.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { dream } from "../../../src/core/brain/dream.ts";
+import { withTopicPass } from "../../../src/core/brain/dream-tail.ts";
+import { readPartition } from "../../../src/core/store/state-digest.ts";
+import { appendRecord } from "../../../src/core/store/appender.ts";
+import { STORE_ROOT_ENV } from "../../../src/core/store/constants.ts";
+import type { StoreHandle } from "../../../src/core/store/store-open.ts";
+import {
+ AUTO_NOW,
+ makeAutoViewEnv,
+ makeLegacyDreamVault,
+ seedWriterStore,
+ type AutoViewEnv,
+} from "../view/fixtures/auto-env.ts";
+
+let env: AutoViewEnv;
+let vault: string;
+let store: StoreHandle;
+
+beforeEach(() => {
+ env = makeAutoViewEnv("o2b-topics-dream-");
+ vault = makeLegacyDreamVault(env.parent);
+ store = seedWriterStore(env.root);
+});
+afterEach(() => env.cleanup());
+
+function seedCluster(on: StoreHandle): void {
+ ["s1", "s1", "s2", "s2", "s2"].forEach((session, i) => {
+ appendRecord(
+ on,
+ {
+ partition: "shared",
+ stream: "events",
+ kind: "signal",
+ agent: "agent-1",
+ body: {
+ id: `sig-2026-11-06-c${i}`,
+ path: `Brain/inbox/c${i}.md`,
+ staged: false,
+ frontmatter: {
+ principle: `Release notes list every migration step ${i}`,
+ project: "o2b",
+ session,
+ },
+ raw: null,
+ raw_shape: "bare",
+ },
+ },
+ { now: () => AUTO_NOW - 5_000 + i },
+ );
+ });
+}
+
+describe("topic planning in a dream pass", () => {
+ test("the summary lists the created topic with its undo command, and the render writes its page", () => {
+ seedCluster(store);
+ // The first pass after the claim only waits, in planning and in the
+ // render; the second plans, and its render writes the page.
+ expect(dream(vault).topics?.report.status).toBe("waiting-for-claim");
+ const first = dream(vault);
+ const report = first.topics?.report;
+ expect(report?.status).toBe("planned");
+ if (report?.status !== "planned") return;
+ expect(report.created.map((c) => [c.title, c.undo])).toEqual([
+ ["Release notes list", `o2b topic undo ${report.created[0]!.record}`],
+ ]);
+ expect(first.topics?.summary).toContain("1 topic(s) created");
+ expect(readdirSync(join(env.view, "topics"))).toHaveLength(1);
+ });
+
+ test("the pass reports the change it made, and plans in the store its config names", () => {
+ // The store is named by the config file only, not by the environment.
+ delete process.env[STORE_ROOT_ENV];
+ const config = join(env.parent, "config.yaml");
+ writeFileSync(config, `store_root: ${env.root}\n`);
+ seedCluster(store);
+ expect(dream(vault, { configPath: config }).topics?.report.status).toBe("waiting-for-claim");
+ const second = dream(vault, { configPath: config });
+ expect(second.topics?.report.status).toBe("planned");
+ expect(second.changed).toBe(true);
+ });
+
+ test("a pass whose deadline has passed plans no topic", () => {
+ seedCluster(store);
+ dream(vault); // the claim's wait
+ const stub = dream(vault, { dryRun: true });
+ const expired = {
+ operation: "dream",
+ timeoutMs: 1,
+ checkpoint: () => {
+ throw new Error("deadline passed");
+ },
+ };
+ const out = withTopicPass(stub, { safeguard: expired });
+ expect(out.topics).toBeUndefined();
+ const records = readPartition(join(env.root, "shared")).flatMap((s) => s.records);
+ expect(records.some((r) => r.kind === "topic-create")).toBe(false);
+ });
+
+ test("a pass whose deadline passes while it waits for the planning lock writes no topic", () => {
+ seedCluster(store);
+ dream(vault); // the claim's wait
+ const stub = dream(vault, { dryRun: true });
+ let asked = 0;
+ const expiring = {
+ operation: "dream",
+ timeoutMs: 1,
+ // In time before the lock, past the deadline under it.
+ checkpoint: () => {
+ asked += 1;
+ if (asked > 1) throw new Error("deadline passed");
+ },
+ };
+ const out = withTopicPass(stub, { safeguard: expiring });
+ expect(asked).toBe(2);
+ expect(out.topics?.report.status).toBe("deferred");
+ expect(out.changed).toBe(stub.changed);
+ const records = readPartition(join(env.root, "shared")).flatMap((s) => s.records);
+ expect(records.some((r) => r.kind === "topic-create")).toBe(false);
+ });
+
+ test("the pass plans on the run's own clock: a topic quiet by that date is offered", () => {
+ seedCluster(store);
+ dream(vault); // the claim's wait
+ const first = dream(vault).topics?.report;
+ if (first?.status !== "planned") throw new Error(String(first?.status));
+ const topic = first.created[0]!.topic;
+ const later = new Date(Date.now() + 40 * 86_400_000);
+ const out = withTopicPass(dream(vault, { dryRun: true }), { now: later });
+ const report = out.topics?.report;
+ if (report?.status !== "planned") throw new Error(String(report?.status));
+ expect(report.quiet.map((q) => q.topic)).toEqual([topic]);
+ });
+
+ test("every undo command names the config the pass ran with", () => {
+ delete process.env[STORE_ROOT_ENV];
+ const config = join(env.parent, "my config.yaml");
+ writeFileSync(config, `store_root: ${env.root}\n`);
+ seedCluster(store);
+ dream(vault, { configPath: config }); // the claim's wait
+ const report = dream(vault, { configPath: config }).topics?.report;
+ if (report?.status !== "planned") throw new Error(String(report?.status));
+ expect(report.created.map((c) => c.undo)).toEqual([
+ `o2b topic undo ${report.created[0]!.record} --config '${config}'`,
+ ]);
+ });
+});
diff --git a/tests/core/topics/fixtures/plan-child.ts b/tests/core/topics/fixtures/plan-child.ts
new file mode 100644
index 00000000..462a8fcf
--- /dev/null
+++ b/tests/core/topics/fixtures/plan-child.ts
@@ -0,0 +1,37 @@
+/**
+ * Test helper: one topic-planning pass in a process of its own, against
+ * the simulated machine whose store root and device-local base the
+ * arguments name. It waits for the start file, so several such processes
+ * plan at the same moment. Prints the report (or the error) and the time
+ * it finished as JSON.
+ */
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { openStore } from "../../../../src/core/store/store-open.ts";
+import { runTopicPlanning } from "../../../../src/core/topics/planning.ts";
+
+const [root, device, parent, start] = process.argv.slice(2) as [string, string, string, string];
+const store = openStore({
+ root,
+ device,
+ dirs: {
+ platform: process.platform,
+ home: join(parent, "home", device),
+ env: {
+ XDG_STATE_HOME: join(parent, "state", device),
+ LOCALAPPDATA: join(parent, "state", device),
+ },
+ },
+});
+const deadline = Date.now() + 20_000;
+while (!existsSync(start) && Date.now() < deadline) Bun.sleepSync(5);
+// Tell the parent this process is about to plan (and so to wait on the lock).
+writeFileSync(`${start}.${process.pid}`, "");
+let out: Record<string, unknown>;
+try {
+ out = { report: runTopicPlanning(store, { agent: "dream" }) };
+} catch (err) {
+ out = { error: err instanceof Error ? err.message : String(err) };
+}
+process.stdout.write(`${JSON.stringify({ ...out, end: Date.now() })}\n`);
diff --git a/tests/core/topics/fold-property.test.ts b/tests/core/topics/fold-property.test.ts
new file mode 100644
index 00000000..66e12351
--- /dev/null
+++ b/tests/core/topics/fold-property.test.ts
@@ -0,0 +1,150 @@
+/**
+ * Property tests of the topic fold (task 3.1): for random topic record
+ * sets from several devices (creates, renames, goals, statuses, items and
+ * their removals, completions, assignments, merges, splits, links and
+ * undos of earlier records), every delivery a file-sync tool can produce
+ * folds to exactly the state of the complete set. Each seed is
+ * reproducible.
+ */
+import { describe, expect, test } from "bun:test";
+
+import type { StoreRecord } from "../../../src/core/store/envelope.ts";
+import { foldTopics } from "../../../src/core/topics/fold.ts";
+import { pick, rec, seededRandom, seededUlid, shuffled } from "../store/fixtures/fold-records.ts";
+
+const T = Date.UTC(2026, 10, 6, 12, 0, 0);
+const DEVICES = ["dev-a", "dev-b", "dev-c"];
+const AUTHORITIES = ["human", "agent", "agent", "model"] as const;
+const idRng = seededRandom(99);
+const TOPICS = [0, 1, 2].map((i) => seededUlid(idRng, T - 1000 + i));
+const ITEMS = ["i1", "i2", "i3", "i4"];
+const ITEM_KINDS = ["decision", "open-question", "log-entry", "milestone"] as const;
+const RECORDS = [0, 1].map((i) => seededUlid(idRng, T - 500 + i));
+
+function randomBody(
+ rng: () => number,
+ written: ReadonlyArray<string>,
+): { kind: string; body: Record<string, unknown> } {
+ const authority = pick(rng, AUTHORITIES);
+ const other = pick(rng, TOPICS);
+ const roll = rng();
+ const body = (kind: string, rest: Record<string, unknown>) => ({
+ kind,
+ body: { authority, ...rest },
+ });
+ if (roll < 0.12)
+ return body("topic-create", { title: `t-${Math.floor(rng() * 4)}`, scope: "project:x" });
+ if (roll < 0.2) return body("topic-rename", { title: `r-${Math.floor(rng() * 4)}` });
+ if (roll < 0.27)
+ return body("topic-goal", { goal: rng() < 0.2 ? null : `g-${Math.floor(rng() * 4)}` });
+ if (roll < 0.33)
+ return body("topic-status", { status: pick(rng, ["active", "done", "on-hold"]) });
+ if (roll < 0.55) {
+ const kind = pick(rng, ITEM_KINDS);
+ const item = pick(rng, ITEMS);
+ if (rng() < 0.15) return body(kind, { item, removed: true });
+ return body(kind, {
+ item,
+ text: `x-${Math.floor(rng() * 4)}`,
+ ...(kind === "log-entry" ? { class: pick(rng, ["blocker", "routine"]) } : {}),
+ });
+ }
+ if (roll < 0.6)
+ return body("milestone-done", {
+ milestone: pick(rng, ITEMS),
+ ...(rng() < 0.5 ? { evidence: "ci" } : {}),
+ });
+ if (roll < 0.64) return body("question-resolved", { question: pick(rng, ITEMS) });
+ if (roll < 0.7) return body("assign", { record: pick(rng, RECORDS) });
+ if (roll < 0.73) return body("unassign", { record: pick(rng, RECORDS) });
+ if (roll < 0.78) return body("merge", { into: other });
+ if (roll < 0.81) return body("split", { into: other, items: [pick(rng, ITEMS)] });
+ if (roll < 0.86) return body("link", { to: other, ...(rng() < 0.3 ? { removed: true } : {}) });
+ if (roll < 0.97 && written.length > 0) return body("undo", { record: pick(rng, written) });
+ // A malformed record: rejected the same way in every delivery.
+ return body("topic-status", { status: "sideways" });
+}
+
+/** One shard per device, records in the order the device wrote them. */
+function randomShards(rng: () => number): StoreRecord[][] {
+ const written: string[] = [];
+ return DEVICES.map((device) => {
+ const records: StoreRecord[] = [];
+ let physical = T;
+ let counter = 0;
+ const count = 15 + Math.floor(rng() * 30);
+ for (let i = 0; i < count; i++) {
+ const step = Math.floor(rng() * 3);
+ if (step === 0) counter += 1;
+ else {
+ physical += step;
+ counter = 0;
+ }
+ const record = rec({
+ device,
+ physical,
+ counter,
+ rng,
+ topic: pick(rng, TOPICS),
+ ...randomBody(rng, written),
+ });
+ written.push(record.id);
+ records.push(record);
+ }
+ return records;
+ });
+}
+
+function state(records: ReadonlyArray<StoreRecord>): unknown {
+ const fold = foldTopics(records);
+ return {
+ topics: [...fold.topics.values()].toSorted((a, b) => (a.id < b.id ? -1 : 1)),
+ canonical: TOPICS.map((t) => fold.canonical(t)),
+ assignments: [...fold.assignments].toSorted(),
+ blocked: [...fold.blockedRoutes].toSorted(),
+ voided: [...fold.voided].toSorted(),
+ rejected: fold.rejected.map((r) => r.id).toSorted(),
+ };
+}
+
+const SEEDS = Array.from({ length: 50 }, (_, i) => i + 1);
+
+describe("topic fold properties", () => {
+ test("the generated sets exercise items, merges, assignments, undos and rejections", () => {
+ const folds = SEEDS.map((seed) => foldTopics(randomShards(seededRandom(seed)).flat()));
+ const topics = folds.flatMap((f) => [...f.topics.values()]);
+ expect(topics.some((t) => t.items.length > 0)).toBe(true);
+ expect(topics.some((t) => t.mergedInto !== null)).toBe(true);
+ expect(topics.some((t) => t.items.some((i) => i.done !== undefined))).toBe(true);
+ expect(folds.some((f) => f.assignments.size > 0 && f.voided.size > 0)).toBe(true);
+ expect(folds.some((f) => f.blockedRoutes.size > 0 && f.rejected.length > 0)).toBe(true);
+ });
+
+ test.each(SEEDS)("seed %i: shards delivered in any device order fold the same", (seed) => {
+ const rng = seededRandom(seed);
+ const shards = randomShards(rng);
+ const expected = state(shards.flat());
+ for (let round = 0; round < 3; round++) {
+ expect(state(shuffled(rng, shuffled(rng, shards).flat()))).toEqual(expected);
+ }
+ });
+
+ test.each(SEEDS)("seed %i: duplicated lines in a shuffled delivery are applied once", (seed) => {
+ const rng = seededRandom(1000 + seed);
+ const all = randomShards(rng).flat();
+ const expected = state(all);
+ const duplicates = all.filter(() => rng() < 0.3);
+ expect(state(shuffled(rng, [...all, ...duplicates, ...duplicates]))).toEqual(expected);
+ });
+
+ test.each(SEEDS)(
+ "seed %i: a partial delivery read again beside the full one folds the same",
+ (seed) => {
+ const rng = seededRandom(2000 + seed);
+ const shards = randomShards(rng);
+ const expected = state(shards.flat());
+ const partial = shards.map((shard) => shard.slice(0, Math.floor(rng() * shard.length)));
+ expect(state([...partial.flat(), ...shuffled(rng, shards).flat()])).toEqual(expected);
+ },
+ );
+});
diff --git a/tests/core/topics/fold.test.ts b/tests/core/topics/fold.test.ts
new file mode 100644
index 00000000..ca263598
--- /dev/null
+++ b/tests/core/topics/fold.test.ts
@@ -0,0 +1,254 @@
+/**
+ * The topic fold's rules (task 3.1, design D8, spec `topics`): a rename
+ * keeps the id and every reference, human edits win and the losing agent
+ * goal stays as a proposal, completion needs the user or evidence, undo
+ * voids a record and blocks the route it took back, merges resolve, and
+ * malformed records are reported rather than applied.
+ */
+import { describe, expect, test } from "bun:test";
+
+import type { StoreRecord } from "../../../src/core/store/envelope.ts";
+import { foldTopics, routeKey, topicOfRecord } from "../../../src/core/topics/fold.ts";
+import { topicCorrection } from "../../../src/core/view/topic-edits.ts";
+import { rec, seededRandom, seededUlid } from "../store/fixtures/fold-records.ts";
+
+const T0 = Date.UTC(2026, 10, 1, 9, 0, 0);
+const ids = seededRandom(5);
+const TOPIC = seededUlid(ids, T0);
+const OTHER = seededUlid(ids, T0 + 1);
+const EVENT = seededUlid(ids, T0 + 2);
+
+let clock = T0;
+function topicRec(
+ kind: string,
+ body: Record<string, unknown>,
+ opts: { topic?: string; agent?: string; authority?: string; device?: string } = {},
+): StoreRecord {
+ clock += 1000;
+ return rec({
+ physical: clock,
+ kind,
+ topic: opts.topic ?? TOPIC,
+ agent: opts.agent ?? "agent-1",
+ device: opts.device ?? "dev-a",
+ body: { authority: opts.authority ?? "agent", ...body },
+ });
+}
+
+const create = (topic = TOPIC, title = "Store migration") =>
+ topicRec("topic-create", { title, scope: "project:o2b", goal: "Move the brain out" }, { topic });
+
+describe("topic fold", () => {
+ test("a rename keeps the id, the items, the assignments, the links and the record's topic", () => {
+ const records = [
+ create(),
+ create(OTHER, "Docs"),
+ topicRec("decision", { item: "d1", text: "Keep JSONL shards" }),
+ topicRec("assign", { record: EVENT }),
+ topicRec("link", { to: OTHER }),
+ topicRec(
+ "topic-rename",
+ { title: "Brain store", description: "Data outside the vault" },
+ { authority: "human" },
+ ),
+ ];
+ const event = rec({ physical: T0 + 5, kind: "log-event", topic: TOPIC, body: { x: 1 } });
+ const fold = foldTopics(records);
+ const topic = fold.topics.get(TOPIC)!;
+ expect(topic.title).toBe("Brain store");
+ expect(topic.description).toBe("Data outside the vault");
+ expect(topic.createdAt).toBe(records[0]!.hlc.split(".").map(Number)[0]!);
+ expect(topic.items.map((i) => [i.id, i.text])).toEqual([["d1", "Keep JSONL shards"]]);
+ expect(fold.assignments.get(EVENT)).toBe(TOPIC);
+ expect(fold.topics.get(OTHER)!.links).toEqual([TOPIC]);
+ expect(topicOfRecord(fold, event)).toBe(TOPIC);
+ });
+
+ test("an agent's status change applies to a topic the user created; a later human one wins", () => {
+ const made = topicRec(
+ "topic-create",
+ { title: "Mine", scope: "project:o2b" },
+ { authority: "human" },
+ );
+ const fold = (extra: StoreRecord[]) => foldTopics([made, ...extra]).topics.get(TOPIC)!.status;
+ const agent = topicRec("topic-status", { status: "waiting" });
+ expect(fold([agent])).toBe("waiting");
+ const human = topicRec("topic-status", { status: "blocked" }, { authority: "human" });
+ const laterAgent = topicRec("topic-status", { status: "done" });
+ expect(fold([agent, human, laterAgent])).toBe("blocked");
+ });
+
+ test("the user's goal wins, and a later agent goal is kept as a proposal", () => {
+ const fold = foldTopics([
+ create(),
+ topicRec("topic-goal", { goal: "Ship phase 3" }, { authority: "human" }),
+ topicRec("topic-goal", { goal: "Ship everything" }, { agent: "planner" }),
+ ]);
+ const topic = fold.topics.get(TOPIC)!;
+ expect(topic.goal).toBe("Ship phase 3");
+ expect(topic.goalProposals.map((p) => [p.agent, p.goal])).toEqual([
+ ["planner", "Ship everything"],
+ ]);
+ });
+
+ test("a milestone is done only by the user or an agent that cites evidence", () => {
+ const fold = foldTopics([
+ create(),
+ topicRec("milestone", { item: "m1", text: "Topics render" }),
+ topicRec("milestone", { item: "m2", text: "Docs written" }),
+ topicRec("milestone", { item: "m3", text: "Release" }),
+ topicRec("milestone-done", { milestone: "m1" }, { authority: "model" }),
+ topicRec("milestone-done", { milestone: "m2" }),
+ topicRec("milestone-done", { milestone: "m3", evidence: "CI run 41 green" }),
+ ]);
+ const [m1, m2, m3] = fold.topics.get(TOPIC)!.items;
+ expect(m1!.done).toBeUndefined();
+ expect(m1!.doneProposed?.authority).toBe("model");
+ expect(m2!.done).toBeUndefined();
+ expect(m2!.doneProposed?.authority).toBe("agent");
+ expect(m3!.done?.evidence).toBe("CI run 41 green");
+ });
+
+ test("an undo voids the record; a human undo of an assign blocks that route", () => {
+ const assign = topicRec("assign", { record: EVENT }, { authority: "model" });
+ const fold = foldTopics([
+ create(),
+ assign,
+ topicRec("undo", { record: assign.id }, { authority: "human" }),
+ ]);
+ expect(fold.voided.has(assign.id)).toBe(true);
+ expect(fold.assignments.has(EVENT)).toBe(false);
+ expect(fold.blockedRoutes.has(routeKey(EVENT, TOPIC))).toBe(true);
+ });
+
+ test("an agent cannot undo the user's record; an undone create removes the topic", () => {
+ const human = topicRec(
+ "decision",
+ { item: "d1", text: "Chosen by hand" },
+ { authority: "human" },
+ );
+ const made = create(OTHER, "Auto topic");
+ const fold = foldTopics([
+ create(),
+ human,
+ topicRec("undo", { record: human.id }),
+ made,
+ topicRec("undo", { record: made.id }, { authority: "human", topic: OTHER }),
+ ]);
+ expect(fold.topics.get(TOPIC)!.items.map((i) => i.id)).toEqual(["d1"]);
+ expect(fold.topics.has(OTHER)).toBe(false);
+ });
+
+ test("a merged topic resolves to its target, whose page carries both topics' items", () => {
+ const fold = foldTopics([
+ create(),
+ create(OTHER, "Docs"),
+ topicRec("decision", { item: "d1", text: "Write the guide" }, { topic: OTHER }),
+ topicRec("merge", { into: TOPIC }, { topic: OTHER, authority: "human" }),
+ // The reverse merge would close a cycle and is ignored.
+ topicRec("merge", { into: OTHER }, { authority: "human" }),
+ ]);
+ expect(fold.canonical(OTHER)).toBe(TOPIC);
+ expect(fold.canonical(TOPIC)).toBe(TOPIC);
+ expect(fold.topics.get(OTHER)!.mergedInto).toBe(TOPIC);
+ expect(fold.topics.get(TOPIC)!.items.map((i) => i.id)).toEqual(["d1"]);
+ });
+
+ test("an item id is its topic's own: the same token in two topics names two items", () => {
+ const fold = foldTopics([
+ create(),
+ create(OTHER, "Docs"),
+ topicRec("milestone", { item: "m1", text: "A milestone" }),
+ topicRec("milestone", { item: "m1", text: "B milestone" }, { topic: OTHER }),
+ topicRec("milestone-done", { milestone: "m1" }, { authority: "human" }),
+ topicRec("decision", { item: "m1", removed: true }, { topic: OTHER }),
+ ]);
+ const show = (id: string) =>
+ fold.topics.get(id)!.items.map((i) => [i.text, i.done !== undefined]);
+ expect(show(TOPIC)).toEqual([["A milestone", true]]);
+ expect(show(OTHER)).toEqual([["B milestone", false]]);
+ expect(fold.rejected).toHaveLength(1);
+ });
+
+ test("a split moves the items it lists to the other topic", () => {
+ const fold = foldTopics([
+ create(),
+ create(OTHER, "Docs"),
+ topicRec("decision", { item: "d1", text: "One" }),
+ topicRec("decision", { item: "d2", text: "Two" }),
+ topicRec("split", { into: OTHER, items: ["d2"] }, { authority: "human" }),
+ ]);
+ expect(fold.topics.get(TOPIC)!.items.map((i) => i.id)).toEqual(["d1"]);
+ expect(fold.topics.get(OTHER)!.items.map((i) => i.id)).toEqual(["d2"]);
+ });
+
+ test("a done status carries its resolved day; malformed records are reported, not applied", () => {
+ const bad = topicRec("topic-status", { status: "sideways" });
+ const fold = foldTopics([
+ create(),
+ topicRec("topic-status", { status: "done" }, { authority: "human" }),
+ bad,
+ ]);
+ const topic = fold.topics.get(TOPIC)!;
+ expect(topic.status).toBe("done");
+ expect(topic.resolved).toBe("2026-11-01");
+ expect(fold.rejected.map((r) => r.id)).toEqual([bad.id]);
+ });
+
+ test("the reader's private record ids mark a private topic and a private item", () => {
+ const made = create();
+ const secret = topicRec("open-question", { item: "q1", text: "Ask about leave" });
+ const fold = foldTopics([made, secret], { privateIds: new Set([secret.id]) });
+ const topic = fold.topics.get(TOPIC)!;
+ expect(topic.private).toBe(false);
+ expect(topic.items[0]!.private).toBe(true);
+ });
+ test("a decision reworded on its page keeps the milestones it serves; an empty list clears them", () => {
+ const records = [
+ create(),
+ topicRec("milestone", { item: "m1", text: "Store core released" }),
+ topicRec("decision", { item: "d1", text: "Keep JSONL shards", serves: ["m1"] }),
+ ];
+ const edit = topicCorrection(
+ `t:${TOPIC}:d:d1`,
+ "- Keep JSONL shards (serves: Store core released)",
+ "- Keep one JSONL shard per month (serves: Store core released)",
+ )!;
+ expect(edit[0]!.body["serves"]).toBeUndefined();
+ const reworded = topicRec(edit[0]!.kind, edit[0]!.body);
+ const decision = (extra: StoreRecord[]) =>
+ foldTopics([...records, reworded, ...extra])
+ .topics.get(TOPIC)!
+ .items.find((i) => i.id === "d1")!;
+ expect(decision([])).toMatchObject({ text: "Keep one JSONL shard per month", serves: ["m1"] });
+ const cleared = topicRec(
+ "decision",
+ { item: "d1", text: "Unlinked", serves: [] },
+ { authority: "human" },
+ );
+ expect(decision([cleared]).serves).toEqual([]);
+ });
+
+ test("a merged topic's item edit and a split's received items count as activity of the topic that shows them", () => {
+ const target = seededUlid(ids, T0 + 3);
+ const merge = [
+ create(),
+ create(OTHER, "Docs"),
+ topicRec("decision", { item: "d1", text: "From the store topic" }),
+ topicRec("merge", { into: OTHER }, { authority: "human" }),
+ ];
+ const edit = topicRec("decision", { item: "d1", text: "Edited through Docs" });
+ expect(foldTopics([...merge, edit]).topics.get(OTHER)!.updatedAt).toBe(
+ Number(edit.hlc.split(".")[0]),
+ );
+ const received = [
+ create(),
+ create(target, "Target"),
+ topicRec("decision", { item: "d2", text: "Moves" }),
+ ];
+ const split = topicRec("split", { into: target, items: ["d2"] }, { authority: "human" });
+ expect(foldTopics([...received, split]).topics.get(target)!.updatedAt).toBe(
+ Number(split.hlc.split(".")[0]),
+ );
+ });
+});
diff --git a/tests/core/topics/planning.test.ts b/tests/core/topics/planning.test.ts
new file mode 100644
index 00000000..8dfbf869
--- /dev/null
+++ b/tests/core/topics/planning.test.ts
@@ -0,0 +1,553 @@
+/**
+ * Topic planning in dream (task 3.4, spec `topics`): only the view writer
+ * plans; it creates a topic from a cluster that recurs across sessions,
+ * routes later records to it, lists every automatic action with its undo
+ * command, honours the user's undo on every pass after, and only proposes
+ * merges, splits and status decisions. A concurrent dream on two machines
+ * and two planning processes on the view writer each leave exactly one
+ * topic per cluster.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { appendRecord } from "../../../src/core/store/appender.ts";
+import type { StorePartition } from "../../../src/core/store/constants.ts";
+import { readPartition } from "../../../src/core/store/state-digest.ts";
+import type { StoreHandle } from "../../../src/core/store/store-open.ts";
+import { foldTopics } from "../../../src/core/topics/fold.ts";
+import {
+ runTopicPlanning,
+ topicPlanLockTarget,
+ type TopicPlanningReport,
+} from "../../../src/core/topics/planning.ts";
+import {
+ claimSettled,
+ claimViewWriter,
+ readViewWriter,
+ requestViewWriter,
+} from "../../../src/core/view/writer.ts";
+import { withLocalLock } from "../../../src/core/store/local-lock.ts";
+import { makeMachines, type Machines } from "../view/fixtures/machines.ts";
+import { seedTopicRecord } from "../view/fixtures/seed.ts";
+
+const T0 = Date.UTC(2026, 10, 2, 9, 0, 0);
+const DAY = 86_400_000;
+let clock = T0;
+const now = () => clock;
+
+let m: Machines;
+let a: StoreHandle;
+beforeEach(() => {
+ clock = T0;
+ m = makeMachines(["dev-a", "dev-b"], "o2b-topics-plan-");
+ a = m.open("dev-a");
+ claimViewWriter(a, { agent: "t", now });
+ // The render's first catch-up after the claim, which planning waits for.
+ claimSettled(a, readViewWriter(a, now));
+});
+afterEach(() => m.cleanup());
+
+let seq = 0;
+function signal(
+ text: string,
+ meta: { project?: string; session?: string; on?: StoreHandle; partition?: StorePartition } = {},
+): string {
+ clock += 1000;
+ seq += 1;
+ return appendRecord(
+ meta.on ?? a,
+ {
+ partition: meta.partition ?? "shared",
+ stream: "events",
+ kind: "signal",
+ agent: "agent-1",
+ body: {
+ id: `sig-2026-11-02-s${seq}`,
+ path: `Brain/inbox/s${seq}.md`,
+ staged: false,
+ frontmatter: {
+ principle: text,
+ project: meta.project ?? "o2b",
+ ...(meta.session !== undefined ? { session: meta.session } : {}),
+ },
+ raw: null,
+ raw_shape: "bare",
+ },
+ },
+ { now },
+ ).record.id;
+}
+
+/** Five records about one subject, from the sessions named. */
+function cluster(sessions: ReadonlyArray<string>, on: StoreHandle = a): string[] {
+ return sessions.map((session, i) =>
+ signal(`Shard compaction keeps monthly shard files small ${i}`, { session, on }),
+ );
+}
+
+/** How many planning children announced they are about to plan. */
+function startedChildren(): number {
+ return readdirSync(m.parent).filter((n) => n.startsWith("start.")).length;
+}
+
+/** Whether a topic-create of dev-a has landed in `shared`. */
+function createdOnDisk(): boolean {
+ return readPartition(join(m.root("dev-a"), "shared"))
+ .flatMap((s) => s.records)
+ .some((r) => r.kind === "topic-create");
+}
+
+function plan(store: StoreHandle = a): TopicPlanningReport {
+ clock += 1000;
+ return runTopicPlanning(store, { agent: "dream", now });
+}
+
+function planned(report: TopicPlanningReport) {
+ if (report.status !== "planned") throw new Error(`not planned: ${report.status}`);
+ return report;
+}
+
+function fold(device = "dev-a") {
+ const records = (["shared", "private"] as const).flatMap((p) =>
+ readPartition(join(m.root(device), p)).flatMap((s) => s.records),
+ );
+ return foldTopics(records);
+}
+
+describe("topic planning", () => {
+ test("a cluster from two sessions becomes one topic, listed with its undo command", () => {
+ const members = cluster(["s1", "s1", "s1", "s2", "s2"]);
+ const report = planned(plan());
+ expect(report.created).toHaveLength(1);
+ const created = report.created[0]!;
+ expect(created.title).toBe("Shard compaction keeps");
+ expect(created.members).toBe(5);
+ expect(created.undo).toBe(`o2b topic undo ${created.record}`);
+ const state = fold();
+ const topic = state.topics.get(created.topic)!;
+ expect(topic.goal).toBe("Shard compaction keeps monthly shard files small 0");
+ expect(topic.scope).toBe("project:o2b");
+ expect(members.map((id) => state.assignments.get(id))).toEqual(
+ members.map(() => created.topic),
+ );
+ // A second pass finds nothing left to do.
+ expect(planned(plan()).created).toEqual([]);
+ });
+
+ test("a cluster written without word spaces still becomes a topic, its title cut to fit", () => {
+ const longA = "シャードの圧縮".repeat(18);
+ const longB = "毎月の小さなファイル".repeat(12);
+ const members = ["s1", "s1", "s2", "s2", "s2"].map((session, i) =>
+ signal(`${longA}、${longB}、${i}`, { session }),
+ );
+ const created = planned(plan()).created[0]!;
+ const state = fold();
+ const topic = state.topics.get(created.topic)!;
+ // The record check counts UTF-16 code units: so does the clamp.
+ expect(topic.title.length).toBeLessThanOrEqual(200);
+ expect(members.map((id) => state.assignments.get(id))).toEqual(
+ members.map(() => created.topic),
+ );
+ });
+
+ test("a cluster in astral-plane characters becomes a topic, its title cut on a whole character", () => {
+ // CJK Extension B: two UTF-16 code units per character.
+ const longA = "𠀀𠀁𠀂𠀃𠀄𠀅".repeat(30);
+ const longB = "𠁀𠁁𠁂𠁃𠁄".repeat(30);
+ const members = ["s1", "s1", "s2", "s2", "s2"].map((session, i) =>
+ signal(`${longA}、${longB}、${i}`, { session }),
+ );
+ const report = planned(plan());
+ expect(report.created).toHaveLength(1);
+ const created = report.created[0]!;
+ const state = fold();
+ const topic = state.topics.get(created.topic)!;
+ expect(topic.title.length).toBeLessThanOrEqual(200);
+ expect(topic.title.length).toBeGreaterThanOrEqual(199);
+ // No lone surrogate: every character is whole.
+ expect(/[\uD800-\uDFFF]/u.test(topic.title)).toBe(false);
+ expect(members.map((id) => state.assignments.get(id))).toEqual(
+ members.map(() => created.topic),
+ );
+ });
+
+ test("a private item's words never route a shared record to a topic", () => {
+ const id = "01KA0000000000000000000000";
+ seedTopicRecord(a, (clock += 1000), "topic-create", id, {
+ title: "Unrelated",
+ scope: "project:o2b",
+ });
+ seedTopicRecord(
+ a,
+ (clock += 1000),
+ "decision",
+ id,
+ { text: "Clinic appointment rescheduling paperwork" },
+ { partition: "private" },
+ );
+ const record = signal("Clinic appointment rescheduling paperwork again", { session: "s9" });
+ expect(planned(plan()).routed.map((r) => r.record)).not.toContain(record);
+ });
+
+ test("a route taken back from a topic merged away is not taken to the topic it merged into", () => {
+ const from = "01KA0000000000000000000007";
+ const into = "01KA0000000000000000000008";
+ const words = "Clinic appointment rescheduling paperwork";
+ seedTopicRecord(a, (clock += 1000), "topic-create", from, {
+ title: words,
+ scope: "project:o2b",
+ });
+ seedTopicRecord(a, (clock += 1000), "topic-create", into, {
+ title: words,
+ scope: "project:o2b",
+ });
+ const record = signal(`${words} again`, { session: "s9" });
+ seedTopicRecord(a, (clock += 1000), "merge", from, { into }, { authority: "human" });
+ const assign = seedTopicRecord(a, (clock += 1000), "assign", from, { record });
+ seedTopicRecord(a, (clock += 1000), "undo", from, { record: assign }, { authority: "human" });
+ expect(planned(plan()).routed.map((r) => r.record)).not.toContain(record);
+ });
+
+ test("a private record is routed to a private topic by its private title", () => {
+ const id = "01KA0000000000000000000009";
+ seedTopicRecord(
+ a,
+ (clock += 1000),
+ "topic-create",
+ id,
+ { title: "Clinic appointment rescheduling paperwork", scope: "project:o2b" },
+ { partition: "private" },
+ );
+ const record = signal("Clinic appointment rescheduling paperwork again", {
+ session: "s9",
+ partition: "private",
+ });
+ const routed = planned(plan()).routed.filter((r) => r.record === record);
+ expect(routed.map((r) => r.topic)).toEqual([id]);
+ // The assign lands in `private`, beside the record and the topic.
+ const assigns = readPartition(join(m.root("dev-a"), "private"))
+ .flatMap((s) => s.records)
+ .filter((r) => r.kind === "assign" && r.body["record"] === record);
+ expect(assigns).toHaveLength(1);
+ });
+
+ test("a private title, description or goal never routes a shared record to a topic", () => {
+ const words = "Clinic appointment rescheduling paperwork";
+ const fields = [
+ ["topic-rename", { title: words }],
+ ["topic-rename", { description: words }],
+ ["topic-goal", { goal: words }],
+ ] as const;
+ const records: string[] = [];
+ for (const [i, [kind, body]] of fields.entries()) {
+ const id = `01KA000000000000000000000${i}`;
+ seedTopicRecord(a, (clock += 1000), "topic-create", id, {
+ title: `Unrelated ${i}`,
+ scope: "project:o2b",
+ });
+ seedTopicRecord(a, (clock += 1000), kind, id, body, { partition: "private" });
+ records.push(signal(`${words} again ${i}`, { session: `s${9 + i}` }));
+ }
+ const routed = planned(plan()).routed.map((r) => r.record);
+ expect(routed.filter((r) => records.includes(r))).toEqual([]);
+ // The same words in a shared field do route.
+ seedTopicRecord(a, (clock += 1000), "topic-goal", "01KA0000000000000000000000", {
+ goal: `${words} shared`,
+ });
+ const late = signal(`${words} shared later`, { session: "s20" });
+ expect(planned(plan()).routed.map((r) => r.record)).toContain(late);
+ });
+
+ test("a log event whose type names an Object property is not a candidate and breaks nothing", () => {
+ appendRecord(
+ a,
+ {
+ partition: "shared",
+ stream: "log",
+ kind: "log-event",
+ agent: "legacy",
+ body: {
+ timestamp: new Date(clock).toISOString(),
+ event_type: "constructor",
+ body: { text: "x" },
+ },
+ },
+ { now },
+ );
+ expect(plan().status).toBe("planned");
+ });
+
+ test("one busy session makes no topic until the subject recurs in another session", () => {
+ cluster(["s1", "s1", "s1", "s1", "s1", "s1"]);
+ expect(planned(plan()).created).toEqual([]);
+ signal("Shard compaction keeps monthly shard files small again", { session: "s2" });
+ expect(planned(plan()).created).toHaveLength(1);
+ });
+
+ test("a later record is routed to the topic; an undone route is never taken again", () => {
+ cluster(["s1", "s1", "s2", "s2", "s2"]);
+ const topic = planned(plan()).created[0]!.topic;
+ const late = signal("Shard compaction should run monthly on each device", { session: "s3" });
+ const report = planned(plan());
+ expect(report.routed.map((r) => [r.record, r.topic])).toEqual([[late, topic]]);
+ seedTopicRecord(
+ a,
+ (clock += 1000),
+ "undo",
+ topic,
+ { record: report.routed[0]!.assign },
+ {
+ authority: "human",
+ },
+ );
+ expect(fold().assignments.has(late)).toBe(false);
+ expect(planned(plan()).routed).toEqual([]);
+ expect(fold().assignments.has(late)).toBe(false);
+ });
+
+ test("an agent's undo of an automatic route (as brain_topic writes it) blocks the route too", () => {
+ cluster(["s1", "s1", "s2", "s2", "s2"]);
+ const topic = planned(plan()).created[0]!.topic;
+ const late = signal("Shard compaction should run monthly on each device", { session: "s3" });
+ const route = planned(plan()).routed[0]!;
+ seedTopicRecord(
+ a,
+ (clock += 1000),
+ "undo",
+ topic,
+ { record: route.assign },
+ { authority: "agent" },
+ );
+ expect(planned(plan()).routed).toEqual([]);
+ expect(fold().assignments.has(late)).toBe(false);
+ });
+
+ test("an undone topic is gone and is not created again from the same records", () => {
+ cluster(["s1", "s1", "s2", "s2", "s2"]);
+ const created = planned(plan()).created[0]!;
+ seedTopicRecord(
+ a,
+ (clock += 1000),
+ "undo",
+ created.topic,
+ { record: created.record },
+ {
+ authority: "human",
+ },
+ );
+ expect(fold().topics.size).toBe(0);
+ expect(planned(plan()).created).toEqual([]);
+ expect(fold().topics.size).toBe(0);
+ });
+
+ test("a cluster with a private record becomes a private topic", () => {
+ cluster(["s1", "s1", "s2", "s2"]);
+ signal("Shard compaction keeps monthly shard files small too", {
+ session: "s2",
+ partition: "private",
+ });
+ const created = planned(plan()).created[0]!;
+ const topicRecords = readPartition(join(m.root("dev-a"), "private"))
+ .filter((s) => s.stream === "topics")
+ .flatMap((s) => s.records);
+ expect(topicRecords.some((r) => r.kind === "topic-create" && r.topic === created.topic)).toBe(
+ true,
+ );
+ const sharedTopicRecords = readPartition(join(m.root("dev-a"), "shared"))
+ .filter((s) => s.stream === "topics")
+ .flatMap((s) => s.records);
+ expect(sharedTopicRecords.filter((r) => r.topic === created.topic)).toEqual([]);
+ expect(topicRecords.filter((r) => r.kind === "assign")).toHaveLength(5);
+ });
+
+ test("a shared record that carries a <private> region makes its cluster's topic private", () => {
+ cluster(["s1", "s1", "s2", "s2"]);
+ signal("Shard compaction keeps monthly shard <private>files of Dr. X</private> small", {
+ session: "s2",
+ });
+ const created = planned(plan()).created[0]!;
+ const shared = readPartition(join(m.root("dev-a"), "shared"))
+ .filter((s) => s.stream === "topics")
+ .flatMap((s) => s.records);
+ expect(shared.filter((r) => r.topic === created.topic)).toEqual([]);
+ });
+
+ test("two topics that look the same are proposed for a merge and both stay as they are", () => {
+ const one = "01KA0000000000000000000000";
+ const two = "01KA0000000000000000000001";
+ for (const id of [one, two]) {
+ seedTopicRecord(a, (clock += 1000), "topic-create", id, {
+ title: "Shard compaction policy",
+ scope: "project:o2b",
+ goal: "Monthly shard compaction",
+ });
+ }
+ const report = planned(plan());
+ expect(report.merges.map((p) => p.topics)).toEqual([[one, two]]);
+ const state = fold();
+ expect([state.topics.get(one)!.mergedInto, state.topics.get(two)!.mergedInto]).toEqual([
+ null,
+ null,
+ ]);
+ });
+
+ test("a quiet active topic is offered for a status decision; its status does not change", () => {
+ const id = "01KA0000000000000000000000";
+ seedTopicRecord(a, clock, "topic-create", id, { title: "Old work", scope: "project:o2b" });
+ clock += 31 * DAY;
+ const report = planned(plan());
+ expect(report.quiet).toEqual([{ topic: id, days: 31 }]);
+ expect(fold().topics.get(id)!.status).toBe("active");
+ });
+
+ test("a topic whose records fall into two clusters is proposed for a split", () => {
+ const id = "01KA0000000000000000000000";
+ seedTopicRecord(a, (clock += 1000), "topic-create", id, {
+ title: "Mixed",
+ scope: "project:o2b",
+ });
+ const records = [
+ ...cluster(["s1", "s1", "s2", "s2", "s2"]),
+ ...["s3", "s3", "s4", "s4", "s4"].map((session, i) =>
+ signal(`Phone views render markdown pages offline ${i}`, { session }),
+ ),
+ ];
+ for (const record of records) {
+ seedTopicRecord(a, (clock += 1000), "assign", id, { record }, { authority: "human" });
+ }
+ const report = planned(plan());
+ expect(report.splits.map((s) => [s.topic, s.groups.map((g) => g.length)])).toEqual([
+ [id, [5, 5]],
+ ]);
+ expect(report.created).toEqual([]);
+ });
+
+ test("dream on two machines at once: only the view writer creates, and one topic exists", () => {
+ const b = m.open("dev-b");
+ cluster(["s1", "s1", "s2", "s2", "s2"], b);
+ m.sync();
+ const onB = plan(b);
+ expect(onB).toEqual({ status: "not-writer", writer: "dev-a" });
+ expect(planned(plan()).created).toHaveLength(1);
+ m.sync();
+ expect(plan(b)).toEqual({ status: "not-writer", writer: "dev-a" });
+ expect(fold("dev-b").topics.size).toBe(1);
+ expect(fold("dev-a").topics.size).toBe(1);
+ });
+
+ test("planning waits for the claim to settle, and hands the role over on a request", () => {
+ const fresh = makeMachines(["dev-c", "dev-d"], "o2b-topics-plan-gate-");
+ try {
+ const c = fresh.open("dev-c");
+ claimViewWriter(c, { agent: "t", now });
+ cluster(["s1", "s1", "s2", "s2", "s2"], c);
+ expect(plan(c)).toEqual({ status: "waiting-for-claim" });
+ fresh.sync();
+ const d = fresh.open("dev-d");
+ requestViewWriter(d, { agent: "t", now, force: false });
+ fresh.sync();
+ expect(plan(c)).toEqual({ status: "released", to: "dev-d" });
+ const records = (["shared", "private"] as const).flatMap((p) =>
+ readPartition(join(fresh.root("dev-c"), p)).flatMap((s) => s.records),
+ );
+ expect(foldTopics(records).topics.size).toBe(0);
+ } finally {
+ fresh.cleanup();
+ }
+ });
+
+ test("a writer move that arrives while the pass holds the planning lock stops it before it plans", () => {
+ cluster(["s1", "s1", "s2", "s2", "s2"]);
+ m.sync();
+ const b = m.open("dev-b");
+ const lock = `${topicPlanLockTarget(a)}.lock`;
+ let moved = false;
+ clock += 1000;
+ const report = runTopicPlanning(a, {
+ agent: "dream",
+ // The first clock reading under the lock comes after the gate read
+ // the settings: the move lands between that read and the plan's.
+ now: () => {
+ if (!moved && existsSync(lock)) {
+ moved = true;
+ requestViewWriter(b, { agent: "t", now, force: true });
+ m.deliver("dev-b", "dev-a");
+ }
+ return clock;
+ },
+ });
+ expect(moved).toBe(true);
+ expect(report).toEqual({ status: "not-writer", writer: "dev-b" });
+ expect(fold().topics.size).toBe(0);
+ });
+
+ test("a write that fails after a topic was created still lists the topic with its undo command", () => {
+ cluster(["s1", "s1", "s2", "s2", "s2"]);
+ clock += 1000;
+ const report = runTopicPlanning(a, {
+ agent: "dream",
+ // A clock that fails once the create has landed: the first assign fails.
+ now: () => {
+ if (createdOnDisk()) throw new Error("clock unavailable");
+ return clock;
+ },
+ });
+ expect(report.status).toBe("error");
+ if (report.status !== "error") return;
+ expect(report.error).toBe("clock unavailable");
+ expect(report.created.map((c) => [c.members, c.undo])).toEqual([
+ [0, `o2b topic undo ${report.created[0]!.record}`],
+ ]);
+ expect(fold().topics.size).toBe(1);
+ });
+
+ test("two planning processes on the view writer wait for the lock and leave one topic per cluster", async () => {
+ cluster(["s1", "s1", "s2", "s2", "s2"]);
+ ["s3", "s3", "s4", "s4", "s4"].forEach((session, i) =>
+ signal(`Phone views render markdown pages offline ${i}`, { session }),
+ );
+ const start = join(m.parent, "start");
+ const children = [0, 1].map(() =>
+ Bun.spawn(
+ [
+ process.execPath,
+ join(import.meta.dir, "fixtures", "plan-child.ts"),
+ m.root("dev-a"),
+ "dev-a",
+ m.parent,
+ start,
+ ],
+ {
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ // Shorter than the time the lock is held: planning must wait longer.
+ env: { ...process.env, OPEN_SECOND_BRAIN_LOCK_WAIT_MS: "200" },
+ },
+ ),
+ );
+ // Hold the planning lock while both children start, so both must wait on it.
+ let released = 0;
+ withLocalLock(topicPlanLockTarget(a), () => {
+ writeFileSync(start, "");
+ // Release only once both children are about to plan, so both meet the held lock.
+ const deadline = Date.now() + 20_000;
+ while (startedChildren() < 2 && Date.now() < deadline) Bun.sleepSync(10);
+ expect(startedChildren()).toBe(2);
+ Bun.sleepSync(300);
+ released = Date.now();
+ });
+ const outs = await Promise.all(children.map((c) => new Response(c.stdout).text()));
+ await Promise.all(children.map((c) => c.exited));
+ const results = outs.map(
+ (o) => JSON.parse(o) as { report?: { status: string; created: unknown[] }; end: number },
+ );
+ for (const result of results) {
+ expect(result.report?.status).toBe("planned");
+ expect(result.end).toBeGreaterThanOrEqual(released);
+ }
+ expect(results.flatMap((r) => r.report!.created)).toHaveLength(2);
+ expect(fold().topics.size).toBe(2);
+ });
+});
diff --git a/tests/core/topics/topic-format-doc.test.ts b/tests/core/topics/topic-format-doc.test.ts
new file mode 100644
index 00000000..8ade6164
--- /dev/null
+++ b/tests/core/topics/topic-format-doc.test.ts
@@ -0,0 +1,28 @@
+/**
+ * The shipped FORMAT.md documents every topic record kind, status and log
+ * class the code defines (task 3.1), so a reader of the store in another
+ * language can fold topics from the document alone.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { shippedFormatDoc } from "../../../src/core/store/format-doc.ts";
+import {
+ TOPIC_LOG_CLASSES,
+ TOPIC_RECORD_KINDS,
+ TOPIC_STATUSES,
+ TOPIC_STREAM,
+} from "../../../src/core/topics/constants.ts";
+
+const doc = shippedFormatDoc();
+
+describe("FORMAT.md", () => {
+ test.each([...TOPIC_RECORD_KINDS])("documents the topic record kind %s", (kind) => {
+ expect(doc).toMatch(new RegExp(`^- \`${kind}\`:`, "m"));
+ });
+
+ test("names every status, log class and the topics stream", () => {
+ for (const name of [...TOPIC_STATUSES, ...TOPIC_LOG_CLASSES])
+ expect(doc).toContain(`"${name}"`);
+ expect(doc).toMatch(new RegExp(`^- \`${TOPIC_STREAM}\`:`, "m"));
+ });
+});
diff --git a/tests/core/topics/write.test.ts b/tests/core/topics/write.test.ts
new file mode 100644
index 00000000..b45abc5f
--- /dev/null
+++ b/tests/core/topics/write.test.ts
@@ -0,0 +1,116 @@
+/**
+ * The topic write path and read (task 3.1): topic events are appended to
+ * the writer's own `topics` shard as one store operation, in one
+ * partition. A personal topic is private by default and every later event
+ * of a private topic stays there; a caller below local reach folds only
+ * `shared`. A malformed event or a topic that does not exist is refused
+ * with nothing written.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+import { withPrivateWithheld } from "../../../src/core/store/caller-reach.ts";
+import { readPartition } from "../../../src/core/store/state-digest.ts";
+import { StoreWriteError } from "../../../src/core/store/store-write.ts";
+import { readTopics } from "../../../src/core/topics/read.ts";
+import {
+ createTopicEvent,
+ TopicWriteError,
+ writeTopicEvents,
+} from "../../../src/core/topics/write.ts";
+import { makeStoreEnv, type StoreEnv } from "../store/fixtures/store-env.ts";
+
+let env: StoreEnv | undefined;
+afterEach(() => {
+ env?.cleanup();
+ env = undefined;
+});
+
+function topicRecords(partition: "shared" | "private") {
+ return readPartition(join(env!.storeRoot, partition))
+ .filter((shard) => shard.stream === "topics")
+ .flatMap((shard) => shard.records);
+}
+
+describe("writeTopicEvents", () => {
+ test("a project topic lands in shared under its id; a personal one in private", () => {
+ env = makeStoreEnv("o2b-topics-write-", { legacyTree: false });
+ const project = createTopicEvent({ title: "Store", scope: "project:o2b", authority: "human" });
+ const personal = createTopicEvent({
+ title: "Move flat",
+ scope: "personal",
+ authority: "human",
+ });
+ writeTopicEvents([project], { configPath: env.configPath });
+ writeTopicEvents([personal], { configPath: env.configPath });
+ writeTopicEvents(
+ [
+ {
+ kind: "decision",
+ topic: personal.topic,
+ authority: "agent",
+ body: { text: "Rent first" },
+ },
+ ],
+ { configPath: env.configPath, private: false },
+ );
+ const shared = topicRecords("shared");
+ expect(shared.map((r) => [r.kind, r.topic, r.scope])).toEqual([
+ ["topic-create", project.topic, "project:o2b"],
+ ]);
+ expect(topicRecords("private").map((r) => [r.kind, r.topic])).toEqual([
+ ["topic-create", personal.topic],
+ ["decision", personal.topic],
+ ]);
+ const local = readTopics(env.configPath).fold;
+ expect([...local.topics.keys()].toSorted()).toEqual([project.topic, personal.topic].toSorted());
+ expect(local.topics.get(personal.topic)!.private).toBe(true);
+ const remote = withPrivateWithheld(true, () => readTopics(env!.configPath)).fold;
+ expect([...remote.topics.keys()]).toEqual([project.topic]);
+ });
+
+ test("an event for a topic that does not exist, or with a malformed body, writes nothing", () => {
+ env = makeStoreEnv("o2b-topics-write-", { legacyTree: false });
+ const made = createTopicEvent({ title: "Store", scope: "project:o2b", authority: "human" });
+ const stray = createTopicEvent({
+ title: "Never written",
+ scope: "project:o2b",
+ authority: "agent",
+ });
+ expect(() =>
+ writeTopicEvents(
+ [made, { kind: "link", topic: made.topic, authority: "agent", body: { to: stray.topic } }],
+ { configPath: env!.configPath },
+ ),
+ ).toThrow(TopicWriteError);
+ expect(() =>
+ writeTopicEvents(
+ [
+ made,
+ {
+ kind: "topic-status",
+ topic: made.topic,
+ authority: "agent",
+ body: { status: "later" },
+ },
+ ],
+ { configPath: env!.configPath },
+ ),
+ ).toThrow(/status must be one of/);
+ expect(topicRecords("shared")).toEqual([]);
+ });
+
+ test("a personal topic on a machine without the private partition is refused", () => {
+ env = makeStoreEnv("o2b-topics-write-", { legacyTree: false, partitions: ["shared"] });
+ const personal = createTopicEvent({ title: "Health", scope: "personal", authority: "human" });
+ let thrown: unknown;
+ try {
+ writeTopicEvents([personal], { configPath: env.configPath });
+ } catch (err) {
+ thrown = err;
+ }
+ expect(thrown).toBeInstanceOf(StoreWriteError);
+ expect((thrown as StoreWriteError).reason).toBe("partition-unavailable");
+ expect(topicRecords("shared")).toEqual([]);
+ });
+});
diff --git a/tests/core/view/auto-render.test.ts b/tests/core/view/auto-render.test.ts
index f605688b..4451b8d7 100644
--- a/tests/core/view/auto-render.test.ts
+++ b/tests/core/view/auto-render.test.ts
@@ -103,8 +103,10 @@ describe("automatic view render", () => {
const page = join(view, "about-me.md");
fs.utimesSync(page, new Date(NOW), new Date(NOW));
read.mockClear();
+ opened.mockClear();
runViewPass(a, opts);
- expect(read.mock.calls.map((c) => String(c[0]))).toContain(page);
+ // A page is opened, then read through its descriptor.
+ expect([...read.mock.calls, ...opened.mock.calls].map((c) => String(c[0]))).toContain(page);
read.mockClear();
opened.mockClear();
diff --git a/tests/core/view/fixtures/seed.ts b/tests/core/view/fixtures/seed.ts
index 593d5849..2607238a 100644
--- a/tests/core/view/fixtures/seed.ts
+++ b/tests/core/view/fixtures/seed.ts
@@ -61,3 +61,67 @@ export function seedSetting(store: StoreHandle, ms: number, key: string, value:
{ now: () => ms },
);
}
+
+/** One topic record, as an agent (or the user) would write it through the topic tools. */
+export function seedTopicRecord(
+ store: StoreHandle,
+ ms: number,
+ kind: string,
+ topic: string,
+ body: Record<string, unknown>,
+ options: {
+ readonly authority?: "human" | "agent" | "model";
+ readonly agent?: string;
+ readonly partition?: StorePartition;
+ } = {},
+): string {
+ return appendRecord(
+ store,
+ {
+ partition: options.partition ?? "shared",
+ stream: "topics",
+ kind,
+ agent: options.agent ?? "seed",
+ topic,
+ body: { authority: options.authority ?? "agent", ...body },
+ },
+ { now: () => ms },
+ ).record.id;
+}
+
+/** One lane entry (a research report, a source summary), as the store-only lane writers write it. */
+export function seedLaneEntry(
+ store: StoreHandle,
+ ms: number,
+ lane: string,
+ entry: string,
+ fields: Record<string, unknown>,
+ text: string,
+): void {
+ appendRecord(
+ store,
+ {
+ partition: "shared",
+ stream: "events",
+ kind: "lane-entry",
+ agent: "seed",
+ body: { authority: "agent", lane, entry, fields, text },
+ },
+ { now: () => ms },
+ );
+}
+
+/** The tombstone of a lane entry. */
+export function seedLaneRemove(store: StoreHandle, ms: number, lane: string, entry: string): void {
+ appendRecord(
+ store,
+ {
+ partition: "shared",
+ stream: "events",
+ kind: "lane-entry-remove",
+ agent: "seed",
+ body: { authority: "human", lane, entry },
+ },
+ { now: () => ms },
+ );
+}
diff --git a/tests/core/view/page-io.test.ts b/tests/core/view/page-io.test.ts
index 0017bd3f..1f169dae 100644
--- a/tests/core/view/page-io.test.ts
+++ b/tests/core/view/page-io.test.ts
@@ -10,7 +10,14 @@ import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "n
import { tmpdir } from "node:os";
import { basename, join } from "node:path";
-import { conflictCopies, replacePage } from "../../../src/core/view/page-io.ts";
+import {
+ capturePage,
+ conflictCopies,
+ moveCompanions,
+ NotAPageFileError,
+ readPage,
+ replacePage,
+} from "../../../src/core/view/page-io.ts";
let dir: string;
beforeEach(() => {
@@ -94,3 +101,149 @@ describe("replacePage", () => {
}
});
});
+
+describe("readPage", () => {
+ test.skipIf(process.platform === "win32")(
+ "a link put under the page name after the check is never read through",
+ () => {
+ const secret = join(dir, "secret.txt");
+ writeFileSync(secret, "secret\n");
+ const page = join(dir, "about-me.md");
+ fs.symlinkSync(secret, page);
+ // The name was a regular file when it was checked; a link took it
+ // before the open.
+ const realLstat = fs.lstatSync;
+ const lstat = spyOn(fs, "lstatSync").mockImplementation(((p: fs.PathLike) =>
+ p === page ? realLstat(secret) : realLstat(p)) as typeof fs.lstatSync);
+ try {
+ expect(() => readPage(page)).toThrow(NotAPageFileError);
+ } finally {
+ lstat.mockRestore();
+ }
+ },
+ );
+});
+
+function folders(): { from: string; to: string } {
+ const from = join(dir, "old");
+ const to = join(dir, "new");
+ fs.mkdirSync(from);
+ writeFileSync(join(from, "notes.md"), "mine\n");
+ return { from, to };
+}
+
+/** Windows: EPERM for a file another program holds. */
+function denied(): never {
+ throw Object.assign(new Error("access denied"), { code: "EPERM" });
+}
+
+describe("capturePage", () => {
+ test("a folder at the name is refused and put back under its name, its files kept", () => {
+ const folder = join(dir, "p.sync-conflict-20260101-120000-abcdefg.md");
+ fs.mkdirSync(folder);
+ writeFileSync(join(folder, "mine.txt"), "mine\n");
+ expect(() => capturePage(folder)).toThrow(NotAPageFileError);
+ expect(readFileSync(join(folder, "mine.txt"), "utf8")).toBe("mine\n");
+ expect(readdirSync(dir)).toEqual([basename(folder)]);
+ });
+
+ test.skipIf(process.platform === "win32")(
+ "a symbolic link at the name is refused and made again as the same link, never followed",
+ () => {
+ const target = join(dir, "target.md");
+ writeFileSync(target, "secret\n");
+ const link = join(dir, "p.md");
+ fs.symlinkSync(target, link);
+ expect(() => capturePage(link)).toThrow(NotAPageFileError);
+ expect(fs.lstatSync(link).isSymbolicLink()).toBe(true);
+ expect(fs.readlinkSync(link)).toBe(target);
+ expect(readdirSync(dir).toSorted()).toEqual(["p.md", "target.md"]);
+ },
+ );
+});
+
+describe("moveCompanions", () => {
+ test("a copy whose source cannot be removed is taken back: the file stays in one folder", () => {
+ const { from, to } = folders();
+ // Both calls fail with EPERM, as on Windows: the link, and taking the
+ // source out of its name (Windows refuses to rename a held file too).
+ const link = spyOn(fs, "linkSync").mockImplementation(denied);
+ const realRename = fs.renameSync;
+ const rename = spyOn(fs, "renameSync").mockImplementation(((p: fs.PathLike, q: fs.PathLike) => {
+ if (String(p) === join(from, "notes.md")) denied();
+ realRename(p, q);
+ }) as typeof fs.renameSync);
+ try {
+ moveCompanions(from, to, new Set());
+ } finally {
+ link.mockRestore();
+ rename.mockRestore();
+ }
+ expect(readdirSync(from)).toEqual(["notes.md"]);
+ expect(readdirSync(to)).toEqual([]);
+ });
+
+ test("a source a sync tool replaced after the link is kept, and the stale link is taken back", () => {
+ const { from, to } = folders();
+ const realLink = fs.linkSync;
+ const link = spyOn(fs, "linkSync").mockImplementation(((a: fs.PathLike, b: fs.PathLike) => {
+ realLink(a, b);
+ // The sync tool delivers a newer version under the old name.
+ fs.renameSync(join(dir, "newer.tmp"), join(from, "notes.md"));
+ }) as typeof fs.linkSync);
+ writeFileSync(join(dir, "newer.tmp"), "newer\n");
+ try {
+ moveCompanions(from, to, new Set());
+ } finally {
+ link.mockRestore();
+ }
+ expect(readFileSync(join(from, "notes.md"), "utf8")).toBe("newer\n");
+ expect(readdirSync(to)).toEqual([]);
+ });
+
+ test("a destination a sync tool replaced while the move is taken back is kept", () => {
+ const { from, to } = folders();
+ const realLink = fs.linkSync;
+ writeFileSync(join(dir, "newer.tmp"), "newer\n");
+ writeFileSync(join(dir, "theirs.tmp"), "theirs\n");
+ const link = spyOn(fs, "linkSync").mockImplementation(((a: fs.PathLike, b: fs.PathLike) => {
+ realLink(a, b);
+ link.mockRestore();
+ // The sync tool delivers newer versions under both names.
+ fs.renameSync(join(dir, "newer.tmp"), join(from, "notes.md"));
+ fs.renameSync(join(dir, "theirs.tmp"), join(to, "notes.md"));
+ }) as typeof fs.linkSync);
+ try {
+ moveCompanions(from, to, new Set());
+ } finally {
+ link.mockRestore();
+ }
+ expect(readFileSync(join(from, "notes.md"), "utf8")).toBe("newer\n");
+ expect(readFileSync(join(to, "notes.md"), "utf8")).toBe("theirs\n");
+ });
+
+ test("a source a sync tool replaced after the last check is kept, never removed", () => {
+ const { from, to } = folders();
+ const source = join(from, "notes.md");
+ const realLstat = fs.lstatSync;
+ writeFileSync(join(dir, "newer.tmp"), "newer\n");
+ let seen = 0;
+ const lstat = spyOn(fs, "lstatSync").mockImplementation(((p: fs.PathLike) => {
+ const stat = realLstat(p);
+ // The second look at the source is the last check before it goes.
+ if (String(p) === source && ++seen === 2) {
+ lstat.mockRestore();
+ fs.renameSync(join(dir, "newer.tmp"), source);
+ }
+ return stat;
+ }) as typeof fs.lstatSync);
+ try {
+ moveCompanions(from, to, new Set());
+ } finally {
+ lstat.mockRestore();
+ }
+ expect(seen).toBe(2);
+ expect(readFileSync(source, "utf8")).toBe("newer\n");
+ expect(readdirSync(to)).toEqual([]);
+ });
+});
diff --git a/tests/core/view/retire.test.ts b/tests/core/view/retire.test.ts
new file mode 100644
index 00000000..458c7a37
--- /dev/null
+++ b/tests/core/view/retire.test.ts
@@ -0,0 +1,448 @@
+/**
+ * Pages leaving the view (review fixes of task 3.2): a forged render
+ * record never makes the view writer read, ingest, move or remove a file
+ * outside the view or outside the page shapes it writes (`..`, a
+ * backslash); when a folder slot passes from one topic to another, each
+ * topic keeps its user's files; and a renamed topic's files follow it
+ * even when its old page was already gone.
+ */
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+ existsSync,
+ linkSync,
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import * as fs from "node:fs";
+import { join } from "node:path";
+
+import { appendRecord } from "../../../src/core/store/appender.ts";
+import { readPartition } from "../../../src/core/store/state-digest.ts";
+import type { StoreHandle } from "../../../src/core/store/store-open.ts";
+import { newUlid } from "../../../src/core/store/ulid.ts";
+import { capturePage, NotAPageFileError } from "../../../src/core/view/page-io.ts";
+import { runViewPass } from "../../../src/core/view/render.ts";
+import { bytesSum, writeBase } from "../../../src/core/view/view-records.ts";
+import { claimViewWriter } from "../../../src/core/view/writer.ts";
+import { makeMachines, type Machines } from "./fixtures/machines.ts";
+import { seedLaneEntry, seedLaneRemove, seedTopicRecord } from "./fixtures/seed.ts";
+
+const T0 = Date.UTC(2026, 10, 2, 9, 0, 0);
+let clock = T0;
+const now = () => clock;
+
+let m: Machines;
+let a: StoreHandle;
+beforeEach(() => {
+ clock = T0;
+ m = makeMachines(["dev-a"]);
+ a = m.open("dev-a");
+});
+afterEach(() => m.cleanup());
+
+function render(passes = 2): void {
+ claimViewWriter(a, { agent: "t", now });
+ for (let i = 0; i < passes; i++) {
+ clock += 1000;
+ runViewPass(a, { target: m.view("dev-a"), vault: null, agent: "t", now });
+ }
+}
+
+function topic(id: string, title: string, kind = "topic-create"): void {
+ clock += 60_000;
+ const body = kind === "topic-create" ? { title, scope: "project:o2b" } : { title };
+ seedTopicRecord(a, clock, kind, id, body, { authority: "human" });
+}
+
+/** A render record for `page` with a real merge base, as a peer could write it. */
+function forgeRender(page: string, text: string, topicId?: string): void {
+ clock += 1000;
+ appendRecord(
+ a,
+ {
+ partition: "shared",
+ stream: "log",
+ kind: "view-render",
+ agent: "peer",
+ body: {
+ page,
+ ...(topicId !== undefined ? { topic: topicId } : {}),
+ sum: bytesSum(`${text}-other`),
+ base: writeBase(a, page, { text: `${text}-base\n`, keys: [null] }),
+ bytes: 1,
+ },
+ },
+ { now },
+ );
+}
+
+const view = (...parts: string[]) => join(m.view("dev-a"), ...parts);
+
+/** Whether two names are one file on disk. */
+function oneFile(first: string, second: string): boolean {
+ try {
+ const sa = statSync(first);
+ const sb = statSync(second);
+ return sa.dev === sb.dev && sa.ino === sb.ino;
+ } catch {
+ return false;
+ }
+}
+
+describe("pages leaving the view", () => {
+ test("a forged render record outside the view or outside the page shapes touches no file", () => {
+ // A file beside the view folder, reached by `..`.
+ const outside = join(m.view("dev-a"), "..", "outside");
+ mkdirSync(outside, { recursive: true });
+ writeFileSync(join(outside, "topic.md"), "secret\n");
+ writeFileSync(join(outside, "keep.txt"), "mine\n");
+ forgeRender("topics/../../outside/topic.md", "a");
+ // A Windows separator: one folder on POSIX, an escape on Windows.
+ const backslash = view("topics", "..\\..\\outside2");
+ mkdirSync(backslash, { recursive: true });
+ writeFileSync(join(backslash, "topic.md"), "secret two\n");
+ forgeRender("topics/..\\..\\outside2/topic.md", "b");
+ // A name the renderer never writes, inside the view.
+ mkdirSync(view("topics", "notes"), { recursive: true });
+ writeFileSync(view("topics", "notes", "todo.md"), "my list\n");
+ forgeRender("topics/notes/todo.md", "c");
+ topic(newUlid(T0), "Real");
+ render();
+ expect(readFileSync(join(outside, "topic.md"), "utf8")).toBe("secret\n");
+ expect(readdirSync(outside).toSorted()).toEqual(["keep.txt", "topic.md"]);
+ expect(readFileSync(join(backslash, "topic.md"), "utf8")).toBe("secret two\n");
+ expect(readFileSync(view("topics", "notes", "todo.md"), "utf8")).toBe("my list\n");
+ const stored = (["shared", "private"] as const)
+ .flatMap((p) => readPartition(join(m.root("dev-a"), p)))
+ .flatMap((s) => s.records)
+ .map((r) => JSON.stringify(r.body));
+ expect(stored.some((body) => body.includes("secret") || body.includes("my list"))).toBe(false);
+ });
+
+ test("when a rename hands a folder slot to another topic, each topic keeps its own files", () => {
+ const first = newUlid(T0);
+ const second = newUlid(T0 + 1);
+ topic(first, "Docs");
+ topic(second, "Docs");
+ render();
+ const base = "2026-11-02-docs";
+ const tail = `${base}-${second.slice(-6).toLowerCase()}`;
+ expect(readdirSync(view("topics")).toSorted()).toEqual([base, tail]);
+ writeFileSync(view("topics", base, "a-notes.md"), "first's\n");
+ writeFileSync(view("topics", tail, "b-notes.md"), "second's\n");
+ topic(first, "Alpha", "topic-rename");
+ render();
+ expect(readdirSync(view("topics")).toSorted()).toEqual(["2026-11-02-alpha", base]);
+ expect(readdirSync(view("topics", "2026-11-02-alpha")).toSorted()).toEqual([
+ "a-notes.md",
+ "topic.md",
+ ]);
+ expect(readdirSync(view("topics", base)).toSorted()).toEqual(["b-notes.md", "topic.md"]);
+ expect(readFileSync(view("topics", base, "topic.md"), "utf8")).toContain(`topic=${second}`);
+ });
+
+ test("two topics that exchange folders each keep their own files", () => {
+ const one = newUlid(T0);
+ const two = newUlid(T0 + 1);
+ topic(one, "Alpha");
+ topic(two, "Beta");
+ render();
+ writeFileSync(view("topics", "2026-11-02-alpha", "a-notes.md"), "one's\n");
+ writeFileSync(view("topics", "2026-11-02-beta", "b-notes.md"), "two's\n");
+ topic(one, "Beta", "topic-rename");
+ topic(two, "Alpha", "topic-rename");
+ render();
+ expect(readdirSync(view("topics")).toSorted()).toEqual(["2026-11-02-alpha", "2026-11-02-beta"]);
+ expect(readdirSync(view("topics", "2026-11-02-beta")).toSorted()).toEqual([
+ "a-notes.md",
+ "topic.md",
+ ]);
+ expect(readdirSync(view("topics", "2026-11-02-alpha")).toSorted()).toEqual([
+ "b-notes.md",
+ "topic.md",
+ ]);
+ expect(readFileSync(view("topics", "2026-11-02-beta", "topic.md"), "utf8")).toContain(
+ `topic=${one}`,
+ );
+ });
+
+ test("a conflict copy a sync tool writes again while the page retires is kept and ingested later", () => {
+ seedLaneEntry(a, (clock += 1000), "reports", "vector", { title: "vector" }, "Lower.");
+ render();
+ const copy = view("reports", "vector.sync-conflict-20261106-120000-abcdefg.md");
+ writeFileSync(copy, "older copy line\n");
+ seedLaneRemove(a, (clock += 1000), "reports", "vector");
+ const newer = join(m.view("dev-a"), "..", "newer.tmp");
+ writeFileSync(newer, "newer copy line\n");
+ const realOpen = fs.openSync;
+ const realRename = fs.renameSync;
+ let delivered = false;
+ // The sync tool writes the copy again right after the writer first
+ // touches it: once a read has closed the file (Windows refuses to
+ // replace a file that is open), or right after a rename took it.
+ const deliver = (): void => {
+ if (delivered) return;
+ delivered = true;
+ realRename(newer, copy);
+ };
+ const realClose = fs.closeSync;
+ let copyFd: number | null = null;
+ const open = spyOn(fs, "openSync").mockImplementation(((p: fs.PathLike, ...rest: never[]) => {
+ const fd = (realOpen as (...args: unknown[]) => number)(p, ...rest);
+ if (String(p) === copy) copyFd = fd;
+ return fd;
+ }) as typeof fs.openSync);
+ const close = spyOn(fs, "closeSync").mockImplementation(((fd: number) => {
+ realClose(fd);
+ if (fd === copyFd) {
+ copyFd = null;
+ deliver();
+ }
+ }) as typeof fs.closeSync);
+ const rename = spyOn(fs, "renameSync").mockImplementation(((p: fs.PathLike, q: fs.PathLike) => {
+ realRename(p, q);
+ if (String(p) === copy) deliver();
+ }) as typeof fs.renameSync);
+ try {
+ render(1);
+ } finally {
+ open.mockRestore();
+ close.mockRestore();
+ rename.mockRestore();
+ }
+ expect(delivered).toBe(true);
+ render(1);
+ const stored = (["shared", "private"] as const)
+ .flatMap((p) => readPartition(join(m.root("dev-a"), p)))
+ .flatMap((s) => s.records)
+ .map((r) => JSON.stringify(r.body));
+ expect(stored.some((body) => body.includes("newer copy line"))).toBe(true);
+ expect(existsSync(copy)).toBe(false);
+ });
+
+ test("a folder named like a conflict copy of a retiring page stays where it is", () => {
+ seedLaneEntry(a, (clock += 1000), "reports", "vector", { title: "vector" }, "Lower.");
+ render();
+ const copy = view("reports", "vector.sync-conflict-20261106-120000-abcdefg.md");
+ mkdirSync(copy);
+ writeFileSync(join(copy, "mine.txt"), "mine\n");
+ seedLaneRemove(a, (clock += 1000), "reports", "vector");
+ render(1);
+ expect(readFileSync(join(copy, "mine.txt"), "utf8")).toBe("mine\n");
+ expect(readdirSync(view("reports")).filter((n) => n.startsWith("."))).toEqual([]);
+ });
+
+ test.skipIf(process.platform === "win32")(
+ "a symbolic link named like a conflict copy of a retiring page is never read or moved",
+ () => {
+ seedLaneEntry(a, (clock += 1000), "reports", "vector", { title: "vector" }, "Lower.");
+ render();
+ const outside = join(m.view("dev-a"), "..", "outside-secret.md");
+ writeFileSync(outside, "outside secret\n");
+ const copy = view("reports", "vector.sync-conflict-20261106-120000-abcdefg.md");
+ symlinkSync(outside, copy);
+ seedLaneRemove(a, (clock += 1000), "reports", "vector");
+ render(1);
+ expect(fs.lstatSync(copy).isSymbolicLink()).toBe(true);
+ expect(readdirSync(view("reports")).filter((n) => n.startsWith("."))).toEqual([]);
+ const stored = (["shared", "private"] as const)
+ .flatMap((p) => readPartition(join(m.root("dev-a"), p)))
+ .flatMap((s) => s.records)
+ .map((r) => JSON.stringify(r.body));
+ expect(stored.some((body) => body.includes("outside secret"))).toBe(false);
+ },
+ );
+
+ test("a renamed topic's files follow it when its old page was already gone", () => {
+ const id = newUlid(T0);
+ topic(id, "Docs");
+ render();
+ writeFileSync(view("topics", "2026-11-02-docs", "notes.md"), "mine\n");
+ // A pass died after the old page left and before its files moved.
+ rmSync(view("topics", "2026-11-02-docs", "topic.md"));
+ topic(id, "Guide", "topic-rename");
+ render();
+ expect(existsSync(view("topics", "2026-11-02-docs"))).toBe(false);
+ expect(readdirSync(view("topics", "2026-11-02-guide")).toSorted()).toEqual([
+ "notes.md",
+ "topic.md",
+ ]);
+ });
+});
+
+describe("pages leaving the view: links, case and device names", () => {
+ test.skipIf(process.platform === "win32")(
+ "a topic folder that is a symbolic link out of the view is never read, emptied or written",
+ () => {
+ const id = newUlid(T0);
+ topic(id, "Live");
+ render();
+ const outside = join(m.view("dev-a"), "..", "elsewhere");
+ mkdirSync(outside, { recursive: true });
+ writeFileSync(join(outside, "id_rsa"), "key\n");
+ const withPage = join(m.view("dev-a"), "..", "elsewhere-two");
+ mkdirSync(withPage, { recursive: true });
+ writeFileSync(join(withPage, "topic.md"), "secret\n");
+ symlinkSync(outside, view("topics", "2026-11-02-evil"));
+ symlinkSync(withPage, view("topics", "2026-11-02-evil-two"));
+ forgeRender("topics/2026-11-02-evil/topic.md", "a", id);
+ forgeRender("topics/2026-11-02-evil-two/topic.md", "b", id);
+ render();
+ expect(readdirSync(outside)).toEqual(["id_rsa"]);
+ expect(readFileSync(join(withPage, "topic.md"), "utf8")).toBe("secret\n");
+ expect(readdirSync(view("topics", "2026-11-02-live")).toSorted()).toEqual(["topic.md"]);
+ const stored = readPartition(join(m.root("dev-a"), "shared"))
+ .flatMap((s) => s.records)
+ .map((r) => JSON.stringify(r.body));
+ expect(stored.some((body) => body.includes("secret"))).toBe(false);
+ },
+ );
+
+ test("a forged record naming a Windows device name is never retired", () => {
+ mkdirSync(view("reports"), { recursive: true });
+ writeFileSync(view("reports", "con.md"), "mine\n");
+ forgeRender("reports/con.md", "a");
+ topic(newUlid(T0), "Real");
+ render();
+ expect(readFileSync(view("reports", "con.md"), "utf8")).toBe("mine\n");
+ });
+
+ test.skipIf(process.platform === "win32")(
+ "a page that is a live page's file under another case is not retired",
+ () => {
+ seedLaneEntry(a, (clock += 1000), "reports", "vector", { title: "vector" }, "Lower.");
+ render();
+ seedLaneRemove(a, (clock += 1000), "reports", "vector");
+ seedLaneEntry(a, (clock += 1000), "reports", "Vector", { title: "Vector" }, "Upper.");
+ render();
+ // What a case-insensitive file system does: both names are one file.
+ // On such a file system (macOS by default) they already are, and
+ // removing one name would remove the live page.
+ if (!oneFile(view("reports", "vector.md"), view("reports", "Vector.md"))) {
+ rmSync(view("reports", "vector.md"), { force: true });
+ linkSync(view("reports", "Vector.md"), view("reports", "vector.md"));
+ }
+ const before = readPartition(join(m.root("dev-a"), "shared")).flatMap(
+ (s) => s.records,
+ ).length;
+ render();
+ const after = readPartition(join(m.root("dev-a"), "shared")).flatMap((s) => s.records);
+ expect(existsSync(view("reports", "vector.md"))).toBe(true);
+ expect(after.slice(before).filter((r) => r.body["page"] === "reports/vector.md")).toEqual([]);
+ },
+ );
+
+ test("a page whose id line a user edited is not taken for another topic's", () => {
+ const one = newUlid(T0);
+ const two = newUlid(T0 + 1);
+ topic(one, "Alpha");
+ topic(two, "Beta");
+ render();
+ const page = view("topics", "2026-11-02-alpha", "topic.md");
+ writeFileSync(view("topics", "2026-11-02-alpha", "notes.md"), "mine\n");
+ writeFileSync(page, readFileSync(page, "utf8").replace(`topic=${one}`, `topic=${two}`));
+ render();
+ expect(readdirSync(view("topics", "2026-11-02-alpha")).toSorted()).toEqual([
+ "notes.md",
+ "topic.md",
+ ]);
+ expect(readdirSync(view("topics", "2026-11-02-beta")).toSorted()).toEqual(["topic.md"]);
+ });
+});
+
+describe("pages leaving the view: review follow-ups", () => {
+ test.skipIf(process.platform === "win32")(
+ "a page name that became a symbolic link is never read through when captured",
+ () => {
+ const outside = join(m.parent, "secret.txt");
+ writeFileSync(outside, "secret\n");
+ mkdirSync(view("topics"), { recursive: true });
+ const page = view("topics", "page.md");
+ symlinkSync(outside, page);
+ expect(() => capturePage(page)).toThrow(NotAPageFileError);
+ expect(readFileSync(outside, "utf8")).toBe("secret\n");
+ expect(existsSync(page)).toBe(true);
+ },
+ );
+
+ test("a folder at a live topic page's name is refused and the rest of the pass renders", () => {
+ const docs = newUlid(T0);
+ const store = newUlid(T0 + 1);
+ topic(docs, "Docs");
+ topic(store, "Store");
+ const blocked = view("topics", "2026-11-02-docs", "topic.md");
+ mkdirSync(blocked, { recursive: true });
+ claimViewWriter(a, { agent: "t", now });
+ let report = runViewPass(a, { target: m.view("dev-a"), vault: null, agent: "t", now });
+ for (let i = 0; i < 2 && report.status !== "rendered"; i++) {
+ clock += 1000;
+ report = runViewPass(a, { target: m.view("dev-a"), vault: null, agent: "t", now });
+ }
+ if (report.status !== "rendered") throw new Error(report.status);
+ const byPage = new Map(report.pages.map((p) => [p.page, p.status]));
+ expect(byPage.get("topics/2026-11-02-docs/topic.md")).toBe("refused");
+ expect(byPage.get("topics/2026-11-02-store/topic.md")).toBe("written");
+ expect(existsSync(view("topics", "2026-11-02-store", "topic.md"))).toBe(true);
+ expect(readdirSync(blocked)).toEqual([]);
+ });
+
+ test("a pass whose time budget ran out retires nothing and defers the pages", () => {
+ const id = newUlid(T0);
+ topic(id, "Docs");
+ render();
+ topic(id, "Guide", "topic-rename");
+ claimViewWriter(a, { agent: "t", now });
+ clock += 1000;
+ const report = runViewPass(a, {
+ target: m.view("dev-a"),
+ vault: null,
+ agent: "t",
+ now,
+ shouldStop: () => true,
+ });
+ expect(existsSync(view("topics", "2026-11-02-docs", "topic.md"))).toBe(true);
+ if (report.status !== "rendered") throw new Error(report.status);
+ expect(report.pages.every((p) => p.status === "deferred")).toBe(true);
+ });
+
+ test("a retired page whose id line names another topic still takes its files to its own topic", () => {
+ const one = newUlid(T0);
+ const two = newUlid(T0 + 1);
+ topic(one, "Alpha");
+ topic(two, "Beta");
+ render();
+ const page = view("topics", "2026-11-02-alpha", "topic.md");
+ writeFileSync(view("topics", "2026-11-02-alpha", "notes.md"), "mine\n");
+ writeFileSync(page, readFileSync(page, "utf8").replace(`topic=${one}`, `topic=${two}`));
+ topic(one, "Gamma", "topic-rename");
+ render();
+ expect(readdirSync(view("topics", "2026-11-02-gamma")).toSorted()).toEqual([
+ "notes.md",
+ "topic.md",
+ ]);
+ expect(readdirSync(view("topics", "2026-11-02-beta")).toSorted()).toEqual(["topic.md"]);
+ });
+
+ test("a slot handed to another topic while the old page was gone still moves the old topic's files", () => {
+ const first = newUlid(T0);
+ const second = newUlid(T0 + 1);
+ topic(first, "Docs");
+ topic(second, "Docs");
+ render();
+ const base = "2026-11-02-docs";
+ writeFileSync(view("topics", base, "a-notes.md"), "first's\n");
+ rmSync(view("topics", base, "topic.md"));
+ topic(first, "Alpha", "topic-rename");
+ render();
+ expect(readdirSync(view("topics", "2026-11-02-alpha")).toSorted()).toEqual([
+ "a-notes.md",
+ "topic.md",
+ ]);
+ expect(readdirSync(view("topics", base))).not.toContain("a-notes.md");
+ });
+});
diff --git a/tests/core/view/topic-edits.test.ts b/tests/core/view/topic-edits.test.ts
new file mode 100644
index 00000000..68c7df12
--- /dev/null
+++ b/tests/core/view/topic-edits.test.ts
@@ -0,0 +1,134 @@
+/**
+ * How a changed line of a topic page maps to a human topic record (task
+ * 3.2): the generated decorations (list marker, checkbox, done marker,
+ * log date and class, "because" tail) are stripped in any view language,
+ * and a line this mapping does not own falls back to the generic view
+ * correction.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { topicAddition, topicCorrection } from "../../../src/core/view/topic-edits.ts";
+
+const ID = "01KA0000000000000000000000";
+const key = (rest: string) => `t:${ID}:${rest}`;
+
+const bodies = (records: ReturnType<typeof topicCorrection>) =>
+ records?.map((r) => [r.kind, r.topic, r.body]);
+
+describe("topicCorrection", () => {
+ test("a status line in either language becomes topic-status, a done day kept", () => {
+ expect(
+ bodies(
+ topicCorrection(key("status"), "Status: Active", "Статус: Готова (решена 2026-11-10)"),
+ ),
+ ).toEqual([
+ ["topic-status", ID, { authority: "human", status: "done", resolved: "2026-11-10" }],
+ ]);
+ expect(bodies(topicCorrection(key("status"), "Status: Active", "Status: on hold"))).toEqual([
+ ["topic-status", ID, { authority: "human", status: "on-hold" }],
+ ]);
+ expect(topicCorrection(key("status"), "Status: Active", "Status: someday")).toBeNull();
+ });
+
+ test("a ticked milestone is marked done; its markers never reach the text", () => {
+ expect(
+ bodies(
+ topicCorrection(
+ key("m:m1"),
+ "- [ ] Migration (looks done, confirm)",
+ "- [x] Migration (looks done, confirm)",
+ ),
+ ),
+ ).toEqual([["milestone-done", ID, { authority: "human", milestone: "m1" }]]);
+ expect(
+ bodies(
+ topicCorrection(
+ key("m:m1"),
+ "- [x] Migration (done 2026-11-02)",
+ "- [x] Data migration (done 2026-11-02)",
+ ),
+ ),
+ ).toEqual([["milestone", ID, { authority: "human", item: "m1", text: "Data migration" }]]);
+ });
+
+ test("an unticked done milestone undoes the record that completed it", () => {
+ const done = "01KA0000000000000000000002";
+ expect(
+ bodies(
+ topicCorrection(
+ key(`mx:${done}:m1`),
+ "- [x] Migration (done 2026-11-02)",
+ "- [ ] Migration",
+ ),
+ ),
+ ).toEqual([["undo", ID, { authority: "human", record: done }]]);
+ });
+
+ test("a reworded log line keeps its class and splits off the reason", () => {
+ expect(
+ bodies(
+ topicCorrection(
+ key("l:rejected:i9"),
+ "- 2026-11-02, rejected approach: One file per writer, because devices churn",
+ "- 2026-11-02, rejected approach: One file per process, because process ids churn",
+ ),
+ ),
+ ).toEqual([
+ [
+ "log-entry",
+ ID,
+ {
+ authority: "human",
+ item: "i9",
+ text: "One file per process",
+ class: "rejected",
+ reason: "process ids churn",
+ },
+ ],
+ ]);
+ });
+
+ test("a deleted item is its tombstone; a deleted goal proposal undoes the agent's record", () => {
+ expect(bodies(topicCorrection(key("d:d1"), "- Keep JSONL", null))).toEqual([
+ ["decision", ID, { authority: "human", item: "d1", removed: true }],
+ ]);
+ const proposal = "01KA0000000000000000000001";
+ expect(
+ bodies(topicCorrection(key(`gp:${proposal}`), "- Goal proposed by planner: Ship", null)),
+ ).toEqual([["undo", ID, { authority: "human", record: proposal }]]);
+ });
+
+ test("lines the mapping does not own fall back to the generic correction", () => {
+ expect(topicCorrection(key("scope"), "- Project: o2b", "- Project: other")).toBeNull();
+ expect(topicCorrection("pref:pref-x", "- a", "- b")).toBeNull();
+ });
+});
+
+const strip = (records: ReturnType<typeof topicAddition>) =>
+ bodies(records)?.map(([kind, topic, body]) => {
+ const { item: _item, ...rest } = body as Record<string, unknown>;
+ return [kind, topic, rest];
+ });
+
+describe("topicAddition", () => {
+ test("a line added in an item section is a new item of that section", () => {
+ expect(strip(topicAddition(key("h:questions"), "- Who owns the view?"))).toEqual([
+ ["open-question", ID, { authority: "human", text: "Who owns the view?" }],
+ ]);
+ expect(strip(topicAddition(key("l:blocker:i1"), "- Waiting for the owner"))).toEqual([
+ ["log-entry", ID, { authority: "human", text: "Waiting for the owner", class: "note" }],
+ ]);
+ expect(topicAddition(key("goal"), "more goal text")).toBeNull();
+ });
+
+ test("the same line added twice (a page and its conflict copy) is one item", () => {
+ const one = topicAddition(key("h:milestones"), "- [x] Ship it")!;
+ const two = topicAddition(key("m:m9"), "- [x] Ship it")!;
+ expect(one.map((r) => r.body["item"] ?? r.body["milestone"])).toEqual(
+ two.map((r) => r.body["item"] ?? r.body["milestone"]),
+ );
+ expect(topicAddition(key("h:decisions"), "- Keep JSONL")![0]!.body["item"]).toBe(
+ topicAddition(key("d:d1"), "- Keep JSONL")![0]!.body["item"],
+ );
+ });
+});
diff --git a/tests/core/view/topic-pages.test.ts b/tests/core/view/topic-pages.test.ts
new file mode 100644
index 00000000..0c772cab
--- /dev/null
+++ b/tests/core/view/topic-pages.test.ts
@@ -0,0 +1,443 @@
+/**
+ * Topic pages, reports and sources in the human view (task 3.2, spec
+ * `topics`): `topics/<date>-<slug>/topic.md` rendered through the phase 2
+ * render protocol in the fixed section order, the page budget with its
+ * companion archive, a rename that moves the folder and keeps the id, the
+ * user's edits landing as human topic records, and `reports/` and
+ * `sources/` pages from their lane entries. Snapshots in English and
+ * Russian.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { readPartition } from "../../../src/core/store/state-digest.ts";
+import type { StoreHandle } from "../../../src/core/store/store-open.ts";
+import { newUlid } from "../../../src/core/store/ulid.ts";
+import { foldTopics } from "../../../src/core/topics/fold.ts";
+import { runViewPass } from "../../../src/core/view/render.ts";
+import { claimViewWriter } from "../../../src/core/view/writer.ts";
+import { makeMachines, type Machines } from "./fixtures/machines.ts";
+import { seedLaneEntry, seedLaneRemove, seedSetting, seedTopicRecord } from "./fixtures/seed.ts";
+
+const T0 = Date.UTC(2026, 10, 2, 9, 0, 0);
+let clock = T0;
+const now = () => clock;
+
+let m: Machines;
+let a: StoreHandle;
+let topic: string;
+let other: string;
+
+beforeEach(() => {
+ clock = T0;
+ m = makeMachines(["dev-a", "dev-b"]);
+ a = m.open("dev-a");
+ topic = newUlid(T0);
+ other = newUlid(T0 + 1);
+});
+afterEach(() => m.cleanup());
+
+type Opts = Parameters<typeof seedTopicRecord>[5] & { topic?: string; on?: StoreHandle };
+function rec(kind: string, body: Record<string, unknown>, opts: Opts = {}): string {
+ clock += 60_000;
+ return seedTopicRecord(opts.on ?? a, clock, kind, opts.topic ?? topic, body, opts);
+}
+
+function createTopic(extra: Record<string, unknown> = {}, opts: Opts = {}): void {
+ rec(
+ "topic-create",
+ {
+ title: "Brain store",
+ scope: "project:o2b",
+ goal: "Move machine data out of the vault",
+ ...extra,
+ },
+ { authority: "human", ...opts },
+ );
+}
+
+function render(passes = 2): void {
+ claimViewWriter(a, { agent: "t", now });
+ for (let i = 0; i < passes; i++) {
+ clock += 1000;
+ runViewPass(a, { target: m.view("dev-a"), vault: null, agent: "t", now });
+ }
+}
+
+const view = (rel = "") => join(m.view("dev-a"), ...rel.split("/").filter(Boolean));
+function page(rel: string): string {
+ return readFileSync(view(rel), "utf8").replaceAll(a.storeId, "<store>").replaceAll(topic, "<id>");
+}
+const topicDir = "topics/2026-11-02-brain-store";
+
+function seedFull(): void {
+ createTopic({ description: "Store outside the vault" });
+ rec("topic-create", { title: "Docs", scope: "project:o2b" }, { topic: other });
+ rec("milestone", { item: "m1", text: "Store core" });
+ rec("milestone", { item: "m2", text: "Migration" });
+ rec("milestone", { item: "m3", text: "Topics" });
+ rec("milestone-done", { milestone: "m1", evidence: "PR 289 merged" });
+ rec("milestone-done", { milestone: "m2" }, { authority: "model" });
+ rec("decision", { text: "Monthly shards per device", serves: ["m1"] });
+ rec("open-question", { text: "Where do phones get the view?" });
+ rec("log-entry", { text: "Ran the tests and they passed", class: "routine" });
+ rec("log-entry", { text: "Sync conflicts on pinned.md", class: "blocker" });
+ rec("log-entry", { text: "One file per writer", class: "rejected", reason: "devices churn" });
+ rec("topic-goal", { goal: "Ship it all" }, { agent: "planner" });
+ rec("link", { to: other });
+}
+
+describe("topic pages", () => {
+ test("a new topic: title, description, Status: Active, the goal and related, no empty section", () => {
+ createTopic();
+ render();
+ expect(page(`${topicDir}/topic.md`)).toBe(
+ [
+ `<!-- open-second-brain-view store=<store> page=${topicDir}/topic.md topic=<id> -->`,
+ "",
+ "# Brain store",
+ "",
+ "No description yet.",
+ "",
+ "Status: Active",
+ "",
+ "## Goal",
+ "",
+ "Move machine data out of the vault",
+ "",
+ "## Related",
+ "",
+ "- Project: o2b",
+ "",
+ ].join("\n"),
+ );
+ });
+
+ test("English snapshot: fixed section order, earned log only, proposals as open questions", () => {
+ seedFull();
+ render();
+ expect(page(`${topicDir}/topic.md`)).toBe(
+ [
+ `<!-- open-second-brain-view store=<store> page=${topicDir}/topic.md topic=<id> -->`,
+ "",
+ "# Brain store",
+ "",
+ "Store outside the vault",
+ "",
+ "Status: Active",
+ "",
+ "## Goal",
+ "",
+ "Move machine data out of the vault",
+ "",
+ "## Milestones",
+ "",
+ "- [ ] Migration (looks done, confirm)",
+ "- [ ] Topics",
+ "- [x] Store core (done 2026-11-02)",
+ "",
+ "## Decisions",
+ "",
+ "- Monthly shards per device (serves: Store core)",
+ "",
+ "## Open questions",
+ "",
+ "- Where do phones get the view?",
+ "- Goal proposed by planner: Ship it all",
+ "",
+ "## Log",
+ "",
+ "- 2026-11-02, rejected approach: One file per writer, because devices churn",
+ "- 2026-11-02, blocker: Sync conflicts on pinned.md",
+ "",
+ "## Related",
+ "",
+ "- Project: o2b",
+ "- [Docs](../2026-11-02-docs/topic.md)",
+ "",
+ ].join("\n"),
+ );
+ });
+
+ test("Russian snapshot: generated prose in Russian, quoted lines as written", () => {
+ seedSetting(a, T0, "view.language", "ru");
+ seedFull();
+ render();
+ const text = page(`${topicDir}/topic.md`);
+ expect(text.split("\n").slice(6)).toEqual([
+ "Статус: Активна",
+ "",
+ "## Цель",
+ "",
+ "Move machine data out of the vault",
+ "",
+ "## Вехи",
+ "",
+ "- [ ] Migration (похоже, готово, подтвердите)",
+ "- [ ] Topics",
+ "- [x] Store core (готово 2026-11-02)",
+ "",
+ "## Решения",
+ "",
+ "- Monthly shards per device (служит: Store core)",
+ "",
+ "## Открытые вопросы",
+ "",
+ "- Where do phones get the view?",
+ "- Цель, предложенная planner: Ship it all",
+ "",
+ "## Журнал",
+ "",
+ "- 2026-11-02, отвергнутый подход: One file per writer, потому что devices churn",
+ "- 2026-11-02, блокер: Sync conflicts on pinned.md",
+ "",
+ "## Связанное",
+ "",
+ "- Проект: o2b",
+ "- [Docs](../2026-11-02-docs/topic.md)",
+ "",
+ ]);
+ });
+
+ test("budget overflow: the oldest done milestones and log entries move to archive.md", () => {
+ createTopic();
+ for (let i = 1; i <= 12; i++) {
+ rec("milestone", { item: `m${i}`, text: `Milestone ${i}` });
+ rec("milestone-done", { milestone: `m${i}` }, { authority: "human" });
+ }
+ for (let i = 1; i <= 17; i++) rec("log-entry", { text: `Blocker ${i}`, class: "blocker" });
+ render();
+ const main = page(`${topicDir}/topic.md`);
+ expect(main.match(/^- \[x\]/gm)!.length).toBe(10);
+ expect(main.match(/, blocker: /g)!.length).toBe(15);
+ expect(main).not.toContain("Milestone 1 ");
+ expect(main).not.toContain("Blocker 2\n");
+ expect(main.trimEnd().endsWith("- [Older entries](archive.md)")).toBe(true);
+ expect(page(`${topicDir}/archive.md`)).toBe(
+ [
+ `<!-- open-second-brain-view store=<store> page=${topicDir}/archive.md topic=<id> -->`,
+ "",
+ "# Brain store: archive",
+ "",
+ "Entries that moved off the topic page, newest first.",
+ "",
+ "[Back to the topic](topic.md)",
+ "",
+ "## Milestones",
+ "",
+ "- [x] Milestone 2 (done 2026-11-02)",
+ "- [x] Milestone 1 (done 2026-11-02)",
+ "",
+ "## Log",
+ "",
+ "- 2026-11-02, blocker: Blocker 2",
+ "- 2026-11-02, blocker: Blocker 1",
+ "",
+ ].join("\n"),
+ );
+ });
+
+ test("a rename moves the folder, keeps the id and takes the user's companion files along", () => {
+ createTopic();
+ rec("decision", { text: "Keep JSONL" });
+ render();
+ writeFileSync(view(`${topicDir}/notes.md`), "my notes\n");
+ rec("topic-rename", { title: "Store and topics" }, { authority: "human" });
+ render(1);
+ const moved = "topics/2026-11-02-store-and-topics";
+ expect(existsSync(view(topicDir))).toBe(false);
+ expect(readdirSync(view(moved)).toSorted()).toEqual(["notes.md", "topic.md"]);
+ const text = page(`${moved}/topic.md`);
+ expect(text).toContain("topic=<id> -->");
+ expect(text).toContain("# Store and topics");
+ expect(text).toContain("- Keep JSONL");
+ });
+
+ test("the user's goal on the page wins, and a later agent goal shows as its open question", () => {
+ createTopic();
+ render();
+ const path = view(`${topicDir}/topic.md`);
+ writeFileSync(
+ path,
+ readFileSync(path, "utf8").replace("Move machine data out of the vault", "Ship phase 3"),
+ );
+ render(1);
+ rec("topic-goal", { goal: "Ship everything at once" }, { agent: "planner" });
+ render(1);
+ const goals = readPartition(join(m.root("dev-a"), "shared"))
+ .flatMap((s) => s.records)
+ .filter((r) => r.kind === "topic-goal")
+ .map((r) => [r.body["authority"], r.body["goal"], r.topic]);
+ expect(goals).toEqual([
+ ["human", "Ship phase 3", topic],
+ ["agent", "Ship everything at once", topic],
+ ]);
+ const text = page(`${topicDir}/topic.md`);
+ expect(text).toContain("## Goal\n\nShip phase 3\n");
+ expect(text).toContain("- Goal proposed by planner: Ship everything at once");
+ });
+
+ test("an item the user deletes or adds on the page becomes a human topic record", () => {
+ createTopic();
+ rec("decision", { item: "d1", text: "Keep JSONL" });
+ rec("decision", { item: "d2", text: "Use SQLite" });
+ render();
+ const path = view(`${topicDir}/topic.md`);
+ const edit = (from: string, to: string): void => {
+ writeFileSync(path, readFileSync(path, "utf8").replace(from, to));
+ render(1);
+ };
+ edit("- Keep JSONL\n", "");
+ edit("- Use SQLite\n", "- Use SQLite\n- Mirror nothing to phones\n");
+ const records = readPartition(join(m.root("dev-a"), "shared")).flatMap((s) => s.records);
+ const fold = foldTopics(records).topics.get(topic)!;
+ expect(fold.items.map((i) => [i.text, i.author.authority])).toEqual([
+ ["Use SQLite", "agent"],
+ ["Mirror nothing to phones", "human"],
+ ]);
+ expect(page(`${topicDir}/topic.md`)).toContain(
+ "## Decisions\n\n- Mirror nothing to phones\n- Use SQLite\n",
+ );
+ });
+
+ test("a milestone unticked on the page is open again on the next render", () => {
+ createTopic();
+ rec("milestone", { item: "m1", text: "Store core" });
+ rec("milestone-done", { milestone: "m1" }, { authority: "human" });
+ render();
+ const path = view(`${topicDir}/topic.md`);
+ writeFileSync(
+ path,
+ readFileSync(path, "utf8").replace("- [x] Store core (done 2026-11-02)", "- [ ] Store core"),
+ );
+ render(2);
+ expect(page(`${topicDir}/topic.md`)).toContain("## Milestones\n\n- [ ] Store core\n");
+ });
+
+ test("two machines' events for one topic land on one page, with no conflict copy", () => {
+ createTopic();
+ const b = m.open("dev-b");
+ rec("log-entry", { text: "Found on A", class: "blocker" });
+ rec("log-entry", { text: "Found on B", class: "reframing" }, { on: b });
+ render();
+ m.sync();
+ render();
+ expect(page(`${topicDir}/topic.md`)).toContain(
+ "## Log\n\n- 2026-11-02, reframing: Found on B\n- 2026-11-02, blocker: Found on A\n",
+ );
+ expect(readdirSync(view(topicDir))).toEqual(["topic.md"]);
+ });
+
+ test("a merged topic's page is removed; its items and name show on the topic it joined", () => {
+ createTopic();
+ rec(
+ "topic-create",
+ { title: "Docs", scope: "project:o2b" },
+ { topic: other, authority: "human" },
+ );
+ rec("decision", { text: "Write the guide" }, { topic: other });
+ render();
+ expect(existsSync(view("topics/2026-11-02-docs/topic.md"))).toBe(true);
+ rec("merge", { into: topic }, { topic: other, authority: "human" });
+ render(1);
+ expect(existsSync(view("topics/2026-11-02-docs"))).toBe(false);
+ const text = page(`${topicDir}/topic.md`);
+ expect(text).toContain("- Write the guide");
+ expect(text).toContain("- Merged from: Docs");
+ });
+
+ test("a folder taken by a title that ends in another topic's id tail is never shared", () => {
+ const tail = "01KA0000000000000000ABCDEF";
+ rec(
+ "topic-create",
+ { title: "alpha-abcdef", scope: "project:o2b" },
+ { topic: newUlid(T0 + 5), authority: "human" },
+ );
+ rec(
+ "topic-create",
+ { title: "alpha", scope: "project:o2b" },
+ { topic: newUlid(T0 + 6), authority: "human" },
+ );
+ rec(
+ "topic-create",
+ { title: "alpha", scope: "project:o2b" },
+ { topic: tail, authority: "human" },
+ );
+ render();
+ expect(readdirSync(view("topics"))).toHaveLength(3);
+ });
+
+ test("a private topic and a shared record carrying a private region stay off the view", () => {
+ rec(
+ "topic-create",
+ { title: "Health", scope: "personal" },
+ { partition: "private", topic: other },
+ );
+ createTopic();
+ rec("decision", { text: "Ask <private>Dr. X</private> first" });
+ render();
+ expect(readdirSync(view("topics"))).toEqual(["2026-11-02-brain-store"]);
+ expect(page(`${topicDir}/topic.md`)).not.toContain("Dr. X");
+ });
+});
+
+describe("report and source pages", () => {
+ test("ids that differ only in case render one page, and a device name renders none", () => {
+ for (const entry of ["2026-11-02-vector", "2026-11-02-Vector", "con", "nul.txt"]) {
+ seedLaneEntry(a, (clock += 1000), "reports", entry, { title: entry }, `Body of ${entry}.`);
+ }
+ render();
+ expect(readdirSync(view("reports"))).toEqual(["2026-11-02-Vector.md"]);
+ });
+
+ test("a report and a source summary render from their lane entries; a removed one goes", () => {
+ seedLaneEntry(
+ a,
+ T0,
+ "reports",
+ "2026-11-02-vector-stores",
+ { title: "Vector stores", report_date: "2026-11-02" },
+ "# Vector stores\n\n## Findings\n\n- SQLite is enough (cites: [[notes/sqlite|SQLite notes]])\n",
+ );
+ seedLaneEntry(
+ a,
+ T0 + 1,
+ "sources",
+ "src-paper-abc123",
+ { source_path: "Papers/hlc.pdf", updated_at: "2026-11-03T10:00:00Z" },
+ "Hybrid logical clocks order events across machines.",
+ );
+ render();
+ expect(page("reports/2026-11-02-vector-stores.md")).toBe(
+ [
+ "<!-- open-second-brain-view store=<store> page=reports/2026-11-02-vector-stores.md -->",
+ "",
+ "# Vector stores",
+ "",
+ "Research report of 2026-11-02.",
+ "",
+ "## Findings",
+ "",
+ "- SQLite is enough (cites: SQLite notes)",
+ "",
+ ].join("\n"),
+ );
+ expect(page("sources/src-paper-abc123.md")).toBe(
+ [
+ "<!-- open-second-brain-view store=<store> page=sources/src-paper-abc123.md -->",
+ "",
+ "# Source: Papers/hlc.pdf",
+ "",
+ "Summary of a source, updated 2026-11-03.",
+ "",
+ "Hybrid logical clocks order events across machines.",
+ "",
+ ].join("\n"),
+ );
+ clock += 1000;
+ seedLaneRemove(a, clock, "reports", "2026-11-02-vector-stores");
+ render(1);
+ expect(existsSync(view("reports"))).toBe(false);
+ });
+});
diff --git a/tests/core/view/vault-guard.test.ts b/tests/core/view/vault-guard.test.ts
index 2a846da7..4dc67bfa 100644
--- a/tests/core/view/vault-guard.test.ts
+++ b/tests/core/view/vault-guard.test.ts
@@ -118,6 +118,17 @@ describe("isInViewFolder", () => {
expect(isInViewFolder("", "about-me (conflicted copy 2026-01-02).md")).toBe(true);
expect(isInViewFolder("", "decisions.sync-conflict-20260102-101010-ABCDEFG.md")).toBe(true);
expect(isInViewFolder("", "history/2026-W01.md")).toBe(true);
+ expect(isInViewFolder("", "topics/2026-11-02-store/topic.md")).toBe(true);
+ expect(isInViewFolder("", "reports/2026-11-02-x.md")).toBe(true);
+ expect(
+ isInViewFolder("", "topics/2026-11-02-store/topic.sync-conflict-20260102-101010-ABCDEFG.md"),
+ ).toBe(true);
+ expect(isInViewFolder("", "topics", { container: true })).toBe(true);
+ expect(isInViewFolder("", "topics/2026-11-02-store", { container: true })).toBe(true);
+ // The user's own notes in folders of the same names stay theirs.
+ expect(isInViewFolder("", "topics/plan.md")).toBe(false);
+ expect(isInViewFolder("", "reports/Q3/summary.md")).toBe(false);
+ expect(isInViewFolder("", "topics")).toBe(false);
expect(isInViewFolder("", ".o2b-view-x-new.md")).toBe(true);
expect(isInViewFolder("", "Notes/about-me.md")).toBe(false);
expect(isInViewFolder("", "about-me-notes.md")).toBe(false);
diff --git a/tests/core/view/view-render.test.ts b/tests/core/view/view-render.test.ts
index 4c2ae2af..294a080a 100644
--- a/tests/core/view/view-render.test.ts
+++ b/tests/core/view/view-render.test.ts
@@ -4,13 +4,17 @@
* before the replacement, conflict copies are ingested and removed, and
* only changed bytes are written. Human edits become human records.
*/
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import * as fs from "node:fs";
import {
existsSync,
+ lstatSync,
+ mkdirSync,
readdirSync,
readFileSync,
renameSync,
statSync,
+ symlinkSync,
unlinkSync,
utimesSync,
writeFileSync,
@@ -270,6 +274,83 @@ describe("render protocol", () => {
expect(readdirSync(m.view("dev-a")).filter((n) => n.startsWith("."))).toEqual([]);
});
+ test("a conflict copy a sync tool writes again while the page renders is kept and ingested later", () => {
+ const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
+ writeFileSync(copy, read().replace("- Rule B.", "- Rule B, older from the phone."));
+ const newer = join(m.view("dev-a"), "..", "newer.tmp");
+ writeFileSync(newer, read().replace("- Rule B.", "- Rule B, newer from the phone."));
+ const realOpen = fs.openSync;
+ const realRename = fs.renameSync;
+ let delivered = false;
+ // The sync tool writes the copy again right after the writer first
+ // touches it: once a read has closed the file (Windows refuses to
+ // replace a file that is open), or right after a rename took it.
+ const deliver = (): void => {
+ if (delivered) return;
+ delivered = true;
+ realRename(newer, copy);
+ };
+ const realClose = fs.closeSync;
+ let copyFd: number | null = null;
+ const open = spyOn(fs, "openSync").mockImplementation(((p: fs.PathLike, ...rest: never[]) => {
+ const fd = (realOpen as (...args: unknown[]) => number)(p, ...rest);
+ if (String(p) === copy) copyFd = fd;
+ return fd;
+ }) as typeof fs.openSync);
+ const close = spyOn(fs, "closeSync").mockImplementation(((fd: number) => {
+ realClose(fd);
+ if (fd === copyFd) {
+ copyFd = null;
+ deliver();
+ }
+ }) as typeof fs.closeSync);
+ const rename = spyOn(fs, "renameSync").mockImplementation(((p: fs.PathLike, q: fs.PathLike) => {
+ realRename(p, q);
+ if (String(p) === copy) deliver();
+ }) as typeof fs.renameSync);
+ try {
+ pass();
+ } finally {
+ open.mockRestore();
+ close.mockRestore();
+ rename.mockRestore();
+ }
+ expect(delivered).toBe(true);
+ pass();
+ expect(
+ humanPreferenceSets().map((s) => (s["fields"] as Record<string, unknown>)["principle"]),
+ ).toContain("Rule B, newer from the phone.");
+ expect(existsSync(copy)).toBe(false);
+ });
+
+ test("a folder named like a conflict copy of a live page is refused and stays where it is", () => {
+ const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
+ mkdirSync(copy);
+ writeFileSync(join(copy, "mine.txt"), "mine\n");
+ const report = pass();
+ expect(readFileSync(join(copy, "mine.txt"), "utf8")).toBe("mine\n");
+ expect(readdirSync(m.view("dev-a")).filter((n) => n.startsWith("."))).toEqual([]);
+ if (report.status !== "rendered") throw new Error(report.status);
+ expect(report.pages.find((p) => p.page === "about-me.md")?.status).toBe("refused");
+ });
+
+ test.skipIf(process.platform === "win32")(
+ "a symbolic link named like a conflict copy of a live page is never read or moved",
+ () => {
+ const outside = join(m.view("dev-a"), "..", "outside-secret.md");
+ writeFileSync(outside, read().replace("- Rule B.", "- Rule B, outside secret."));
+ const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
+ symlinkSync(outside, copy);
+ pass();
+ pass();
+ expect(lstatSync(copy).isSymbolicLink()).toBe(true);
+ expect(readdirSync(m.view("dev-a")).filter((n) => n.startsWith("."))).toEqual([]);
+ expect(JSON.stringify(allRecords(catchUp(a, now)).map((r) => r.body))).not.toContain(
+ "outside secret",
+ );
+ },
+ );
+
test("a private racing edit lands in private, and no shared file holds its text", () => {
// A new rule makes the pass render, so the edit races the replace.
seedPreference(a, clock + 10, "pref-c", {
diff --git a/tests/docs/topics-guide.test.ts b/tests/docs/topics-guide.test.ts
new file mode 100644
index 00000000..3b1c1fce
--- /dev/null
+++ b/tests/docs/topics-guide.test.ts
@@ -0,0 +1,131 @@
+/**
+ * The topics guide (`docs/topics.md`, task 3.6) runs as written: every
+ * command of its `doc-test: topics` block goes through the real CLI in a
+ * child process, in order, against a fresh store with no vault, and must
+ * exit 0. `<topic>` is replaced by the id `create` printed and `<record>`
+ * by the record id the last command printed, as the guide says. Every verb
+ * the guide lists by name in the block is run; the test also checks that
+ * the page `show` printed has the rename and the decision.
+ */
+import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
+
+setDefaultTimeout(CLI_SPAWN_BUDGET_MS * 6);
+
+const REPO_ROOT = resolve(import.meta.dir, "..", "..");
+const GUIDE = join(REPO_ROOT, "docs", "topics.md");
+const CLI_ENTRY = join(REPO_ROOT, "src", "cli", "main.ts");
+
+let parent: string | undefined;
+afterEach(() => {
+ if (parent !== undefined)
+ rmSync(parent, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+ parent = undefined;
+});
+
+/** The command lines of the guide's `doc-test: topics` block. */
+function guideCommands(): string[] {
+ const lines = readFileSync(GUIDE, "utf8").split(/\r?\n/);
+ const at = lines.findIndex((l) => l.trim() === "<!-- doc-test: topics -->");
+ expect(at).toBeGreaterThan(-1);
+ expect(lines[at + 1]!.trim().startsWith("```")).toBe(true);
+ const out: string[] = [];
+ for (let i = at + 2; !lines[i]!.trim().startsWith("```"); i++) {
+ if (lines[i]!.trim() !== "") out.push(lines[i]!.trim());
+ }
+ return out;
+}
+
+/** Split a command line into words, honouring double quotes. */
+function words(line: string): string[] {
+ return [...line.matchAll(/"([^"]*)"|(\S+)/g)].map((m) => m[1] ?? m[2]!);
+}
+
+function run(
+ args: ReadonlyArray<string>,
+ env: Record<string, string>,
+): { code: number; out: string } {
+ const child = Bun.spawnSync([process.execPath, CLI_ENTRY, ...args], {
+ env: { ...process.env, ...env },
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ timeout: CLI_SPAWN_BUDGET_MS,
+ });
+ return {
+ code: child.exitCode ?? -1,
+ out: `${child.stdout.toString()}${child.stderr.toString()}`,
+ };
+}
+
+describe("docs/topics.md", () => {
+ test("the guide names the one verb that does not write as you", () => {
+ const guide = readFileSync(GUIDE, "utf8");
+ const sentence = guide
+ .split("\n")
+ .find((l) => l.includes("Commands you run (`o2b topic ...`)"));
+ expect(sentence).toBeDefined();
+ expect(sentence).toContain("except `o2b topic record`");
+ expect(sentence).toContain("`--as-human`");
+ });
+
+ test("the listed CLI verbs run as written", () => {
+ parent = mkdtempSync(join(tmpdir(), "o2b-topics-guide-"));
+ const config = join(parent, "config.yaml");
+ writeFileSync(config, "");
+ const env = {
+ OPEN_SECOND_BRAIN_CONFIG: config,
+ OPEN_SECOND_BRAIN_STORE_ROOT: join(parent, "store"),
+ O2B_DEVICE_ID: "laptop",
+ HOME: join(parent, "home"),
+ XDG_STATE_HOME: join(parent, "state"),
+ LOCALAPPDATA: join(parent, "state"),
+ VAULT_DIR: "",
+ };
+ expect(run(["store", "init"], env).code).toBe(0);
+ let topic: string | null = null;
+ let record: string | null = null;
+ let page = "";
+ const verbs = new Set<string>();
+ for (const line of guideCommands()) {
+ const argv = words(line);
+ expect(argv.slice(0, 2)).toEqual(["o2b", "topic"]);
+ verbs.add(argv[2]!);
+ const args = argv
+ .slice(1)
+ .map((w) => (w === "<topic>" ? topic! : w === "<record>" ? record! : w));
+ const result = run(args, env);
+ expect({ line, code: result.code, out: result.code === 0 ? "" : result.out }).toEqual({
+ line,
+ code: 0,
+ out: "",
+ });
+ const printed = /: topic ([0-9A-Z]{26}), record ([0-9A-Z]{26})/.exec(result.out);
+ if (printed !== null) {
+ topic ??= printed[1]!;
+ record = printed[2]!;
+ }
+ if (argv[2] === "show") page = result.out;
+ }
+ expect([...verbs].toSorted()).toEqual(
+ [
+ "archive",
+ "create",
+ "list",
+ "record",
+ "rename",
+ "review",
+ "show",
+ "status",
+ "undo",
+ ].toSorted(),
+ );
+ expect(page).toContain("# Brain store and topics");
+ expect(page).toContain("- Keep one shard per device and month");
+ expect(page).toContain("Status: Waiting");
+ });
+});
diff --git a/tests/helpers/tool-probe-catalogue.ts b/tests/helpers/tool-probe-catalogue.ts
index df4f2e2c..49667bda 100644
--- a/tests/helpers/tool-probe-catalogue.ts
+++ b/tests/helpers/tool-probe-catalogue.ts
@@ -303,8 +303,10 @@ export const REASONS_REACHING_OWNER_CONTENT: ReadonlySet<string> = new Set([REAS
// record ids from the index, and store records carry no `owner:`.
// 109 -> 110, the shared-settings change: brain_settings, one ownerless
// recipe - settings are one value for every machine, never owner-tagged.
-export const PROBE_ENTRY_COUNT = 110;
-export const PROBE_RECIPE_COUNT = 253;
+// 110 -> 111, topics: brain_topic, one ownerless recipe - topics are store
+// records with no `owner:`, and their privacy is the partition's.
+export const PROBE_ENTRY_COUNT = 111;
+export const PROBE_RECIPE_COUNT = 254;
export const PROBE_TWO_SIDED_COUNT = 32;
/**
@@ -541,6 +543,12 @@ export const NON_CONTENT: ReadonlyArray<ProbeEntry> = [
name: "brain_settings",
calls: one({ action: "list" }, REASON.ownerlessLane),
},
+ {
+ // Topics carry no owner: a topic is a store record family whose privacy
+ // is its partition, withheld whole below local reach.
+ name: "brain_topic",
+ calls: one({ action: "list" }, REASON.ownerlessLane),
+ },
{
name: "brain_claims",
calls: [
diff --git a/tests/mcp/brain-query-as-of.test.ts b/tests/mcp/brain-query-as-of.test.ts
index e80dbbd2..a4f6b655 100644
--- a/tests/mcp/brain-query-as-of.test.ts
+++ b/tests/mcp/brain-query-as-of.test.ts
@@ -2,7 +2,7 @@
* `brain_query` point-in-time recall + honest time-filter descriptions
* (what-the-index-already-knew, task J).
*
- * `queryByTopic` has accepted a `now` option since C5 and the MCP handler
+ * `queryByRuleTopic` has accepted a `now` option since C5 and the MCP handler
* passed `{ showExpired }` and dropped it, so an agent could ask to SEE
* lapsed memories but never to ask what the brain held at an instant.
*
diff --git a/tests/mcp/brain-tools-parity.test.ts b/tests/mcp/brain-tools-parity.test.ts
index d8961dc8..005a3046 100644
--- a/tests/mcp/brain-tools-parity.test.ts
+++ b/tests/mcp/brain-tools-parity.test.ts
@@ -195,6 +195,7 @@ const FROZEN_BRAIN_TOOL_NAMES = [
"brain_tension",
"brain_tiers",
"brain_token_impact",
+ "brain_topic",
"brain_trigger",
"brain_truth",
"brain_tune",
@@ -321,6 +322,7 @@ const FROZEN_BRAIN_WRITE_TOOL_NAMES = [
"brain_tension",
"brain_tiers",
"brain_token_impact",
+ "brain_topic",
"brain_trigger",
"brain_truth",
"brain_tune",
diff --git a/tests/mcp/brain-topic.test.ts b/tests/mcp/brain-topic.test.ts
new file mode 100644
index 00000000..d7fd5f86
--- /dev/null
+++ b/tests/mcp/brain-topic.test.ts
@@ -0,0 +1,653 @@
+/**
+ * `brain_topic` and `osb://topic/{id}` (task 3.5): the contract of the
+ * topic tool. A request is stored as a human topic record and an agent's
+ * own entry as an agent one; reads answer at the caller's reach, so a
+ * caller below local reach never sees a private topic, not in a list, a
+ * show, a resource read, nor through the refusal of a write that names
+ * it. The server runs a remote call inside the withheld scope; these
+ * tests call the handler inside the same scope.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
+import { withPrivateWithheld } from "../../src/core/store/caller-reach.ts";
+import { readPartition } from "../../src/core/store/state-digest.ts";
+import { appendRecord } from "../../src/core/store/appender.ts";
+import { openStore } from "../../src/core/store/store-open.ts";
+import { runTopicAction } from "../../src/core/topics/actions.ts";
+import { TOPIC_TOOLS } from "../../src/mcp/brain/topic-tools.ts";
+import { MCPError } from "../../src/mcp/protocol.ts";
+import { readResource } from "../../src/mcp/resources.ts";
+import type { ServerContext } from "../../src/mcp/tool-contract.ts";
+import { makeStoreEnv, type StoreEnv } from "../core/store/fixtures/store-env.ts";
+
+let env: StoreEnv;
+let ctx: ServerContext;
+beforeEach(() => {
+ env = makeStoreEnv("o2b-brain-topic-", { legacyTree: false });
+ ctx = { vault: env.vault, configPath: env.configPath, repoRoot: null, agentName: "claude" };
+});
+afterEach(() => env.cleanup());
+
+const handler = TOPIC_TOOLS[0]!.handler;
+type Answer = Record<string, unknown>;
+const local = async (args: Answer): Promise<Answer> => (await handler(ctx, args)) as Answer;
+const remote = async (args: Answer): Promise<Answer> =>
+ (await withPrivateWithheld(true, () =>
+ handler({ ...ctx, reach: TRANSPORT_REACH.remote }, args),
+ )) as Answer;
+
+const ids = (answer: Answer) => (answer["topics"] as Answer[]).map((t) => t["id"]);
+
+async function refusal(call: Promise<unknown>): Promise<MCPError> {
+ try {
+ await call;
+ } catch (err) {
+ if (err instanceof MCPError) return err;
+ throw err;
+ }
+ throw new Error("expected a refusal");
+}
+
+function topicRecords(partition: "shared" | "private") {
+ return readPartition(join(env.storeRoot, partition))
+ .filter((s) => s.stream === "topics")
+ .flatMap((s) => s.records);
+}
+
+function completionKinds(partition: "shared" | "private"): string[] {
+ return topicRecords(partition)
+ .map((r) => r.kind)
+ .filter((k) => k === "milestone-done" || k === "question-resolved");
+}
+
+function decisionTexts(partition: "shared" | "private"): unknown[] {
+ return topicRecords(partition)
+ .filter((r) => r.kind === "decision")
+ .map((r) => r.body["text"]);
+}
+
+describe("brain_topic", () => {
+ test("an agent's writes carry agent authority unless it names human, and show renders them", async () => {
+ const made = await local({
+ action: "create",
+ title: "Brain store",
+ scope: "project:o2b",
+ goal: "Move data out",
+ });
+ const topic = made["topic"] as string;
+ await local({
+ action: "record",
+ topic,
+ kind: "log-entry",
+ fields: { text: "Sync conflicts on pinned.md", class: "blocker" },
+ });
+ await local({ action: "status", topic, status: "waiting", authority: "human" });
+ expect(topicRecords("shared").map((r) => [r.kind, r.body["authority"], r.agent])).toEqual([
+ ["topic-create", "agent", "claude"],
+ ["log-entry", "agent", "claude"],
+ ["topic-status", "human", "claude"],
+ ]);
+ const shown = await local({ action: "show", topic });
+ expect((shown["topic"] as Answer)["status"]).toBe("waiting");
+ expect(shown["page"]).toContain("Status: Waiting");
+ expect(shown["page"]).toContain(", blocker: Sync conflicts on pinned.md");
+ expect(
+ readResource({ vault: env.vault, reach: TRANSPORT_REACH.local }, `osb://topic/${topic}`).text,
+ ).toBe(shown["page"] as string);
+ });
+
+ test("undo takes back the record it names", async () => {
+ const topic = (await local({ action: "create", title: "Docs", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const added = await local({
+ action: "record",
+ topic,
+ kind: "decision",
+ fields: { text: "Write the guide" },
+ });
+ await local({ action: "undo", record: (added["records"] as string[])[0] });
+ const shown = await local({ action: "show", topic });
+ expect((shown["topic"] as Answer)["items"]).toEqual([]);
+ });
+
+ test("below local reach a private topic does not exist: not listed, not shown, not writable", async () => {
+ const shared = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const personal = (await local({ action: "create", title: "Health", scope: "personal" }))[
+ "topic"
+ ] as string;
+ expect(topicRecords("private").map((r) => r.topic)).toEqual([personal]);
+ expect(ids(await local({ action: "list" })).toSorted()).toEqual([shared, personal].toSorted());
+ expect(ids(await remote({ action: "list" }))).toEqual([shared]);
+
+ const missing = "01KA0000000000000000000000";
+ const absent = await refusal(remote({ action: "show", topic: missing }));
+ const hidden = await refusal(remote({ action: "show", topic: personal }));
+ expect(hidden.message).toBe(absent.message.replace(missing, personal));
+ const write = await refusal(remote({ action: "rename", topic: personal, title: "Renamed" }));
+ expect(write.message).toContain(`no topic with id ${personal}`);
+ expect(topicRecords("private").map((r) => r.kind)).toEqual(["topic-create"]);
+
+ // Both answer as a rule-topic slug with nothing recorded under it.
+ const resource = (uri: string) => {
+ let text: string;
+ try {
+ text = readResource({ vault: env.vault, reach: TRANSPORT_REACH.remote }, uri).text;
+ } catch (err) {
+ text = (err as Error).message;
+ }
+ return text.replaceAll(personal, "<id>").replaceAll(missing, "<id>");
+ };
+ expect(resource(`osb://topic/${personal}`)).toBe(resource(`osb://topic/${missing}`));
+ expect(
+ readResource({ vault: env.vault, reach: TRANSPORT_REACH.local }, `osb://topic/${personal}`)
+ .text,
+ ).toContain("# Health");
+ });
+
+ test("a merge on request resolves the merged topic to its target", async () => {
+ const a = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const b = (await local({ action: "create", title: "Store again", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ await local({ action: "merge", topic: b, into: a });
+ const shown = await local({ action: "show", topic: b });
+ expect((shown["topic"] as Answer)["id"]).toBe(a);
+ expect(shown["page"]).toContain("- Merged from: Store again");
+ });
+
+ test("a malformed event is refused with nothing written", async () => {
+ const topic = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const err = await refusal(
+ local({
+ action: "record",
+ topic,
+ kind: "log-entry",
+ fields: { text: "x", class: "chatter" },
+ }),
+ );
+ expect(err.message).toContain("class must be one of");
+ expect(topicRecords("shared")).toHaveLength(1);
+ });
+});
+
+describe("brain_topic authority and item checks", () => {
+ test("the user's goal stays when an agent later sets one, which shows as its open question", async () => {
+ const topic = runTopicAction(
+ { action: "create", title: "Store", scope: "project:o2b", goal: "Ship phase 3" },
+ { configPath: env.configPath, humanRequest: true },
+ )["topic"] as string;
+ await local({ action: "goal", topic, goal: "Ship everything at once" });
+ const shown = await local({ action: "show", topic });
+ expect((shown["topic"] as Answer)["goal"]).toBe("Ship phase 3");
+ expect(shown["page"]).toContain("- Goal proposed by claude: Ship everything at once");
+ });
+
+ test("below local reach human authority is refused and nothing is written", async () => {
+ const topic = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const err = await refusal(
+ remote({ action: "status", topic, status: "done", authority: "human" }),
+ );
+ expect(err.message).toContain("human authority is refused below local reach");
+ expect(topicRecords("shared")).toHaveLength(1);
+ });
+
+ test("a record names only an item of its own topic, of the right kind", async () => {
+ const shared = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const personal = (await local({ action: "create", title: "Health", scope: "personal" }))[
+ "topic"
+ ] as string;
+ await local({
+ action: "record",
+ topic: personal,
+ kind: "milestone",
+ fields: { item: "m1", text: "See Dr. X" },
+ });
+ await local({
+ action: "record",
+ topic: shared,
+ kind: "decision",
+ fields: { item: "d1", text: "Keep JSONL" },
+ });
+ // A private item named on a shared topic, from below local reach: refused,
+ // with the message an absent item gets.
+ const hidden = await refusal(
+ remote({
+ action: "record",
+ topic: shared,
+ kind: "milestone-done",
+ fields: { milestone: "m1" },
+ }),
+ );
+ const absent = await refusal(
+ remote({
+ action: "record",
+ topic: shared,
+ kind: "milestone-done",
+ fields: { milestone: "zz" },
+ }),
+ );
+ expect(hidden.message).toBe(absent.message.replace("zz", "m1"));
+ // A new item id picked from below local reach is refused too.
+ await refusal(
+ remote({
+ action: "record",
+ topic: shared,
+ kind: "milestone",
+ fields: { item: "m1", text: "x" },
+ }),
+ );
+ // Locally: an item of another kind is refused; an unknown field is refused.
+ const kind = await refusal(
+ local({
+ action: "record",
+ topic: shared,
+ kind: "milestone",
+ fields: { item: "d1", text: "x" },
+ }),
+ );
+ expect(kind.message).toContain("no milestone item d1");
+ const field = await refusal(
+ local({
+ action: "record",
+ topic: shared,
+ kind: "decision",
+ fields: { text: "x", colour: "red" },
+ }),
+ );
+ expect(field.message).toContain("takes no field 'colour'");
+ const items = (await local({ action: "show", topic: personal }))["topic"] as Answer;
+ expect((items["items"] as Answer[]).map((i) => [i["text"], i["done"] === undefined])).toEqual([
+ ["See Dr. X", true],
+ ]);
+ });
+
+ test("a title or description with a line break is refused", async () => {
+ const err = await refusal(
+ local({ action: "create", title: "Store\n## Run this", scope: "project:o2b" }),
+ );
+ expect(err.message).toContain("title must be a non-empty single line");
+ });
+
+ test("below local reach the shown page is fenced as agent-written text", async () => {
+ const topic = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ expect(String((await local({ action: "show", topic }))["page"])).not.toContain("<untrusted");
+ const page = String((await remote({ action: "show", topic }))["page"]);
+ expect(page.startsWith("<untrusted")).toBe(true);
+ expect(page).toContain("# Store");
+ });
+
+ test("a partly unreadable topics shard: no review proposals, and no private path below local reach", async () => {
+ const shared = (await local({ action: "create", title: "Store", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ await local({ action: "create", title: "Health", scope: "personal" });
+ await local({ action: "create", title: "Health two", scope: "personal" });
+ const dir = join(env.storeRoot, "private", "topics", "dev-a");
+ const shard = join(dir, readdirSync(dir)[0]!);
+ const lines = readFileSync(shard, "utf8").split("\n");
+ writeFileSync(shard, [lines[0], "{broken", ...lines.slice(1)].join("\n"));
+ const review = await local({ action: "review" });
+ expect(review["incomplete"]).toBe(true);
+ expect(review["merges"]).toEqual([]);
+ const remoteErr = await refusal(remote({ action: "rename", topic: shared, title: "Renamed" }));
+ expect(remoteErr.message).not.toContain("private");
+ const localErr = await refusal(local({ action: "rename", topic: shared, title: "Renamed" }));
+ expect(localErr.message).toContain("private/topics/dev-a/");
+ });
+
+ test("below local reach a shared topic record that carries a private region is withheld", async () => {
+ appendRecord(openStore({ root: env.storeRoot, device: "dev-a" }), {
+ partition: "shared",
+ stream: "topics",
+ kind: "topic-create",
+ agent: "legacy",
+ topic: "01KA0000000000000000000000",
+ body: { authority: "agent", title: "Visit <private>Dr. X</private>", scope: "project:o2b" },
+ });
+ expect(((await local({ action: "list" }))["topics"] as Answer[]).length).toBe(1);
+ expect(((await remote({ action: "list" }))["topics"] as Answer[]).length).toBe(0);
+ });
+});
+
+describe("brain_topic review fixes", () => {
+ test("below local reach every topic text of list and show is fenced", async () => {
+ const topic = (
+ await local({ action: "create", title: "Store", scope: "project:o2b", goal: "Ship" })
+ )["topic"] as string;
+ await local({ action: "record", topic, kind: "decision", fields: { text: "Keep JSONL" } });
+ const head = ((await remote({ action: "list" }))["topics"] as Answer[])[0]!;
+ expect(String(head["title"]).startsWith("<untrusted")).toBe(true);
+ expect(String(head["goal"]).startsWith("<untrusted")).toBe(true);
+ expect(String(head["scope"]).startsWith("<untrusted")).toBe(true);
+ expect(String(head["scope"])).toContain("project:o2b");
+ const detail = (await remote({ action: "show", topic }))["topic"] as Answer;
+ expect(String(detail["scope"]).startsWith("<untrusted")).toBe(true);
+ const item = (detail["items"] as Answer[])[0]!;
+ expect(String(item["text"]).startsWith("<untrusted")).toBe(true);
+ const plain = ((await local({ action: "list" }))["topics"] as Answer[])[0]!;
+ expect(plain["title"]).toBe("Store");
+ expect(plain["scope"]).toBe("project:o2b");
+ });
+
+ test("after a merge an item id two topics share is ambiguous until its owner is named", async () => {
+ const a = (await local({ action: "create", title: "A", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const b = (await local({ action: "create", title: "B", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ await local({
+ action: "record",
+ topic: a,
+ kind: "milestone",
+ fields: { item: "m1", text: "A one" },
+ });
+ await local({
+ action: "record",
+ topic: b,
+ kind: "milestone",
+ fields: { item: "m1", text: "B one" },
+ });
+ await local({ action: "merge", topic: a, into: b });
+ const err = await refusal(
+ local({
+ action: "record",
+ topic: b,
+ kind: "milestone-done",
+ fields: { milestone: "m1" },
+ authority: "human",
+ }),
+ );
+ expect(err.message).toContain("on more than one merged topic");
+ await local({
+ action: "record",
+ topic: b,
+ kind: "milestone-done",
+ fields: { milestone: "m1" },
+ owner: a,
+ authority: "human",
+ });
+ const items = ((await local({ action: "show", topic: b }))["topic"] as Answer)[
+ "items"
+ ] as Answer[];
+ expect(items.map((i) => [i["text"], i["done"] !== undefined]).toSorted()).toEqual([
+ ["A one", true],
+ ["B one", false],
+ ]);
+ });
+
+ test("a split from a topic moves an item of a topic merged into it; an unknown item is refused", async () => {
+ const made = async (title: string) =>
+ (await local({ action: "create", title, scope: "project:o2b" }))["topic"] as string;
+ const a = await made("A");
+ const b = await made("B");
+ const c = await made("C");
+ await local({
+ action: "record",
+ topic: a,
+ kind: "decision",
+ fields: { item: "d1", text: "From A" },
+ });
+ await local({ action: "merge", topic: a, into: b, authority: "human" });
+ const answer = await local({ action: "split", topic: b, into: c, items: ["d1"] });
+ expect(answer["topic"]).toBe(b);
+ const texts = async (topic: string) =>
+ (((await local({ action: "show", topic }))["topic"] as Answer)["items"] as Answer[]).map(
+ (i) => i["text"],
+ );
+ expect(await texts(c)).toEqual(["From A"]);
+ expect(await texts(b)).toEqual([]);
+ const err = await refusal(local({ action: "split", topic: b, into: c, items: ["d9"] }));
+ expect(err.message).toContain("no item d9");
+ });
+
+ test("editing a private item of a shared topic keeps the new text private", async () => {
+ const topic = (await local({ action: "create", title: "Shared", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ await local({
+ action: "record",
+ topic,
+ kind: "decision",
+ fields: { item: "d1", text: "Private first" },
+ private: true,
+ });
+ await local({
+ action: "record",
+ topic,
+ kind: "decision",
+ fields: { item: "d1", text: "Private reworded" },
+ });
+ expect(decisionTexts("shared")).toEqual([]);
+ expect(decisionTexts("private")).toEqual(["Private first", "Private reworded"]);
+ });
+
+ test("a private or removed flag that is not a boolean is refused and nothing is written", async () => {
+ const err = await refusal(
+ local({ action: "create", title: "Clinic", scope: "project:o2b", private: "true" }),
+ );
+ expect(err.message).toContain("'private' must be a boolean");
+ expect(topicRecords("shared")).toEqual([]);
+ expect(topicRecords("private")).toEqual([]);
+ const made = async (title: string) =>
+ (await local({ action: "create", title, scope: "project:o2b" }))["topic"] as string;
+ const a = await made("A");
+ const b = await made("B");
+ const linked = await refusal(local({ action: "link", topic: a, to: b, removed: "true" }));
+ expect(linked.message).toContain("'removed' must be a boolean");
+ expect(topicRecords("shared").map((r) => r.kind)).toEqual(["topic-create", "topic-create"]);
+ });
+
+ test("a split of a merged topic's item together with a record of the named topic is written", async () => {
+ const made = async (title: string) =>
+ (await local({ action: "create", title, scope: "project:o2b" }))["topic"] as string;
+ const a = await made("A");
+ const b = await made("B");
+ const c = await made("C");
+ await local({
+ action: "record",
+ topic: a,
+ kind: "decision",
+ fields: { item: "d1", text: "From A" },
+ });
+ await local({ action: "merge", topic: a, into: b });
+ const record = "01KA0000000000000000000009";
+ await local({ action: "split", topic: b, into: c, items: ["d1"], records: [record] });
+ const shown = ((await local({ action: "show", topic: c }))["topic"] as Answer)[
+ "items"
+ ] as Answer[];
+ expect(shown.map((i) => i["text"])).toEqual(["From A"]);
+ const splits = topicRecords("shared").filter((r) => r.kind === "split");
+ expect(
+ splits.map((r) => [r.topic, r.body["items"] ?? null, r.body["records"] ?? null]),
+ ).toEqual([
+ [b, null, [record]],
+ [a, ["d1"], null],
+ ]);
+ });
+
+ test("after a private resolution or completion, a later one without the flag stays private", async () => {
+ const topic = (await local({ action: "create", title: "Shared", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const record = (kind: string, fields: Answer, extra: Answer = {}) =>
+ local({ action: "record", topic, kind, fields, authority: "human", ...extra });
+ await record("open-question", { item: "q1", text: "Shared question" });
+ await record("milestone", { item: "m1", text: "Shared step" });
+ await record(
+ "question-resolved",
+ { question: "q1", answer: "Private answer" },
+ { private: true },
+ );
+ await record(
+ "milestone-done",
+ { milestone: "m1", evidence: "Private proof" },
+ { private: true },
+ );
+ await record("question-resolved", { question: "q1", answer: "Revised answer" });
+ await record("milestone-done", { milestone: "m1", evidence: "Revised proof" });
+ expect(completionKinds("shared")).toEqual([]);
+ expect(completionKinds("private")).toEqual([
+ "question-resolved",
+ "milestone-done",
+ "question-resolved",
+ "milestone-done",
+ ]);
+ });
+
+ test("a removed item's id can be recorded again on its topic", async () => {
+ const topic = (await local({ action: "create", title: "Reuse", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const record = (fields: Answer) => local({ action: "record", topic, kind: "decision", fields });
+ await record({ item: "d1", text: "First take" });
+ await record({ item: "d1", removed: true });
+ await record({ item: "d1", text: "Second take" });
+ const items = ((await local({ action: "show", topic }))["topic"] as Answer)[
+ "items"
+ ] as Answer[];
+ expect(items.map((i) => [i["id"], i["text"]])).toEqual([["d1", "Second take"]]);
+ });
+
+ test("completing or resolving an item that has a private record writes to private", async () => {
+ const topic = (await local({ action: "create", title: "Shared", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const record = (kind: string, fields: Answer, extra: Answer = {}) =>
+ local({ action: "record", topic, kind, fields, ...extra });
+ await record("milestone", { item: "m1", text: "Private step" }, { private: true });
+ await record("open-question", { item: "q1", text: "Private question" }, { private: true });
+ await record("milestone-done", { milestone: "m1" }, { authority: "human" });
+ await record("question-resolved", { question: "q1", answer: "Yes" }, { authority: "human" });
+ expect(completionKinds("shared")).toEqual([]);
+ expect(completionKinds("private")).toEqual(["milestone-done", "question-resolved"]);
+ });
+
+ test("an item id a split moved away is not taken again for a new item of the old topic", async () => {
+ const made = async (title: string) =>
+ (await local({ action: "create", title, scope: "project:o2b" }))["topic"] as string;
+ const a = await made("A");
+ const b = await made("B");
+ await local({
+ action: "record",
+ topic: a,
+ kind: "milestone",
+ fields: { item: "m1", text: "Moved one" },
+ });
+ await local({ action: "split", topic: a, into: b, items: ["m1"] });
+ const err = await refusal(
+ local({
+ action: "record",
+ topic: a,
+ kind: "milestone",
+ fields: { item: "m1", text: "New one" },
+ }),
+ );
+ expect(err.message).toContain("moved to another topic");
+ const items = ((await local({ action: "show", topic: b }))["topic"] as Answer)[
+ "items"
+ ] as Answer[];
+ expect(items.map((i) => i["text"])).toEqual(["Moved one"]);
+ });
+
+ test("undoing the undo of a private topic's create stays in the private partition", async () => {
+ const made = await local({ action: "create", title: "Health", scope: "personal" });
+ const undo = await local({ action: "undo", record: (made["records"] as string[])[0] });
+ await local({ action: "undo", record: (undo["records"] as string[])[0] });
+ expect(topicRecords("shared")).toEqual([]);
+ expect(topicRecords("private").map((r) => r.kind)).toEqual(["topic-create", "undo", "undo"]);
+ expect(ids(await local({ action: "list" }))).toEqual([made["topic"]]);
+ });
+
+ test("an owner that holds no such item, or is not this topic or one merged into it, is refused", async () => {
+ const a = (await local({ action: "create", title: "A", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const b = (await local({ action: "create", title: "B", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ const c = (await local({ action: "create", title: "C", scope: "project:o2b" }))[
+ "topic"
+ ] as string;
+ await local({
+ action: "record",
+ topic: a,
+ kind: "decision",
+ fields: { item: "shared1", text: "From A" },
+ });
+ await local({
+ action: "record",
+ topic: b,
+ kind: "decision",
+ fields: { item: "shared1", text: "From B" },
+ });
+ await local({ action: "merge", topic: b, into: a });
+ const before = topicRecords("shared").length;
+ const typo = await refusal(
+ local({
+ action: "record",
+ topic: a,
+ kind: "decision",
+ owner: "01KA0000000000000000000000",
+ fields: { item: "shared1", text: "edited" },
+ }),
+ );
+ expect(typo.message).toContain("is not this topic or a topic merged into it");
+ const unrelated = await refusal(
+ local({
+ action: "record",
+ topic: a,
+ kind: "decision",
+ owner: c,
+ fields: { item: "shared1", text: "edited" },
+ }),
+ );
+ expect(unrelated.message).toBe(typo.message.replace("01KA0000000000000000000000", c));
+ const missing = await refusal(
+ local({
+ action: "record",
+ topic: a,
+ kind: "decision",
+ owner: b,
+ fields: { item: "other", text: "edited" },
+ }),
+ );
+ expect(missing.message).toContain(`no decision item other on topic ${a}`);
+ const noItem = await refusal(
+ local({ action: "record", topic: a, kind: "decision", owner: c, fields: { text: "new" } }),
+ );
+ expect(noItem.message).toBe(unrelated.message);
+ expect(topicRecords("shared")).toHaveLength(before);
+ const items = ((await local({ action: "show", topic: a }))["topic"] as Answer)[
+ "items"
+ ] as Answer[];
+ expect(items.map((i) => i["text"]).toSorted()).toEqual(["From A", "From B"]);
+ });
+
+ test("undoing the undo of a topic's create brings the topic back", async () => {
+ const made = await local({ action: "create", title: "Store", scope: "project:o2b" });
+ const topic = made["topic"] as string;
+ const undo = await local({ action: "undo", record: (made["records"] as string[])[0] });
+ expect(((await local({ action: "list" }))["topics"] as Answer[]).length).toBe(0);
+ await local({ action: "undo", record: (undo["records"] as string[])[0] });
+ expect(((await local({ action: "list" }))["topics"] as Answer[]).map((t) => t["id"])).toEqual([
+ topic,
+ ]);
+ });
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index b22e3a1f..f3e7a304 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -377,6 +377,8 @@ describe("tool listing", () => {
"brain_retrieval_plan",
// Durable token-impact ledger (context-pack-economics-observability).
"brain_token_impact",
+ // Topics (brain-store-and-topics phase 3).
+ "brain_topic",
].toSorted(),
);
// Explicit grep: legacy writable tools are no longer advertised.
diff --git a/tests/mcp/resources.test.ts b/tests/mcp/resources.test.ts
index 3bb6a59e..ede8e64f 100644
--- a/tests/mcp/resources.test.ts
+++ b/tests/mcp/resources.test.ts
@@ -135,7 +135,8 @@ describe("MCP resources — capabilities and discovery", () => {
"osb://backlinks/{id}",
"osb://log/{date}",
"osb://preference/{id}",
- "osb://topic/{slug}",
+ "osb://rule-topic/{slug}",
+ "osb://topic/{id}",
]);
});
});
@@ -295,7 +296,25 @@ Body.
});
});
-describe("MCP resources — read osb://topic/{slug}", () => {
+describe("MCP resources — read osb://rule-topic/{slug} and its alias osb://topic/{slug}", () => {
+ test("a rule-topic slug shaped like a topic id still answers through the old name", async () => {
+ const slug = "01KA0000000000000000000000";
+ writeSignal(vault, {
+ topic: slug,
+ signal: "positive",
+ agent: "claude",
+ principle: "Keep ids short",
+ created_at: "2026-05-14T10:00:00Z",
+ date: "2026-05-14",
+ slug: "ulid-like",
+ scope: "writing",
+ });
+ const server = makeServer();
+ await initialize(server);
+ const r = await read(server, `osb://topic/${slug}`);
+ expect(r.result.contents[0].text).toContain(`# Brain topic: ${slug}`);
+ });
+
test("returns a markdown summary of signals + current preference", async () => {
writeSignal(vault, {
topic: "tidy",
@@ -318,8 +337,11 @@ describe("MCP resources — read osb://topic/{slug}", () => {
});
const server = makeServer();
await initialize(server);
- const r = await read(server, "osb://topic/tidy");
+ const r = await read(server, "osb://rule-topic/tidy");
const text = r.result.contents[0].text as string;
+ // The old name answers the same body for one minor version.
+ const alias = await read(server, "osb://topic/tidy");
+ expect(alias.result.contents[0].text).toBe(text);
expect(text).toContain("# Brain topic: tidy");
expect(text).toContain("pref-tidy");
expect(text).toContain("sig-2026-05-14-first");
diff --git a/tests/mcp/surface-error-codes.test.ts b/tests/mcp/surface-error-codes.test.ts
index 3dee2844..2c6c0e4c 100644
--- a/tests/mcp/surface-error-codes.test.ts
+++ b/tests/mcp/surface-error-codes.test.ts
@@ -515,6 +515,11 @@ describe("every operation-dispatching tool answers unknown_operation", () => {
{ action: BOGUS },
"brain_settings: 'action' must be one of get, list, set, unset",
],
+ [
+ "brain_topic",
+ { action: BOGUS },
+ "brain_topic: 'action' must be one of list, show, review, create, rename, status, goal, assign, unassign, merge, split, link, archive, undo, record",
+ ],
[
"brain_note_lifecycle",
{ action: BOGUS },
diff --git a/tests/mcp/topic-page-write-refusal.test.ts b/tests/mcp/topic-page-write-refusal.test.ts
new file mode 100644
index 00000000..3bdc6612
--- /dev/null
+++ b/tests/mcp/topic-page-write-refusal.test.ts
@@ -0,0 +1,95 @@
+/**
+ * A note tool never writes a topic page (task 3.3, spec `topics` "Direct
+ * page write is refused"): `brain_create_note` and `brain_update_note`
+ * on a path inside the view's topics folder are refused with a message
+ * that names the topic event tool to use instead, and the page on disk
+ * keeps its bytes. A page beside the view folder is written as before.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { VIEW_TARGET_ENV } from "../../src/core/view/constants.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+
+const ENV_KEYS = [VIEW_TARGET_ENV, "VAULT_AGENT_NAME", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"];
+const saved = new Map<string, string | undefined>();
+let tmp: string;
+let vault: string;
+let configPath: string;
+
+const PAGE_REL = "Views/brain/topics/2026-11-02-brain-store/topic.md";
+const PAGE_BYTES =
+ "<!-- open-second-brain-view store=x page=topics/2026-11-02-brain-store/topic.md -->\n\n# Brain store\n";
+
+beforeEach(() => {
+ for (const key of ENV_KEYS) saved.set(key, process.env[key]);
+ tmp = mkdtempSync(join(tmpdir(), "o2b-topic-page-refusal-"));
+ vault = join(tmp, "vault");
+ for (const dir of ["preferences", "retired", "inbox", "log"]) {
+ mkdirSync(join(vault, "Brain", dir), { recursive: true });
+ }
+ writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema_version: 1\n");
+ mkdirSync(join(vault, "Views", "brain", "topics", "2026-11-02-brain-store"), { recursive: true });
+ writeFileSync(join(vault, PAGE_REL), PAGE_BYTES);
+ configPath = join(tmp, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+ delete process.env["VAULT_AGENT_NAME"];
+ delete process.env["VAULT_DIR"];
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+ process.env[VIEW_TARGET_ENV] = join(vault, "Views", "brain");
+});
+
+afterEach(() => {
+ for (const [key, value] of saved) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<string> {
+ const server = new MCPServer({ vault, configPath });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "topic-refusal-test", version: "0" },
+ },
+ });
+ await server.handleRequest({ jsonrpc: JSONRPC_VERSION, method: "notifications/initialized" });
+ const out = await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 2,
+ method: "tools/call",
+ params: { name, arguments: args },
+ });
+ return JSON.stringify(out);
+}
+
+describe("note tools on a topic page", () => {
+ test("brain_create_note refuses a page in the topics folder and names brain_topic", async () => {
+ const rel = "Views/brain/topics/2026-11-03-new/topic.md";
+ const text = await callTool("brain_create_note", { path: rel, content: "# Forged" });
+ expect(text).toContain("human view folder");
+ expect(text).toContain("brain_topic");
+ expect(existsSync(join(vault, rel))).toBe(false);
+ });
+
+ test("brain_update_note refuses the existing topic page and leaves its bytes", async () => {
+ const text = await callTool("brain_update_note", { path: PAGE_REL, content: "# Forged goal" });
+ expect(text).toContain("human view folder");
+ expect(text).toContain("brain_topic");
+ expect(readFileSync(join(vault, PAGE_REL), "utf8")).toBe(PAGE_BYTES);
+ });
+
+ test("a note beside the view folder is written as before", async () => {
+ await callTool("brain_create_note", { path: "Views/topics-notes.md", content: "mine" });
+ expect(readFileSync(join(vault, "Views", "topics-notes.md"), "utf8")).toContain("mine");
+ });
+});