# What Is the Responsibility of the Core Package in Apache Maka?

> Discover the core package's role in Apache Maka. It defines Maka's platform-neutral data model contract, ensuring seamless communication across all subsystems.

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

---

**The `@maka/core` package serves as the platform-neutral contract layer and single source of truth for Maka's data model, providing pure type definitions that define how the runtime, storage, and other subsystems communicate.**

The `@maka/core` package forms the foundational layer of the Apache Maka system. It establishes the canonical schemas and boundary contracts that ensure type safety across the entire workspace architecture. According to the source code, this package maintains the responsibility of the core package in Maka by declaring pure TypeScript definitions that all other packages—such as `runtime`, `desktop`, and `eval`—import and consume.

## Core Responsibilities of the Maka Core Package

The responsibility of the core package in Maka centers on three primary architectural concerns: defining pure types, establishing runtime boundaries, and serving as the cross-package contract source.

### Pure Type Definitions

At its heart, `@maka/core` declares **pure type definitions** for every shared data structure in the system. These include canonical schemas for events, sessions, permissions, connections, and capabilities.

In [`packages/core/package.json`](https://github.com/apache/maka/blob/main/packages/core/package.json), the package description explicitly states it contains "Pure types for Maka — events, session, permission, connections". This ensures that fundamental data structures remain consistent and versioned in a single location rather than duplicated across workspace packages.

### Runtime Boundary Language

The package defines the **runtime-boundary types** that govern communication between the sandboxed runtime (`packages/runtime`) and the persistent storage layer (`packages/storage`). These contracts describe how data crosses system boundaries without exposing implementation details.

The file [`packages/core/src/runtime-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-boundary.ts) specifically encodes these boundary contracts, enabling the runtime to interact with host capabilities through well-defined interfaces rather than ad-hoc messaging.

### Cross-Package Contract Source

Every other workspace package imports types from `@maka/core` to maintain semantic consistency. For example, the runtime package imports `Permission` using `import { Permission } from '@maka/core/permission'`.

As noted in [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md), shared pure contracts live in `packages/core`, making it the authoritative source that prevents type drift between the desktop client, evaluation engine, and runtime sandbox.

## Key Files Defining the Core Contract

Several critical files in `packages/core/src/` implement the responsibility of the core package in Maka:

- **[`packages/core/src/permission.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission.ts)** – Defines the core permission model used throughout the Maka permission system.
- **[`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts)** – Centralizes the event schema that all subsystems emit and consume.
- **[`packages/core/src/runtime-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-boundary.ts)** – Establishes the boundary language between sandboxed execution contexts and the host environment.
- **[`packages/core/package.json`](https://github.com/apache/maka/blob/main/packages/core/package.json)** – Declares the package purpose and exports, explicitly listing it as the pure types container.

## Practical Usage Examples

The following examples demonstrate how other packages consume the core contracts in production code.

### Defining Permission Profiles

Import type definitions from the core package to ensure your permission structures match the system-wide schema:

```typescript
import { PermissionProfile } from '@maka/core/permission-profile';

const myProfile: PermissionProfile = {
  id: 'example',
  description: 'A simple permission profile used for demo',
  grants: [{ kind: 'read', resource: 'files/*' }],
};

```

This code imports `PermissionProfile` from `@maka/core/permission-profile`, leveraging the canonical definition stored in the permission module.

### Emitting Runtime Events

Use core event types to maintain consistency across the runtime boundary:

```typescript
import { RuntimeEvent } from '@maka/core/runtime-event';

function emitStart(event: RuntimeEvent) {
  console.log('Runtime started:', event);
}

const startEvent: RuntimeEvent = {
  type: 'runtime.start',
  timestamp: Date.now(),
  payload: { version: '0.1.0' },
};

emitStart(startEvent);

```

The `RuntimeEvent` type imported from `@maka/core/runtime-event` ensures that events crossing the runtime boundary conform to the schema defined in [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts).

## Summary

The responsibility of the core package in Maka encompasses the foundational contracts that enable type-safe interoperability across the entire system:

- **Platform-neutral contracts** – Provides pure TypeScript definitions that are implementation-agnostic.
- **Single source of truth** – Maintains canonical schemas for permissions, events, sessions, and connections in one versioned location.
- **Runtime boundary definition** – Establishes the communication protocol between sandboxed runtimes and persistent storage without leaking implementation details.
- **Cross-package consistency** – Serves as the imported contract layer for all workspace packages including `runtime`, `desktop`, and `eval`.

## Frequently Asked Questions

### What specific types does the `@maka/core` package export?

The package exports pure type definitions for `Permission`, `PermissionProfile`, `RuntimeEvent`, `Session`, `Connection`, and various runtime boundary interfaces. These are defined in files such as [`packages/core/src/permission.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission.ts) and [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts), providing the data structures that all other Maka packages consume to ensure semantic consistency.

### How does the core package differ from the runtime package?

While `packages/runtime` contains the sandboxed execution environment and implementation logic, `@maka/core` contains only the type contracts and boundary definitions. According to the runtime package README, the runtime imports types from `@maka/core` to maintain clean separation between implementation details and shared data models.

### Why are the types in `@maka/core` considered "pure"?

The types are considered pure because they contain no implementation logic, side effects, or platform-specific dependencies. The [`package.json`](https://github.com/apache/maka/blob/main/package.json) description explicitly identifies the package as containing "Pure types for Maka", meaning it consists solely of TypeScript interfaces and type aliases that define the shape of data crossing system boundaries.

### Can I extend or modify types in the core package?

While you can technically fork or modify `packages/core/src/`, doing so affects the entire system's contract layer. Any changes to the core types require corresponding updates in all dependent packages (`runtime`, `storage`, `desktop`, etc.) because these packages import directly from `@maka/core`. The file [`packages/core/package.json`](https://github.com/apache/maka/blob/main/packages/core/package.json) establishes this package as the versioned source of truth for this reason.