# 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.