# What Is the packages/core Directory in Apache Maka? Architecture and Purpose

> Explore the packages/core directory in Apache Maka. Understand its role in defining canonical data models and providing a stable, versioned API for all other packages.

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

---

**The `packages/core` directory serves as Apache Maka's foundational "pure-type" layer, defining canonical data models, enums, and serialization contracts that provide a stable, versioned API consumed by all other packages in the monorepo.**

The `packages/core` directory establishes the architectural bedrock of the Apache Maka project. Located within the monorepo structure, this package contains the immutable domain types and lightweight utilities that describe system entities—such as sessions, capabilities, and work items—without coupling to platform-specific implementation details. By maintaining strict separation between type definitions and execution logic, `@maka/core` enables consistent data contracts across both the main Node.js process and browser renderer contexts.

## Core Responsibilities and Architecture

The primary function of `packages/core` is to declare *what* the system knows and *how* that knowledge is represented, while leaving *how* it is executed to higher-level packages like `runtime`, `cli`, and `ui`.

### Domain Type Definitions

The package establishes a single source of truth for runtime entities through TypeScript type declarations. Key definitions include **`SessionStatus`**, **`CapabilityId`**, and **`ConnectionReadinessState`**, which are declared in files such as [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts) and [`packages/core/src/capabilities.ts`](https://github.com/apache/maka/blob/main/packages/core/src/capabilities.ts).

This centralization prevents type drift between the main process and UI layers. When the system needs to check if a session is active, it references the same `SessionStatus` enum regardless of whether the code executes in the Node backend or the browser frontend.

### Serialization Contracts

`packages/core` houses the encoding and decoding logic required for durable storage and cross-process communication. Functions like **`decodeMessageContent`** and **`decodeCanonicalToolResultContent`** in [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts) provide standardized serialization contracts.

These utilities allow the runtime to remain agnostic of the transport layer while ensuring that events and tool results maintain consistent shape across process boundaries. The record schemas defined here enable reliable data persistence without importing platform-specific storage APIs.

### Pure-Type Guarantees

A strict architectural constraint governs `packages/core`: the code must remain pure TypeScript with no direct dependencies on Electron, Node.js, or browser APIs. This purity enables the same definitions to be safely reused in both the main process and renderer process without side effects or environment-specific branching logic.

By avoiding platform dependencies, the package guarantees that importing a type definition never inadvertently pulls in heavy runtime dependencies or triggers unexpected I/O operations.

## Public API and Module Exports

The [`package.json`](https://github.com/apache/maka/blob/main/package.json) in `packages/core` defines a clean public API through the **`exports`** field. This configuration maps logical module paths to their compiled counterparts under `dist/`, enabling intuitive imports like:

```typescript
import { SessionStatus, CapabilityId } from '@maka/core';

```

For example, the export map routes `./session` to [`./dist/session.js`](https://github.com/apache/maka/blob/main/./dist/session.js), allowing downstream packages to rely on stable import paths while the core team maintains flexibility with internal file organization. This contract ensures that changes to internal directory structures do not break consuming packages across the monorepo.

## Key Source Files in packages/core

The following files collectively form the immutable contract powering Maka's distributed architecture:

- **[`src/session.ts`](https://github.com/apache/maka/blob/main/src/session.ts)** – Defines session lifecycles, status enums, and the `WORKHUB_COORDINATION_SESSION_ID` constant used to identify the special WorkHub coordination session.
- **[`src/capabilities.ts`](https://github.com/apache/maka/blob/main/src/capabilities.ts)** – Enumerates available capabilities through `CapabilityId` and tracks permission states via `CapabilityReadinessState`.
- **[`src/work-board.ts`](https://github.com/apache/maka/blob/main/src/work-board.ts)** – Declares the durable `WorkBoard` schema and versioning constants like `WORK_BOARD_ITEM_SCHEMA_VERSION` for user-owned work items.
- **[`src/connections.ts`](https://github.com/apache/maka/blob/main/src/connections.ts)** and **[`src/connection-readiness.ts`](https://github.com/apache/maka/blob/main/src/connection-readiness.ts)** – Describe connection objects and their readiness states.
- **[`src/events.ts`](https://github.com/apache/maka/blob/main/src/events.ts)** – Provides event and tool-result type definitions used throughout the platform, including serialization helpers.
- **[`package.json`](https://github.com/apache/maka/blob/main/package.json)** – Exposes the public API via the exports map and documents the package's purpose as the shared type foundation.

## Usage Examples: Consuming @maka/core

Other packages throughout the Maka ecosystem import from `@maka/core` to maintain type consistency. Below are typical implementation patterns derived from the source code.

### Importing Session Types

```typescript
import { SessionStatus, WORKHUB_COORDINATION_SESSION_ID } from '@maka/core';

// Check a session's status
function isActive(status: SessionStatus): boolean {
  return status === 'active';
}

// Detect the special WorkHub coordination session
function isWorkHub(sessionId: string): boolean {
  return sessionId === WORKHUB_COORDINATION_SESSION_ID;
}

```

*(Source: [[`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts)](https://github.com/apache/maka/blob/main/packages/core/src/session.ts))*

### Using Capability Enums

```typescript
import { CapabilityId, CapabilityReadinessState } from '@maka/core';

function canRunCapability(cap: CapabilityId, readiness: CapabilityReadinessState) {
  return readiness === 'enabled' && cap === 'computer_use';
}

```

*(Source: [[`packages/core/src/capabilities.ts`](https://github.com/apache/maka/blob/main/packages/core/src/capabilities.ts)](https://github.com/apache/maka/blob/main/packages/core/src/capabilities.ts))*

### Defining Work-Board Items

```typescript
import { defineObjectShape, hasExactShape, WORK_BOARD_ITEM_SCHEMA_VERSION } from '@maka/core';

export const myWorkItem = defineObjectShape({
  version: WORK_BOARD_ITEM_SCHEMA_VERSION,
  title: 'Write knowledge-base article',
  createdAt: Date.now(),
});

```

*(Source: [[`packages/core/src/work-board.ts`](https://github.com/apache/maka/blob/main/packages/core/src/work-board.ts)](https://github.com/apache/maka/blob/main/packages/core/src/work-board.ts))*

### Checking Connection Readiness

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

function isReady(state: ConnectionReadinessState): boolean {
  return state === 'ready';
}

```

*(Source: [[`packages/core/src/connection-readiness.ts`](https://github.com/apache/maka/blob/main/packages/core/src/connection-readiness.ts)](https://github.com/apache/maka/blob/main/packages/core/src/connection-readiness.ts))*

## Summary

The `packages/core` directory functions as the "brain" of Apache Maka, establishing the foundational contracts that enable the system's modular architecture:

- **Immutable Type Contracts**: Provides the single source of truth for domain entities like sessions, capabilities, and work items across all processes.
- **Platform Agnostic Design**: Maintains pure TypeScript implementations without Electron, Node.js, or browser API dependencies, ensuring safe reuse in any execution context.
- **Serialization Foundation**: Houses encoding/decoding logic for cross-process communication and durable storage.
- **Stable Public API**: Exports versioned types through a carefully curated [`package.json`](https://github.com/apache/maka/blob/main/package.json) exports map, allowing downstream packages to import `@maka/core` with confidence.

## Frequently Asked Questions

### What types of definitions are stored in packages/core?

The directory contains "pure-type" definitions including TypeScript interfaces for `SessionStatus`, `CapabilityId`, and `WorkBoard` schemas, along with lightweight utility functions for serialization like `decodeMessageContent`. These definitions describe runtime entities without implementing platform-specific behavior.

### Why does packages/core avoid platform-specific APIs?

By prohibiting direct usage of Electron, Node.js, or browser APIs, `packages/core` ensures that type definitions can be safely imported into both the main Node.js process and the browser renderer process. This architectural constraint prevents side effects and keeps the package lightweight, avoiding heavy runtime dependencies that would bloat the renderer bundle.

### How do runtime packages consume types from core?

Runtime packages like `runtime` and `ui` import types using the `@maka/core` package name, which maps to the compiled output of `packages/core`. The `exports` field in [`packages/core/package.json`](https://github.com/apache/maka/blob/main/packages/core/package.json) routes specific paths (e.g., `@maka/core/session`) to their corresponding `dist/` files, providing a stable import interface regardless of internal file restructuring.

### What is the relationship between packages/core and the runtime layer?

`packages/core` declares *what* data structures exist and *how* they are represented, while `packages/runtime` and other implementation packages handle *how* that data is processed and executed. The core package provides the immutable contracts, while runtime layers provide the platform-specific logic that operates on those contracts.