kmint

The Assertion ingestion engine — one installable, one console script (kmint) that executes the URBA-0003 micro-decision lifecycle as graph + lake mutations. It is the write engine of the sovereign Knowledge map's Assertion face; kledger is the read appliance it writes into.

Implements ADR-TECH-STRAT-001 (§"kmint — the Assertion ingestion engine") and ADR-TECH-STRAT-004 (the 5-state / 4-event machine + actor model), both in banking-knowledge.

Where kmint sits

kmint is to Assertion what kpack is to packaging: a single shared engine, run against a running kledger appliance over the same env-var substrate contract (NEO4J_*, S3_*). It does not import kledger; the appliance owns schema application and the read path.

The lifecycle it executes (the URBA-0003 spine)

S0 Capture   →  S1 Distillation (N→1)  →  S2 Refinement  →  S3 Archival / Purge

• S0 Capture — store verbatim bytes in the immutable lake (content-addressed by checksum), mint a :Capture + :Capturing activity. Bytes are immutable from here.
• S1 Distillation — read 1..N sources (:Capture, the Published corpus, prior candidates) and mint a brand-new :MicroDecision in SubmittedForRefinement (sources never mutated), DERIVED_FROM all of them, GENERATED_BY a :Distillation carrying the disposition. Non-Candidate dispositions are recorded but do not advance. Idempotent on contentHash = sha256(text + sorted(lineage)) + the sequential id.
• S2 Refinement — SubmittedForRefinement → Published, gated by the transition policy. Only the deterministic actor may auto-advance; everything else is human-gated (a recorded validator basis is required). Human refinement adds VALIDATED_BY without changing primalProvider (provider ≠ validator).
• S3 Archival / Purge — supersede/amend (prior → Archived, on a temporal or authority axis) or end-of-retention (Purged tombstone). Never deletes.

Three distillation modes behind one interface

Selected by the source-type binding (URBA-0004), one per transition actor: deterministic (the :Script actor — reproducible, audited, may auto-advance) / llm (LLM-bounded, defaults to human-gated) / human (human-gated). Conservative default: origin uncertain ⇒ llm-tool ⇒ human-gated.

Ingestion is cadence-driven and hybrid: the URBA-0004 cadence selects batch (one-shot | static) vs streaming (recurring-stream | continuous).

Append-never-erase

kmint is the only writer, and it never deletes: graph.GraphWriter refuses any query containing DELETE/REMOVE as a hard backstop (Rule F). Discard/replace is a state change plus a SUPERSEDES / REVISION_OF edge.

Install & use

pip install -e ".[dev]"        # or: pip install -e ".[dev,lake]" for the S3 writer
make test                      # unit tests — no engine needed

kmint capture transcript.txt --form verbatim --capture-id cap-1 --domain MEMORY --dry-run
kmint distill --text "Retention defaults to 7 years." --domain MEMORY \
      --actor human --source cap-1 --source-confidence 3
kmint refine BNK.KNOW.MD.MEMORY.001 --actor human --validator alice
kmint archive BNK.KNOW.MD.MEMORY.001 --by BNK.KNOW.MD.MEMORY.005 --axis authority

make smoke runs an end-to-end capture→distill→refine against a throwaway neo4j:5-enterprise (point KLEDGER_SCHEMA at kledger/schema/schema.cypher to exercise the LOCKED constraints too).

Design

See docs/kmint-design.md for the ADR → implementation map and the scaffold's deferred internals.