Repository navigation
Review queues are organised by what a decision changes #725
Description
Follows 0044 (#710) and 0045 (#724). A survey of the review and governance code on dev (about 12k lines: resolution, temporal, governance, review routes, type resolution, mappings, adjudication, pending; plus 2.2k in #699) against the three-layer design.
Queues
Today's queues are grouped by where an item came from (pending, duplicates, conflicts, unconfirmed, lowconf, violations, defects, plus proposals on the ontology page and mappings). The new queues are grouped by what a person's decision changes. Agents handle every single item; people see what an agent could not settle or what one decision resolves at once.
| Queue | What arrives | The decision | Writes back to |
|---|---|---|---|
| Ontology proposals | object/link types and properties proposed by the ontology agent or drawn from the open graph's most frequent unbound signatures; duplicate properties; domain/range changes; definition edits; implication rules | approve, edit and approve, reject | ontology version; recompute of affected signatures; regression cases |
| Alignment | a signature (phrase + subject classes + object classes) the aligner cannot settle, and implication rules it proposes for a signature | property and direction, or none; accept or reject the rule | binding cache and rule set, reused across the base; "none" feeds a proposal |
| Time anchors | document date missing or conflicting; relative mention with no anchor; undefined calendar | the date or anchor | document time context; dependent valid times recomputed |
| Identity | pairs deterministic evidence cannot settle; merges the gate held | same, different, cannot-link | merge or split action; cannot-link list |
| Typed-fact errata | retractions and revisions the errata agent could not settle or the gate held | keep, retract, revise | fact invalidated plus its replacement, on the record axis |
| Cross-document conflicts | incompatible values of a functional property or incompatible times | which holds, both at different times, disputed | supersede, valid_to, dispute mark |
| Nods | memory facts awaiting the person (0015, 0043) | nod or not | fact takes effect |
Alignment is the operation that produces the typed graph from the open graph: bindings decided once per signature, and implication rules (a statement of this shape implies a fact of that property, with the value read from the object phrase) proposed by the agent, approved on the ontology workbench, and executed by code. The ontology workbench has three sources: suggestions from the open graph, an imported ontology file (packs, 0008), and online editing.
Ordering is by leverage (statements a decision resolves), then impact, then age.
Cards
One fixed template per queue. Every field is assembled by code from the ledger: the question and options from the template; quotes fetched from the chunk by offset (extraction no longer repeats quotes); both clocks from the fact; the agent's reason from agent_decisions; impact from execution_gate::impact_of, snapshotted at enqueue and refreshed on open; precedents from bindings and decisions. Zero model calls at review time. Actions: approve, edit and approve, reject, defer, and "make a rule" (alias, cannot-link, regression case). Everything reverts and the revert shows in history.
Queue metrics: leverage per decision, agreement with the agent's suggestion, revert rate, backlog and age. Agreement and revert rates tune the gate.
Retired
- The lowconf and unconfirmed queues. Model-reported confidence is not calibrated; the unconfirmed state (evidence chunk superseded) becomes an automatic re-attach or re-extraction with an alert on failure.
- Write-time resolution:
resolve_mentionwithSIM_ATTACH,SIM_NEW,SIM_TIE_MARGIN,containment_reviews,resolve_type_drift,doc_cache, the no-embedding fallback; the batch adjudicator andresolution_verdicts. Identity becomes profiles, deterministic evidence with cannot-links, one agent path, constrained clustering (0044 decision 6). - Word lists and shape rules:
GENERIC_SUFFIXES_CJK,GENERIC_WORDS_EN,CORPORATE_SUFFIX,name_shape,type_family,CONFUSABLE_TYPE_KEYS,MAX_NAME_WORDS,CLAUSE_MARKERS,MODALS. Names come from name facts checked against the text; type conflicts from declared disjointness and the class hierarchy; described things are legitimate entities of the open graph. - The type machinery:
proposed_type,adopt/unadopt/sweep_proposed_types,type_refinement_pairs,type_resolution. Type words are open-graph facts; classes are ontology views bound by signature. - Predicate adoption from
proposed_predicate; proposals come from the ontology agent with definitions and signatures. - Mappings (0036) leave the Review page for the data-source side; they are configuration.
Removal of the resolution code waits until the identity design passes the identity bench and the Linked-Re-DocRED pairs.
Kept
agent_decisions, execution_gate, the temporal engine and its ledger rules, name facts (0041), pending_facts, the audit ledger, and the undo table of 0043 decision 4.
#699
Split three ways: the temporal engine fixes merge first (one govern run per base, facts judged over their dates, the tidy defect on relations unique on both sides); the conflict actions and their tests become the cross-document conflicts queue; the low-confidence handling and the per-queue dispatch are dropped. The five review findings on #699 are fixed in the rewrite (decisions repeating after a revert, decisions applied from a stale snapshot, one malformed reply blocking the queue, nodded facts rejected by the agent, the tidy defect).
Sequence
After 0044 cuts 1 and 2 (open graph in the ledger, signature bindings). No backfill and no legacy layer: there is no released version, so the upgrade may break.
Status 2026-10-22
Done on dev:
- Alignment queue (The aligner's open questions have a queue #754)
- Errata agent and its queue over typed facts (An errata agent reviews each document's typed facts, structure first, through the gate #885, migration 0074)
- Ontology proposals from the agent, with definitions and signatures (0061: The ontology is proposed from the open graph and judged by its questions: cut 1 #947, The ontology agent remembers what it has seen, and "already in the ontology" becomes a proposal (0061 cut 1.1) #950, The agent proposes questions for a base that has none, and the ontology is measured by two numbers (0061 cut 3, first slice) #955, The competency bench records whether an answer went through the graph (0061 cut 3, second slice) #962)
- Regression cases on adoption and the workbench view (Remember approved property examples so definition edits expose alignment regressions. #1178, Show property regression cases and their source evidence in the ontology workbench. #1184, Specify ontology regression cases that expect no property binding #1203; negative cases in A regression case can expect no binding while a person's binding remains authoritative #1334)
- Adoption commits the element, its follow-up jobs and the decision together (Adopting a proposal commits the element, its follow-up work and the decision together #1257)
Not done:
- Queues regrouped by what a decision changes (
Review.tsxQUEUE_ORDERis still pending, duplicates, conflicts, …) - Retire write-time resolution:
resolve_mention,SIM_ATTACH/SIM_NEW,containment_reviews,resolve_type_drift, the batch adjudicator — waits on the identity bench and 0044 d6 - Retire the word lists and shape rules (
GENERIC_WORDS_EN,GENERIC_SUFFIXES_CJK,CORPORATE_SUFFIX,name_shape,CONFUSABLE_TYPE_KEYS, …) - Retire the type machinery (
proposed_type,type_resolution, adoption fromproposed_predicate,ontology_misses; 0061 cut 4) - Mappings leave the Review page (Metric and Dimension retire, and a mapping is rendered from an alignment and a rule #556)
- The declined split (Maya-Kid's follow-up above)
Activity
Maya-Kid commentedon Sep 19, 2026
Moving the useful design material from #805 here as requested in review, and closing the draft PR. The intended workflow follows 0044 cut 5; it does not introduce another proposal platform.
A narrow first slice would use current, known-class relation signatures and their original statements to suggest reuse of an existing property, one new relation, insufficient evidence, or no ontology gap. Structural absence, model disagreement, overflow, and failure must stay distinguishable; a
nonebinding is not permission to create ontology automatically. #802 supplies the now-merged statement-count correction, not the proposal workflow itself.The existing ontology workbench should show the definition, server-resolved source excerpts, affected statement count, and direction for each signature. A human reviews, edits/adopts, or rejects. Adoption needs one atomic operation that rechecks current evidence/access and ontology inputs, creates or reuses the property through ordinary writers, records the reviewed bindings and adoption, and leaves durable recomputation work. “Approved”, “recomputation queued”, and “typed view ready” are different states. Open statements and human choices remain intact.
Decisions still needed: stable proposal identity, which changed inputs reopen a rejection, source-version/access handling, conflict behavior when another person creates a matching property, and the shared writer/acceptance protocol discussed in #795 and #807. Repeated adoption should be idempotent; repeated extraction should not undo a rejection.
The draft’s 18 synthetic cases across three domains were proposed evaluation inputs only: no runner consumed them and no model-quality result was established. I agree that checking JSONL into docs makes an unenforced intention, not a regression. If implementation proceeds, cases should live with runnable
scripts/bench/scoring for correct reuse versus unwanted additions, direction, and expected answer pairs. State-transition tests should separately cover stale/deleted sources, mixed evidence, rejection, concurrent adoption, and no effect before approval.No implementation or new contract is claimed here. A numbered decision record and executable evaluation should accompany the eventual cuts, rather than a new directory of unaccepted drafts.
WaylandYang commentedon Sep 25, 2026
The narrow first slice you describe is cut 5 of 0044 as intended, and the boundaries you state are the ones that matter: a
nonebinding is never permission to create ontology, and absence, disagreement, overflow and failure stay distinguishable in what the workbench shows. Since you wrote this, #906 gave the aligner a candidate shortlist and #913 gave rule definitions a history, so the suggestion has a version to name when it says "reuse this property".Go ahead as a PR with that scope: current known-class signatures and their statements, a suggestion of reuse, one new relation, insufficient evidence, or no gap, shown in the ontology workbench with definition, server-resolved excerpts, affected statement count and direction; adoption as one atomic operation that re-checks the current state, the way
decide_with_deliverydoes for phrase decisions. A person edits, adopts or rejects; nothing lands on its own.Maya-Kid commentedon Sep 27, 2026
Since the go-ahead above, 0061 has landed cut 1 (#947), cut 1.1 (#950) and the first two slices of cut 3 (#955, #962), with the glossary in #963 and #965. Reading the record, they cover most of the slice you described: proposals from unbound signatures with a definition, the motivating statements, the signatures they would bind and their counts; reuse as a
map_toproposal adopted as a person's binding per shape; adoption that writes the element and re-decides those signatures. Before I write anything: what of that scope is still open for a PR? Three points I cannot tell from the record are an explicitinsufficient evidence/no gapverdict per signature (a signature the agent proposes nothing for stays unbound without saying which), the direction of a reuse suggestion, and whether adoption already re-checks the current state as one operation, the waydecide_with_deliverydoes. If any of those is wanted I can take it; if you would rather have help on 0061's open cuts (cut 2, cut 4's regression cases, the packmap_toquestion), say which; and if nothing remains, this issue may be ready to close in favour of 0061.WaylandYang commentedon Oct 4, 2026
Sorry for the wait. Against the code on dev:
proposed,existing,declined), butdeclinedis one bucket and does not say whether the evidence was insufficient or there is no gap. Small and open.map_toshape carries its direction and adoption writes it as the person's binding.So please take the third, with the first if you like. After that, 0061 cut 2 (regression cases) is specified and open. This issue stays open: 0061 covers only its first row.
Maya-Kid commentedon Oct 15, 2026
Thanks @WaylandYang. I'll take adoption first, then the
declinedsplit as a small follow-up. 0061 cut 2 has moved since your comment (#1178 and #1184 by virtue039, with #1203 open), so I'll leave it there.Adoption, without a migration:
GET /ontology/proposalscarries aversion, a digest computed from the stored row (payload, shapes, questions served); nothing new is stored. Adopt and reject send back the version the person reviewed.embed_ontologyand alignment; a reuse queues what the review page queues for the same decisions. The embedding call leaves the request in place of cut 1.1's in-place refresh, and the design note changes with it, so adopting makes no model call; alignment already waits forembed_ontology, as it does after an editor change.proposal_changed(the card reloads),proposal_decided, orproposal_stalewhen the key was taken in the meantime, a class or the reused property it names no longer exists, or none of a reuse's shapes or kind words can still be written. A class reuse can still meet alignment's lock and answeralignment_busy, as the review page does. A shape or kind word a person decided after the proposal was last updated stays as they left it and is listed in the response.POST /ontology/proposalsno longer acceptsadopted.add_onrejects the example after the attribute is committed, which leaves an attribute that no proposal adopted, a queued alignment job, and a proposal whose key is now taken. After the change the same request writes nothing and answers 422bad_property_shape, and the proposal stays open for a person to reject.Undoing an adoption is not part of this.
Verdicts, one small PR with a migration: the prompt asks for a verdict on every shape, and
declinedsplits intoinsufficient,no_gap, anddeclinedfor no usable answer. All three come back when a shape's statements double, asdeclineddoes now. The counts show on the workbench and inagent.mjs, with a bench run of the prompt change.One question: should adopting the same version twice return the first result, so a retried request succeeds, or be refused, as the draft #1179 does for tables (409 when two requests race, 404 once the first has committed)? I would return the first result. Either way
create_entity_typeandcreate_relation_typechange exactly as in #1179, so either PR can land first; the two PRs also both edit the status-only POST handler.