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

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, 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 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, 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 – Defines the core permission model used throughout the Maka permission system.
• packages/core/src/events.ts – Centralizes the event schema that all subsystems emit and consume.
• packages/core/src/runtime-boundary.ts – Establishes the boundary language between sandboxed execution contexts and the host environment.
• 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:

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:

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.

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 and 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 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 establishes this package as the versioned source of truth for this reason.

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