content/engineering/modules/audit.html

<article class="doc" id="doc-modules-audit" aria-hidden="true"><div class="strip"><span class="path">modules/audit.md</span><span class="tag">Engineering, modules</span><span class="meta">~1 min read</span></div>
<h1>Module: <code>audit</code></h1>
<blockquote>
<p>Part of the Travi AI Agent monolith (<code>app/modules/audit/</code>). Read <code>00-overview.md</code> §3 (hard rules) before changing anything here.</p>
</blockquote>
<div class="tbl-wrap"><table class="plain col-table compact"><colgroup><col class="col-auto"/><col class="col-lg"/></colgroup>
<thead>
<tr>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td data-label=""><strong>Purpose</strong></td>
<td data-label="">The append-only ledger of everything: every PHI access, state transition, agent action, config publish, and export.</td>
</tr>
<tr>
<td data-label=""><strong>Owns (data)</strong></td>
<td data-label="">audit_event (monthly partitions, own schema, INSERT-only role)</td>
</tr>
<tr>
<td data-label=""><strong>Public surface</strong></td>
<td data-label=""><code>audit.emit()</code> facade; admin lineage-replay query API</td>
</tr>
<tr>
<td data-label=""><strong>Depends on</strong></td>
<td data-label="">none (everything depends on it)</td>
</tr>
<tr>
<td data-label=""><strong>Requirements owned</strong></td>
<td data-label="">SEC-003, DQS-001</td>
</tr>
<tr>
<td data-label=""><strong>Constraining ADRs</strong></td>
<td data-label="">ADR-018</td>
</tr>
<tr>
<td data-label=""><strong>Key references</strong></td>
<td data-label="">adr/ADR-018.md, reference/security.md</td>
</tr>
</tbody>
</table></div>
<hr/>
<h2 id="doc-modules-audit--h1">Rules that must never break</h2>
<ol>
<li><strong>Writers:</strong> every PHI-reading API call, every state transition, every agent tool call, every consent action, every export, one event each, with <code>purpose</code> and <code>trace_id</code>.</li>
<li><strong>Fields:</strong> actor_type/id, on_behalf_of, action, object_type/id, purpose, context (diff hash), ip, user_agent, trace_id, occurred_at.</li>
<li><strong>Immutability:</strong> INSERT-only DB role; partitions export nightly to S3 Object-Lock (compliance mode, 6 y); runtime roles are denied delete on the archive.</li>
<li><strong>The 5-minute drill (DQS-001):</strong> any instruction shown to a patient must be reproducible to its source span and gate trail in ≤5 minutes using admin tools, this is rehearsed, not aspirational.</li>
</ol>
<div class="pn"><a class="pn-prev" href="#"></a><a class="pn-next" href="#"></a></div></article>