Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 7 additions & 9 deletions docs/decisions/0001-ontology-import-and-governance.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,6 @@
# 0001 · Ontology import and governance

- **Status**: In progress. P0, P1, P2 and P2c built. P3's budget switch built
(`deployment_settings.ontology_prompt_budget`, default 24,000 characters; over budget the ontology
is retrieved per chunk, [0006](0006-ontology-scale-and-the-prompt.md)). P3a built but runs only by
hand. P3b built in a different shape: the surface predicate lands on
`fact_evidence.proposed_predicate`, and mapping back is `predicate_match` plus the adoption loop of
[0003](0003-ontology-growth-loop.md). P4a built (`entities.type_source`, #114); P4b and P4c pending.
P5 delivered by [0002](0002-reasoning-engine.md). The "argument order" half of criterion 2
overturned by [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md). Checked against the code
2026-09-02.
- **Status**: In progress · P0–P2c, the P3 budget and P4a built; P5 delivered by 0002 · open: P3a runs by hand only, P4b, P4c
- **Written**: 2026-08-27 / 28 · condensed into English 2026-09-03
- **Related**: [0002](0002-reasoning-engine.md) replaces P5's schedule;
[0003](0003-ontology-growth-loop.md) is what P3b and P4 became;
Expand Down Expand Up @@ -263,3 +255,9 @@ since moved to `scripts/bench/` (0012); these numbers are real but no longer com
- `disjointWith` pruning of merge candidates on the resolution side is not done.
- The `active` flag has only a governance use left (retired classes take no new entities); whether
it is worth building waits for a real large ontology.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> In progress. P0, P1, P2 and P2c built. P3's budget switch built (`deployment_settings.ontology_prompt_budget`, default 24,000 characters; over budget the ontology is retrieved per chunk, [0006](0006-ontology-scale-and-the-prompt.md)). P3a built but runs only by hand. P3b built in a different shape: the surface predicate lands on `fact_evidence.proposed_predicate`, and mapping back is `predicate_match` plus the adoption loop of [0003](0003-ontology-growth-loop.md). P4a built (`entities.type_source`, #114); P4b and P4c pending. P5 delivered by [0002](0002-reasoning-engine.md). The "argument order" half of criterion 2 overturned by [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md). Checked against the code 2026-09-02.
13 changes: 7 additions & 6 deletions docs/decisions/0002-reasoning-engine.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,6 @@
# 0002 · Reasoning engine

- **Status**: R0 built: six fact-level violation kinds in `axiom_violations` (five checks plus
`derived_contradiction`, 0017), eight ontology defect kinds in `ontology_defects`, two Review tabs. R1 built behind the KB switch `materialize_inferences`
(default on since 0050; off when this was written), rules from four axiom kinds (#132, #177, #179). R2 built as a proof chain
(`GET /kbs/{id}/derived/{id}/proof`, 0016 B1). Contradiction signals for derivations built per
[0017](0017-a-contradiction-points-upstream.md). R3 not built: every run recomputes the whole KB,
on `inference_interval_minutes` (default 60).
- **Status**: In progress · R0, R1 and R2 built · open: R3, incremental maintenance
- **Written**: 2026-08-28 · condensed into English 2026-09-03
- **Related**: [0001](0001-ontology-import-and-governance.md) P5 (this record replaces its schedule);
[0010](0010-no-relation-is-no-relation.md);
Expand Down Expand Up @@ -98,3 +93,9 @@ corpus is cleaned, then materialization is switched on.
- Materialize or evaluate at query time: 4.5× expansion on a small corpus, unknown at scale. For now
a per-predicate cap and a periodic full recompute.
- R3 incremental maintenance: correctness is the hardest to verify, and full recompute holds.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> R0 built: six fact-level violation kinds in `axiom_violations` (five checks plus `derived_contradiction`, 0017), eight ontology defect kinds in `ontology_defects`, two Review tabs. R1 built behind the KB switch `materialize_inferences` (default on since 0050; off when this was written), rules from four axiom kinds (#132, #177, #179). R2 built as a proof chain (`GET /kbs/{id}/derived/{id}/proof`, 0016 B1). Contradiction signals for derivations built per [0017](0017-a-contradiction-points-upstream.md). R3 not built: every run recomputes the whole KB, on `inference_interval_minutes` (default 60).
14 changes: 7 additions & 7 deletions docs/decisions/0003-ontology-growth-loop.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
# 0003 · The ontology grows out of the corpus

- **Status**: Built and running (#44; switch `knowledge_bases.auto_extend_ontology`, default on). Its
starting point has moved: `related_to` is deleted ([0010](0010-no-relation-is-no-relation.md)) and
the seed ontology retired (#125, #128), so a new KB starts from an ontology pack
([0008](0008-ontology-packs-as-cold-start.md)) and this loop fills the gaps a pack leaves.
"Dismissal has memory" redone per [0007](0007-who-decides-what-becomes-a-relation.md). Two of three
known gaps closed (`adopt_proposed_types` + `entity_retypes`; `ontology_proposals`, #112); the "new
phrasings since you last looked" reminder still pending. Checked against the code 2026-09-02.
- **Status**: Implemented (#44) · open: the "new phrasings" reminder
- **Written**: 2026-08-28 · condensed into English 2026-09-03
- **Related**: [0001](0001-ontology-import-and-governance.md) P3b and P4 are the plan, this is what
grew; [0007](0007-who-decides-what-becomes-a-relation.md); [0008](0008-ontology-packs-as-cold-start.md);
Expand Down Expand Up @@ -94,3 +88,9 @@ by this loop. The loop itself is unchanged and still on by default.
- With the switch off there is no "88 new phrasings since you last looked"; the index
`ontology_proposals_open_idx` was laid for it and the reminder never built. The only banner today
is `last_auto_extension`, which reports the last automatic run.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Built and running (#44; switch `knowledge_bases.auto_extend_ontology`, default on). Its starting point has moved: `related_to` is deleted ([0010](0010-no-relation-is-no-relation.md)) and the seed ontology retired (#125, #128), so a new KB starts from an ontology pack ([0008](0008-ontology-packs-as-cold-start.md)) and this loop fills the gaps a pack leaves. "Dismissal has memory" redone per [0007](0007-who-decides-what-becomes-a-relation.md). Two of three known gaps closed (`adopt_proposed_types` + `entity_retypes`; `ontology_proposals`, #112); the "new phrasings since you last looked" reminder still pending. Checked against the code 2026-09-02.
14 changes: 7 additions & 7 deletions docs/decisions/0004-language-and-localization.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
# 0004 · Language follows the reader of each text

- **Status**: Built · UI strings in `web/src/i18n/`; user-reachable server errors carry a
`code` (`AppError::Invalid`, 81 sites; 23 `Validation` guards stay English), and so do
the chat stream's `error` frames, in the same `{error, code}` body (2026-09-26);
`description` follows `knowledge_bases.ontology_lang`; LLM output for people takes
`locale` from the request; extracted data stays verbatim; the chat's step trail carries
fields the client words (`status`, counts, moments), and keeps its English `detail` for
stored messages (2026-09-26); the UI does not guess the browser language yet.
- **Status**: Implemented · open: the UI does not guess the browser language
- **Written**: 2026-08-29 · condensed into English 2026-09-03
- **Related**: [0001](0001-ontology-import-and-governance.md) made `description`
load-bearing; [0003](0003-ontology-growth-loop.md) separated `reason` from
Expand Down Expand Up @@ -84,3 +78,9 @@ The last row is not copy. It is a quotation.
and the Chinese did not". Edit both together.
- **Mixed-language corpora in one knowledge base**: one language per KB; design it when it
happens.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Built · UI strings in `web/src/i18n/`; user-reachable server errors carry a `code` (`AppError::Invalid`, 81 sites; 23 `Validation` guards stay English), and so do the chat stream's `error` frames, in the same `{error, code}` body (2026-09-26); `description` follows `knowledge_bases.ontology_lang`; LLM output for people takes `locale` from the request; extracted data stays verbatim; the chat's step trail carries fields the client words (`status`, counts, moments), and keeps its English `detail` for stored messages (2026-09-26); the UI does not guess the browser language yet.
11 changes: 7 additions & 4 deletions docs/decisions/0005-alert-center.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
# 0005 · The alert center

- **Status**: Built · five kinds live (`source.sync_failed`, `llm.unreachable`,
`llm.rate_limited` #160, `llm.out_of_credit` #182, `data_source.schema_sync_failed`);
the panel has search and per-group paging; decisions 1 and 2 were overturned during
implementation; `document.no_text_layer` still unwired.
- **Status**: Implemented · open: `document.no_text_layer` is unwired
- **Written**: 2026-08-29 · condensed into English 2026-09-03
- **Related**: adjacent to the Review queue
([0001](0001-ontology-import-and-governance.md) P4);
Expand Down Expand Up @@ -127,3 +124,9 @@ channel: something in this document did not land. None of it goes to Review.
endpoint, so the message can say "no text layer; configure OCR and reprocess". When
wired, do not ask when it is fixed: one row per scan, the panel folds adjacent rows,
reprocessing needs no cleanup.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Built · five kinds live (`source.sync_failed`, `llm.unreachable`, `llm.rate_limited` #160, `llm.out_of_credit` #182, `data_source.schema_sync_failed`); the panel has search and per-group paging; decisions 1 and 2 were overturned during implementation; `document.no_text_layer` still unwired.
11 changes: 7 additions & 4 deletions docs/decisions/0006-ontology-scale-and-the-prompt.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
# 0006 · Ontology scale and the extraction prompt

- **Status**: Built · the character budget (`deployment_settings.ontology_prompt_budget`,
24,000) and per-chunk retrieval are live, values unchanged; the "built-in classes always
present" floor is replaced by ancestor completion; the per-chunk list keeps to the same budget
and carries first sentences (#701); answer keys are still hand-filled.
- **Status**: Superseded by 0044 · was built
- **Written**: 2026-08-29 · condensed into English 2026-09-03
- **Related**: [0008](0008-ontology-packs-as-cold-start.md) packs are now the starting
ontology; [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) measured the bias
Expand Down Expand Up @@ -90,3 +87,9 @@ classes), hence no hit rate.
attributes) are guesses; tuning before the corpus question is settled only tightens the
overfit. `run.mjs --packs schema-org,prov-o` walks the real cold-start path, but that
comparison has not been run.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Built · the character budget (`deployment_settings.ontology_prompt_budget`, 24,000) and per-chunk retrieval are live, values unchanged; the "built-in classes always present" floor is replaced by ancestor completion; the per-chunk list keeps to the same budget and carries first sentences (#701); answer keys are still hand-filled.
16 changes: 7 additions & 9 deletions docs/decisions/0007-who-decides-what-becomes-a-relation.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,6 @@
# 0007 · Counting decides what becomes a relation

- **Status**: Built · adoption by counting (`MIN_DOCS = 2`; an LLM run needs `MIN_SIGNALS
= 3`); six defects fixed; proposals persist in `ontology_proposals` (#112); open:
narrative verbs in the ontology, `merge_key` not folding `_by`; the starting point (10
seeds, the `related_to` share) no longer exists · 2026-09-10: the counting path now
takes `temporal` from the proposal it already reads for classes and attributes, instead
of writing `state` for every relation it adopts — the comment that justified `state`
("temporal has no consequence unless functional is set") stopped being true at
[0031](0031-an-event-holds-at-the-moment-it-names.md), which normalises every write by
it; counting still decides *whether*, the model only answers *which kind*.
- **Status**: Implemented (#112) · open: narrative verbs, `merge_key` not folding `_by`
- **Written**: 2026-08-30 · condensed into English 2026-09-03
- **Related**: [0006](0006-ontology-scale-and-the-prompt.md) for the bench and its
caveats; [0010](0010-no-relation-is-no-relation.md) and
Expand Down Expand Up @@ -110,3 +102,9 @@ the corpus is dense in training data.
`_by` into the group and mark it for swapping.
- **What a 1,500-term start does to the adoption loop** has not been measured; no
threshold has moved.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Built · adoption by counting (`MIN_DOCS = 2`; an LLM run needs `MIN_SIGNALS = 3`); six defects fixed; proposals persist in `ontology_proposals` (#112); open: narrative verbs in the ontology, `merge_key` not folding `_by`; the starting point (10 seeds, the `related_to` share) no longer exists · 2026-09-10: the counting path now takes `temporal` from the proposal it already reads for classes and attributes, instead of writing `state` for every relation it adopts — the comment that justified `state` ("temporal has no consequence unless functional is set") stopped being true at [0031](0031-an-event-holds-at-the-moment-it-names.md), which normalises every write by it; counting still decides *whether*, the model only answers *which kind*.
12 changes: 7 additions & 5 deletions docs/decisions/0008-ontology-packs-as-cold-start.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
# 0008 · Ontology packs as the cold start

- **Status**: Built · five packs embedded in the binary (gzip, 1.7 MB → 316 KB),
multi-select at KB creation, 22-row static alignment table · a new KB seeds no
relations: the packs are the whole ontology · **no pack is checked by default and the
base made at registration installs none** (2026-09-10, #580) · the three open questions
stay open; the Chinese-label one got worse (2026-09-02 check)
- **Status**: Implemented · open: the record's three open questions
- **Written**: 2026-08-30 · condensed into English 2026-09-03
- **Related**: [0001](0001-ontology-import-and-governance.md) criteria and IRI/key split;
[0006](0006-ontology-scale-and-the-prompt.md) prompt budget;
Expand Down Expand Up @@ -133,3 +129,9 @@ order status).
- **Starting scale is a variable.** 0007's Snowball run showed that growing the vocabulary
from 10 to 629 changes matching (49 recalls → 18). Nobody has studied what starting at
1500 does to the adoption loop; `MIN_DOCS = 2` and `MIN_SIGNALS = 3` were never retuned.

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Built · five packs embedded in the binary (gzip, 1.7 MB → 316 KB), multi-select at KB creation, 22-row static alignment table · a new KB seeds no relations: the packs are the whole ontology · **no pack is checked by default and the base made at registration installs none** (2026-09-10, #580) · the three open questions stay open; the Chinese-label one got worse (2026-09-02 check)
17 changes: 7 additions & 10 deletions docs/decisions/0009-no-type-is-a-type.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,6 @@
# 0009 · An undecided type stays empty

- **Status**: Implemented · `entities.type_id` and `entity_retypes.from_type_id` are
nullable; the nine builtin classes and the seeding function left with the seed relations
(#110 / #125 / #128 / [0011](0011-a-mapping-is-not-a-fact.md)) · `owl:disjointWith` now
reaches resolution (0016 B3): a declared disjointness, inherited down both hierarchies, keeps
same-name entities apart ahead of every heuristic; since #226 same-name entities of kin classes
(ancestor, descendant or a shared non-root ancestor) go to Review; `CONFUSABLE_TYPE_KEYS` stays
as the fallback when nothing is declared · `metric` /
`dimension` were created on demand by mapping exploration (#231); **they are to retire**
under [0036](0036-exploration-aligns-a-schema-to-the-ontology.md), which found them to be
the same species this record removed
- **Status**: Implemented · open: `metric` and `dimension` retire under 0036
- **Written**: 2026-08-30 · condensed into English 2026-09-03
- **Related**: [0008](0008-ontology-packs-as-cold-start.md) makes a real vocabulary the
optional start; [0001](0001-ontology-import-and-governance.md) IRI/key split behind the
Expand Down Expand Up @@ -114,3 +105,9 @@ in the ontology as a class, as if someone had decided it.
- **Where `metric` / `dimension` belong.** Today they are builtin-on-demand. A "Utopia
semantic layer" pack would move the last builtin classes out of code into something
optional, with IRIs, replaceable (0016 D2).

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Implemented · `entities.type_id` and `entity_retypes.from_type_id` are nullable; the nine builtin classes and the seeding function left with the seed relations (#110 / #125 / #128 / [0011](0011-a-mapping-is-not-a-fact.md)) · `owl:disjointWith` now reaches resolution (0016 B3): a declared disjointness, inherited down both hierarchies, keeps same-name entities apart ahead of every heuristic; since #226 same-name entities of kin classes (ancestor, descendant or a shared non-root ancestor) go to Review; `CONFUSABLE_TYPE_KEYS` stays as the fallback when nothing is declared · `metric` / `dimension` were created on demand by mapping exploration (#231); **they are to retire** under [0036](0036-exploration-aligns-a-schema-to-the-ontology.md), which found them to be the same species this record removed
13 changes: 7 additions & 6 deletions docs/decisions/0010-no-relation-is-no-relation.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,6 @@
# 0010 · An unnamed relation stays empty

- **Status**: Implemented · `facts.predicate_id` is nullable, `related_to` is gone, display
falls back to the source's wording through `fact_surface_predicate(uuid)`, guarded by
`no_predicate_still_shows.rs` · both `mapped_to` follow-ups done with
[0011](0011-a-mapping-is-not-a-fact.md) (#126); the seed table and
`ensure_default_ontology` left with #128 · the two pieces of dead code noted 2026-09-02 are
cleared
- **Status**: Implemented
- **Written**: 2026-08-30 (undated in the original; the day its migration ran) · condensed
into English 2026-09-03
- **Related**: [0009](0009-no-type-is-a-type.md) the twin on the type side;
Expand Down Expand Up @@ -97,3 +92,9 @@ fake vocabulary word.
- 2026-09-02: two pieces of dead code. `graph.rs` `confirmed_mappings()` had zero callers
(chat reads `mappings::confirmed`), and the `r.key = 'mapped_to'` join in `confirm_fact`
matched zero rows. Both removed since (0016 A3).

## Status history

The status line as it stood on 2026-09-27, before status lines were cut to one line:

> Implemented · `facts.predicate_id` is nullable, `related_to` is gone, display falls back to the source's wording through `fact_surface_predicate(uuid)`, guarded by `no_predicate_still_shows.rs` · both `mapped_to` follow-ups done with [0011](0011-a-mapping-is-not-a-fact.md) (#126); the seed table and `ensure_default_ontology` left with #128 · the two pieces of dead code noted 2026-09-02 are cleared
Loading