What Is the `runtime-event-authority.ts` Contract in Maka and How It Separates Storage from Evaluation

The runtime-event-authority.ts contract in Apache Maka is a runtime-event guard that prevents generic storage components from writing to the reserved workspace authority stream, ensuring atomic versioning guarantees remain intact.

runtime-event-authority.ts defines a critical runtime-event contract that protects the workspace authority stream from unauthorized writes. In Maka's architecture, runtime events serve as the unit of work driving both evaluation (logical processing of actions, mutations, and facts) and storage (persistence in SQLite). The workspace authority stream requires strict access control to maintain correct evaluation semantics.

The Core Guard: assertNoReservedWorkspaceAuthorityAppend

The contract is implemented by the exported function assertNoReservedWorkspaceAuthorityAppend in packages/storage/src/runtime-event-authority.ts:

export function assertNoReservedWorkspaceAuthorityAppend(event: RuntimeEvent): void {
  if (event.actions?.workspaceFact !== undefined) {
    throw new Error('Workspace facts require the atomic workspace version authority writer');
  }
  if (event.actions?.managedMutationTerminal !== undefined) {
    throw new Error('Managed mutation terminals require the atomic terminal authority writer');
  }
  if (event.sessionId === WORKSPACE_AUTHORITY_SESSION_ID) {
    throw new Error('RuntimeEvent targets the reserved workspace authority stream');
  }
}

This guard performs three critical validations before any storage operation proceeds.

Validation 1: Workspace Facts Are Restricted

The check event.actions?.workspaceFact !== undefined ensures that workspace facts can only be written by the dedicated workspace version authority writer. Generic event writers are prohibited from appending these facts directly.

Validation 2: Managed Mutation Terminals Are Protected

The check event.actions?.managedMutationTerminal !== undefined prevents unauthorized writes to managed mutation terminals. Only the terminal authority writer may append events containing these terminals.

Validation 3: Reserved Session ID Is Enforced

The check event.sessionId === WORKSPACE_AUTHORITY_SESSION_ID blocks any event that explicitly targets the reserved authority stream using the special session identifier.

How Storage-Evaluation Separation Works

Storage Isolation at the Persistence Layer

Generic storage implementations like sqlite-runtime-store.ts invoke assertNoReservedWorkspaceAuthorityAppend before persisting any event. If the guard throws, the write is rejected entirely. This creates a hard boundary: only atomic writers can touch the authority stream, while normal storage handles all other events.

Evaluation Safety Through Authority Guarantees

The evaluation engine consumes events assuming that authority facts originate exclusively from designated writers. This invariant guarantees that:

• Workspace versioning remains consistent across concurrent operations
• Terminal resolution follows predictable, single-writer semantics
• Race conditions and state corruption are prevented at the architectural level

Practical Code Examples

Guarding a Generic Event Before Storage

import { assertNoReservedWorkspaceAuthorityAppend } from '@maka/storage/runtime-event-authority';
import { type RuntimeEvent } from '@maka/core/runtime-event';

// A generic event that does NOT touch workspace authority
const genericEvent: RuntimeEvent = {
  sessionId: 'user-123',
  actions: { someAction: { /* … */ } },
};

assertNoReservedWorkspaceAuthorityAppend(genericEvent); // passes
await sqliteRuntimeStore.append(genericEvent);

Illegal Write Attempt From Generic Writer

import { assertNoReservedWorkspaceAuthorityAppend } from '@maka/storage/runtime-event-authority';
import { type RuntimeEvent } from '@maka/core/runtime-event';

const illegalEvent: RuntimeEvent = {
  sessionId: 'user-456',
  actions: { workspaceFact: { /* workspace fact data */ } },
};

try {
  assertNoReservedWorkspaceAuthorityAppend(illegalEvent);
} catch (e) {
  console.error(e.message);
  // → "Workspace facts require the atomic workspace version authority writer"
}

Correct Usage by Dedicated Authority Writer

import { WORKSPACE_AUTHORITY_SESSION_ID } from '@maka/core/workspace-version-authority';
import { type RuntimeEvent } from '@maka/core/runtime-event';

const authorityEvent: RuntimeEvent = {
  sessionId: WORKSPACE_AUTHORITY_SESSION_ID,
  actions: { workspaceFact: { /* valid fact */ } },
};

// No guard is called here because the dedicated writer knows it is allowed
await workspaceAuthorityWriter.append(authorityEvent);

Key Files in the Authority Contract

File	Location	Role
runtime-event-authority.ts	packages/storage/src/	Defines the guard enforcing the authority contract
sqlite-runtime-store.ts	packages/storage/src/	Generic SQLite store invoking the guard before persistence
agent-run-store.ts	packages/storage/src/	Alternative store implementation respecting the same contract
workspace-version-authority.ts	packages/core/src/	Provides WORKSPACE_AUTHORITY_SESSION_ID for the authority stream

Summary

• assertNoReservedWorkspaceAuthorityAppend enforces a runtime boundary between evaluation-critical authority streams and generic storage
• Three checks protect workspace facts, managed mutation terminals, and the reserved session ID
• Storage components like sqlite-runtime-store.ts invoke this guard to reject unauthorized writes before persistence
• The separation lets evaluation logic rely on immutable, single-writer authority guarantees while storage safely handles all other events
• This architecture prevents race conditions and maintains atomic versioning across Maka's distributed runtime

Frequently Asked Questions

What happens if a generic writer tries to append a workspace fact?

The assertNoReservedWorkspaceAuthorityAppend function throws an error with the message "Workspace facts require the atomic workspace version authority writer", preventing the storage layer from persisting the event. This ensures workspace versioning remains consistent.

Where is WORKSPACE_AUTHORITY_SESSION_ID defined?

The reserved session identifier is exported from workspace-version-authority.ts in the @maka/core package. Only the dedicated workspace authority writer uses this value; all other writers must use different session IDs.

Why separate storage from evaluation at the event level?

Maka's evaluation engine assumes authority facts come from a single, controlled source. By enforcing this contract during storage, the system prevents corrupted versioning states that would break concurrent evaluation correctness without adding overhead to the hot evaluation path.

Which storage implementations use this contract?

Both sqlite-runtime-store.ts and agent-run-store.ts invoke assertNoReservedWorkspaceAuthorityAppend before persisting events, as do other generic stores in Maka's storage layer. Dedicated atomic writers bypass the guard by design.

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