From e9d81f3b1cc033c0d620d745d8e828c8a7694f3e Mon Sep 17 00:00:00 2001
From: Molecule AI Documentation Specialist
 <documentation-specialist@agents.moleculesai.app>
Date: Fri, 17 Apr 2026 18:46:28 +0000
Subject: [PATCH] =?UTF-8?q?docs(api-ref):=20molecule-audit-ledger=20?=
 =?UTF-8?q?=E2=80=94=20HMAC=20chain,=20/audit=20endpoint,=20CLI=20(PR=20#6?=
 =?UTF-8?q?51)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Audit Ledger section to api-reference.mdx:
- GET /workspaces/:id/audit with all query params (agent_id, session_id,
  from/to RFC 3339, limit cap 500, offset)
- Response shape including chain_valid tri-state (true/false/null)
- AUDIT_LEDGER_SALT callout (platform + workspace envs must match)
- LedgerHooks Python usage snippet for workspace templates
- molecule_audit.verify CLI exit codes

Pairs with monorepo PR #651 (feat: molecule-audit-ledger — EU AI Act
Art. 12/13 compliance, HMAC-SHA256-chained agent event log).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 content/docs/api-reference.mdx | 82 ++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx
index adde987..60470ed 100644
--- a/content/docs/api-reference.mdx
+++ b/content/docs/api-reference.mdx
@@ -365,6 +365,88 @@ LLM trace retrieval from Langfuse.
 
 ---
 
+## Audit Ledger
+
+HMAC-SHA256-chained immutable agent event log for compliance record-keeping (EU AI Act Art. 12 / Art. 13). Each event is cryptographically chained to the previous one — tampering with any record breaks all subsequent HMACs.
+
+<Callout type="warn">
+  **`AUDIT_LEDGER_SALT` required.** The platform and workspace containers must share the same `AUDIT_LEDGER_SALT` environment variable to compute and verify event HMACs. Set it in both your platform env and workspace container env. If the variable is absent, `chain_valid` returns `null` (not `false`) — no records are lost, verification is simply unavailable.
+</Callout>
+
+### Query
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/workspaces/:id/audit` | WorkspaceAuth | Query the audit ledger for a workspace. Returns events in descending chronological order with inline chain verification. |
+
+**Query parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agent_id` | string | Filter to a specific agent. |
+| `session_id` | string | Filter to a specific session. |
+| `from` | RFC 3339 | Start of time range (e.g. `2026-04-01T00:00:00Z`). |
+| `to` | RFC 3339 | End of time range. |
+| `limit` | int | Max records to return. Capped at **500**. |
+| `offset` | int | Pagination offset. |
+
+**Response shape:**
+
+```json
+{
+  "events": [
+    {
+      "id": "uuid",
+      "workspace_id": "uuid",
+      "agent_id": "my-researcher",
+      "session_id": "sess_abc123",
+      "event_type": "tool_call",
+      "payload": { "tool": "bash", "input": "ls /workspace" },
+      "hmac": "sha256hex...",
+      "prev_hmac": "sha256hex...",
+      "created_at": "2026-04-17T12:00:00Z"
+    }
+  ],
+  "chain_valid": true
+}
+```
+
+`chain_valid` values:
+- `true` — all HMACs verified; ledger is intact.
+- `false` — at least one HMAC mismatch; possible tampering.
+- `null` — `AUDIT_LEDGER_SALT` is absent from the platform env; verification skipped.
+
+### Workspace-side: recording events
+
+In your workspace template, wire `LedgerHooks` into the agent pipeline:
+
+```python
+from molecule_audit.hooks import LedgerHooks
+
+hooks = LedgerHooks(agent_id="my-researcher", session_id=session_id)
+
+async with hooks:
+    # hooks.on_task_start / on_llm_call / on_tool_call / on_task_end
+    # fire automatically at each pipeline stage
+    result = await agent.run(task)
+```
+
+`LedgerHooks` is exception-safe — a failed ledger write never aborts the agent task.
+
+### CLI chain verification
+
+```bash
+# Verify the full chain for an agent; exit 0 = intact
+python -m molecule_audit.verify --agent-id my-researcher
+
+# Custom DB URL
+python -m molecule_audit.verify --agent-id my-researcher --db postgresql://user:pass@host/db
+```
+
+Exit codes: `0` = chain valid · `1` = broken chain · `2` = `AUDIT_LEDGER_SALT` missing · `3` = DB error.
+
+---
+
 ## Events
 
 Append-only event log for structure changes.