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]

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
interpretation_pack.json	RuleEntry[]	Rules of thumb — how to interpret data or behaviour
formulas.json	FormulaEntry[]	Formulas, transcribed from the document
brief_context.json	BriefContext	One orientation brief per document

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

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.

---

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. Converting to 1-based is the UI's job, done once at display time.
• 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,
  "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
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 · interpretation_pack.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 · brief_context.json → BriefContext — 5 fields (single object)

{
  "brief_id": "b_2ef60a8c19",
  "title": "Standard Parameter Produksi & ECA",
  "purpose": "Standard Parameter ini merupakan pedoman dalam perhitungan parameter produksi yang meliputi Qty, PA, UA, PTY, serta Equipment Capacity Analysis (ECA)...",
  "key_parameters": ["Qty", "PA", "UA", "PTY", "ECA", "Grouping (Composite)"],
  "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
title	string | null	—
purpose	string | null	—
key_parameters	string[]	✅ Default []
provenance	Provenance	✅

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

⚠️ The only branch that cannot be span-checked. A summary is not verbatim by construction, so the primary anti-hallucination control does not apply — a plausible summary is indistinguishable from a correct one. That is why summary_md is cut (longest unverifiable prose on the least verifiable branch), why this branch belongs on a larger model tier when one is provisioned (DEV_PLAN §0.8 D3), and why a reviewer should treat this artifact differently from the other three.

---

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

This is the consumption surface — the payload a review UI binds to. A flattened projection of glossary.json, deliberately denormalised so a row renders with no joins.

[
  {
    "rank": 1,
    "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"
  }
]

Field	Type	Req	Notes
rank	int	✅	1-based display order — see sorting below
term_id	string	✅	New in v2. What an approve / edit / reject decision attaches to, so it survives a re-run
term · definition · source_wording · mention_count			Copied from the entry
page · section_no · span			Lifted out of provenance so a row is self-contained
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 — (conflicting first, then mention_count descending). Conflicts outrank frequency unconditionally, because a contradiction is a decision only the expert can make.

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

---

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.