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

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, 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 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, 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 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 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 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. 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 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 and 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:

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:

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:

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 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) is the data structure describing what happened—containing payloads, roles, and statuses. RuntimeEventStore (defined in 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 and 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.

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