[NOTICKET] feat(knowledge): review diff + the rule/domain boundary (r4, o2)

r4 `changed_fields()` and `review_diff()`. The queue can now say WHAT moved
rather than only that something did - which was the ask: show before /
after, do not send the expert back to read the entry from the start.
`changed` is empty when the approval still stands, so the screen can say
"nothing to re-read" instead of rendering two identical panes. `before` is
what the expert actually had in front of them; for an `edited` decision
that is their own corrected text, not the model's claim. A test pins
changed_fields() and has_mutated() to the same answer - two notions of
"has this changed" that can disagree is the same defect as two notions of
readiness.

o2 The rule/domain boundary, written down in the output contract. The two
blurred on screen during the 8 Sep review and a boundary nobody has
recorded is one the prompts cannot hold. The test: if removing it would
change how a NUMBER IS COMPUTED OR SOURCED it is a rule; if it would only
leave an agent less oriented it is domain. Grain settles the hard cases
faster than "high level" does - one document's sentence, or the corpus as
a whole. Where it is genuinely both, prefer rule: it carries a span an
expert can check.

Also marks section 6 as EXECUTED (2026-09-14, after the handoff went to Harry -
run by hand AND handed over, in that order) and adds section 7, NOT RUN: the
three columns r1/r2/r3 need. An entry approved with no human looking at it must
still record who allowed that, which is why it belongs in columns rather than a
free-text note.

Verified: ruff clean on both knowledge modules; 808 passed / 7 skipped (was
801+7, +7 new); import main exits 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/knowledge/KNOWLEDGE_OUTPUT_CONTRACT.md

@@ -85,6 +85,38 @@ registry, which belongs with persistence (DEV_PLAN §0.8 D2).
 
 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** —

docs/knowledge/knowledge_tables.sql

@@ -22,9 +22,10 @@
 -- Executed: 2026-09-07 · Idempotent (IF NOT EXISTS throughout) · Additive only:
 -- no DROP, no ALTER, nothing touching an existing table.
 --
--- ⚠️ Updated 2026-09-14: §1-§5 are LIVE and unchanged. A new **§6 at the end
--- is NOT run anywhere** — it is the column request from the 2026-09-08
--- discussion (m3, m4, m5, m8). Read the banner there before adopting.
+-- ⚠️ Updated 2026-09-14. §1-§5 LIVE and unchanged. §6 (m3/m4/m5/m8/i7) was
+-- EXECUTED against dedorch on 2026-09-14 by Rifqi, after the handoff had
+-- already been sent to Harry — run by hand AND handed over, in that order,
+-- which is the thing the banner above asks for. §7 is NOT run anywhere yet.
 
 -- 1. Parsed document artifact. Chunks live INSIDE `artifact` (jsonb), deliberately
 --    not a child table: documents are small (9 pages = 31 chunks) and the artifact
@@ -175,9 +176,11 @@ CREATE INDEX IF NOT EXISTS idx_knowledge_jobs_user ON knowledge_jobs (user_id, c
 
 
 -- ============================================================================
--- §6. NOT RUN ANYWHERE YET — from the 2026-09-08 discussion (m3, m4, m5, m8).
+-- §6. EXECUTED 2026-09-14 — from the 2026-09-08 discussion (m3, m4, m5, m8, i7).
 --
--- Everything above this line is live in dedorch. Everything below is a request.
+-- Verified after the run: 4 new columns and 2 new indexes present, and the
+-- ORM reads all of them against live. Harry still needs this in the
+-- migration set so a fresh environment reproduces it.
 --
 -- Additive only: three columns and one index on `knowledge_entries`. Nothing
 -- is dropped and no column changes type, so a pre-migration reader keeps
@@ -228,3 +231,38 @@ CREATE INDEX IF NOT EXISTS idx_knowledge_entries_key ON knowledge_entries (scope
 ALTER TABLE knowledge_documents ADD COLUMN IF NOT EXISTS withdrawn_at timestamptz;
 CREATE INDEX IF NOT EXISTS idx_knowledge_documents_live
     ON knowledge_documents (scope_id, doc_id) WHERE withdrawn_at IS NULL;
+
+
+-- ============================================================================
+-- §7. NOT RUN ANYWHERE YET — the review system (r1, r2, r3) from the
+--     2026-09-08 discussion.
+--
+-- Additive only: three columns, no drops, no type changes.
+--
+-- The point of these, in Mas's words: an entry approved without a human
+-- looking at it must still say WHO allowed that to happen. *"Kalau ada apa-apa
+-- jangan sampai kita yang disalahin… ya udah itu by mereka aja."* It is a
+-- risk-mitigation requirement, not bookkeeping — which is why it belongs in
+-- columns rather than in a free-text note.
+-- ============================================================================
+
+-- r1. Which review mode a batch was ingested under. Chosen by the caller at
+--     ingest time: 'expert' leaves entries waiting for a human; 'llm' takes
+--     them straight to approved with no reviewer step at all.
+--     Nullable so every job written before this column existed stays legal.
+ALTER TABLE knowledge_jobs ADD COLUMN IF NOT EXISTS review_mode text
+    CHECK (review_mode IS NULL OR review_mode IN ('expert','llm'));
+
+-- r2. WHO decided. 'human' is the existing behaviour and the default, so every
+--     review already recorded keeps its meaning without a backfill.
+ALTER TABLE knowledge_reviews ADD COLUMN IF NOT EXISTS decided_by text
+    NOT NULL DEFAULT 'human'
+    CHECK (decided_by IN ('human','llm'));
+
+-- r3. On WHOSE AUTHORITY. The admin who clicked ingest and the expert who
+--     reviews can be different people, and in 'llm' mode there is no reviewer
+--     at all — so the clicker's id has to reach this row or the decision has
+--     no owner. `reviewer_id` stays "who performed the review";
+--     `authorised_by` is "who permitted it to happen this way".
+--     Together they render: approved by LLM with permission of <person>.
+ALTER TABLE knowledge_reviews ADD COLUMN IF NOT EXISTS authorised_by text;

src/knowledge_extraction/mutation.py

@@ -83,6 +83,23 @@ def ruled_content(kind: str, payload: Mapping[str, Any] | None) -> dict[str, Any
     }
 
 
+def changed_fields(
+    kind: str,
+    reviewed: Mapping[str, Any] | None,
+    current: Mapping[str, Any] | None,
+) -> list[str]:
+    """Which ruled-on fields moved — the before/after a reviewer is shown (r4).
+
+    Same comparison as `has_mutated`, reported field by field so the queue can
+    say *what* changed instead of making the expert re-read the whole entry to
+    find out. That was the ask: show before / after, do not send them back to
+    the start.
+    """
+    before = ruled_content(kind, reviewed)
+    after = ruled_content(kind, current)
+    return [field for field in before if before[field] != after.get(field)]
+
+
 def has_mutated(
     kind: str,
     reviewed: Mapping[str, Any] | None,

src/knowledge_ingest/knowledge_store.py

@@ -555,6 +555,58 @@ class KnowledgeStore:
                 index.setdefault(row.label, row.payload)
         return index
 
+    async def review_diff(
+        self, scope_id: str, entity_id: str, kind: str = "glossary"
+    ) -> dict | None:
+        """Before / after for one entry, for the review screen (r4).
+
+        Returns None when there is nothing to compare — no decision on record,
+        or the entry is gone. `changed` is empty when the approval still
+        stands, which is the common case and the one worth making cheap: the
+        screen can say "nothing to re-read" instead of showing two identical
+        panes.
+
+        `before` is what the expert had in front of them; for an `edited`
+        decision that is their own corrected text, not the model's claim.
+        """
+        reviews = await self.latest_reviews(scope_id, [entity_id])
+        review = reviews.get(entity_id)
+        if review is None:
+            return None
+
+        rows = await self.list_entries(scope_id=scope_id, kind=kind, limit=1000)
+        current = next(
+            (r for r in sorted(rows, key=lambda r: r.created_at or 0, reverse=True)
+             if r.entity_id == entity_id),
+            None,
+        )
+        if current is None:
+            return None
+
+        if review.decision == "edited" and review.edited_payload:
+            before = review.edited_payload
+        else:
+            async with AsyncSessionLocal() as session:
+                result = await session.execute(
+                    select(KnowledgeEntryRow).where(
+                        KnowledgeEntryRow.id == review.entry_id
+                    )
+                )
+                reviewed_row = result.scalars().first()
+            before = reviewed_row.payload if reviewed_row else None
+
+        changed = mutation.changed_fields(kind, before, current.payload)
+        return {
+            "entity_id": entity_id,
+            "kind": kind,
+            "decision": review.decision,
+            "decided_at": review.created_at,
+            "changed": changed,
+            "status": "waiting_approval" if changed else review.decision,
+            "before": mutation.ruled_content(kind, before),
+            "after": mutation.ruled_content(kind, current.payload),
+        }
+
     async def withdraw_document(self, scope_id: str, doc_id: str) -> int:
         """Mark every version of a document withdrawn (i7). Returns how many.