docs/knowledge/KNOWLEDGE_OUTPUT_CONTRACT.md

Knowledge Pipeline — Output Contract v2

Implemented 2026-08-26. src/knowledge_extraction/ emits this shape. The schema review of 2026-08-26 landed with it: ids on every entity, formulas referenced rather than restated, rules linked to formulas and terms, and 16 fields cut.

Not yet re-measured. The prompt changes this required have not been scored — no source document, parsed artifact or MinerU install exists on the dev box (all three data/ directories are gitignored and absent), so the free stages have nothing to read. The last measured figures in §12 predate these edits. See §13.

Supersedes: v1 of this document (2026-08-24) Reference run: v2_full_document_2026-08-24_093051 · BUMA STD_2026_006_MNO · 9 pages · gpt-5.4-nano Producer: python -m src.knowledge_extraction.cli <artifact.json> --extract Status: offline artifacts only — no endpoint, no table.

---

0 · What changed from v1

Harry's review of v1 asked for entity ids, a formula reference instead of a restated formula, and a link between rules and formulas. All are adopted. The schema was also cut back — v1 carried fields nothing consumes.

Change	Detail
Ids on every entity	term_id, formula_id, brief_id; rule_id re-specified. All deterministic and content-derived
Glossary no longer restates formulas	formula_latex removed → defining_formula_id reference
Rules link to formulas and terms	formula_ids[], term_ids[]
rule_type added	interpretation | calculation — see §2 for why
16 fields cut, 8 added	50 → 42 fields total
chunk_id separator fixed	DOC#0007 → DOC::0007, adopting the parser's format
Reference numbers corrected	v1 quoted a superseded run (13 chunks / 66 clusters). Current is 31 chunks / 58 clusters

Why the ids had to be re-specified

Neither id in v1 survived a re-run. cluster_id was a frequency-rank ordinal (f"{doc_id}#c{i:03d}" over a list sorted by mention count), and rule_id was written by the model (rule.txt asks for SCREAMING_SNAKE_CASE). Either way, re-running with a tuned prompt reshuffles the ids — and if an expert has approved 40 entries, we have lost which 40.

Approval continuity, not linking, is the real reason these exist.

---

1 · Id scheme

All ids are deterministic, content-derived, and stable across re-runs of the same document. None is model-generated; none is positional.

term_id     = "t_" + sha256(doc_id + "|" + canonical)[:10]
formula_id  = "f_" + sha256(doc_id + "|" + name_or_latex_or_chunk_id)[:10]
rule_id     = "r_" + sha256(doc_id + "|" + chunk_id + "|" + char_start)[:10]
brief_id    = "b_" + sha256(doc_id)[:10]    # per-document card; `d_` belongs to the
                                            # scope-level DomainContext in src/knowledge_domain/

Implemented in src/knowledge_extraction/ids.py. term_id is keyed on the cluster canonical, not on the term the model returned — the cluster is the stable thing across runs, and the model is free to answer "PA" or "Physical Availability" for the same cluster. formula_id falls back through name → formula_latex → chunk_id, because both of the first two are Optional and without the fallback every unnamed formula in a document would collide.

Scope is per document. The same term appearing in two documents receives two different term_ids. Deciding that BUMA's "PA" and a textbook's "PA" are the same concept is an expert judgement at review time, not something the pipeline asserts — the same reasoning that makes the pipeline record "Physical of Availability" instead of normalising it, and the reason MTTR at BUMA (breakdown duration ÷ breakdown frequency) must not silently merge with MTTR in IT.

Known limit. Ids derive from content, so if content changes the id changes — retune clustering such that a term canonicalises differently and its term_id moves. The alternative is a persisted registry, which belongs with persistence (DEV_PLAN §0.8 D2).

---

2 · The four artifacts

File	Entity	Holds
glossary.json	GlossaryEntry[]	Terms and their definitions
rules.json	RuleEntry[]	Rules of thumb — how to interpret data or behaviour. Renamed from interpretation_pack.json 2026-09-08 — the file, the entity and the DB kind now share one name. The Interpretation Pack remains the deliverable's name in prose
formulas.json	FormulaEntry[]	Formulas, transcribed from the document
document_brief.json	DocumentBrief	One per-document card. Prefix history, not churn: b_ (BriefContext) -> d_ (DomainContext, 2026-09-01) -> b_ again (DocumentBrief, 2026-09-08), once v4 gave d_ to the real scope-level DomainContext in src/knowledge_domain/

Plus three derived/audit payloads: review_queue.json, rejected.json, usage.json.

Rule vs domain knowledge — where the line is

Added 2026-09-14 (o2). The two blurred on screen during the 2026-09-08 review, and a boundary nobody has written down is one the prompts cannot hold.

	rule	domain
Grain	One statement, from one document	One per company, composed across all of them
Shape	A condition and a consequence	Identity, boundary, conventions, measures
Evidence	Span-checked against its source	Derived from entries, or expert-declared
Answers	"…and how do I compute this correctly?"	"…what does this company measure, and what does it call it?"

The test to apply. If removing it would change how a number is computed or sourced, it is a rule — "if joint-survey data is unavailable, use truck count" changes the figure. If removing it would only leave an agent less oriented — not knowing that this company works in overburden and BCM — it is domain.

Two consequences worth stating, because they are what the distinction is for:

• A rule is actionable alone; domain knowledge is not. A planner can apply a rule to a specific calculation. It cannot apply "this is a mining company" to anything — that shapes which questions make sense, not which column to sum.
• Domain is high-level and rules are specific, but "high-level" is not the test. A long, general rule is still a rule. The grain question — does this come from one document's sentence, or from the corpus as a whole? — settles it faster and does not drift.

Where it is genuinely both, prefer the rule: it carries provenance and a span, so an expert can check it. Domain fields are the ones the pipeline can least easily prove.

Why RuleEntry carries a rule_type

The Interpretation Pack exists to improve analytics insight from expert interpretation rules — interpretation logic, action benchmarks, and rules for when to conclude or not conclude from data.

Measured against the reference document, 0 of the 15 gold rules are interpretation rules. They are calculation conventions (PA_COMPOSITE_WEIGHTED), data-sourcing rules (PTY_PRODUCTION_SOURCE), and unit conventions (GAINLOSS_UNITS). This is a property of the document type: a Standard Parameter document defines how to calculate parameters, not how to read them. Interpretation rules live in other document types, or in the expert's head.

rule_type keeps both in one artifact rather than discarding the conventions we do extract:

• interpretation — how to read a value or behaviour. The target.
• calculation — how a value is computed or sourced. What this corpus actually yields.

A consumer wanting only interpretation logic filters on rule_type.

---

2c · Evidence now carries figures and tables (parsing 0.4.0, 2026-09-10)

The artifact this half consumes changed shape: a figure is no longer its own chunk. It is folded into the prose chunk at its reading-order position as ![](asset://<id>), and travels as an Asset on that chunk. adapter.py carries assets, referenced_by and table_html across; evidence_block renders them into the prompt under ASSETS REFERENCED BY THIS CHUNK.

What that means for an extraction branch, and the distinction is enforced in the prompts:

	may be quoted?	may be a provenance span?
Asset.caption — printed in the document	yes	yes
Asset.description — written by a vision model	no	no — it is not in the document, so the span check rejects it and the field is discarded

Why it mattered: before 0.4.0 a figure chunk had an EMPTY text, so it produced no mentions, joined no cluster, and was never selected as evidence. 13 figures across three documents, each already described by a paid vision call, reached zero prompts. Full detail: knowledge_pipeline_runs/CHANGELOG_v2.md §2.

✅ RESOLVED 2026-09-11 — §1, §2 and §8 now match the code. The note is kept for the record.

⚠️ Correction to §8 of this document (noted 2026-09-10). The code writes document_brief.json with brief_id and a b_ prefix; §8 below documents domain_context.json with domain_id and d_. The v3 rename was partly reverted for the per-document object once the scope-level DomainContext became a separate thing in src/knowledge_domain/. §8 does not describe what the code emits. Worth one edit, and it matters because entity_id prefixes are the key an expert's approvals hang on.

---

3 · Transport reality

Every payload is written by the CLI as a file into --out-dir (default out/knowledge/), as a bare JSON array with no envelope. There is no endpoint and no table.

Three conventions hold across every payload:

• page is 0-based, exactly as the parser reports; page_no is the 1-based number a human reads and is what a review UI binds to. Both travel together on every entity, derived from one value so they cannot disagree (S6b, 2026-09-02).
• All content fields are nullable by design. null is a valid, correct answer — the model abstaining, not failing. On the reference run 48 of 58 entries carry no definition.
• provenance is mandatory and provenance.span is verbatim-checked. A field whose span cannot be located in the source is set to null and logged to rejected.json — never repaired.

---

4 · Common types

Provenance — required on every entity

{
  "doc_id": "STD_2026_006_MNO",
  "span": "Adalah jumlah equipment/unit yang digunakan untuk menghasilkan produksi dalam suatu periode.",
  "page": 3,
  "page_no": 4,
  "section_no": "2.1.2",
  "chunk_id": "STD_2026_006_MNO::0007"
}

Field	Type	Req	Notes
doc_id	string	✅
span	string	✅	Verbatim from the source. The anti-hallucination control — the reviewer checks a quote against a page, not a claim against memory
page	int | null	—	0-based, exactly as the parser reports
page_no	int | null	—	1-based. Added 2026-09-02 (S6b). DERIVED from page, never stored, so it cannot drift. A review UI must render this one — an off-by-one is invisible until an expert opens the wrong page and concludes the provenance is wrong. null when page is unknown
section_no	string | null	—	e.g. "2.1.2"; null when the document is unnumbered
chunk_id	string | null	—	Back-reference into the parsed artifact. Format <doc_id>::<seq>, matching KNOWLEDGE_PARSING_OUTPUT_CONTRACT.md. Treat as opaque — do not split it

Enums

Enum	Values
subdomain_tags[]	production · maintenance · hauling · loading · drilling_blasting · equipment · safety · quality · planning · cost · geology · other
extraction_status	ok · no_definition_found · escalated
diff_status	new · duplicate · conflicting
rule_type	interpretation · calculation
latex_verification	verified · unverified_no_markup · unverified_operator

subdomain_tags is a closed enum — classification, not generation. Adding a member changes what the model is allowed to answer, which makes it a prompt change, not a data change.

---

5 · glossary.json → GlossaryEntry[] — 13 fields

[
  {
    "term_id": "t_9f2a41c0b7",
    "term": "Qty",
    "full_name": "Quantity",
    "source_wording": "2.1.2. Quantity (Qty)",
    "definition": "Adalah jumlah equipment/unit yang digunakan untuk menghasilkan produksi dalam suatu periode.",
    "defining_formula_id": "f_31de08aa95",
    "subdomain_tags": ["production", "equipment"],
    "mention_count": 20,
    "provenance": {
      "doc_id": "STD_2026_006_MNO",
      "span": "Adalah jumlah equipment/unit yang digunakan untuk menghasilkan produksi dalam suatu periode.",
      "page": 3,
      "section_no": "2.1.2",
      "chunk_id": "STD_2026_006_MNO::0007"
    },
    "extraction_status": "ok",
    "diff_status": "new",
    "definition_conflict": false,
    "conflict_variants": []
  },
  {
    "term_id": "t_5b71ce0d34",
    "term": "Gain/Loss",
    "full_name": null,
    "source_wording": null,
    "definition": null,
    "defining_formula_id": null,
    "subdomain_tags": ["production"],
    "mention_count": 4,
    "provenance": {
      "doc_id": "STD_2026_006_MNO",
      "span": "Gain/Loss",
      "page": 6,
      "section_no": null,
      "chunk_id": "STD_2026_006_MNO::0011"
    },
    "extraction_status": "no_definition_found",
    "diff_status": "new",
    "definition_conflict": false,
    "conflict_variants": []
  }
]

Field	Type	Req	Notes
term_id	string	✅	New in v2. Stable across re-runs — the key an approval hangs on
term	string	✅	The only required content field
full_name	string | null	—	Expanded name. Span-guarded as a literal transcription
source_wording	string | null	—	The document's literal wording, un-normalised. Read deterministically from the section heading, not asked of the model — asked directly, it returned the tidied form
definition	string | null	—	null = correct abstention (48 of 58 on the reference run)
defining_formula_id	string | null	—	New in v2, replaces formula_latex. The formula that defines this term. Null when the formula branch did not extract one
subdomain_tags	enum[]	✅	Defaults []
mention_count	int	✅	Default 0. Drives review-queue ordering
provenance	Provenance	✅
extraction_status	enum	✅	Default ok
diff_status	enum | null	—	Set by the diff stage against the active glossary version
definition_conflict	bool	✅	Default false
conflict_variants	string[]	✅	Default []. The competing definitions — the pipeline never picks a winner

Removed in v2: formula_latex (→ defining_formula_id) · interpretation (belongs in the Interpretation Pack, reached via term_id) · domain · company · language.

domain and company were never in the extraction prompt's field guide — the model filled them by copying worked examples — and neither was span-guarded, so a wrong value was undetectable. language is a genuine three-value field (id/en/mixed) but nothing consumes it and it is recoverable from the document; it is cut for simplicity and can return if a consumer needs it.

Writer split. The LLM fills only term, full_name, definition and subdomain_tags. term_id, defining_formula_id, source_wording, mention_count, extraction_status, diff_status, definition_conflict and conflict_variants are all set by deterministic code — the model never writes its own ids, links or audit fields, so none of them can be hallucinated.

---

6 · rules.json → RuleEntry[] — 8 fields

[
  {
    "rule_id": "r_c07be41f22",
    "rule_type": "calculation",
    "statement": "Production yang digunakan dalam perhitungan adalah produksi hasil joint survey.",
    "condition": "Apabila data joint survey belum tersedia",
    "consequence": "maka digunakan data produksi berdasarkan truck count sebagai dasar perhitungan",
    "formula_ids": ["f_77c1ab9e40"],
    "term_ids": ["t_a4e2f81b06"],
    "provenance": {
      "doc_id": "STD_2026_006_MNO",
      "span": "Apabila data joint survey belum tersedia maka digunakan data produksi berdasarkan truck count sebagai dasar perhitungan",
      "page": 4,
      "section_no": "2.1.5",
      "chunk_id": "STD_2026_006_MNO::0009"
    }
  }
]

Field	Type	Req	Notes
rule_id	string	✅	Re-specified in v2. Was written by the model, therefore unstable; now deterministic
rule_type	enum	✅	interpretation | calculation — see §2
statement	string | null	—	The rule as prose. Prose, not an equation — evidence carrying both yields the prose, and the equation goes to the formula branch
condition	string | null	—	The triggering condition, split out — not left buried in prose
consequence	string | null	—	What follows when the condition holds
formula_ids	string[]	✅	New in v2. The formulas this rule constrains. Default []
term_ids	string[]	✅	New in v2. The terms this rule governs. Default []
provenance	Provenance	✅

Removed in v2: applies_to (free text → term_ids[]) · subdomain_tags · language · extraction_status.

condition + consequence is the point of this artifact, and the seed of the interpretation logic tree: a rule stored as one paragraph cannot be attached to a skill later; a trigger and its consequence can.

Deliberately not modelled yet: the interpretation logic tree, action benchmarks, and explicit conclude / do-not-conclude verdicts. Those are the direction of travel, but designing their schema against zero real examples would be guessing. They land when a document containing them does.

---

7 · formulas.json → FormulaEntry[] — 7 fields

[
  {
    "formula_id": "f_77c1ab9e40",
    "name": "Production",
    "formula_latex": "Production = MOHH \\times Qty \\times PA \\times UA \\times Pty",
    "variables": [
      { "symbol": "MOHH", "term_id": "t_1c9d5e7a83", "meaning": "Machine on Hand Hours" },
      { "symbol": "Qty",  "term_id": "t_9f2a41c0b7", "meaning": "Quantity" },
      { "symbol": "PA",   "term_id": "t_a4e2f81b06", "meaning": "Physical Availability" },
      { "symbol": "UA",   "term_id": "t_6d40b2fc17", "meaning": "Utilization of Availability" },
      { "symbol": "Pty",  "term_id": "t_e8b3092d55", "meaning": "Productivity" }
    ],
    "unit": "BCM",
    "latex_verification": "unverified_operator",
    "provenance": {
      "doc_id": "STD_2026_006_MNO",
      "span": "Production = MOHH x Qty x PA x UA x Pty",
      "page": 1,
      "section_no": "2.1",
      "chunk_id": "STD_2026_006_MNO::0003"
    }
  }
]

Field	Type	Req	Notes
formula_id	string	✅	New in v2
name	string | null	—	What the formula computes, as named in the source
formula_latex	string | null	—	Transcribed, never derived. The pipeline copies what the document states
variables[]	object[]	✅	{ symbol (required), term_id | null, meaning | null }. term_id is new in v2
unit	string | null	—	Result unit if stated
latex_verification	enum | null	—	Added 2026-08-26. Which guarantee formula_latex actually carries. Set by the span check, never by the model. null when there is no formula_latex to characterise
provenance	Provenance	✅

Removed in v2: extraction_status.

Read latex_verification before trusting formula_latex. Three paths leave the field populated and they are not equally strong. verified means the transcription was located in the source markup (Chunk.latex), compared in a notation-aware canonical form. The two unverified_* values mean the claim could not be checked either way and the entry is guarded by its provenance span alone — the same guarantee everything carried before 2026-08-26.

unverified_operator is not rare. MinerU's pipeline backend transcribes multiplication as a bare letter x, so every product formula from such an artifact lands here — including the sample above. An artifact parsed with hybrid/high carries \times and verifies normally.

variables[].symbol is not always a legend abbreviation — the extraction prompt's own worked example emits "Total Hours" and "Breakdown" as symbols. So term_id resolution is best-effort and nulls are expected; the link stage reports its dangle rate rather than hiding it.

---

8 · document_brief.json → DocumentBrief — 6 fields (single object)

✅ The v3 reshape is complete, corrected 2026-09-08. This banner previously said the LLM-facing parts — purpose as a span-guarded verbatim quote, and the subdomains aggregate — were "still proposed and not built". They shipped on 2026-09-02 and the banner was never updated, so it contradicted the field table directly below it, which dates both changes. Verified live: a domain entry persisted on 2026-09-07 carries purpose_verbatim and subdomains.

The delivery really was split, and that part was deliberate: the deterministic half (outline read off the artifact, key_parameters corroborated against extracted terms) shipped first because it costs nothing to prove, and the LLM-facing half followed once an eval run could pay for itself.

{
  "brief_id": "d_2ef60a8c19",
  "title": "Standard Parameter Produksi & ECA",
  "purpose_verbatim": "Standard Parameter ini merupakan pedoman dalam perhitungan parameter produksi yang meliputi Quantity (Qty) Physical Availability (PA), Utilization of Availability (UA), Productivity (PTY), serta Equipment Capacity Analysis (ECA).",
  "outline": [
    "1. TUJUAN PARAMETER",
    "2.1.2. Quantity (Qty)",
    "2.1.3. Physical of Availability (PA)",
    "2.2. Equipment Capacity Analysis (ECA)"
  ],
  "key_parameters": [
    {"surface": "Physical Availability (PA)", "term_id": "t_8c7359e27f"},
    {"surface": "Equipment Capacity Analysis (ECA)", "term_id": null}
  ],
  "subdomains": ["equipment", "production"],
  "n_terms": 5,
  "n_formulas": 6,
  "n_rules": 0,
  "provenance": {
    "doc_id": "STD_2026_006_MNO",
    "span": "Standard Parameter ini merupakan pedoman dalam perhitungan parameter produksi",
    "page": 0,
    "section_no": "1",
    "chunk_id": "STD_2026_006_MNO::0000"
  }
}

Field	Type	Req
brief_id	string	✅ New in v2. b_ prefix — reconciled with the code 2026-09-11
title	string | null	—
purpose_verbatim	string | null	— Renamed + guarded 2026-09-02 (was purpose)
outline	string[]	✅ Default []. Added 2026-09-02
subdomains	SubdomainEnum[]	✅ Default []. Added 2026-09-02
n_terms · n_formulas · n_rules	int	✅ Default 0. Added 2026-09-02
key_parameters	KeyParameter[]	✅ Default []. Shape changed 2026-09-02 — was string[]
provenance	Provenance	✅

KeyParameter — {surface: string, term_id: string | null}. surface is what the model named; term_id is the glossary term that corroborates it, resolved deterministically by link.py. A null term_id means nothing in the extracted glossary supports that name — reported, never guessed, and it earns its own review_queue.json row (§9). Dangle count is reported as key_parameters_unresolved.

subdomains is AGGREGATED from the glossary entries' own subdomain_tags, never asked of the model — each tag was already chosen once, per term, with that term's evidence in front of the model, and a second document-level classification would be the same judgement made with less context and no way to check it. Ordered by tag frequency descending, alphabetical tiebreak, so two runs of one document agree. n_terms / n_formulas / n_rules are counts of the other three artifacts, computed after every branch and the diff have run.

outline is DERIVED from the artifact's heading_path, in reading order, de-duplicated. No LLM and no spend. It carries the strong guarantee the rest of this entry cannot: it is verbatim source structure, so there is nothing to hallucinate — including wording a reader would be tempted to fix (the reference document heads a section "Physical of Availability (PA)"). Empty is normal for a document with no headings.

Removed in v2: scope (overlaps purpose, frequently null) · summary_md.

✅ This branch is span-checked as of 2026-09-02. It used to be the one exception: it asked the model to SUMMARISE, and a summary is not verbatim by construction, so the primary anti-hallucination control could not apply. It now asks the model to locate — purpose_verbatim is the document's own statement of purpose, copied, not a sentence composed about it — so title and purpose_verbatim are guarded like any other transcription. A value that is not verbatim is nulled and recorded in rejected.json, never repaired.

Measured on the reference document: 0 fields rejected, and a deliberately fabricated purpose is refused with purpose_verbatim is not a verbatim transcription of the source.

Two consequences worth knowing. title will look wrong sometimes and that is correct — the reference document yields "BUMA | STANDARD PARAMETERProduction Parameter andEquipment Capacity Analysis (ECA)", missing spaces and all, because that is what the PDF says; tidying it is the UI's job at display time, never the pipeline's. And this weakens the case that the branch needs a larger model tier (DEV_PLAN §0.8 D3, risk R5): locating a sentence is a much smaller ask than composing one.

---

9 · review_queue.json → ReviewQueueRow[] — 12 fields

This is the consumption surface — the payload a review UI binds to. Deliberately denormalised so a row renders with no joins.

⚠️ Changed 2026-09-02: the queue is no longer glossary-only. Every row now carries row_kind, and a consumer must switch on it rather than assume every row is a term. A key_parameter row has a surface and no term_id, no definition and no mention count — a client that binds term_id unconditionally will break on it.

[
  {
    "rank": 1,
    "row_kind": "term",
    "term_id": "t_a4e2f81b06",
    "term": "PA",
    "definition": "Adalah ketersediaan fisik suatu equipment/unit yang menunjukkan proporsi waktu equipment/unit tersebut berada pada kondisi available (siap pakai) selama suatu periode tertentu.",
    "source_wording": "2.1.3. Physical of Availability (PA)",
    "mention_count": 43,
    "page": 3,
    "section_no": "2.1.3",
    "span": "Adalah ketersediaan fisik suatu equipment/unit",
    "review_reason": "source wording differs from the expanded name — confirm which is correct"
  },
  {
    "rank": 2,
    "row_kind": "key_parameter",
    "term_id": null,
    "brief_id": "d_2ef60a8c19",
    "term": "Grouping (Composite)",
    "definition": null,
    "source_wording": null,
    "mention_count": 0,
    "page": 0,
    "section_no": "1",
    "span": "Standard Parameter ini merupakan pedoman dalam perhitungan parameter produksi",
    "review_reason": "named as a key parameter but no extracted term corroborates it — confirm it is real"
  }
]

Field	Type	Req	Notes
rank	int	✅	1-based display order — see sorting below
row_kind	term | key_parameter	✅	New 2026-09-02. Switch on this before reading anything else
term_id	string | null	✅	New in v2. What an approve / edit / reject decision attaches to, so it survives a re-run. Null on a key_parameter row — that it resolves to no term is the reason the row exists
brief_id	string	—	key_parameter rows only — what the decision attaches to instead. Named brief_id on the wire, not domain_id; see the correction under Sort order
surface_full	string | null	—	key_parameter rows only. New 2026-09-11. The untruncated surface when term had to be shortened to a head; null when it did not
term · definition · source_wording · mention_count			Copied from the entry
page · page_no · section_no · span			Lifted out of provenance so a row is self-contained. Render page_no (1-based), not page
review_reason	string	✅	Human-readable, one of five

Removed in v2: extraction_status · diff_status · definition_conflict · conflict_variants — all four are already expressed by review_reason, and remain available on the entry itself.

Sort order — changed 2026-09-11. (conflicts, then mention_count descending, with unresolved key parameters spliced in at most one per five term rows).

Conflicts still outrank everything, because a contradiction is a decision only the expert can make. What changed is the tier beneath them. Unresolved key parameters used to occupy one, which meant every unresolved parameter outranked every routine term regardless of how many there were — and the branch produces them in bulk on exactly the documents it understands least. On the Komatsu shop manual that was 24 junk rows standing in front of Engine, a term with 108 mentions, which sat at rank 25.

The original reason for promoting them is preserved and is still sound: that branch has no span check at all, so an unresolvable surface is the one hallucination signal it can raise, and it must not sink beneath sixty routine rows where nobody reaches it. A cap expresses that without letting the tail take the queue over. Measured by replaying the three persisted v2 runs:

Document	unresolved key parameters	first one at rank	top term, rank
BUMA	0	—	Qty 1 → 1 (unchanged)
Komatsu	24	1 → 6	Engine 25 → 1
Open Pit	7	1 → 6	Resource 8 → 1

Row counts are identical before and after on all three — nothing is dropped; parameters the splice cannot place are appended rather than discarded.

Also new on key_parameter rows: surface_full. The branch is supposed to return a parameter name and on a textbook it returns the right concept wrapped in its whole defining sentence (185 characters, in one measured case). term now carries a head — split at the first ., : or newline — and surface_full carries the untruncated text, or null when no shortening was needed. The head is only taken past 60 characters, which is what keeps a legitimate short name containing a period ("No. of units") intact.

⚠️ Field-name correction, 2026-09-11. This document described the key_parameter row's owning id as domain_id. The code emits brief_id and always has: the K12 rename changed the entity from BriefContext to DomainContext but left the id field's name alone, deliberately — renaming it is a migration that invalidates every expert approval recorded against the old prefix. The wire field is brief_id. Corrected here rather than in code, per the trust order.

review_reason values:

Value	Meaning
conflicting definitions — expert decision required	Contradiction found; the pipeline picked no winner
source wording differs from the expanded name — confirm which is correct	e.g. "Physical of Availability" vs "Physical Availability"
term found but no definition in document	Correct abstention — 48 of 58 on the reference run
definition rejected by span check or absent	Control fired; see rejected.json
routine confirmation	Nothing anomalous
named as a key parameter but no extracted term corroborates it — confirm it is real	key_parameter rows only. Added 2026-09-02

---

10 · Linking model

GlossaryEntry is the hub. Every link is computed after both branches run, by a deterministic never-throw link stage. No additional LLM calls, and nothing a model could fabricate.

RuleEntry ──term_ids[]────────► GlossaryEntry ◄──variables[].term_id── FormulaEntry
     └────formula_ids[]──────────────────────────────────────────────────────► ▲
                          GlossaryEntry ──defining_formula_id───────────────────┘

Two properties that must hold:

1. A dangling link is null or an empty array — never a fabrication. Same rule as spans.
2. The "appears in" edge is derived, not stored. That PA appears inside Production = MOHH × Qty × PA × UA × Pty is recoverable by scanning formulas[].variables[]. Do not add a field for it.

---

11 · Audit payloads — unchanged from v1

rejected.json → RejectedField[] — what the span check caught, kept so a reviewer sees the control working, not only what it let through. The reference run rejected 2 fields.

[
  {
    "entry_term": "<term>",
    "field": "full_name",
    "offending_value": "<value the model returned>",
    "reason": "full_name is not a verbatim transcription of the source",
    "branch": "glossary"
  }
]

Field	Type	Req
entry_term	string	✅
field	string	✅
offending_value	string	✅
reason	string	✅
branch	glossary | rule | formula | summary	✅

usage.json → CallUsage[] — per-call accounting. cached_tokens is read from the API, never modelled: caching does not engage below 1024 prompt tokens, so assuming it would understate input cost by roughly 10×.

[
  {
    "branch": "glossary",
    "deployment": "gpt-5.4-nano",
    "tier": "nano",
    "prompt_tokens": 2676,
    "cached_tokens": 2389,
    "completion_tokens": 214,
    "latency_s": 3.4,
    "retries": 0,
    "structured_output_mode": "json_schema",
    "simulated": false
  }
]

simulated: true marks a --mock run — never a quality measurement.

---

12 · Reference run — real figures

From eval/knowledge/results/v2_full_document_2026-08-24_093051.json. The parsing module built the artifact; extraction ran all four branches.

Artifact	schema_version 0.2.0 · 31 chunks · 9 pages · mineru/pipeline 3.4.4
Funnel	188 raw mentions → 163 after noise → 58 clusters (compression 2.81×)
Entries	58 glossary · 8 rules · 6 formulas
LLM	77 calls · 139,283 prompt tokens · 79.6% cached · 168.4 s
Quality	48 abstained, 10 with a definition · 2 fields rejected by the span check
E1 term-filter recall	0.8049 (kill line 0.70, PASS)
E3 schema-fill precision	0.90 (kill line 0.80, PASS — the prototype failed this at 0.75)

v1 of this contract quoted 13 chunks / 66 clusters / 66 entries. That run predates the section-aware chunker. Anything calibrated against those figures should be re-checked.

These figures also predate the v2 schema itself: they were measured on the v1 prompts, which asked for fields that no longer exist. The funnel counts (chunks, clusters, calls) should carry over unchanged — the filter, cluster and rank stages were not touched — but E3 must be re-scored, because trimming a prompt can move definition quality even when the scored fields are unchanged.

---

13 · Open items

#	Item	Owner
1	Unevaluated. Cutting interpretation / formula_latex and adding rule_type are prompt changes, and no eval has run against them — there is no document or parsed artifact on the dev box to run one. Same position X20 was committed in, and it needs the same first paid run to clear	Rifqi
2	Rule-branch quality is a separate track. The branch measures 3/15, an unevaluated prompt fix is already in flight (X20), and a prompt/gold contradiction caps it at 14/15 (X23). rule_type and the X23 de-contamination make this the third and fourth uncommitted-to-measurement changes on that one prompt — the first paid run measures the prompt as a whole, and isolating any single edit would cost one full run each. Expect the raw score to move in both directions: X20 should add rules back, X23 removes a free hit (example 1 was gold PTY_PRODUCTION_SOURCE verbatim) and lifts the 14/15 ceiling	Rifqi
2b	rule.txt grew again. X20 already pushed it past the 1024-token cache floor; example 4 adds more. Only the API's cached_tokens proves a hit — verify on the first paid run	Rifqi
3	Persistence. Stage output is JSON on disk; parsed artifacts, candidate entries, glossary versions and the approval audit trail still need one consolidated DDL handoff. Go owns the schema — Python never executes DDL	Rifqi → Harry
4	Page indexing at the API boundary — stays 0-based to the UI, or converts once at the boundary? Currently 0-based everywhere	Harry + Rifqi
5	Endpoint shape — four endpoints, or one with an ?artifact= parameter? Not started; the offline CLI is the honest first milestone	Rifqi

---

Caveat on the sample values

Field shapes, types and defaults are the agreed v2 target. Run-level figures in §12 are literal, from the cited result file. The per-entity sample values are illustrative — the underlying out/*.json from that run is not in version control, and all *_id values shown are placeholders that demonstrate format, not real hashes. Replace them with literal output once v2 is implemented and a run exists.