Mako Immutable Event Log Reproducibility: A Technical Deep Dive

Mako’s append-only Runtime Event Log serves as the canonical, tamper-proof record of every model message, tool invocation, and termination fact, enabling deterministic replay and cryptographic auditability across distributed sessions.

The Apache Mako runtime guarantees execution reproducibility through an immutable event log architecture that treats the Runtime Event Log as the single source of truth. Unlike mutable state stores that allow history modification, Mako’s storage layer enforces append-only semantics with cryptographic integrity checks. This design ensures that any session can be replayed verbatim across different machines or timeframes without hidden state divergence.

Foundational Immutability Guarantees

Canonical Source of Truth

According to ARCHITECTURE.md lines 45-46, the Runtime Event Log is explicitly defined as the "canonical source" of session history. Context pruning operations alter provider input projections but never mutate the underlying history, preserving the exact sequence of model messages and tool results required for faithful replay.

Immutable Ledger Enforcement

The SQLite storage layer enforces strict immutability at lines 437-438 of packages/storage/src/sqlite-runtime-store.ts by validating that any terminal RuntimeEvent must be the immutable ledger tail. Attempts to rewrite or delete historical events trigger invariant violations with the error "terminal RuntimeEvent must be the immutable ledger tail", guaranteeing that once written, events remain permanent.

Safe Projection Pruning

Mako distinguishes between volatile projections and the immutable ledger. As noted in the architecture documentation, context pruning safely compacts derived provider input projections without touching the raw event log, allowing memory optimization while maintaining the reproducible seed intact.

Cryptographic Integrity and Auditability

Tamper-Evident Provenance

Every event carries a cryptographic digest computed by the immutableSteeringMessageId function defined in packages/storage/src/runtime-event-invariants.ts lines 28-30. This stable hash creates an auditable chain where any modification would invalidate the digest, making the provenance tamper-evident for security reviews and compliance auditing.

Reliable Crash Recovery

Recovery mechanisms leverage the immutable prefix guarantee implemented at lines 974-976 of sqlite-runtime-store.ts and documented in docs/architecture/runtime-resume-architecture.md. The system reconstructs exact prior states by reading the validated immutable prefix, ensuring that recovered executions match the original run bit-for-bit.

Cross-Run Consistency for Experiments

The evaluation framework (@maka/eval) relies on immutable attempts as the source of truth. Per ARCHITECTURE.md lines 63-64, experiments treat the earliest valid attempt as authoritative because the immutable log ensures all runs reference identical historical outcomes, eliminating non-determinism in experiment comparisons.

Enforcement in the Runtime Layer

The runtime implementation in packages/runtime/src/tool-runtime.ts freezes tool outcomes as immutable snapshots before logging. This ensures that ephemeral execution results—including tool invocations and their returns—become permanent, reproducible facts within the event sequence rather than mutable state that could diverge across replays.

Implementing Verifiable Session Replay

Reading the Immutable Event Stream

The storage package exposes readImmutableRuntimeEventsSync to safely consume the event log. This function returns events that are guaranteed to match the original execution order, suitable for feeding back into the Runtime Host for deterministic replay.

// Example: Reading an immutable slice of the Runtime Event Log
import { readImmutableRuntimeEventsSync } from '@maka/storage';

// `sessionId` identifies the session, `runId` the execution instance.
const immutableEvents = readImmutableRuntimeEventsSync(sessionId, runId);

// The returned array can be fed back into the Runtime Host to replay exactly
// the same execution, because the events are guaranteed immutable.

Validating Ledger Extensions

When appending new events, the immutableSteeringMessageId invariant ensures new entries reference the current immutable tail. This prevents history forking and maintains the linear, append-only property required for reproducibility.

// Example: Verifying that a new event respects the immutable ledger tail
import { immutableSteeringMessageId } from '@maka/storage';

function appendEvent(event: RuntimeEvent) {
  const tailId = immutableSteeringMessageId(event);
  if (!tailId) {
    throw new Error('New event must reference the immutable ledger tail');
  }
  // … insert event into SQLite store …
}

Summary

• The Runtime Event Log acts as an append-only, canonical source of truth that never modifies historical events, even during context pruning operations.
• Cryptographic digests (immutableSteeringMessageId) provide tamper-evident provenance for every event in the chain.
• The SQLite storage layer enforces immutable ledger tail validation at lines 437-438, rejecting any attempts to rewrite or delete history.
• Crash recovery relies on immutable prefixes (lines 974-976) to reconstruct exact prior states without state divergence.
• Cross-run consistency for experiments is guaranteed because all attempts reference the same immutable historical record.

Frequently Asked Questions

How does Mako prevent accidental modification of historical events?

The runtime store in packages/storage/src/sqlite-runtime-store.ts throws an error if a terminal event is not the immutable ledger tail, enforcing that writes can only append to the end of the log. This architecture-level constraint makes deletion or mutation of existing events impossible through the standard API, as attempts to rewrite history violate the invariant checks at the storage layer.

Can I safely delete old events to save disk space without breaking reproducibility?

No, you cannot delete events from the immutable log without violating reproducibility guarantees. However, Mako supports context pruning that compacts derived projections (provider inputs) without altering the underlying event history stored in the SQLite runtime store, allowing memory optimization while preserving the ability to replay sessions verbatim from the immutable seed.

How does the cryptographic digest ensure auditability?

Each event's immutableSteeringMessageId serves as a stable hash of its content computed in runtime-event-invariants.ts. Because these identifiers form a chain where each new event references the previous digest via the immutable ledger tail requirement, any tampering with historical data would break the cryptographic linkage, making unauthorized modifications immediately detectable during validation.

What happens if a session crashes during execution?

Mako's recovery mechanism reads the immutable prefix of the Runtime Event Log up to the point of failure, as implemented in sqlite-runtime-store.ts lines 974-976. Since the log is never partially written or corrupted by pruning operations, and the runtime in tool-runtime.ts commits immutable snapshots atomically, the system can reconstruct the exact pre-crash state and resume execution deterministically.

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