Metadata-Version: 2.4
Name: kmint
Version: 0.1.0
Summary: Assertion ingestion engine — executes the URBA-0003 lifecycle as Neo4j + S3 mutations (ADR-TECH-STRAT-001).
Author: yremy
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: neo4j<6,>=5
Requires-Dist: jsonschema>=4.21
Provides-Extra: lake
Requires-Dist: boto3>=1.34; extra == "lake"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"

# 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`](https://github.com/papeete-consulting-lab/banking-knowledge).

## Where kmint sits

| Repo | Org | Role |
|--|--|--|
| **`banking-knowledge`** | `papeete-consulting-lab` | The **contract** — schema v1 + lifecycle ADRs. Documentary. |
| **`kledger`** | `papeete-consulting-lab` | The **appliance** — schema + deploy + read-only resolver + validation. |
| **`kmint`** (this repo) | `papeete-consulting` | The **ingestion CLI** — writes both planes. Sibling of `kpack`. |

`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

```bash
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`](docs/kmint-design.md) for the ADR → implementation map and the
scaffold's deferred internals.
