Decision records

The current design, condensed per domain, is in ../design/; this directory holds the reasons behind it.

Code records what was built and git records when it changed. Neither records why it was built this way and which roads turned out to be dead ends. This directory does.

The test for writing one: if someone (including us) looks at a piece of code in six months and asks "why not simply…", and the answer is not in the code, there should be a record.

Conventions

File names are NNNN-short-english-title.md, four digits, increasing in creation order, no gaps. The number is a stable anchor for references and says nothing about priority.

The directory is flat. No subdirectories until a second kind of document appears.

Revisions stay in place. When a conclusion changes, especially because checking the code overturned it, keep a dated revision note where the original claim stood: what it said, why it was wrong, what changed it. The ledger this product keeps never updates a fact in place; a correction inserts a new row that supersedes the old one, because the change of mind is information. Records follow the same rule: knowing "we assumed a range would take effect immediately, checked, and found it never did" tells the next reader what to check first.

When too much has changed, write a new record and mark the old one superseded by NNNN at the top instead of rewriting it.

The PR that implements a record updates its status line. Three status lines once lagged behind the code in the same PR, written by the same person. So the PR description answers one question: which record does this change implement or overturn, and is its status line updated. (Added 2026-09-02, from 0016.)

A status line is one line. It starts with one of five words, Proposed, Accepted, In progress, Implemented or Superseded by NNNN, then the date and the PR or migration, then open: and what is not built. What a cut contains belongs in the record's body or in the design file, not in the status line. The index below repeats only the first word, so a PR touches this README only when that word changes. (Added 2026-09-27; the longer lines that stood before are kept at the end of each record under Status history.)

Line numbers drift and file names change. Prefer function, table and constant names over file.rs:123. Migrations were consolidated from 53 files into one per domain (#130, #131); older references to migration files are by domain.

Language: English. The first sixteen records were written in Chinese and condensed into English on 2026-09-03; the Chinese originals remain in git history. Code comments are still Chinese; UI, README and records are English.

Index

By domain; the domains are the files of ../design/. Status is the first word of the record's own status line. Overtaken says whether a later record overturned it: partly (by NNNN) means some decisions fell and the record's revision notes say which. Open work: grep 'open:' docs/decisions/0*.md.

ontology

	Record	Status	Overtaken
0001	Ontology import and governance	In progress	partly (by 0009, 0010, 0012, 0044)
0003	The ontology grows out of the corpus	Implemented	partly (by 0007, 0010, 0044)
0007	Counting decides what becomes a relation	Implemented	partly (by 0044)
0008	Ontology packs as the cold start	Implemented
0009	An undecided type stays empty	Implemented
0012	The ontology is a contract	Implemented	partly (by 0044)
0044	The ontology is a view over what documents say	In progress
0051	A human phrase decision carries its materialization work	Implemented
0053	A phrase decision records the inputs it considered	Implemented
0061	The ontology is proposed from the open graph and judged by its questions	In progress
0062	The export says what is contested	Implemented

extraction

	Record	Status	Overtaken
0006	Ontology scale and the extraction prompt	Superseded	fully (by 0044)

identity

	Record	Status	Overtaken
0041	A name is a claim about an entity	In progress
0071	A source may declare its names identities	Proposed

time

	Record	Status	Overtaken
0019	The second clock can be rewound	Implemented
0022	An unknown date is not an open one	Implemented	partly (by 0045)
0024	The world axis reaches the second	Implemented
0031	An event holds at the moment it names	Implemented
0045	A time mention is resolved against its document	In progress

ledger

	Record	Status	Overtaken
0010	An unnamed relation stays empty	Implemented	partly (by 0044)
0037	A relation carries its own attributes	In progress	partly (by 0044)
0048	Provenance references stay inside the knowledge base	Implemented
0070	A role word speaks while its chunk is live	Proposed

governance

	Record	Status	Overtaken
0015	A recorded sentence waits for a nod	Implemented
0017	A contradiction points at an error upstream	Implemented
0025	Governance reads the ledger before it decides	Implemented
0026	A decision records why	Implemented
0027	An automatic merge is gated by what it can undo	Implemented
0028	The adjudicator looks before it asks	Implemented
0043	Every review queue is governed	Accepted

rules

	Record	Status	Overtaken
0002	Reasoning engine	In progress
0021	A rule reads attributes and concludes a type	Implemented
0029	A rule may say "or", once	Implemented
0030	A rule may read what a rule concluded	In progress
0032	A rule computes what it concludes	In progress
0047	A rule may conclude a relation	Implemented
0049	Expression declarations are checked when a rule is written	Proposed
0060	A rule's definition has a history	Implemented

sources

	Record	Status	Overtaken
0013	A source hands over its history	Implemented
0023	RSS observations are not documents	Implemented
0033	RSS summaries are scoped to the source being listed	Implemented
0035	A vector index is built by a job	Implemented
0039	A chunk is what extraction sees	In progress
0040	A chunk says where its words came from	Implemented
0052	Document content is a read contract over the retained ledger	Proposed
0054	A source may push statements in the open contract	Implemented
0065	The OCR reader chooses its provider	Implemented

lakehouse-and-actions

	Record	Status	Overtaken
0011	A mapping is configuration	Implemented	partly (by 0036, 0044)
0018	The lakehouse is one protocol away	Implemented
0034	An action is a declared call	Proposed
0036	Exploration aligns a schema to the ontology	In progress
0050	An action attempt keeps its identity and uncertain outcome	Proposed

access-and-audit

	Record	Status	Overtaken
0014	Identity from the person, scope from the token	Implemented
0020	An auditor reads it without us	Implemented
0066	Another app may trade a fresh ID token for a session	Implemented	partly (by 0069)
0069	The identity provider vouches for listed domains	Implemented

interface

	Record	Status	Overtaken
0004	Language follows the reader of each text	Implemented	partly (by 0044)
0005	The alert center	Implemented
0038	The interface has a light side	Implemented

chat-and-mcp

	Record	Status	Overtaken
0042	The chat loop is a runner with hooks	Implemented
0046	The app surface is MCP	Accepted
0063	Stopping a chat ends the generation	Implemented
0064	Extraction reads time as it goes	In progress

process

	Record	Status	Overtaken
0016	Close the open seams before cutting new ones	In progress	partly (by 0036)

Not a decision record

../pipeline.md, how a document becomes a graph. Records explain why; that page explains how things flow and where they get dropped, with five mermaid diagrams. Newcomers read it first, then come back here for the reasons. It is the "second kind of document" the conventions mention, kept at the docs/ root beside decisions/.

What does not belong here

The docs/ root is a local scratch area (/docs/* is git-ignored except /docs/decisions/, /docs/design/ and /docs/pipeline.md). Research notes, temporary checklists and test output live there and stay out of the repository. When a draft settles into a judgment worth keeping, it moves here as a record.