How Apache Maka Ensures Auditability of Agent Operations

Apache Maka guarantees auditability of agent operations by recording every step in an append-only, immutable RuntimeEvent log that functions as the system's single source of truth.

Apache Maka treats auditability as a core architectural requirement rather than an afterthought. According to the Apache Maka source code, every model interaction, tool invocation, and permission decision is captured in a canonical, tamper-evident ledger stored in a local SQLite database. This design ensures that the UI, crash-recovery logic, and external auditors all project from the same immutable history.

The RuntimeEvent Ledger: Single Source of Truth

Canonical Event Schema

The foundation of Maka's auditability lies in the RuntimeEvent type defined in packages/core/src/runtime-event.ts. This schema captures every significant action including model messages, tool calls, permission decisions, timestamps, and unique UUIDs. By enforcing a well-defined structure, Maka ensures that every event has a canonical representation that remains stable across the entire system.

Append-Only Storage Implementation

The SQLiteRuntimeStore in packages/storage/src/sqlite-runtime-store.ts implements the physical persistence layer using a SQLite database (runtime.sqlite). This store strictly enforces an append-only policy through the appendRuntimeEvent method—attempts to rewrite or delete existing events trigger hard errors. The implementation only supports two operations: appending new events and terminal-event sealing, which permanently finalizes a run's history.

Tamper-Evident Integrity Mechanisms

Canonicalization and Content Hashing

Before any event reaches the database, Maka transforms it using canonicalizeRuntimeEventForStorage from @maka/core/canonical-runtime-event. This process, visible in sqlite-runtime-store.ts (lines 376-384), computes a deterministic canonical form and generates a content hash stored alongside the event. If any later read detects a hash mismatch, the system rejects the record, preventing silent tampering.

Terminal Event Sealing

The ensureTerminalRuntimeEventDurable method (lines 403-440 in sqlite-runtime-store.ts) guarantees ledger integrity by validating that only one terminal RuntimeEvent exists per run. This event marks the immutable tail of the ledger, ensuring that once a run completes, its audit trail cannot be extended or modified—only read or exported.

Projecting State from the Audit Trail

Maka enforces a strict read-model projection pattern through the RuntimeEventReadModel class in packages/runtime/src/runtime-event-read-model.ts. Rather than maintaining mutable state, the UI and recovery systems rebuild higher-level representations directly from the raw event log. This architectural choice means any derived state can be recomputed from the audit trail alone, eliminating the risk of state divergence.

Exporting and Importing Audit Logs

For external compliance workflows, the storage layer exposes exportRuntimeEvents and importRuntimeEvent functions (lines 542-564 in sqlite-runtime-store.ts). These methods serialize runs as JSONL files while preserving original IDs and content hashes. Auditors can export a complete run history, analyze it offline, and later import it back for verification without altering the original ledger.

The following example demonstrates how to retrieve a complete audit trail for a specific run:

import { RuntimeStore } from '@maka/storage';

const store = new SQLiteRuntimeStore();
const events = await store.readRuntimeEvents('session-default', 'run-123');
console.log(events.map(e => `${e.id}: ${e.kind} at ${e.timestamp}`));

To export a run for external compliance review:

import { exportRuntimeEvents } from '@maka/storage';

const auditPath = await exportRuntimeEvents({
  sessionId: 'default',
  runId: 'run-123',
  destination: '/compliance/run-123.audit.jsonl',
});
console.log(`Audit trail exported to ${auditPath}`);

Security and Access Controls

According to the repository's SECURITY.md, Maka stores all persistent audit data in the local user-only directory protected by OS file permissions. The credential vault remains isolated from the renderer process, ensuring that sensitive authentication data never appears in the audit log or exposed interfaces.

Summary

• RuntimeEvent schema provides a canonical, versioned structure for every agent action.
• Append-only SQLite storage in sqlite-runtime-store.ts prevents deletion or modification of historical records.
• Canonicalization and hashing detect any attempted tampering with stored events.
• Terminal event sealing creates an immutable tail for each run, finalizing the audit trail.
• Read-model projection ensures all UI and recovery state derives solely from the log.
• Export/Import APIs enable external verification workflows without compromising ledger integrity.

Frequently Asked Questions

What makes the RuntimeEvent log immutable?

The SQLiteRuntimeStore enforces immutability at the storage layer by only exposing appendRuntimeEvent and ensureTerminalRuntimeEventDurable operations. The underlying SQLite database operates in append-only mode, and the codebase contains explicit checks that reject any attempt to update or delete existing rows in runtime.sqlite.

How does Maka detect if someone tampered with the audit database?

Every event is processed through canonicalizeRuntimeEventForStorage before persistence, which computes a content hash stored alongside the record. When reading events back, Maka verifies these hashes; any mismatch between the stored hash and the computed hash triggers an integrity error, immediately flagging potential tampering.

Can I export audit logs for compliance auditing?

Yes. The exportRuntimeEvents function in packages/storage/src/sqlite-runtime-store.ts serializes complete run histories as JSONL files while preserving original UUIDs and content hashes. These exports include all model interactions, tool calls, and permission decisions, allowing external compliance tools to verify agent behavior without accessing the production database.

Where does Maka store the audit data physically?

The audit log resides in a SQLite database named runtime.sqlite located in the local user-only application directory, as specified in SECURITY.md. The file permissions restrict access to the operating system user running the application, and the credential vault remains separate from this audit storage to prevent sensitive data leakage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}