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

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, sqlite-runtime-schema.ts, sqlite-core-execution-schema.ts, sqlite-session-metadata-schema.ts, sqlite-usage-schema.ts, and 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 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:

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 must be present:

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:

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:

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

Summary

• Schema files such as sqlite-artifact-schema.ts and 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. 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. 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, 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.

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