# What Is the packages/core Directory in Apache Maka? Foundational Types Explained

> Explore the packages/core directory in Apache Maka. Understand foundational types for session semantics, capability modeling, and event contracts, powering the entire platform.

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

---

**The `packages/core` directory in Apache Maka contains the foundational, pure-type-only building blocks that define session semantics, capability modeling, and event contracts for the entire platform.**

The `packages/core` directory serves as the type-safe foundation of the Apache Maka repository, providing the canonical data models and serialization-aware contracts that all other packages depend on. Located within the monorepo's `packages/` folder, this directory defines how sessions, capabilities, and runtime events are represented, validated, and exchanged across the entire codebase. Every higher-level package—from UI components to agent implementations—imports from `@maka/core` to maintain consistency with this architectural single source of truth.

## Core Responsibilities of packages/core

The `packages/core` directory delivers four critical responsibilities that power the Maka platform's data integrity and cross-package communication.

### Session and Turn Management

At the heart of the package lies the **session model** defined in [`src/session.ts`](https://github.com/apache/maka/blob/main/src/session.ts). This file establishes immutable session headers, status enumerations, and helper functions that govern turn-record derivation, sub-agent lineage tracking, and revision handling. The session schema ensures that every interaction within Maka adheres to a strict, versioned structure that supports complex conversation flows and branching agent hierarchies.

### Capability and Permission Modeling

The [`src/capabilities.ts`](https://github.com/apache/maka/blob/main/src/capabilities.ts) file defines the **capability readiness** system that determines whether platform features can activate based on OS permissions, configuration states, and runtime probes. This module exports the `deriveCapabilityReadiness` algorithm, which aggregates inputs from feature flags, settings, and system permissions to compute a definitive readiness state. The capability snapshot types enable the UI layer to render accurate permission states while maintaining type safety across the capability lifecycle.

### Event and Message Contracts

Data integrity across persistence layers relies on the strict decoders implemented in [`src/events.ts`](https://github.com/apache/maka/blob/main/src/events.ts). These decoders validate every stored message type—including user inputs, assistant responses, tool calls, and permission decisions—ensuring that data retrieved from storage or network layers conforms to expected schemas. The `decodeStoredMessage` function provides runtime validation that prevents corrupted or malformed data from propagating through the system.

### Public API Stability

The [`package.json`](https://github.com/apache/maka/blob/main/package.json) in `packages/core` declares an **exports map** that exposes a stable public API while keeping implementation details private. The description field identifies the package as `"Pure types for Maka — events, session, permission, connections,"` accurately summarizing its role. Consumers access specific submodules via paths like `@maka/core/session` or `@maka/core/capabilities`, enabling tree-shaking and explicit dependency management.

## Key Files in packages/core

Understanding the file structure demonstrates how the package organizes its type definitions and logic:

- **[`packages/core/package.json`](https://github.com/apache/maka/blob/main/packages/core/package.json)** — Declares the package metadata and export map that defines the public surface area for `@maka/core` imports.
- **[`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts)** — Contains the central `SessionHeader` interface, status enums, and utility functions that drive the entire session persistence model.
- **[`packages/core/src/capabilities.ts`](https://github.com/apache/maka/blob/main/packages/core/src/capabilities.ts)** — Houses the `CapabilitySnapshot` types and the `deriveCapabilityReadiness` function that powers the capability health UI.
- **[`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts)** — Implements the `decodeStoredMessage` decoder and message type definitions that guarantee data integrity across storage layers.
- **`packages/core/src/__tests__/`** — Contains comprehensive test suites including [`session-event.test.ts`](https://github.com/apache/maka/blob/main/session-event.test.ts) and [`capabilities.test.ts`](https://github.com/apache/maka/blob/main/capabilities.test.ts) that validate type correctness and algorithm behavior.

## Practical Usage Examples for @maka/core

The following examples demonstrate how to leverage the pure types and utilities exported from the `packages/core` directory.

### Creating a Session Header

Import the `SessionHeader` type to ensure your session initialization adheres to the canonical schema:

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

const header: SessionHeader = {
  id: 'session-123',
  workspaceRoot: '/Users/alice/project',
  cwd: '/Users/alice/project',
  createdAt: Date.now(),
  name: 'Demo Session',
  titleIsManual: false,
  isFlagged: false,
  labels: [],
  isArchived: false,
  status: 'active',
  hasUnread: false,
  backend: 'ai-sdk',
  llmConnectionSlug: 'openai-gpt-4',
  connectionLocked: false,
  model: 'gpt-4',
  permissionMode: 'allow',
};

```

### Deriving Capability Readiness

Use the `deriveCapabilityReadiness` function to calculate whether a capability can be enabled based on system state:

```typescript
import {
  deriveCapabilityReadiness,
  type CapabilitySnapshot,
  type DeriveCapabilityReadinessInput,
} from '@maka/core';

const input: DeriveCapabilityReadinessInput = {
  feature: { state: 'enabled', source: 'settings' },
  configuration: { state: 'present', source: 'runtime' },
  osPermissions: [
    { id: 'accessibility', required: true, status: 'granted' },
    { id: 'screen_recording', required: true, status: 'granted' },
  ],
  runtimeProbe: { state: 'healthy', source: 'bot_registry' },
};

const readiness = deriveCapabilityReadiness(input); // → 'enabled'

```

### Decoding Stored Messages Safely

Validate and type unknown data using the strict decoder pattern:

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

const raw = JSON.parse(`{
  "type":"assistant","id":"msg-1","turnId":"turn-1","ts":1690000000000,
  "text":"Hello!", "modelId":"gpt-4"
}`);

const message: StoredMessage = decodeStoredMessage(raw);
// `message` is now strongly typed as AssistantMessage.

```

## Summary

- The `packages/core` directory provides **pure TypeScript types** with zero runtime dependencies, ensuring lightweight imports across the monorepo.
- **Session management** relies on [`src/session.ts`](https://github.com/apache/maka/blob/main/src/session.ts) for immutable headers and turn-semantics that support complex agent hierarchies.
- **Capability modeling** uses the `deriveCapabilityReadiness` algorithm in [`src/capabilities.ts`](https://github.com/apache/maka/blob/main/src/capabilities.ts) to aggregate OS permissions, feature flags, and runtime health into deterministic readiness states.
- **Data integrity** is enforced through strict decoders like `decodeStoredMessage` in [`src/events.ts`](https://github.com/apache/maka/blob/main/src/events.ts), preventing malformed data from corrupting application state.
- The **exports map** in [`package.json`](https://github.com/apache/maka/blob/main/package.json) exposes a stable public API via submodule paths, allowing precise imports such as `@maka/core/session` or `@maka/core/capabilities`.

## Frequently Asked Questions

### What types are exported from @maka/core?

The package exports pure TypeScript interfaces and types including `SessionHeader`, `CapabilitySnapshot`, `StoredMessage`, and various enums for session status and permission states. According to the [`package.json`](https://github.com/apache/maka/blob/main/package.json) description, the focus remains on events, session management, permissions, and connections.

### How does deriveCapabilityReadiness determine if a capability is ready?

The `deriveCapabilityReadiness` function accepts a `DeriveCapabilityReadinessInput` object containing feature flags, configuration presence, OS permission arrays, and runtime probe states. As implemented in [`src/capabilities.ts`](https://github.com/apache/maka/blob/main/src/capabilities.ts), the algorithm evaluates these inputs hierarchically to return a readiness state such as `'enabled'`, `'disabled'`, or `'missing_permissions'`.

### Is packages/core available as a standalone dependency?

While `packages/core` exists as a discrete package within the Apache Maka monorepo, it is primarily designed for internal consumption by other Maka packages. The [`package.json`](https://github.com/apache/maka/blob/main/package.json) declares the exports field that enables precise submodule imports, suggesting it could theoretically be published independently, though it serves as the shared contract layer for the broader application.

### How does packages/core ensure data integrity across storage layers?

Data integrity is maintained through strict decoder functions like `decodeStoredMessage` defined in [`src/events.ts`](https://github.com/apache/maka/blob/main/src/events.ts). These decoders validate JSON payloads against expected schemas at runtime, throwing errors when fields are missing or types mismatch, thereby guaranteeing that only valid data structures propagate through the persistence and network layers.