# Core Contracts Defined in the packages/core Directory: Apache Maka's Type Foundation

> Explore Apache Maka's core contracts in packages/core. Discover immutable TypeScript structures for workspace versioning, events, and recovery, ensuring type-safe interoperability across Maka's layers.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-08-22

---

**The `packages/core` directory contains pure TypeScript contracts that define immutable data structures for workspace versioning, runtime events, work boards, and tool recovery, ensuring type-safe interoperability between Maka's runtime, UI, and storage layers.**

The Apache Maka project centralizes its foundational data definitions in `packages/core`, creating a single source of truth for all cross-layer communication. These contracts are deliberately side-effect-free TypeScript interfaces and type guards that enforce consistent data shapes across the ledger, runtime, and React UI. By versioning every major schema—such as `WORKSPACE_FACT_VERSION` and `WORK_BOARD_ITEM_SCHEMA_VERSION`—the system enables safe migrations and deterministic replay of execution history.

## Durable Data and Workspace Management

### Workspace Version Authority

The **workspace version authority** system defines how Maka tracks immutable workspace states across time. In [`packages/core/src/workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/packages/core/src/workspace-version-authority.ts), the contract `WorkspaceEpochDescriptorV1` describes immutable descriptors for workspace epochs and baselines. This file also specifies the envelope used for runtime facts and the scan results required for authority validation. The constant `WORKSPACE_FACT_VERSION` ensures that persisted data can be migrated safely as the schema evolves.

### Work Board Schema

The **work board** contract in [`packages/core/src/work-board.ts`](https://github.com/apache/maka/blob/main/packages/core/src/work-board.ts) defines a durable "to-do" list that persists inside a session. The core interface `WorkBoardItemBase` establishes the item schema, while `CreateWorkBoardItemInput` structures creation and update inputs. The contract includes pagination queries and validation helpers, with versioning controlled by `WORK_BOARD_ITEM_SCHEMA_VERSION`. This allows the UI and runtime to coordinate on task state without coupling to specific storage implementations.

## Runtime Communication Architecture

### The RuntimeEvent Contract

At the heart of Maka's event system lies [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts), which defines the canonical "Runtime v2" event contract. The central `RuntimeEvent` type covers **roles**, **authors**, **statuses**, **origins**, and diverse **payloads** including text, thinking streams, function calls/responses, errors, and token usage. Specific content types like `RuntimeEventTextContent` and `RuntimeEventErrorContent` ensure that the UI can render messages deterministically while the runtime produces them from model calls.

### Event Store Persistence

The [`packages/core/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts) file abstracts persistence for `RuntimeEvent` objects behind a clean interface. This contract mandates **append-only writes**, **read-by-session** queries, and **stream query** capabilities. By separating the event definition from storage logic, Maka can switch between SQLite, git-tree, or other backends without changing the runtime or UI code.

## UI and External Service Integration

### Web Search Abstractions

[`packages/core/src/web-search.ts`](https://github.com/apache/maka/blob/main/packages/core/src/web-search.ts) provides **provider-agnostic** contracts for web-search results. The `WebSearchResultRow` type standardizes how search results flow between the UI and agent-tool layers, regardless of the underlying provider. The file also defines credential status structures and settings shared across the application boundary.

### Interactive User Question Flows

The **user question** contract in [`packages/core/src/user-question.ts`](https://github.com/apache/maka/blob/main/packages/core/src/user-question.ts) structures the "ask-the-assistant" dialog flow. It defines option sets, request objects, response shapes, and result objects that the UI renders as interactive question dialogs. These types ensure that user input collected in the React frontend strictly conforms to what the runtime expects when processing assistant queries.

## Security and Permission Models

### Tool Categories and Execution Facts

Security policy in Maka is codified in [`packages/core/src/permission.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission.ts). This contract defines the `ToolCategory` enumeration and `ToolExecutionFacts`, which encode isolation strategies, network access rules, and secret handling requirements. The runtime consults these contracts to determine whether a shell command is safe to execute. The file also handles legacy `PermissionMode` payloads and deprecation strategies.

## Observability and Recovery Systems

### Usage Statistics and Billing

The [`packages/core/src/usage-stats/types.ts`](https://github.com/apache/maka/blob/main/packages/core/src/usage-stats/types.ts) file defines structures for **usage tracking** and **billing**. Types like `UsageQuery`, `UsageSummaryV2`, and `PricingConfig` describe how diagnostic objects and bucketed logs travel to the billing subsystem. These contracts scrub sensitive details (note the optional `details?` field in `RuntimeEventErrorContent`) while preserving metrics necessary for tool-invocation budgeting.

### Tool Recovery Contracts

Resilience mechanisms rely on [`packages/core/src/tool-recovery-fact.ts`](https://github.com/apache/maka/blob/main/packages/core/src/tool-recovery-fact.ts) and [`tool-recovery-bundle.ts`](https://github.com/apache/maka/blob/main/tool-recovery-bundle.ts). These files define `ToolRecoveryOperationIdentity`, `ToolRecoveryBundleValidationResult`, and `ToolRecoveryFactEnvelope` to record recovery decisions and reconciliation results. When tools fail or pause, these contracts enable deterministic replay or rollback while preserving execution history integrity.

## Working with Core Contracts: Code Examples

Below are practical implementations demonstrating how to consume the core contracts in application code.

### Creating a Work-Board Item

This example uses `CreateWorkBoardItemInput` and related types from the work board contract:

```typescript
import {
  WORK_BOARD_ITEM_SCHEMA_VERSION,
  type WorkBoardScope,
  type WorkBoardCreator,
  type CreateWorkBoardItemInput,
} from '@maka/core';

// Build a simple "inbox" item
const inboxScope: WorkBoardScope = { kind: 'inbox' };
const creator = { kind: 'user' } as const;

const newItem: CreateWorkBoardItemInput = {
  scope: inboxScope,
  title: 'Draft proposal for next sprint',
  creator,
  provenance: { kind: 'manual' },
};

// The runtime will assign schemaVersion and IDs internally
await fetch('/api/work-board/items', {
  method: 'POST',
  body: JSON.stringify(newItem),
  headers: { 'Content-Type': 'application/json' },
});

```

### Validating Runtime Event Roles

Use the type guard `isRuntimeEventRole` to validate event roles at runtime:

```typescript
import { isRuntimeEventRole, RUNTIME_EVENT_ROLES } from '@maka/core';

function assertRole(role: unknown) {
  if (!isRuntimeEventRole(role)) {
    throw new Error(`Invalid role ${role}; allowed: ${RUNTIME_EVENT_ROLES.join(', ')}`);
  }
  // TypeScript now narrows `role` to RuntimeEventRole
}

```

### Querying Usage Statistics

This snippet constructs a `UsageQuery` for the observability layer:

```typescript
import type { UsageQuery } from '@maka/core';

const query: UsageQuery = {
  range: '7d',
  groupBy: 'model',
  limit: 50,
};

const resp = await fetch('/api/usage', {
  method: 'POST',
  body: JSON.stringify(query),
  headers: { 'Content-Type': 'application/json' },
});
const data = await resp.json(); // Complies with UsageSummaryV2

```

## Summary

- **Immutable versioning**: Contracts like `WorkspaceEpochDescriptorV1` and `WorkBoardItemBase` use explicit version constants to enable safe data migrations.
- **Runtime-UI bridge**: `RuntimeEvent` and `UserQuestion` provide the exclusive data shapes crossing between backend runtime and React frontend.
- **Security enforcement**: `ToolCategory` and `ToolExecutionFacts` define the permission model for isolated tool execution.
- **Resilience patterns**: `ToolRecoveryOperationIdentity` and related types support deterministic replay of failed tool invocations.
- **Reusable helpers**: Files like [`record-schema.ts`](https://github.com/apache/maka/blob/main/record-schema.ts) export `defineObjectShape` for consistent schema definition across other contracts.

## Frequently Asked Questions

### What is the primary purpose of the contracts in the `packages/core` directory?

The contracts establish a **single source of truth** for data shapes exchanged between Maka's runtime, UI, storage, and external services. By centralizing these definitions in pure TypeScript, Apache Maka ensures type-safe interoperability without runtime-specific conversions or ad-hoc type definitions in consuming packages.

### How does Maka handle versioning for workspace and work-board data?

Maka embeds version constants—such as `WORKSPACE_FACT_VERSION` and `WORK_BOARD_ITEM_SCHEMA_VERSION`—directly into the contract definitions. When the runtime persists data to the ledger (git-tree or SQLite), it stores these version identifiers, enabling the system to perform schema migrations deterministically when reading historical records.

### What distinguishes the RuntimeEvent contract from the RuntimeEventStore interface?

`RuntimeEvent` (defined in [`runtime-event.ts`](https://github.com/apache/maka/blob/main/runtime-event.ts)) is the **data structure** describing what happened—containing payloads, roles, and statuses. `RuntimeEventStore` (defined in [`runtime-event-store.ts`](https://github.com/apache/maka/blob/main/runtime-event-store.ts)) is the **persistence interface** that dictates how these events are written (append-only) and queried (by session or stream). This separation allows the runtime logic to remain agnostic of storage implementation details.

### How does the tool recovery system ensure deterministic execution after failures?

The tool recovery contracts in [`tool-recovery-fact.ts`](https://github.com/apache/maka/blob/main/tool-recovery-fact.ts) and [`tool-recovery-bundle.ts`](https://github.com/apache/maka/blob/main/tool-recovery-bundle.ts) capture `ToolRecoveryOperationIdentity` and `ToolRecoveryBundleValidationResult` objects. These structures record the exact state of a failed or paused tool invocation, including reconciliation results and validation codes, allowing the runtime to replay or rollback operations while maintaining a consistent execution history.