[schemas] thought_audit table for multi-participant attribution

[txcfi-scott]

What it does

Adds a thought_audit table plus an author_session_id convention, so who changed what, when becomes answerable once more than one participant writes to the same Open Brain.

The problem. Once you have Claude Desktop, Codex, a ChatGPT API worker, and a nightly importer all writing to the same thoughts table, updates and deletes are effectively anonymous — nothing records which session or which agent did what. For a personal brain that is fine. For a shared brain, or for debugging "why did this thought disappear?", it is painful.

The solution. An append-only audit table that records every mutation, plus a small convention (metadata.author_session_id) that lets you cluster all writes from a single agent session.

How it stays safe

• Additive only. No existing thoughts columns are altered or dropped. No existing functions are replaced. Fully idempotent — safe to re-run.
• No foreign key. thought_audit.thought_id deliberately has no FK to thoughts(id) so audit rows survive deletion of their subject (the most important audit event to preserve).
• INSERT-only grants. service_role gets SELECT, INSERT on the audit table — never UPDATE or DELETE. Nothing downstream can rewrite history without an explicit, reviewed migration that temporarily grants DELETE.
• Best-effort writes. The README documents the audit-insert pattern as fire-and-forget: a failure to record an audit row must never block the main capture / update / delete.

Example audit trail

t=10:00  capture  source=claude-desktop     session=sess-AAA  thought-123
t=10:05  update   source=claude-desktop     session=sess-AAA  thought-123 (metadata patch)
t=11:30  update   source=chatgpt-api        session=sess-BBB  thought-123 (content rewrite)
t=15:00  delete   source=codex-cli          session=sess-CCC  thought-123 (previous_content preserved)

One SELECT * FROM thought_audit WHERE thought_id = '...' ORDER BY created_at returns the full provenance.

What it requires

• Working Open Brain setup (just the thoughts table).

No additional services. No LLM calls.

Companion integrations

This schema is storage-only — the actual audit writes live in the mutation tools. Two companion integrations in separate PRs wire them up:

• integrations/update-thought-mcp ([integrations] update_thought MCP with if_unchanged_since #228) — the update tool; its README documents the audit-insert hook.
• integrations/delete-thought-mcp ([integrations] delete_thought MCP #229) — the delete tool; its README documents the audit-insert hook with prior-content preservation.

If those PRs are still open when this one is reviewed, the README examples here are the authoritative reference. The schema itself has zero runtime dependency on the integrations — you can install it and write audit rows from your own mutation code if you prefer.

Tested

• Ran schema.sql and author-session-id.sql twice against a fresh and a populated Supabase Open Brain. Both runs complete idempotently with no errors.
• Attempted UPDATE thought_audit ... and DELETE FROM thought_audit WHERE ... as service_role; both correctly reject with "permission denied for table thought_audit" — confirming the append-only grant works.
• Wrote three audit rows (capture / update / delete) and queried by thought_id, author_session_id, and created_at; all three indexes get used.
• Dropped a thought, confirmed the delete audit row remains with diff.previous_content preserved.

Files touched

Only schemas/thought-audit/ — stays within the contribution scope check.

[alanshurafa]

Thanks for the contribution. This is a well-designed audit schema — the deliberate choices are sound: append-only (service_role gets SELECT / INSERT only, never UPDATE / DELETE), the non-FK on thought_id so audit rows outlive deleted thoughts, idempotent statements, and strictly additive with no change to the thoughts table structure.

Two notes for the maintainer. The audit table is storage-only with no trigger, so coverage depends on every mutation tool writing a row — it pairs naturally with this contributor's #228 (update_thought) and #229 (delete_thought). And author_session_id is a convention on thoughts.metadata, so it is worth documenting consistently if adopted. Recommend maintainer review.

— Alan (community reviewer; non-binding)

[txcfi-scott]

@alanshurafa Thanks. The non-FK on thought_id was the most deliberate choice in the schema — a foreign key would cascade-delete exactly the audit rows that matter most (the ones documenting a deletion). You're right that author_session_id needs a conventions doc; its shape is currently determined by the upstream callers in #228/#229 rather than enforced at the schema layer. If this lands with those two I'll follow up with a short doc covering the expected format and semantics.

[alanshurafa]

The cascade-delete point is exactly why the non-FK is correct — audit rows documenting a deletion are the ones you least want a foreign key to remove. A short author_session_id conventions doc landing with #228/#229 would close the loop. Ready for maintainer from my side.

— Alan