# How Maka's Core Contracts Are Implemented Using SQLite in `packages/storage`

> Discover how Maka's core contracts leverage SQLite within packages storage. Learn about versioned schemas, typed store classes, and Node.js native driver implementation for robust data management.

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

---

**Maka’s core contracts are implemented as versioned SQLite schemas in the `packages/storage` directory, where each contract defines table structures, indexes, and constraints that are enforced at runtime by typed store classes using Node.js’s native `node:sqlite` driver.**

Maka is an Apache open-source project that persists its data model definitions as enforceable contracts within a SQLite-backed storage layer. In the `packages/storage` directory, each core contract—ranging from artifact metadata to workflow definitions—is codified as a schema file that declares exact table layouts and versioning constraints, ensuring that TypeScript types and database schemas remain synchronized. This dual representation guarantees that the storage API cannot accidentally write data that breaches the contract while maintaining efficient on-disk storage.

## Schema Declaration and Contract Versioning

Maka defines its data contracts through dedicated schema files that export both a `SCHEMA_VERSION` constant and a `migrate` function responsible for creating or upgrading tables.

### Versioned Schema Files

Files such as [`sqlite-artifact-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-artifact-schema.ts), [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts), [`sqlite-core-execution-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-core-execution-schema.ts), [`sqlite-session-metadata-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-schema.ts), [`sqlite-usage-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-usage-schema.ts), and [`sqlite-workflow-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-workflow-schema.ts) declare the SQLite table structures for their respective domains. Each file exports a compiled `SCHEMA_VERSION` constant that represents the current iteration of the contract. When a store initializes, it compares this compiled version against the value persisted in the database, ensuring every store works against the exact contract version.

### Migration and Evolution

The exported `migrate` function in each schema file handles schema evolution by creating tables or applying alterations to reach the expected version. If the persisted version differs from the compiled constant, the migration logic automatically bumps the schema to the latest version. This mechanism guarantees that the contract—the exact set of columns, types, and constraints—never drifts across deployments.

## Store Classes and CRUD Enforcement

For each schema definition, Maka provides a corresponding store class that opens a SQLite database and exposes typed CRUD APIs.

### Database Initialization and Lazy Loading

Store classes such as `SqliteArtifactStore`, `SqliteRuntimeStore`, `SqliteCoreExecutionStore`, `SqliteSessionMetadataStore`, `SqliteUsageStore`, and `SqliteWorkflowStore` manage database connections. The constructor lazily loads the `node:sqlite` module via `loadDatabaseSync()`, then opens the database file—typically `runtime.sqlite` for most stores, with separate files for artifacts and usage data. Upon opening, the store immediately runs the migration function to validate or upgrade the schema before accepting operations.

### Transactional Guarantees

All write operations are wrapped in SQLite transactions using `BEGIN IMMEDIATE`, `COMMIT`, and `ROLLBACK` on error. This enforces atomicity of contract updates and protects against partial writes that could leave the database in a state violating the defined constraints.

### Concurrency and Lock Handling

The runtime schema implementation in [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts) includes specific error handling logic that inspects SQLite error codes. When the store encounters `SQLITE_BUSY` or `SQLITE_LOCKED` errors, it implements retry logic to provide robust concurrency behavior for contract-compatible writes across multiple processes.

## Runtime Contract Validation

Higher-level components such as `WorkBoardStore` and `OperationalStateStore` serve as consumers of the base SQLite stores. These components invoke the stores and assert that returned rows conform to the expected contract, emitting clear error messages such as "Work Board item … failed contract validation" when a row violates the contract constraints.

## Practical Implementation Examples

The following examples demonstrate how to instantiate stores and interact with the contract-enforced APIs.

### Creating a Runtime Store

The runtime store automatically enforces its contract upon initialization:

```typescript
import { createSqliteRuntimeStore } from './sqlite-runtime-store.js';

const runtimeStore = await createSqliteRuntimeStore({
  dbPath: 'runtime.sqlite',
});
await runtimeStore.initialize();

```

### Inserting Contract-Compliant Data

When inserting artifacts, all required columns defined in [`sqlite-artifact-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-artifact-schema.ts) must be present:

```typescript
await runtimeStore.insertArtifact({
  id: 'artifact-123',
  version: 1,
  createdAt: new Date(),
});

```

### Reading Session Metadata

The session metadata store returns typed data according to its schema contract:

```typescript
import { createSqliteSessionMetadataStore } from './sqlite-session-metadata-store.js';

const sessionStore = await createSqliteSessionMetadataStore({ dbPath: 'runtime.sqlite' });
const meta = await sessionStore.getSessionMetadata('session-42');

```

### Handling Contract Violations

Attempting to insert incomplete data triggers validation errors:

```typescript
try {
  await sessionStore.insertMetadata({ sessionId: 's1' });
} catch (err) {
  console.error('Contract violation:', err.message);
}

```

## Summary

- **Schema files** such as [`sqlite-artifact-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-artifact-schema.ts) and [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts) define the contractual table structures and export `SCHEMA_VERSION` constants for version guarding.
- **Store classes** like `SqliteRuntimeStore` and `SqliteSessionMetadataStore` use Node.js’s `node:sqlite` driver to open databases lazily and enforce contracts via typed CRUD methods including `insertArtifact()`, `getRuntime()`, and `recordExecution()`.
- **Migration logic** ensures that database schemas automatically upgrade to match the compiled contract version, preventing drift between code and persisted data.
- **Transactional guarantees** and SQLite lock-handling (retry on `SQLITE_BUSY`) ensure atomic, concurrency-safe writes that respect contract constraints.
- Higher-level consumers such as `OperationalStateStore` provide additional validation layers that emit explicit errors when data violates the core contracts.

## Frequently Asked Questions

### How does Maka prevent schema drift between code and database?

Maka embeds a `SCHEMA_VERSION` constant in each schema file. When a store initializes, it compares this compiled constant against the version stored in the SQLite database via [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts). If they differ, the `migrate` function automatically applies the necessary changes to bring the database schema into alignment with the code contract.

### What Node.js module does Maka use for SQLite access?

Maka uses the native `node:sqlite` module, which it loads lazily through a `loadDatabaseSync()` helper. This approach ensures the SQLite driver is only imported when the store constructor executes, optimizing startup performance for applications that may not immediately require database access.

### How does Maka handle concurrent writes to the SQLite database?

The storage layer wraps all writes in transactions using `BEGIN IMMEDIATE` and implements retry logic for `SQLITE_BUSY` and `SQLITE_LOCKED` errors within [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts). This ensures that concurrent processes attempting to modify contract-compliant data do not corrupt the database or violate atomicity constraints.

### What happens when data violates a core contract?

When higher-level components like `WorkBoardStore` detect rows that fail validation against the expected schema defined in files such as [`sqlite-session-metadata-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-schema.ts), they throw explicit errors with messages such as "Work Board item … failed contract validation." This immediate feedback prevents invalid data from propagating through the application stack.