@furongjun1999/dsh-memory 0.9.22 → 0.9.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/CHANGELOG.en.md +404 -0
  2. package/CHANGELOG.md +45 -0
  3. package/README.en.md +240 -0
  4. package/README.md +3 -1
  5. package/docs/README.md +2 -0
  6. package/docs/en/README.md +190 -0
  7. package/docs/en/TRANSLATION.md +78 -0
  8. package/docs/en/TRANSLATION_MANIFEST.json +170 -0
  9. package/docs/en/TRANSLATION_REPORT.md +11 -0
  10. package/docs/en/dev/README.md +10 -0
  11. package/docs/en/dev/coding-testing.md +72 -0
  12. package/docs/en/dev/switch-matrix.md +10 -0
  13. package/docs/en/glossary.md +97 -0
  14. package/docs/en/harnesses/claude.md +100 -0
  15. package/docs/en/harnesses/codebuddy.md +93 -0
  16. package/docs/en/harnesses/codex.md +88 -0
  17. package/docs/en/harnesses/dsh.md +84 -0
  18. package/docs/en/harnesses/zcode.md +42 -0
  19. package/docs/en/mdcg/ccg.md +32 -0
  20. package/docs/en/mdcg/generated-docs.md +20 -0
  21. package/docs/en/mdcg/guardrail-charter.md +170 -0
  22. package/docs/en/mdcg/mcp-tool-names.md +43 -0
  23. package/docs/en/mdcg/multi-harness.md +43 -0
  24. package/docs/en/mdcg/recall-metadata.md +30 -0
  25. package/docs/en/mdcg/world-model-endpoint.md +379 -0
  26. package/docs/en/mdcg/write-aliases.md +130 -0
  27. package/docs/en/ops/README.md +11 -0
  28. package/docs/en/ops/environment-known-issues.md +244 -0
  29. package/docs/en/ops/install.md +72 -0
  30. package/docs/en/ops/operations-troubleshooting.md +86 -0
  31. package/docs/en/ops/permissions-review.md +79 -0
  32. package/docs/en/ops/release-governance.md +49 -0
  33. package/docs/en/ops/tool-name-migration.md +30 -0
  34. package/docs/en/ops/ui-install-troubleshooting.md +53 -0
  35. package/docs/en/standards/ai-coding-standard-checklist.md +71 -0
  36. package/docs/en/standards/ai-coding-standard-lingshu.md +47 -0
  37. package/docs/en/standards/ai-coding-standard.md +185 -0
  38. package/docs/en/ui/minimal.md +62 -0
  39. package/docs/mdcg/cogmap_ops.md +15 -15
  40. package/lib/hooks.d.ts +22 -0
  41. package/lib/hooks.js +124 -32
  42. package/lib/index.js +19 -3
  43. package/lib/lib/console_web.mjs +30 -3
  44. package/lib/lib/hook_audit.d.ts +3 -2
  45. package/lib/lib/hook_audit.js +14 -4
  46. package/lib/lib/mdcg_client.d.ts +5 -2
  47. package/lib/lib/mdcg_client.js +8 -4
  48. package/lib/lib/prompt_safety.d.ts +24 -0
  49. package/lib/lib/prompt_safety.js +77 -1
  50. package/lib/lib/token_store.js +5 -2
  51. package/lib/tools.js +5 -3
  52. package/md_cg/fsutil.py +80 -25
  53. package/md_cg/mcp_server.py +5761 -5557
  54. package/md_cg/mdcg.py +570 -73
  55. package/md_cg/mdcos.py +36 -11
  56. package/md_cg/nodefile.py +147 -23
  57. package/md_cg/op_table.py +14 -4
  58. package/md_cg/reconcile.py +9 -11
  59. package/md_cg/rollback.py +16 -1
  60. package/md_cg/scrub.py +94 -14
  61. package/md_cg/security.py +4 -2
  62. package/md_cg/test_cond_term_fold.py +183 -0
  63. package/md_cg/test_cond_terms_colon.py +348 -0
  64. package/md_cg/test_generation_guard.py +63 -42
  65. package/md_cg/test_issue362_neg_condition.py +44 -7
  66. package/md_cg/test_issue39_utf8_stdio.py +3 -3
  67. package/md_cg/test_issue444_scrub_evidence_plaintext.py +14 -8
  68. package/md_cg/test_issue677_flush_batch_io.py +139 -0
  69. package/md_cg/test_issue677_info_fast.py +82 -0
  70. package/md_cg/test_issue677_remember_dedupe.py +106 -0
  71. package/md_cg/test_issue712_tokens_sessions_read.py +199 -0
  72. package/md_cg/test_issue722_strict_conditions.py +96 -0
  73. package/md_cg/test_issue730_narrowing_audit.py +121 -0
  74. package/md_cg/test_issue733_verify_override.py +193 -0
  75. package/md_cg/test_issue733_verify_override_and_overwrite_inherit.py +315 -0
  76. package/md_cg/test_issue740_filelock_fd_leak.py +218 -0
  77. package/md_cg/test_issue741_content_hash_same_source.py +158 -0
  78. package/md_cg/test_issue747_slot_contradiction.py +125 -0
  79. package/md_cg/test_issue754_nested_root_guard.py +197 -0
  80. package/md_cg/test_issue757_index_hash_compare.py +85 -0
  81. package/md_cg/test_issue758_disk_hash_single.py +67 -0
  82. package/md_cg/test_issue759_twophase_hash.py +67 -0
  83. package/md_cg/test_n204_n205_n226_n227_n228_n229_exit_gates.py +545 -542
  84. package/md_cg/test_n209_verify_write_face_gates.py +5 -2
  85. package/md_cg/test_neg_condition_hits.py +336 -333
  86. package/md_cg/test_scrub_source_line_false_positive.py +64 -0
  87. package/md_cg/test_twophase.py +286 -286
  88. package/md_cg/tokens.py +55 -7
  89. package/md_cg/twophase.py +15 -6
  90. package/md_cg/writepipe.py +35 -3
  91. package/package.json +137 -134
  92. package/scripts/workspace_index.py +2 -0
  93. package/src/hooks.ts +139 -33
  94. package/src/index.ts +19 -3
  95. package/src/lib/console_web.mjs +30 -3
  96. package/src/lib/hook_audit.ts +15 -5
  97. package/src/lib/mdcg_client.ts +8 -4
  98. package/src/lib/prompt_safety.ts +73 -1
  99. package/src/lib/token_store.ts +5 -2
  100. package/src/tools.ts +5 -3
  101. package/ui/minimal/integrity.json +2 -2
  102. package/ui/minimal/payload/lib/lib/console_web.mjs +30 -3
  103. package/ui/minimal/payload/src/lib/console_web.mjs +30 -3
@@ -0,0 +1,379 @@
1
+ > **Languages:** [中文](../../mdcg/世界模型功能端_使用与运维_v1.0.md) · English
2
+
3
+ # World model feature endpoint · Usage and operations guide (v1.0)
4
+
5
+ > **This page answers one thing: once the semantic spatiotemporal graph's 'state layer' is live, how you record events, how you query them, where the switches are, how to re-run the readings, and where the boundaries are.**
6
+ > Basis: `docs/plans/语义时空图补全_世界模型功能端_设计_v0.1.md` (six acceptance points) and `docs/秤_记忆系统评测规范_v2.1.md` §5.1 (ledger completeness criterion).
7
+ > User positioning (2026-10-06): '0.7.4 lays the foundation for the world model, that is, the semantic spatiotemporal graph.' This page corresponds to batch P3 (write-side entry + ledger completeness probe + usage documentation).
8
+
9
+ ---
10
+
11
+ ## 1. In one sentence
12
+
13
+ **Events are the source, slots are the projection, queries go through stg**:
14
+
15
+ ```
16
+ 记账(写口) 台账(源) 投影(物化视图,查询时现算) 查询面
17
+ cg(op=state_event) → <root>/_state_events.jsonl → md_cg/state_slots.py → stg(op=state_chain)
18
+ (MCP 面) append-only、不截断 (只读台账、不落盘、不缓存) (默认关)
19
+ ↘ CLI:python -m md_cg.state_slots
20
+ ```
21
+
22
+ The four surfaces each have a single source of truth and do not copy each other: the write entry does only permission/normalization/persisting (`md_cg/mcp_server.py`), the ledger only appends (`md_cg/state_events.py`), the projection only replays (`md_cg/state_slots.py`), and the query surface only handles the switch and response shaping (`md_cg/stg.py`).
23
+
24
+ ---
25
+
26
+ ## 2. Where the ledger (source) is and what it looks like
27
+
28
+ | Item | Content |
29
+ |---|---|
30
+ | Location | `_state_events.jsonl` under the library root (same level as `_recent.jsonl`, `_write_2pc.jsonl`) |
31
+ | Nature | **append-only**: append only, no read-modify-write, no truncation (the rolling window surface `_recent.jsonl` cannot serve as a first-class record, hence this separate ledger) |
32
+ | One line per record | `{t, subject, slot, old, new, kind, seq, evidence, actor}` |
33
+ | Five `kind` values | `migration` / `retraction` / `enablement` / `acquisition` / `replacement`; **uncategorized (None) is legal** |
34
+ | Retraction semantics | `old` has a value and `new` is empty = the value is voided with no new value; enablement = old empty, new has a value; migration/replacement = both have values |
35
+ | Bad lines | Tolerance ≠ silence: count on skip + bounded sample + stderr warning (`state_events.BAD_ROWS` is readable) |
36
+ | Multi-process | Cross-process file lock (`FileLock`); a crash leaves no half-written file (flush+fsync) |
37
+
38
+ **Recording does not judge semantics**: `kind` is only a retrieval-surface label and does not enter the criterion; the disambiguation marker (`not_fact`) for utterances that are 'not facts' (jokes / meta level / recalling a retelling) is **not in this batch** (see §8 boundaries).
39
+
40
+ ---
41
+
42
+ ## 3. Write: MCP recording entry `cg(op=state_event)`
43
+
44
+ ### Usage
45
+
46
+ ```
47
+ cg(op="state_event", subject="鲸娘", slot="住所",
48
+ old="别墅", new="小屋", kind="migration", seq=1108, evidence="r1108")
49
+ ```
50
+
51
+ | Parameter | Required | Description |
52
+ |---|---|---|
53
+ | `subject` | Yes | Event subject (whose state); empty after stripping whitespace is an error |
54
+ | `slot` | Yes | Event slot (which state); same as above |
55
+ | `old` / `new` | At least one | Value before/after the change; **both empty is illegal** (an empty event is meaningless). Retraction = leave `new` empty |
56
+ | `kind` | No | One of five values; missing/empty string/whitespace only → normalized to 'uncategorized' (None); other values raise an error |
57
+ | `seq` | No | Turn or sequence number (used to point back to the corpus location) |
58
+ | `evidence` | No | Provenance (short evidence / turn number / file path all work, for later lookback) |
59
+
60
+ Response body: `{"ok": true, "event": {…落盘记录…}}` (`event` is the line that was appended and persisted).
61
+
62
+ ### Failure basis (fail-closed, nothing swallowed)
63
+
64
+ | Situation | Result |
65
+ |---|---|
66
+ | Missing/empty `subject`, missing/empty `slot` | `ValueError` (naming which one is missing) |
67
+ | Both `old` and `new` empty | `ValueError` |
68
+ | Illegal `kind` value | `ValueError` (listing the five allowed values) |
69
+
70
+ All of the above are `ValueError`s **raised as-is** (not wrapped errors), so the client can handle them as ordinary errors — **on failure nothing is persisted**.
71
+
72
+ ---
73
+
74
+ ## 4. Read: projection and query
75
+
76
+ ### 1. Query surface `stg(op=state_chain)` (off by default, see §5)
77
+
78
+ ```
79
+ stg(op="state_chain", subject="鲸娘", slot="住所", include_retired=true)
80
+ ```
81
+
82
+ The response body follows stg's existing basis: `count` (total condition hits, before truncation) / `items` (the first limit items) /
83
+ `kept` / `truncated`. Unit fields:
84
+
85
+ | Field | Semantics |
86
+ |---|---|
87
+ | `value` | Current value (null after a retraction, until the next event with a value brings it back) |
88
+ | `state` | `active` / `retired` (**retirement does not delete**; default queries drop retired items, `include_retired=true` makes them visible) |
89
+ | `t_from` / `t_to`, `seq_from` / `seq_to` | Effective interval and sequence numbers: `*_from` = the last event that produced the current value; `*_to` = the next event that supersedes it (not superseded = null = still effective / not yet closed) |
90
+ | `tier` | Source tier (passed through from the top-level `tier` of the ledger row; absent = `unspecified`, **never fabricated**) |
91
+ | `history` | All events of that slot, the original seven fields (`t/seq/old/new/kind/evidence/actor`); when `history=false` the key is omitted |
92
+ | `alternatives` / `blindspots` | Structure present, **always empty lists** (the verdict criterion is deferred, see §8) |
93
+ | `event_count` | Number of events in that slot |
94
+
95
+ **The projection is a materialized view, not a second source of truth**: it is computed from the ledger at query time and neither persisted nor cached — append one line to the ledger and the next query result changes.
96
+
97
+ ### 2. CLI manual entry (`md_cg.state_slots`, **always available**)
98
+
99
+ ```
100
+ python -X utf8 -m md_cg.state_slots --status
101
+ python -X utf8 -m md_cg.state_slots --subject 鲸娘 [--slot 住所] [--include-retired] [--no-history]
102
+ ```
103
+
104
+ The data root is taken from `MDCG_ROOT` (defaulting to `datapath.mdcg_root()`). This CLI is **independent** of the `MDCG_STG_STATE`
105
+ switch — that switch governs the MCP read surface; the CLI is a read-only manual inspection entry (it changes no state).
106
+
107
+ ---
108
+
109
+ ## 5. Switches
110
+
111
+ | Switch | Default | What it governs |
112
+ |---|---|---|
113
+ | `MDCG_STG_STATE` | **off** | The MCP query surface `stg(op=state_chain)`; the off arm returns `{"error": "disabled", "hint": …}` (**not an exception** — 'not enabled' and 'no hit' must be distinguishable); same discipline as `MDCG_STG_INDEX`/`MDCG_STG_QUALIFY` |
114
+ | (no switch) | — | The `cg(op=state_event)` recording entry is **always available** (subject to the permission gate, see §6); the `md_cg.state_slots` CLI is **always available** |
115
+
116
+ ---
117
+
118
+ ## 6. Authorization basis (zero new words against the existing token surface)
119
+
120
+ - **`state_event` goes through the `write` word mapping**: the op-scope gate of the `cg` surface decides by `write` —
121
+ any role whose `ops_allow` whitelist contains `write` (or a designer token using `"*"`) may record events;
122
+ guest/read-only tokens are still rejected. The token surface **introduces no new op word** (role whitelists and derived narrowing surfaces are unchanged).
123
+ - **`actor` always comes from the token** (request parameters have no effect): the persisted `actor` is always the token identity (in no-token form it is
124
+ `"system"`) — clients must not rewrite attribution (following the repository's existing anti-forgery basis).
125
+ - **Double insurance on the write gate**: the ledger is an append-only file on the direct-disk surface that **bypasses the library-layer node write gate**, so the recording entry
126
+ additionally makes `require_write("internal")` explicit — `can_write` × `theory_ok` × clearance three-state each take effect
127
+ (read-only tokens, failed version-layer validation, and clearance below internal are all rejected without persisting).
128
+
129
+ ---
130
+
131
+ ## 7. Readings and re-runs: probes + guards
132
+
133
+ ### 1. Ledger completeness probe (Scale 5.1 criterion)
134
+
135
+ ```
136
+ python -X utf8 scripts/probe_c_ledger_integrity.py \
137
+ --events %TEMP%/state_events.jsonl --expect-slots 住所,房贷,名字 \
138
+ [--out %TEMP%/probe_c_out]
139
+ ```
140
+
141
+ | Reading | Criterion |
142
+ |---|---|
143
+ | ① Event coverage gap rate | Among the `--expect-slots` list, the share of slots with 'no records at all in the ledger' (both numerator and denominator are printed) |
144
+ | ② No-ledger distinguishability rate | For 'slots with no records' plus a fixed synthetic non-existent slot, query `state_chain`: the pass ratio of `count==0 且 items==[]` (**no fabrication, no reverse inference**) |
145
+ | ③ Transition-history queryability rate | Among slots with records, the ratio where the total history count returned by `state_chain` (`include_retired=True`, `history=True`) == the ledger's record count for that slot |
146
+
147
+ Characteristics (hard requirements): reads input only; isolates a temp root (copies `--events` to that root's
148
+ `_state_events.jsonl`) — **zero writes to the memory library**; `--out` must land outside the repository (fail-closed);
149
+ **determinism** (two runs on the same input produce byte-identical stdout and `--out` artifacts);
150
+ the last stdout line is a `PROBE_C_LEDGER_JSON {...}` summary (machine-readable), and with `--out` it also writes
151
+ `rates.json` + `probe_c_slots.jsonl`.
152
+
153
+ ### 2. Write-side guard
154
+
155
+ ```
156
+ python -X utf8 -m md_cg.test_state_event_op # 全链/双闸/防伪造/归一/校验/回归
157
+ python -X utf8 -m md_cg.test_state_event_op --mutate # 定点变异自证(每条机制必须能被断言钉红)
158
+ ```
159
+
160
+ ---
161
+
162
+ ## 8. Boundaries (as they are)
163
+
164
+ - The verdict criterion for `alternatives` (concurrent undecided values) / `blindspots` (declared gaps) is **deferred**: in this batch the structure is present and
165
+ the lists are always empty, with **no invented filling**.
166
+ - The **disambiguation marker** (`not_fact` etc.) for utterances that are 'not facts' (jokes / meta level / recalling a retelling) is not in this batch
167
+ (the P1 event row has no such signal).
168
+ - The probe only measures **ledger-surface** distinguishability; **generator-level 'answering without a ledger' is not measured** — that requires readings from the generator side and is deferred.
169
+ - Slots are matched **exactly by label** (slot names equal), with no synonym merging or fuzzy matching.
170
+ - `state_chain` has no `time_axis` semantics: ledger event rows have only the recording timestamp `t`, no second axis (**no fabrication**);
171
+ for axis semantics use the `stg` timeline/relation/anchors.
172
+ - One library = one ledger: cross-library / multi-tenant merging is not covered here.
173
+
174
+ ---
175
+
176
+ ## 9. Retirement discipline: node lifecycle `archived` (excluded from retrieval by default)
177
+
178
+ > The landing page for the 'retirement discipline' criterion of Scale v2.1 §5.2. **First distinguish the two kinds of 'retirement'** (same name, different things):
179
+
180
+ | Which one | Field / parameter | Who manages it |
181
+ |---|---|---|
182
+ | The survival state of a ledger **slot unit** (§4) | Projection unit `state` = `active`/`retired`, query parameter `include_retired` | `md_cg/state_slots.py` (computed at query time) |
183
+ | The archive state of a **node** (md memory entry) (this section) | frontmatter / index `lifecycle_state` = `archived` | `md_cg/lifecycle.py` state machine + read-surface exclusion |
184
+
185
+ ### 1. Semantics (fixed in writing, comparable level by level)
186
+
187
+ | `lifecycle_state` | Default read/injection surfaces (retrieval surface · stg surface · session continuation pack in full) | Notes |
188
+ |---|---|---|
189
+ | `active` (**missing key or illegal value is the same**) | Participates | fail-open: existing nodes need zero migration and are not wrongly dropped |
190
+ | `converged` | Participates | **down-weighting axis** (isomorphic aggregation finalized), not retirement |
191
+ | `demoted` | Participates | **down-weighting axis** (weakened), not retirement |
192
+ | `archived` | **Excluded by default** | Retirement does not delete: the node file remains and can be explicitly restored |
193
+
194
+ ### 2. Criterion and landing points (single criterion, three consumer surfaces)
195
+
196
+ - Single criterion: `lifecycle.is_archived(e)` (`md_cg/lifecycle.py`) ≡ `state_of(e) == "archived"`;
197
+ all consumption points reference it together and do not each write their own version.
198
+ - Consumer point ① (**cg retrieval surface**): `MdCGOS._candidates` (`md_cg/mdcos.py`) — the **retrieval-type** cg read ops
199
+ (`route` / `read`'s retrieval branch and its `budget_tokens` budget-recall branch / `search` / `search_rrf` and the
200
+ lexical·bucket·entity·graph·chain·temporal paths they contain) all go through this one candidate pool;
201
+ `MdCGSecure._candidates` stacks read visibility on top of it via `super()`, with the same criterion.
202
+ Note: cg's read ops do not all go through the candidate pool — see consumer point ③ (the session continuation surface holds its own data-fetch surface).
203
+ - Consumer point ② (**stg scan surface**): `stg._scan_one` (`md_cg/stg.py`, the single per-item implementation of `_scan`)
204
+ — the candidate surfaces of the `timeline` / `anchors` / `consistency` ops are covered at the same point, and the indexed subset
205
+ (`MDCG_STG_INDEX=1`) and the full traversal branches agree bit for bit. `relation` reads an explicit id directly and
206
+ `state_chain` goes through the ledger, so neither passes through the candidate surface (not constrained by this section).
207
+ - Consumer point ③ (**session continuation injection surface**): the **four data-fetch segments** of `MdCGOS.session_recall` (`md_cg/mdcos.py`)
208
+ — session notes `_session_notes`, active goals `goals`, task ledger `tasks`, and unresolved questions `unresolved` (`goals`/`tasks` look up the index by id via `_retired_by_id` and then hand it to the same
209
+ criterion). `cg(op=session, action=recall)` holds its own data-fetch surface (bypassing `_candidates`); it assembles node
210
+ content into a 'continuation pack' returned to the caller / injected into the context (= the injection surface), so it is likewise subject to this criterion. The two ledger segments take the **full window**
211
+ (`_LEDGER_WINDOW`), filter, and then truncate to `_PACK_ROWS=5` rows, so retirement exclusion does not make the
212
+ pack 'short'; `tasks.active_total/done_total` accordingly take the **post-exclusion** full-window counts (self-consistent with the list
213
+ source). The `recent` segment is an event window (not nodes), and `self_state` is a read-only snapshot card, so neither involves retirement.
214
+ (An independent review measured two rounds on 2026-10-06: before the wiring, archived note summaries, unresolved-question bodies, active goals,
215
+ and task cards all still came back through that op; they are now pinned by guards R1.12/R1.13/R3.5/R3.6/R4.6.)
216
+
217
+ ### 3. Unrestricted surfaces (the other half of 'retirement does not delete')
218
+
219
+ - `cg.get(node_id)` direct read and the `cg(op=audit)` evidence audit view: **still reachable** while archived;
220
+ - The engineering ledger surface (`goal` / `task`) and statistical surfaces (`health` / `whoami` / conformance): read the index directly,
221
+ not constrained by this section;
222
+ - **Lifecycle recovery**: the library-layer entry `MdCG.set_state(node, "archived"→"active")`
223
+ (`md_cg/mdcg.py:3900` → `lifecycle.set_state`, following the legal transition table, one level at a time with no level skipping); after recovery
224
+ the read surface / continuation surface see it again. **The MCP tool surface has no standalone lifecycle entry** (`mcp_server.py` contains the strings `set_state` / `lifecycle` nowhere)
225
+ — 'explicit recovery' is a library-layer call surface.
226
+ - Difference from `op=restore` (easy to confuse, stated explicitly): `op=restore` is `action=restore` of `op=forget`
227
+ → `restore` (`md_cg/mdcos.py:4350`) = putting back a node that has been **forgotten** (soft-deleted into `trash/`);
228
+ it is the **deletion axis** and unrelated to the lifecycle state machine; moreover, on restore `lifecycle_state` is judged as a new node (`active`),
229
+ and an `active→archived` level skip is rejected ⇒ **no pass-through (lands as `active`)** (existing behavior, unchanged this round).
230
+
231
+ ### 4. Re-run readings
232
+
233
+ ```
234
+ python -X utf8 scripts/probe_d_retirement_discipline.py # 《秤》v2.1 §5.2 探针
235
+ python -X utf8 -m md_cg.test_lifecycle_retire_leak # 守卫 R1–R4
236
+ ```
237
+
238
+ | Reading (`PROBE_D_JSON`) | Criterion | Target (surface counts; ratios in parentheses) |
239
+ |---|---|---|
240
+ | ① Retirement leak rate | After retirement, the number of surfaces where v2 still appears on verification surfaces (read surface search∪recall, spatiotemporal surface timeline∪anchors) / number of surfaces | `0/2` (0.0) |
241
+ | ② Update adoption rate | After v2 is written, the number of visible surfaces / number of surfaces (guards against the reverse defect of 'filtering everything indiscriminately') | `2/2` (1.0) |
242
+ | ③ Old-fact residue rate | After the retirement step, the number of surfaces where v1 is still visible / number of surfaces (no collateral exclusion) | `2/2` (1.0) |
243
+ | ④ Invalidity misjudgment falsification rate | Number of retired nodes wrongly set to falsified/rejected / number of retired nodes (retirement ≠ falsification) | `0/1` (0.0) |
244
+
245
+ (The probe's human-readable line prints exactly the **surface count** 'n/denominator (target m)'; the table above uses the same unit, and the ratios are converted values.)
246
+
247
+ Probe characteristics: isolated temp root (zero writes to the live library), pure stdlib, no randomness/no timestamps,
248
+ `--out` must land outside the repository (fail-closed), last line `PROBE_D_JSON {...}`, **two runs produce byte-identical stdout**.
249
+
250
+ ### 5. Boundaries (as they are)
251
+
252
+ - Only `archived` is excluded. To make `converged`/`demoted` not participate, use the existing other dimensions
253
+ (`role` / `view` / `layer` / `session` / `validity`) — they must not be merged into the retirement criterion.
254
+ - Ledger unit retirement (§4 `retired`) and node retirement (this section's `archived`) are **independent of each other with no linkage**.
255
+ - **Surface criterion (fixed, for future wiring to classify accordingly)**: the **default read/injection surface** = the caller gives a query/intent/session view,
256
+ **the library chooses the node set**, and the result goes directly back to the caller or into the injected context ⇒ it must consume `is_archived`;
257
+ a **targeted/management/statistical surface** = the caller gives an **explicit node selection key** (`node_id` / `subject:*` label / prefix /
258
+ layer / state), or the surface itself is diagnostic·statistical·write ⇒ direct read, not constrained by this section.
259
+ - Wired consumer surfaces (3 places, 4 sub-surfaces): retrieval surface `_candidates`, stg surface `_scan_one`, and the session continuation injection surface
260
+ `session_recall`'s **all four data-fetch segments** (notes `_session_notes` + active goals + task ledger +
261
+ unresolved questions; the latter two go through `_retired_by_id` by id criterion) (§2).
262
+ - **Enumerated but classified as 'targeted/management/statistical surfaces' (unrestricted, declared item by item)**: `cg.get` direct read, `op=audit`
263
+ evidence audit, the **explicit management query surface of the engineering ledger** (`cg(op=goal, action=list)` / `cg(op=task,
264
+ action=list)` — direct ledger reads; archived items are still listed while archived, pinned by guard R1.13c),
265
+ `health`/`whoami`/`_role_counts`/`_sensitivity_counts`/`conformance`/`census`/`insight`
266
+ statistics, `review_records` review records, `export`/`evidence` export and evidence surfaces, `crosscheck`/
267
+ `ghostref`/`consistency` diagnostic surfaces, `backfill*`/`writelimit`/`freshness`/`forgetting`
268
+ maintenance write surfaces, `mreview/govern` governance surfaces, and the white-box KB tool surface.
269
+ **Do not read this together with consumer point ③**: for the same goal/task ledger, **the injection surface (continuation pack) excludes archived,
270
+ while the management query surface reads directly** — this is not a contradiction but a division of labor between the two sides of the criterion (guards pin both sides at once: R1.13b exclusion,
271
+ R1.13c direct read).
272
+ One representative surface that **returns content and whose set is chosen by the library** must be named honestly: `identity.profile`
273
+ (`md_cg/identity.py:310`, which self-selects by the `subject:<id>` label and returns anchor body excerpts) — measured archived
274
+ anchors are still returned (evidence: the `anchors[0].content` returned by `identity.profile` contains the archived node's body marker);
275
+ under the criterion above it is a **targeted surface** (`subject_id` is an explicit selection key, same family as `cg.get`), so **it was not wired this round**
276
+ (its file is outside the surfaces this round is allowed to change).
277
+ - **Surface wiring state (landed in the 2026-10-06 user-ruling batch — the disposition of the original four 'known uncovered surfaces')**:
278
+ - **Base class `MdCG.search` → wired** (the candidate condition in `md_cg/mdcg.py` adds the `lifecycle.is_archived`
279
+ criterion): the default retrieval surface of plain `MdCG` instances (white-box KB / offline scripts / tests) now uses the same criterion as the production path
280
+ (guard R5, including the 'converged down-weighting axis is not wrongly dropped' control).
281
+ - **Causal chain / graph surface `chain.adjacency` → wired** (a new `skip_archived=True` default parameter):
282
+ outgoing edges of retired nodes do not enter the table at all, and edges pointing at retired targets are truncated — `cg(op=causal, action=chain)`,
283
+ `predict.*` and other read/prediction surfaces no longer diffuse into archived (guards R6.0/R6.1/R6.4, including the measured leg where archiving happens
284
+ while the cache is already warm). **Maintenance surfaces explicitly bypass**: `scrub` decontamination sampling passes
285
+ `skip_archived=False` to take the full table (guards R6.2/R6.3 pin the bypass — the division of surface criteria:
286
+ default read/injection surfaces must consume it, maintenance/management surfaces read directly).
287
+ - **Cache invalidation hook (the delivery gap evidenced in this batch)**: a state transition changes the `is_archived` reading,
288
+ while the `chain` adjacency cache was previously **not invalidated** after `set_state` (probe evidence: after archiving,
289
+ `causal_chain` still contained the target) — now `lifecycle.set_state` calls `chain.invalidate_cache` at the same point as the write-disk point
290
+ (lazy import; `invalidate_cache` swallows its own exceptions and does not block progress).
291
+ - **Structural/topological surface `subgraph.children_index` / `parents_index` → ruled not wired**
292
+ (the caller gives explicit parent/child ids and the return is an id mapping with no body, so it is a targeted/structural surface and reads directly) —
293
+ guards R7.0/R7.1 **pin the ruling**: after a child node retires the mapping still exists; if anyone 'conveniently wires it' in the future,
294
+ R7.1 turning red is the reminder to change the ruling first.
295
+ - **rust retrieval kernel → wired** (`rust/src/store.rs`): `Entry` gains a
296
+ `lifecycle_state` field (the key name shares its source with Python's `lifecycle.STATE_FIELD`), and
297
+ `candidates()` excludes `archived` (missing key/illegal = active, fail-open; converged/
298
+ demoted still participate) — crate unit tests `archived_entries_excluded_from_candidates`
299
+ and `lifecycle_state_parsed_from_index_json` pin both; consistency of the two sides continues to be watched by the
300
+ `rank_parity` gate leg (the evaluation corpus has no archived, so it is a bit-for-bit zero shift).
301
+ - Cross-process consistency: the criterion reads only **this process's index entries** (`lifecycle_state` is synced with
302
+ migrations by `lifecycle._sync_index` and recorded in `_index_log`); within the window where another process has just archived but this process's index
303
+ has not reloaded, readings may lag (same source as the existing persist basis of `lifecycle.set_state`).
304
+
305
+ ---
306
+
307
+ ## 10. Multi-subject state tracking (core capability and resident read view)
308
+
309
+ > User positioning 2026-10-06: 'This feature can be resident, maintaining state tracking for other characters; this should be
310
+ > a core function of the semantic spatiotemporal graph.'
311
+
312
+ **Capability statement**: state tracking (multi-subject · five-element events · slot projection) is the **core function** of the semantic spatiotemporal graph —
313
+ `subject` is parameterized to any subject (character/institution/me), the ledger (`_state_events.jsonl`) is the sole source of truth,
314
+ and everything else is projection/view.
315
+
316
+ **Resident form** = **a read-only view computed at query time** (same philosophy as `state_slots`, no second source of truth):
317
+ calling at any moment yields the latest state; no background task dependency. Tool surfaces (all in `scripts/`):
318
+
319
+ | Item | Purpose |
320
+ |---|---|
321
+ | `state_atlas.py` | **Generic multi-subject tracking map** (resident piece): one md = a worldbook for all characters (current values/retirement/transition history/major events/per-act) plus optional `--worldbook-json` (tavern-style key/content) |
322
+ | `whale_state_tracker.py` | Corpus-line extractor (turns dialogue corpora into five-element events; the whale character ruleset, whose machinery can be imitated to build rule packs for other characters) |
323
+ | `whale_state_atlas.py` | Corpus-line dedicated tracking map (generated from the extractor's md output) |
324
+ | `state_slots.py` (CLI) | Read-only entry for slot projection (always available, `--status` etc.) |
325
+ | `stg(op=state_chain)` | MCP query surface (flag `MDCG_STG_STATE` off by default — discipline unchanged, complementary to the always-available CLI) |
326
+
327
+ **Library root resolution (same source as zcode MCP, preventing two-library forking)**: `--root` > env `MDCG_ROOT` >
328
+ `~/.zcode/cli/config.json`'s `mcp.servers.mdcg.env.MDCG_ROOT` > `mdcg_root()` default.
329
+ **Read-only discipline**: tool surfaces are read-only, and `--out` is always outside the repository (fail-closed).
330
+
331
+ **Recording discipline (general guidance, distilled from the whale-character line's three-layer disambiguation basis)**: ① record when a state change happens (whose
332
+ what slot, old/new, one of five kinds); ② **user-side statements take precedence** (a state the user explicitly states is authoritative;
333
+ a character's self-reported 'misremembering' does not overwrite the true value); ③ the three non-fact categories (jokes/meta level/recalling a retelling) are labeled truthfully and
334
+ do not overwrite the true value; ④ retraction = old has a value and new is empty (explicit voiding, no silent rewriting).
335
+
336
+ **Live status (measured 2026-10-06)**: the authoritative library (the AEIS data-area library root — root resolution follows the same-source basis above)
337
+ has **0 events** in its ledger — the full mechanism is in place and the data is uncharted territory; multi-subject rendering was demonstrated and verified in an isolated library
338
+ (2 subjects/30 events/15 slots/15 worldbook entries; readings in the `docs/eval/` report v1.2 section).
339
+
340
+ **Pending ruling (optional enhancement for resident automation)**: whether to hang a step
341
+ 'pre-generate tracking map md by subject → state surface' on the sleep-cycle 'organize' slot — the current state is **computed on demand** (open it and it is the latest), and pre-generation would only be a cache object for
342
+ 'a file exists as soon as you open it'; changing the resident loop is a production behavior change and must be filed as its own item.
343
+
344
+ ### Session link integration (step two of the turn write chain; user ruling 2026-10-06)
345
+
346
+ > 'Treat this feature as the 10-turn information write for the session, and process it when writing mdcg... each write
347
+ > adds some processes asynchronously, but the benefit is a maintainable state, and at the same time a cognitive map and a semantic spatiotemporal graph,
348
+ > with relationship traceability of the original information.'
349
+
350
+ - **Wiring point**: `scripts/sync_zcode_session.py::sync_to_window` (zcode side, every turn —
351
+ Stop hook/cold start/compression recovery share the same chain) — **within the same loop** that writes the `_recent` window, call
352
+ `scripts/state_extract.py` for conservative extraction on the same turn → `state_events.append` into the ledger. The hook runs as a subprocess at the end of the turn (processed outside the session, i.e. 'asynchronous'),
353
+ **fail-soft per turn** (extraction failure never affects window writing or turn progress).
354
+ - **Conservative basis (the discipline for writing into the live library: better to miss than to be wrong)**: extract only **user turns** (a real person = the fact source);
355
+ only two high-precision rules (`地点·所在` migration / `情感·偏好`, with the negative direction explicitly recorded as `不喜欢:`); values have
356
+ sentence-final modal particles stripped; **deduplicate identical values** (to prevent repeated recording every turn); evidence `[auto] session=… turn=…`,
357
+ `actor=state_extract` — so it can be identified/cleaned up wholesale; the switch `MDCG_STATE_EXTRACT` is **on by default**
358
+ (=0 turns it off). The probe has shown: bare word forms (promise 138 / causal 59/225 hits) do not enter the rule table.
359
+ - **Three layers from one source + relationship traceability**: cognitive map (`_recent`/knowledge surface) + semantic spatiotemporal graph (ledger/`state_slots`
360
+ projection/`state_atlas` view) + original text (session md mirror/full transcription) — the event `evidence` carries
361
+ session/turn number/short evidence, so any layer can look back at the other two.
362
+ - **Readings**: guard `scripts/test_state_extract.py` **10/10** (zero hits from the three noise families, deduplication,
363
+ value-change chains, evidence format, switch, wiring point) + full run **359/359**.
364
+ - **DSH side**: the same wiring lives on the plugin side (TS) — it is a follow-up item (requires changing the plugin and releasing it with the package); this batch only has
365
+ the zcode side online, and DSH-side behavior is unchanged.
366
+ - **Known boundary (left to be ruled)**: generalized word forms of the 'lives here' kind will match (the value is taken as 'inside' and the like) — this is how the v1 word forms
367
+ are; whether to narrow them is up to the user.
368
+
369
+ ---
370
+
371
+ ## Revision history
372
+
373
+ | Date | Key points |
374
+ |---|---|
375
+ | 2026-10-06 | v1.0 first edition (batch P3): full chain (ledger→projection→query→recording entry→CLI→probe) / switch `MDCG_STG_STATE` off by default and the CLI always available / authorization basis (`state_event`→`write` word mapping, actor always from the token) / re-run commands for the probe's three readings / boundaries as they are (§1–§8) |
376
+ | 2026-10-06 | Added §9 'Retirement discipline': default retrieval exclusion of nodes with `lifecycle_state=archived` (single criterion `lifecycle.is_archived`, consumer surfaces `MdCGOS._candidates` + `stg._scan_one` + the four segments of the session continuation injection surface `session_recall` [notes/active goals/task ledger/unresolved questions]) / the boundary between the two meanings of 'retirement' / unrestricted surfaces (direct read · audit · **ledger management query surface** · statistics) and 'lifecycle recovery ≠ `op=restore` (deletion axis)' / the four readings of the Scale 5.2 probe (surface-count basis) and guard re-runs / boundaries as they are (uncovered surfaces: base class `MdCG.search`, causal chain surface `chain.adjacency`, structural surface `subgraph`, rust kernel, targeted surface `identity.profile`) |
377
+ | 2026-10-06 | **Boundary four-item ruling batch landed (user ruling: 1/2/4 wired, 3 not wired)**: base class `MdCG.search` wired (R5) / `chain.adjacency` wired (`skip_archived` parameter, R6; scrub maintenance surface explicit bypass) / rust kernel wired (crate unit tests pin both) / `subgraph` structural surface **ruled not wired** (R7 pins the ruling); and added `chain.invalidate_cache` same-point invalidation in `lifecycle.set_state` (the cache gap evidenced by this batch's probe); guards 36→45 assertions |
378
+ | 2026-10-06 | **Added §10 'Multi-subject state tracking' (core capability positioning, user 2026-10-06)**: resident form = read-only view computed at query time (no second source of truth); four tool surfaces (`state_atlas` generic multi-subject / two corpus-line pieces / CLI); library root resolution from the same source as MCP (preventing two-library forking); four recording disciplines (distilled from the whale-character line's three-layer disambiguation basis); 0-event live ledger measurement + isolated multi-subject demo readings; sleep-slot pre-generation listed as pending ruling |
379
+ | 2026-10-06 | **Added §10 'Session link integration' (step two of the turn write chain, user ruling 2026-10-06)**: `sync_to_window` conservatively extracts the same turn within the same loop (`state_extract`: user turns only / two high-precision rules / deduplication / identifiable evidence; switch on by default) → ledger; three layers from one source + relationship traceability; guard `test_state_extract` 10/10, full run 359/359; the same wiring on the DSH side is listed as a follow-up item |
@@ -0,0 +1,130 @@
1
+ > **Languages:** [中文](../../mdcg/写入别名aliases规范_v0.6.md) · English
2
+
3
+ # Write aliases specification v0.6
4
+
5
+ > 2026-10-31 · Cause: issue #722 "the condition gate matches literally, so natural phrasings are mostly judged DEFER"
6
+ > **This specification is backed by a measured closed loop**: the mechanism is ready (#719), the case has been verified to work, and in-library usage is 0%.
7
+ > v0.1–v0.5, five versions, all took "change the verdict / change the condition quality" and were all overturned by measurement; this version switches to **adding aliases on the write side**.
8
+
9
+ ## 1. Empirical evidence (all reproducible)
10
+
11
+ ### 1.1 Decisive case (given by the issue reporter)
12
+
13
+ Condition: when talking about handover, switching sessions, compression, or when he shows reluctance to part
14
+ Query: `我不想你被换掉`
15
+
16
+ | Matching method | Result |
17
+ |---|---|
18
+ | **Whole word in** (current) | ❌ No match |
19
+ | **Bigram overlap** | ❌ `换会`/`会话` vs `我不`/`不想`/`想你`/`你被`/`被换`/`换掉` — **empty intersection** |
20
+ | **Query expansion** (`expand_query_terms`) | ❌ Expands `换掉`/`被换`, still **no intersection** with `换会话` |
21
+ | **Existing synonym table** (10 groups, all technical terms) | ❌ No `会话`/`换掉` group |
22
+ | **Adding aliases** (`换掉`/`被换`/`别消失`/`舍不得`/`不想你走`/`会交接`/`换会话`/`压缩上下文`) | ✅ **Match** (False → True) |
23
+
24
+ ⇒ **All four literal paths are dead; only aliases work.**
25
+
26
+ ### 1.2 Current state in the library (full scan + sampling)
27
+
28
+ | Item | Reading |
29
+ |---|---|
30
+ | aliases coverage | **0 / 120 = 0%** |
31
+ | Share whose effective condition is **metadata** | **65 / 85 = 76.5%** (sample 120, structured slot-label criterion) |
32
+ | role=None in the knowledge layer (index cards) | **99.7%** (30,468 / 30,558) |
33
+ | Recall count for natural phrasings | **2 items / 32,845** |
34
+
35
+ ⇒ **The mechanism exists and works, but nobody uses it** — that is the whole truth of #722.
36
+
37
+ ## 2. Specification
38
+
39
+ ### 2.1 What to write
40
+
41
+ > **When writing a memory, aliases must at least contain "how the user might ask about this".**
42
+
43
+ **Not**: technical term abbreviations, field names, path fragments.
44
+ **But**: the colloquial wording, emotional expressions, and near-synonyms the user would say.
45
+
46
+ Taking the case in 1.1 as an example, the condition is `聊交接、换会话、压缩、或他流露舍不得时`,
47
+ and the aliases are written as: `换掉` / `被换` / `别消失` / `舍不得` / `不想你走` / `会交接` / `换会话` / `压缩上下文`.
48
+
49
+ ### 2.2 Why not write them into tags
50
+
51
+ tags are already occupied by machine criteria (is it a task card: tasks.py; can it be an anchor: anchor.py / predict.py).
52
+ Stuffing aliases in would **change those criteria**. aliases and tags are **physically separate** and take part only in retrieval recall.
53
+
54
+ ### 2.3 How to generate them (**recommend the LLM asking itself**)
55
+
56
+ > **When writing aliases, first ask yourself: "How will I ask about this later?" — write those phrasings into aliases verbatim.**
57
+
58
+ Concrete approach (when the writer is an LLM):
59
+
60
+ 1. After reading the memory, **without looking at the condition first**, ask yourself: "If three months from now I forget this, what words would I use to ask about it?"
61
+ 2. Write **3–8** such questions/keywords (colloquial, emotional, and near-synonyms all count);
62
+ 3. Write them into `aliases`; words already present in the source text do not need repeating (the criterion would judge them "thin").
63
+
64
+ **Demonstration** (#722 case):
65
+
66
+ ```
67
+ 条件:聊交接、换会话、压缩、或他流露舍不得时
68
+ 自问:以后会怎么问?
69
+ → 「换掉」「被换」「别消失」「舍不得」「不想你走」「会交接」「压缩上下文」
70
+ aliases: 换掉 / 被换 / 别消失 / 舍不得 / 不想你走 / 会交接 / 换会话 / 压缩上下文
71
+ ```
72
+
73
+ ⚠️ **Do not extract words mechanically**. Measured (2026-10-31): auto-generating aliases by splitting feature names on spaces,
74
+ 5 real questions × 20 nodes = **lift +0** — because Chinese feature names have no spaces, so what gets split out is the whole sentence,
75
+ which has nothing to do with "how the user would say it". **Aliases must be predicted by the party that understands the content and cannot be generated automatically.**
76
+
77
+ ### 2.4 Criterion (executable)
78
+
79
+ `aliases_is_thin(fm) -> bool`: **no aliases**, or **all aliases can be found verbatim in the body/condition**
80
+ (= only repeats existing words, expands no recall head) ⇒ judged "thin".
81
+
82
+ ⚠️ **Does not judge "whether the count is enough"** — 3 precise aliases may beat 10 noisy ones.
83
+
84
+ ## 3. Write guard (warn first)
85
+
86
+ Reuse the three write_gate levels from #708:
87
+
88
+ | Level | Behavior |
89
+ |---|---|
90
+ | off | No check |
91
+ | **warn (default)** | Write succeeds + counted + hint "this entry has no expansion aliases, natural phrasings may not recall it" |
92
+ | enforce | Reject the write |
93
+
94
+ **Does not block writes**: aliases are a bonus, not a prerequisite for correctness. Missing them should not make a memory unwritable.
95
+
96
+ ## 4. Legacy data (explicitly no bulk backfill)
97
+
98
+ Bulk-adding aliases to 32,845 nodes is **not realistic** (it requires understanding every item). The realistic path:
99
+
100
+ 1. **New writes** follow this specification (the guard starts at warn);
101
+ 2. **Hot spots first**: **backfill** aliases after the fact for queries that actually fail to recall (whichever fails to recall, backfill that one);
102
+ 3. **Observable**: `cg(op=info)` exposes "the number of nodes without aliases" as an improvement baseline.
103
+
104
+ ## 5. Verification approach (every item must be testable)
105
+
106
+ | Assertion | How to test | Current state |
107
+ |---|---|---|
108
+ | Aliases can rescue the #722 case | Same comparison as 1.1 | ✅ **Tested** (False → True) |
109
+ | Library-wide alias coverage | Sample-read fm.aliases | ✅ **Tested** (0/120) |
110
+ | All literal paths are dead | Compare whole word / bigram / expansion / synonym table one by one | ✅ **Tested** (all empty intersections) |
111
+ | aliases_is_thin can identify the current state | Run it on the sample, ≈100% judged thin | To be built |
112
+ | Aliases do not pollute the tags criteria | After adding aliases, "is it a task card" and "can it be an anchor" are unchanged | ✅ **Tested** (C/D group guards of PR #719) |
113
+ | The warn level does not block writes | Nodes without aliases are still written successfully, only counted | To be built |
114
+
115
+ ## 6. Non-applicable conditions
116
+
117
+ 1. **Does not solve "phrasings that were never anticipated"** — aliases depend on someone writing them; whatever is not written still cannot be recalled;
118
+ 2. **Does not replace semantic retrieval** — semantic coverage is 0, which is a separate engineering line;
119
+ 3. **Does not bulk-backfill legacy data**;
120
+ 4. **Does not change tags semantics** (the machine criteria of that field stay put);
121
+ 5. **Does not support automatic alias generation** — measured (2026-10-31): mechanically extracting words from feature names/body, 5 real questions × 20 items = **lift +0**.
122
+ Aliases must be written by the party that understands the content (a human or an LLM) **predicting how the user would ask**.
123
+
124
+ ## 7. Criterion evolution record (do not repeat)
125
+
126
+ | Version | Direction | Why it was overturned |
127
+ |---|---|---|
128
+ | v0.1–v0.4 | Change the verdict algorithm (text source / weak state / S3 graph diffusion / topic surface) | **Wrong target**: what gets judged is 99.7% index cards |
129
+ | v0.5 | Change condition quality (judge whether it is metadata) | **A diagnosis, not a solution** — metadata conditions are a product of the indexer and cannot be changed |
130
+ | **v0.6** | **Add aliases on the write side** | ✅ The mechanism already exists (#719) + the case proves it works |
@@ -0,0 +1,11 @@
1
+ > **Languages:** [中文](../../ops/README.md) · English
2
+
3
+ # ops/ · Installation and operations
4
+
5
+ | Document | Content |
6
+ |---|---|
7
+ | [Installation and prerequisites](install.md) | One-command setup / manual three steps / prerequisites (Node, Python, and DSH versions) / verified environments / post-install verification / automatic memory scope / troubleshooting clues |
8
+ | [Environment and known issues](environment-known-issues.md) | DSH Desktop startup warnings (host side) / size and whole-directory coupling / **persistence timing (nodes sync, indexing is async #677 P2, plus three exits)** / **timeout is not failure: check before writing (#677 P1)** / Windows rmtree quirks / **design tradeoffs (not bugs)** |
9
+ | [Operations and troubleshooting](operations-troubleshooting.md) | Restart the long-running process after an upgrade (proxy verification of five fields) / write credentials and `committed` semantics / common questions (FAQ) |
10
+
11
+ > Domain assignment rules are in the [docs/ directory index](../README.md).