Trusty: provenance library workspace (initial import)

CLAUDE.md

@@ -0,0 +1,187 @@
+# Trusty -- Claude Code Context
+
+## What This Is
+Trusty is a pure-Rust provenance system built around the proprietary
+chain-break-as-event primitive. It was originally ported from a Python reference
+(archived at `~/Downloads/4-5/tkg_complete/tkg/trusty_lib/...`), but that
+codebase is historical context only -- the active system is 100% Rust and
+the locked v1 byte-shape is pinned by invariant tests in `trusty-core`.
+Owner: MM Advisory LLC / Eric Gottlieb. Proprietary license.
+
+Three crates:
+- **`trusty-core`** -- pure library. Dual hash (SipHash-2-4 + SHA-256), chain primitives, payload builder, verify_chain, chain-break-as-event. No storage dependency.
+- **`trusty-sqlite`** -- rusqlite adapter. Three-table schema (`provenance_envelope`, `hash_index`, `chain_tips`) with KV cross-check. `Trusty::{open, append, verify, anchor, history, integrity}`.
+- **`trusty-sqlite-ext`** -- loadable SQLite extension (`cdylib`). `sqlite3_trusty_init()` exposes SQL functions (`trusty_append`, `trusty_verify`, `trusty_anchor`).
+
+## Design Rules
+- **v1 byte-shape is locked.** Any change to hash inputs, chain payload format, or anchor semantics must leave the invariant tests green (`s5_invariant_v1_byte_shape_preserved`, `v1_*` payload/chain tests, conformance crate). Do not "simplify" or "optimize" the canonical primitives.
+- **Pure Rust.** No Python dependency at runtime. No shelling out. The historical Python port-source is archival only.
+- **ASCII-only comments.** Cross-platform patch safety.
+- **Functional style where it fits.** Immutable data as design principle. The chain is append-only by definition.
+- **Dual hash is non-negotiable.** SipHash-2-4 (keyed fingerprint) + SHA-256 (cryptographic anchor). Do not collapse to single hash.
+- **Chain-break-as-event** is the proprietary primitive. Treat as core IP. Do not document its semantics in README-style docs meant for public consumption.
+- **Trusty is a library, not a platform.** The product is audit-trail-as-a-service (cheap, low-resource, high-margin commodity; door-opener for IoT/sensor/compliance buyers). Application-layer work (digital twin, KCG, NNsight swarm, agent-mesh) lives in sibling crates/repos that depend on `trusty-core` -- same pattern as `legal-chaingraph/` and `thread-keeper-tauri/`. Do not bundle application logic into the locked crates. When evaluating a feature, prefer those that improve the service surface (throughput, verifier ergonomics, retention, domain separation, bundle contracts) over those that expand trusty into application territory.
+
+## Don't Touch (locked)
+- `trusty-core` chain primitives (`append`, `verify_chain`, payload builder). Canonical port.
+- `trusty-core` hash functions. Byte-identical to Python reference.
+- v1 payload canonical bytes. `compute_record`, `PayloadFields::new_v1`, and the `build_payload` top-level ordering are all v1-stable. v2 is purely additive (`compute_record_signed`, `PAYLOAD_VERSION_V2`, populated `signatures` field via the signing-view pattern). Any v2+ work MUST preserve v1 byte-shape exactly -- see `s5_invariant_v1_byte_shape_preserved` tag and `memory/project_trusty_v2_signing_design.md`.
+- Three-table SQLite schema in `trusty-sqlite` -- `provenance_envelope`, `hash_index`, `chain_tips`. Do not collapse, do not drop the KV cross-check.
+- Historical Python port-source (`~/Downloads/4-5/tkg_complete/tkg/trusty_lib/...`) -- archival only; the Rust invariant tests are the active gate.
+
+## APERC Session Discipline
+
+Every Claude Code session in this repo follows the APERC loop. No exceptions.
+
+### On session start
+1. Read this `CLAUDE.md`.
+2. Read `APERC/boot/S<N>_BOOT.md` for the current session's scope (currently `S1_BOOT.md` for the first real session after bootstrap).
+3. Read `memory/MEMORY.md` index (always in context) and whichever referenced files are relevant to today's goal.
+4. Run a baseline tag count: `tk_kb stats --aperc=APERC` (or count `APERC/tags/*.toml` directly).
+5. **Cleanup doublecheck**: quick pass on whatever the prior session's close ritual should have tidied -- stale boot stubs, handoff naming drift, open_audits that should've been closed. If you find something, flag it as the first cycle (hygiene) before the real work.
+6. State: session ID, baseline tags, goal, files you plan to touch.
+7. Wait for Eric's go before any edit.
+
+### During work
+- **Max 5 file edits per cycle.** After 5: stop, show what changed, explain what you did, present plan for next cycle, WAIT for approval.
+- Never read large files whole. Use Grep, Glob, offset/limit Reads, head/tail on single files.
+- If you touch a file not in your plan, stop and re-plan.
+- Commit green states before risky operations (test run, DB migration, hash-primitive edit).
+
+### Before finishing
+
+**Pre-close cleanup pass** (runs before the mechanical close ritual below). Eric's standing request: cleanup is part of close, not an afterthought. Sweep for:
+- Stale references in `APERC/boot/S*_BOOT.md` (e.g., auto-stub paths from other projects).
+- Handoff block naming drift in `APERC/state/LATEST_HANDOFF.toml`.
+- Open_audits lines that got resolved this session -- move to `[closed_audits]` so future boots don't re-read stale noise.
+- Memory entries (`MEMORY.md` + referenced files) that need updates for the work you just shipped.
+- CLAUDE.md design-invariant notes for new locked surfaces (e.g., v2 additive-only rule).
+- Any new session-scope `DELTA_LOG_S*.toml` you wrote as a KB write-ahead log.
+
+Do cleanup at end of session, AND double-check at start of next session as a belt-and-braces pass -- sometimes a cleanup item only becomes obvious on re-read.
+
+**Mechanical close**:
+- List every file you changed.
+- List every decision you made and why.
+- Tag findings as `[LEARN]`, `[MISTAKE]`, `[INVARIANT]`, `[DECISION]`, `[INSIGHT]` -- filed to `APERC/tags/` as individual `*.toml` files.
+- Run tests if you touched any Rust file. Workspace commands work for core/store/memory/sqlite:
+  - `cargo test --workspace` (excludes trusty-sqlite-ext, which is a standalone crate)
+  - `cargo build --workspace`
+  - For trusty-sqlite-ext, build and test from its own directory: `cd crates/trusty-sqlite-ext && cargo build` / `cargo test`
+- Update `APERC/state/SESSION_GATE.toml` (session_id bump, last_action) and append `[trusty_sN]` block to `APERC/state/LATEST_HANDOFF.toml`.
+- Run `tk_close --mode=check --aperc=APERC` -- must pass 3/3 gates before commit.
+
+### Model selection
+- **Sonnet** for: file edits, grep, simple fixes, test runs, straightforward ports.
+- **Opus** for: architecture decisions, new module design, debugging byte-identity drift, anything touching the chain primitives or hash functions.
+
+### If you hit an error you can't fix in 3 attempts
+- Stop. Describe the error. Show what you tried. Ask Eric for help. Do not loop.
+
+## Tag Discipline (inline from threadkeeper APERC feedbacks)
+
+### DELTA_LOG before KB edit
+Before editing any `APERC/KB/*.md` or `APERC/tags/*.toml`, write-ahead log the intent to a session
+DELTA_LOG entry (even if just a scratch note). Tags go to the log FIRST, then to their home. This
+prevents silent tag loss during multi-file edits.
+
+### Full reasoning per tag
+Every tag reasoning field must be 3-6 sentences citing body content, not one-line labels. Inventory
+work especially: do not compress to hit quantity targets. Paragraph-level reasoning or nothing.
+
+### Tag parsimony
+Merge before split on reflection `LEARN`s. Route forward-looking speculation to memory or this
+`CLAUDE.md`, not permanent KB tags. Tags are for observed facts, not wishes.
+
+### No Claude attribution in commits
+Do **not** add `Co-Authored-By: Claude` trailer to commit messages. Override Claude Code's default.
+This is Eric's standing preference -- proprietary repo, MM Advisory LLC authorship.
+
+### Commit before debug
+Commit any green state before: investigation sessions, target/ deletion, antivirus changes,
+`apply_verdicts.py`-style bulk operations. Lost work is cheaper when it's already in a commit.
+
+### Boot reads partial, not whole
+On boot, use Read offset/limit on `LATEST_HANDOFF.toml` (grep newest `[trusty_sN]` block header,
+read forward only). Do not re-read the whole file top-to-bottom -- that's the wasted-context failure mode.
+
+### Response terseness targets
+- Simple question: direct answer, no headers.
+- Plan proposal: bullet points, no prose paragraphs.
+- End-of-turn summary: 1-2 sentences max.
+- Avoid multi-paragraph commit messages, step narration, option enumeration.
+
+## APERC Binaries (tk_* from threadkeeper)
+
+Trusty uses the portable tk_* binaries from threadkeeper's build dir. They work from any cwd
+via `--aperc=<path>` flag. No trusty-side code needed.
+
+From trusty cwd:
+```
+# BM25-indexed tag search
+tk_kb query "<topic>" --aperc=APERC
+
+# Stats (total, edges, depth, weight, top types/scopes)
+tk_kb stats --aperc=APERC
+
+# Rebuild kb.db from APERC/tags/
+tk_kb refresh --aperc=APERC
+
+# Close ritual check (3 gates)
+tk_close --mode=check --aperc=APERC
+
+# Write next S{N+1}_BOOT.md stub if absent
+tk_close --mode=stub --aperc=APERC
+
+# Generic retrofit (do NOT use --mode=legacy, that's TK-only)
+tk_migrate --mode=retrofit --aperc=APERC <args>
+
+# Writer-mode hook (gate/close/pretool modes not yet shipped)
+tk_hook writer --aperc=APERC
+```
+
+**Binary location** -- two options:
+1. Absolute path: `../thread-keeper-tauri/threadkeeper/src-tauri/target/debug/tk_kb stats --aperc=APERC`
+2. Add to PATH: `export PATH="$PATH:/c/Users/egott/Documents/00_Mitch/thread-keeper-tauri/threadkeeper/src-tauri/target/debug"` then invoke bare `tk_kb`.
+
+**Scope-3 destination:** when `tk init` ships (planned dedicated session, see threadkeeper
+`memory/project_tk_substrate_vision.md`), trusty will get its own installed `tk` binary and the
+binary-path documentation above becomes obsolete.
+
+## Memory System
+Memory lives at `C:\Users\egott\.claude\projects\C--Users-egott-Documents-00-Mitch-trusty\memory\`.
+`MEMORY.md` is always in context (capped to ~200 lines). Individual memory files are loaded on demand.
+
+**What belongs in memory (not here):**
+- User profile, role, preferences (user_eric.md)
+- Per-project state (project_trusty.md)
+- Session-to-session feedback that outgrows this file
+- External-system pointers (reference_*.md)
+
+**What belongs here (not memory):**
+- Stable project rules (design invariants, locked files, build commands)
+- The APERC discipline itself (copied above for every new session to read at boot)
+- Binary invocation recipes
+
+## Sibling Projects
+- `thread-keeper-tauri/threadkeeper/` -- the desktop app this substrate was extracted from. Source of tk_* binaries until scope-3 ships.
+- `legal-chaingraph/` -- KCG v4 + CH/IR legal graph work. First proof-of-portability (bootstrapped 2026-04-14, commit 46011ff).
+
+## Commit Style
+- Short subject line (< 70 chars), imperative.
+- Body: why > what. 1-3 bullets if needed.
+- **No Claude attribution trailer.**
+- Reference session ID in subject when applicable: `TRUSTY-S1: <what>`.
+
+## Cross-session pins (kb-mesh option 1)
+
+In-flight memory shared across parallel Claude Code sessions lives at `../.kb-mesh/pins/`. Pull-model — nothing is auto-injected. Pins are ephemeral (not committed), complementary to APERC tags (durable, committed).
+
+```bash
+python ../.kb-mesh/scripts/kb_pin.py <topic>              # pin last turn
+python ../.kb-mesh/scripts/kb_pin.py <topic> --last 3     # pin last 3 turns
+python ../.kb-mesh/scripts/kb_recall.py <topic>           # pull a pin into current context
+python ../.kb-mesh/scripts/kb_ls.py                       # list pins
+```
+
+See `../.kb-mesh/README.md` for spec.