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

> Discover the runtime-event-authority.ts contract in Apache Maka. Learn how it separates storage from evaluation to protect atomic versioning guarantees in your workspace.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-01

---

**The [`runtime-event-authority.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-authority.ts):

```typescript
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`](https://github.com/apache/maka/blob/main/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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/apache/maka/blob/main/runtime-event-authority.ts) | `packages/storage/src/` | Defines the guard enforcing the authority contract |
| [`sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-store.ts) | `packages/storage/src/` | Generic SQLite store invoking the guard before persistence |
| [`agent-run-store.ts`](https://github.com/apache/maka/blob/main/agent-run-store.ts) | `packages/storage/src/` | Alternative store implementation respecting the same contract |
| [`workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/sqlite-runtime-store.ts) and [`agent-run-store.ts`](https://github.com/apache/maka/blob/main/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.