diff --git a/03-DESIGN/01-to-be/55-the-knowledge-base.md b/03-DESIGN/01-to-be/55-the-knowledge-base.md index de3f1520..4a260e4e 100644 --- a/03-DESIGN/01-to-be/55-the-knowledge-base.md +++ b/03-DESIGN/01-to-be/55-the-knowledge-base.md @@ -9,6 +9,7 @@ decisions: - "ADR 0423" - "ADR 0424" - "ADR 0592" + - "ADR 0593" --- # 55 — The knowledge base @@ -133,7 +134,7 @@ when a bucket or stream is at its cap. It names the source it serves from (the d of the move's last check, and counts drafts idle more than a week, records the form-only check refused, and parts waiting more than 30 minutes. A part waiting more than 30 minutes is asked of the operator once through the operator channel, and the ask clears when the part is judged; the module stays healthy meanwhile, because a record waiting on -its review is not the module failing (issue 508). The condition at 75 percent of a cap is the controller's (§ 2.1). +its review is not the module failing (issue 508). The condition at 75 percent of a cap is the grants part's (§ 2.1). **Events** (ADR 0592 §34) are kept 30 days; what a later reader needs is also in the version message. Each carries: @@ -204,12 +205,12 @@ A record is kept in three of the bus's own forms, so that a new version costs on with no age limit, and when it reaches its cap it refuses a new message rather than dropping its oldest, with a condition raised at 75 percent of the cap. A module's stream may declare that retention; before, a stream was kept at most 30 days (ADR 0592 §6, changing ADR 0363 §1). The stream `reviews` keeps its history the same way. The - condition at 75 percent is raised by the controller, in one place, for every history stream and object bucket of - every module. + condition at 75 percent is raised by the grants part (mesh-grants), in one place, for every history stream and + object bucket of every module (ADR 0593 §10, changing ADR 0592 §16). - **A section's body** is one object in the bucket `sections`, named by the sha256 digest of the body: a section unchanged in a new version costs nothing. The module checks that a body hashes to its name each time it reads one. The state `names` keeps, per digest, how many versions and drafts name it and since when none has; an object no - version and no draft names is removed a day after the last stopped naming it, each removal the event `swept`. The bucket is storage of the bus, as the controller's object bucket of ADR 0486 is. Any module + version and no draft names is removed a day after the last stopped naming it, each removal the event `swept`. The bucket is storage of the bus, as the object bucket of ADR 0486 is. Any module may declare an object bucket of its own in its manifest, with a local name and a cap, created as its state buckets are, kept with no age limit and refusing a new object when full (ADR 0592 §5). - **A draft** is a key in the state `drafts` (§ 4). **A part's verdict** is a message on the stream `reviews`, and a @@ -234,7 +235,8 @@ A write refused at a cap names the cap, and the module's health turns unhealthy restricted streams (ADR 0363): a module hears them only through its own `consumes` and a `grant` in mesh-knowledge's trusted config value `readers`, which names the web page that shows records once it exists and nothing today. The object bucket `sections` is read the same way, through a `reads` entry and a `grant` of `readers`: ADR 0592 extends -ADR 0363's grant to a module's object bucket, and the controller composes a read-only grant on that one bucket. +ADR 0363's grant to a module's object bucket, and the grants part composes a read-only grant on that one bucket +(ADR 0593 §10). `heads` is read by a module that names it in `reads`; `drafts`, `asked`, `names` and `findings` by mesh-knowledge alone. No secret is kept in any of them. A grant cannot limit a reader to some objects of a bucket (ADR 0488), which is why reading is announced per bucket and never per record. @@ -454,11 +456,12 @@ field by field and section by section, and the result is written on issue 426. The records leave the store once, and the database is dropped only after a check and the operator's yes (ADR 0592 §12 to §16): -1. **Order.** Three deliveries, in order: mesh-sdk (the manifest's field types for `objects` and - `retention: history`, and the catalog's check of them); then the controller (it creates the object buckets and - history streams, composes the read-only grants of `readers` on them, and raises the condition at 75 percent for every such bucket and - stream in one place); then mesh-knowledge. An older controller refuses a manifest with these keys through the - catalog's check, so mesh-knowledge cannot be delivered before them. The claude-code module's `judged` event is +1. **Order.** Two deliveries, in order (ADR 0593 §10, changing ADR 0592 §16): first the mesh-sdk release sdk1 + (issue 1585), which carries the manifest's field types for `objects` and `retention: history`, their checks in + the indexer's judge, and in the grants part the creation of the object buckets and history streams, the + read-only grants of `readers` on them and the condition at 75 percent for every such bucket and stream in one + place; then mesh-knowledge. An indexer whose judge predates these keys refuses a manifest that has them, so + mesh-knowledge cannot be delivered before the release. The claude-code module's `judged` event is delivered beside, and is not needed for the move (§ 5). 2. **Copy.** The move copies everything the database holds onto the bus, every record, version, clause, link, review, finding, ask with its warrant, reservation and told mark: each version's sections into `sections` by @@ -491,7 +494,7 @@ The records leave the store once, and the database is dropped only after a check | 2 | the decision records and research efforts leave this repository; path mentions become "ADR NNNN" and "research NNN"; playbooks 01 and 02 changed | this repository holds no decision record, and `get` answers every one | issue 426 | | 3 | designs and the glossary's entries as records, moved in one delivery, and each design's state worked out by the knowledge base (§ 9.1 to § 9.3; ADR 0423, ADR 0424) | `get` answers design 47 with its sections and links, a word's entry answers from the knowledge base, and a design's state follows its issues' deliveries without anyone writing it | issue 428 | | 4 | meeting notes, drawings and blog posts | not decided; needs its own decision | issue 429 | -| 5 | the records on the bus, written and reviewed by section, the move off the store and the titles (§ 1, § 2, § 4, § 5, § 8.1; ADR 0592), delivered as mesh-sdk, then the controller, then mesh-knowledge, with claude-code's `judged` event beside | the acceptance tests of the fifth slice in § 10, live; the knowledge base requires no database | the issues its hand-off opens (playbook 04) | +| 5 | the records on the bus, written and reviewed by section, the move off the store and the titles (§ 1, § 2, § 4, § 5, § 8.1; ADR 0592), delivered as the mesh-sdk release sdk1, then mesh-knowledge, with claude-code's `judged` event beside | the acceptance tests of the fifth slice in § 10, live; the knowledge base requires no database | the issues its hand-off opens (playbook 04) | Numbers from the issue tracker, which `reserve` needs, are the tracker's own slice, tracked by issue 424. This repository keeps no copy of the records, generated or otherwise (issue 435, answered by the operator). Playbooks @@ -619,7 +622,7 @@ table-driven; one integration test starts the module whole against the real bus | a second run of the move | unit: changes nothing and says so | | the move's check | unit: a changed review, a missing finding and a missing ask, each named | | writes during the switch | unit: every writing verb refused with its reason; reading verbs answer | -| an older controller | the controller's test: a manifest with `objects` or `retention: history` refused through the catalog's check | +| an older judge | the indexer's judge test (release sdk1): a manifest with `objects` or `retention: history` refused by a judge that does not know them, accepted by one that does | | a reference | unit: "record › title › row" resolves to the section; a nested title is refused | | a form-only version | unit: accepted when only names and links changed and each target resolves; refused otherwise | | an unproven caller | unit: `open`, `write`, `submit`, `propose` and `take-over` refuse it |