# Understanding the Purpose of `packages/core` in Apache Maka

> Discover the purpose of packages/core in Apache Maka. This module defines immutable data structures and validation logic, ensuring a single source of truth for all inter-package communication.

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

---

**The `packages/core` module in Apache Maka serves as the pure contract layer that defines immutable data structures, validation logic, and serialization limits for sessions, runtime events, permissions, and sandbox boundaries, establishing a single source of truth for all inter-package communication.**

The Apache Maka repository organizes its architecture into distinct packages, with `packages/core` acting as the foundational backbone that remains free of side-effects and runtime-specific implementations. By isolating these definitions from execution logic, the core package ensures that every component—from the CLI to the runtime host—speaks the same protocol when handling interaction requests, permission prompts, and sandbox expansions.

## The Role of `packages/core` as a Pure Contract Layer

At its essence, `packages/core` houses **pure contracts** that describe how data flows through the Maka ecosystem. According to the repository's documentation, this directory contains "Pure contracts for Sessions, Events, Permissions, and Connections"[^README.md:65-66^], making it the stable interface upon which all other packages depend.

Unlike the `runtime` or `runtime-host` packages that contain execution logic, the core module focuses exclusively on:
- **Immutable data shapes** that prevent mutation across package boundaries
- **Validation helpers** that enforce size limits and structural constraints before data reaches the runtime
- **Canonical outcome definitions** that standardize how success and failure states are represented
- **Serialization contracts** that support Maka's high-performance, append-only event log

Other packages such as `cli`, `ui`, and `runtime` import these contracts via the `@maka/core` namespace, ensuring consistent protocol adherence without coupling to implementation details.

## Core Functional Domains

The `packages/core` directory organizes its contracts into several key domains that govern agent-host interactions.

### Session and Interaction Modeling

The central definitions for session management reside in [`packages/core/src/interaction.ts`](https://github.com/apache/maka/blob/main/packages/core/src/interaction.ts). This file exports types like `InteractionRequest` and `InteractionAnswer` along with their canonical outcomes. These structures model the complete lifecycle of a user-agent exchange, from the initial request projection to the final validation of responses.

### Permission Handling

Security-critical permission flows are defined in [`packages/core/src/permission.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission.ts). This module specifies structures for permission prompts, risk level classifications, reviewer assignments, and audit trail entries. By centralizing these definitions, Maka ensures that permission grants maintain consistent metadata and validation rules across all UI implementations.

### Sandbox Boundary Management

Safe expansion of execution privileges is governed by [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). The contracts here define request and decision types that control read, write, and network access extensions. These immutable boundaries prevent runtime hosts from accidentally over-privileging agents during execution.

### Client Capability Grants

The [`packages/core/src/client-capability-grant.ts`](https://github.com/apache/maka/blob/main/packages/core/src/client-capability-grant.ts) file structures how agents request capabilities from their host environment. These grants follow strict validation schemas to ensure that capability negotiations remain transparent and auditable within Maka's event log.

## Key Source Files and Architecture

The following table maps the critical files within `packages/core` to their specific responsibilities:

| File Path | Description |
|-----------|-------------|
| [`packages/core/src/interaction.ts`](https://github.com/apache/maka/blob/main/packages/core/src/interaction.ts) | Central definitions for interaction requests, answers, canonical outcomes, and validation helpers |
| [`packages/core/src/permission.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission.ts) | Types and utilities for permission prompts, reviewers, and risk-level handling |
| [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) | Contracts governing sandbox-boundary expansion requests and status tracking |
| [`packages/core/src/client-capability-grant.ts`](https://github.com/apache/maka/blob/main/packages/core/src/client-capability-grant.ts) | Structures for client-capability grant requests and responses |
| [`packages/core/src/record-schema.ts`](https://github.com/apache/maka/blob/main/packages/core/src/record-schema.ts) | Helper utilities for defining and validating object shapes used throughout the core contracts |
| [`packages/core/src/workhub-session-resolver.ts`](https://github.com/apache/maka/blob/main/packages/core/src/workhub-session-resolver.ts) | Session-resolution logic that ties together the core contracts with higher-level workspace concepts |
| [`packages/core/src/usage-stats/pricing.ts`](https://github.com/apache/maka/blob/main/packages/core/src/usage-stats/pricing.ts) | Domain-specific contract demonstrating how the core validation framework supports business logic |

These files collectively import no runtime-specific dependencies, maintaining the **zero side-effect guarantee** that makes `packages/core` suitable for use in both server and client contexts.

## Practical Usage Examples

The following examples demonstrate how other packages consume the `packages/core` contracts to enforce type safety and validation.

### Creating a Permission Interaction Request

To initiate a permission flow, packages import projection functions that validate and freeze user input into safe contract shapes:

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

// Build a permission request payload
const permReq = projectInteractionPermissionRequest({
  requestId: 'req-123',
  toolUseId: 'tool-456',
  prompt: {
    kind: 'tool_permission',
    title: 'Access Files',
    description: 'Allow the agent to read/write files in your workspace.',
    rememberForTurnAllowed: true,
    // …other fields defined by InteractionPermissionPrompt
  },
});

// Encode to a safe runtime event
const encoded = decodeInteractionRequest(permReq);

```

Here, `projectInteractionPermissionRequest` projects user-provided data into a validated shape, while `decodeInteractionRequest` performs final validation and freezing before the request enters the event log.

### Validating Interaction Answers

Runtime hosts use core validation helpers to verify that incoming answers match their corresponding requests:

```typescript
import {
  decodeInteractionAnswer,
  isInteractionAnswerValidForRequest,
} from '@maka/core';

// Suppose we received a permission answer from the UI
const answer = decodeInteractionAnswer({
  kind: 'permission',
  decision: 'allow',
  rememberForTurn: true,
});

// Verify the answer matches the original request
if (isInteractionAnswerValidForRequest(permReq, answer)) {
  // Proceed with the granted permission
}

```

The `isInteractionAnswerValidForRequest` function ensures that the answer structure aligns with the original request constraints defined in [`packages/core/src/interaction.ts`](https://github.com/apache/maka/blob/main/packages/core/src/interaction.ts).

### Defining Sandbox Boundary Requests

Agents requesting expanded sandbox permissions use specialized projectors:

```typescript
import {
  projectInteractionSandboxBoundaryRequest,
  decodeInteractionRequest,
} from '@maka/core';

const sandboxReq = projectInteractionSandboxBoundaryRequest({
  expansion: { read: true, write: false, network: false },
  justification: 'Need to read config files for setup.',
});

const encoded = decodeInteractionRequest(sandboxReq);

```

These examples illustrate how `packages/core` enforces strict shape, size, and safety constraints before any interaction reaches the `runtime-host` package.

## Summary

- **`packages/core` provides pure contracts** that define immutable data structures for sessions, events, permissions, and sandbox boundaries in Apache Maka
- **Zero side-effect architecture** ensures these definitions remain free of runtime dependencies, making them safe for import across `cli`, `ui`, `runtime`, and `runtime-host` packages
- **Centralized validation** through functions like `decodeInteractionRequest` and `projectInteractionPermissionRequest` prevents invalid data from entering the append-only event log
- **Key source files** including [`interaction.ts`](https://github.com/apache/maka/blob/main/interaction.ts), [`permission.ts`](https://github.com/apache/maka/blob/main/permission.ts), and [`sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary.ts) establish the protocol that drives Maka's high-performance runtime communication
- **Single source of truth** design ensures that all packages share identical type definitions and validation logic for agent-host interactions

## Frequently Asked Questions

### What types are defined in [`packages/core/src/interaction.ts`](https://github.com/apache/maka/blob/main/packages/core/src/interaction.ts)?

The [`interaction.ts`](https://github.com/apache/maka/blob/main/interaction.ts) file defines the fundamental structures for request-response cycles, including `InteractionRequest`, `InteractionAnswer`, and their canonical outcomes. It also exports validation helpers such as `decodeInteractionAnswer` and `isInteractionAnswerValidForRequest` that runtime hosts use to verify interaction integrity before processing.

### How does `packages/core` ensure type safety across the runtime?

By keeping `packages/core` free of side-effects and runtime-specific code, the module serves as a **stable contract layer** imported by all other packages. Functions like `projectInteractionPermissionRequest` and `decodeInteractionRequest` enforce immutability and structural validation at the boundaries, ensuring that only well-formed data enters the runtime event log.

### Can I import `@maka/core` in external packages or third-party extensions?

Yes, the `packages/core` module is designed for consumption by any package requiring Maka protocol compliance. External tools and extensions can import the contract definitions to generate valid interaction requests or parse event logs while maintaining compatibility with the core validation rules defined in files like [`record-schema.ts`](https://github.com/apache/maka/blob/main/record-schema.ts).

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

The `packages/core` module provides the **data contracts and validation logic**, while `packages/runtime` and `packages/runtime-host` contain the execution environment that acts upon these contracts. The runtime imports types and validation functions from `@maka/core` but never the reverse, maintaining a clean separation between protocol definition and protocol execution.