Trusty/CLAUDE.md

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 LEARNs. 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).

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.