audit-event-mcp: Instructions file for Claude Code

CLAUDE.md — @kajaril/audit-event-mcp

This file is the constitution for Claude Code working in this repo. Read it before any non-trivial change.

---

What this repo is

@kajaril/audit-event-mcp is agent steward infrastructure: a hash-chained audit log backed by a Cloudflare Durable Object, with optional Merkle notarisation and a GDPR/AI-Act compliance skill. MIT-licensed.

This is a governance product. Every decision in the codebase is on the record. DPO buyers and regulators will read this code.

Required reading before structural changes

1. .context/kajaril-source-of-truth.md — strategy, stack, roadmap
2. .context/kajaril-decisions-addendum-wk0.md — entity-level locked decisions
3. .context/audit-event-mcp-build-plan.md — this repo's build plan + all locked decisions

These live in the workspace .context/ folder, not in this repo. Deviating from any locked decision requires stopping, asking, and recording the new decision before code changes.

Locked decisions

1. Two Workers — wrangler.jsonc (main) + wrangler.notary.jsonc (notary). They are independent deployments. Never merge them into one config.
2. DO SQLite, not D1 — state.storage.sql.exec() is the API. Never add a D1 binding to this repo.
3. new_sqlite_classes, not new_classes — Wrangler migration tag for SQLite-enabled DOs. Do not change.
4. Shared R2 bucket — one audit-payloads bucket, per-client isolation via {client_id}/{event_id} key prefix in do.ts. Never per-client buckets.
5. CF Access JWT routing — Worker reads payload.custom.client_id from the CF Access JWT; DO name = audit-do-{client_id}. Never use URL segments for client routing.
6. Hash chain algorithm — locked. input_hash_slot = input_hash ?? input_hash_omitted_reason. Never empty string. chain_hash = SHA-256(id + "|" + event_type + "|" + input_hash_slot + "|" + (prev_hash ?? "")). Do not change without a new decision entry.
7. Six MCP tools exactly — record_event, verify_chain, query_events, export_dossier, request_approval, check_approval. Was four; widened by the witness integration decision (kajaril-witness-integration-draft.md §3, Day 3, 2026-06-12). Do not add tools without a new decision.
8. payload_ref never returned — tool responses never include payload_ref keys or raw payload content. This is a privacy invariant.
9. NOTARY_PRIVATE_KEY is a Workers Secret — set via wrangler secret put, never in source, comments, or commits.
10. migrations/0001_init.sql is applied by do.ts — the DO constructor calls state.storage.sql.exec(SCHEMA_SQL). Never apply via wrangler d1 migrations apply.
11. License + metadata — MIT. package.json author, repository, homepage, bugs are locked.
12. EU jurisdiction pin (2026-07-10) — every tenant DO is created via env.AUDIT_DO.jurisdiction("eu") before .idFromName(...), never the raw binding. All three call sites (src/index.ts, src/lib/approval-flow.ts, src/lib/audit-log.ts) must agree — a client whose ID is ever derived without the jurisdiction call would resolve to a different DO than one derived with it, silently splitting that tenant's chain in two. The R2 side needed no code change: AUDIT_PAYLOADS binding now points at audit-payloads-eu (created via wrangler r2 bucket create audit-payloads-eu --jurisdiction eu) instead of the original non-jurisdictional audit-payloads bucket — binding name unchanged, so nothing in do.ts/main.ts had to change. Decided with zero pilot clients on the old bucket/namespace, so no data migration was needed; if that's no longer true when this is read, check first.