@architect-engine/sdk

A local-first application engine for TypeScript. Entity system, workflows, simulation sandbox, real-time subscriptions, bitemporal journal, external integrations — all running on local SQLite with offline support.

Install

npm install @architect-engine/sdk

Quick Start

import { Architect } from '@architect-engine/sdk';

const architect = await Architect.boot();
const db = await architect.connect({ database: 'my-app' });

// Query entities by type
const tasks = await db.query({ filter: { type_id: 'type:task' }, limit: 10 });

// Atomic transaction — create, update, delete, patch in one operation
await db.transact([
  { kind: 'create', resource: 'entity', data: { id: 'task:1', title: 'Ship it' } },
]);

// Trigger a workflow — multi-step logic composed from primitives
await db.workflowTrigger('workflow:onboarding', { payload: { userId: 'user:alice' } });

// Read the audit journal
const journal = await db.journalRead('audit', { limit: 50 });

// Call external services through the engine's managed pipeline
await db.callExternal('https://api.example.com/notify', {
  method: 'POST', body: JSON.stringify({ event: 'signup' }),
});

await db.close();

With React

import { useArchitect, useEntities } from '@architect-engine/sdk/react';

function App() {
  const { db, isReady } = useArchitect({ database: 'my-app' });

  if (!isReady) return <div>Loading...</div>;

  return <TaskList db={db} />;
}

function TaskList({ db }) {
  const { data: tasks, isLoading } = useEntities(db, { type_id: 'type:task', limit: 10 });

  if (isLoading) return <div>Loading tasks...</div>;

  return (
    <ul>
      {tasks.map(task => <li key={task.id}>{task.title}</li>)}
    </ul>
  );
}

With Next.js

// next.config.js
const { withArchitect } = require('@architect-engine/sdk/bundler/next');
module.exports = withArchitect({ /* your Next.js config */ });

With Vite

// vite.config.ts
import { architectVite } from '@architect-engine/sdk/bundler/vite';
export default { plugins: [architectVite()] };

Features

• Entity system — schema-driven EEAF data model (entities, types, properties, facts) with type-safe queries
• Workflows — trigger and cancel multi-step workflows with ephemeral or autonomous execution modes
• Simulation sandbox — create and run simulations against an in-memory backend with zero writes to production data
• Bitemporal journal — append-only audit log with topic-based reads and cursor pagination
• Real-time subscriptions — push-based entity change events via WebSocket with cursor-based resume
• Secret store — access secrets with TTL handles and one-time read support
• Schema mutations — write schema changes (entity types, properties) through the SDK
• External integrations — call external services through the engine's managed HTTP pipeline
• Custom WASM plugins — execute user-provided WASM functions with timeout control
• Execution Nodes — invoke compute/storage/network jobs on any device via the AEP protocol
• Local-first — reads are instant (local SQLite via OPFS), writes sync in the background
• Multi-database — one boot(), unlimited connect() calls to independent databases
• Offline-capable — works without network; automatically syncs when connectivity returns
• Multi-tab safe — Web Lock-based leader election prevents database corruption across browser tabs
• Type-safe — full TypeScript types for every operation, result, and error
• Structured errors — every error includes a machine-readable code and a remediation string
• Zero-config bundler support — first-class plugins for Vite, Webpack, and Next.js

What It Costs You

| Dimension | Cost | |-----------|------| | SDK bundle | ~38 JS files + 38 .d.ts type files. Zero native binaries in the npm package. | | Engine binary | ~2MB WASM, fetched separately at build time by architect-sync (not bundled in npm). | | Read latency | Microseconds — reads hit local SQLite, no network round-trip. | | Write latency | Local write is instant. Sync to cloud is async and batched. | | Build time | Vite/Webpack plugin adds <1s. Engine sync is a one-time download cached locally. | | Learning curve | 3 concepts: boot() (once), connect() (per database), then call any method on the connection. | | Peer dependencies | None. The SDK is self-contained. Engine binary is fetched, not installed. |

Supported Environments

| Environment | Version | Notes | |-------------|---------|-------| | Chrome / Edge | 102+ | Requires OPFS + Web Workers + SharedArrayBuffer | | Firefox | 111+ | Requires OPFS + Web Workers + SharedArrayBuffer | | Safari | 16.4+ | Requires OPFS + Web Workers + SharedArrayBuffer | | Node.js | 18+ | Via Tauri or Daemon adapter (no OPFS needed) | | Vite | 5+ | Plugin: @architect-engine/sdk/bundler/vite | | Webpack | 5+ | Plugin: @architect-engine/sdk/bundler/webpack | | Next.js | 13+ | Wrapper: @architect-engine/sdk/bundler/next | | React | 18+ | Hooks: @architect-engine/sdk/react |

Requires cross-origin isolation in browser environments. Your server must set Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers. Without these, SharedArrayBuffer is unavailable and boot() will throw MissingCrossOriginIsolationError with the exact headers to add.

API

Architect

| Method | Returns | Description | |--------|---------|-------------| | Architect.boot(config?) | Promise<void> | One-time engine initialization. Idempotent — concurrent calls share one promise. | | Architect.connect(config) | Promise<ArchitectConnection> | Open a database connection. Lightweight, call as many times as needed. | | Architect.status() | BootStatus | Synchronous snapshot of engine boot state. | | Architect.reset() | Promise<void> | Tear down the engine (for testing). |

ArchitectConnection

Data

| Method | Returns | Description | |--------|---------|-------------| | db.query(request) | Promise<QueryResult> | Read entities by type, ID, or arbitrary filter. | | db.transact(operations, options?) | Promise<TransactResult> | Atomic write: create, update, delete, patch. All-or-nothing. | | db.schemaWrite(operations) | Promise<TransactResult> | Write schema changes (entity types, properties). |

Workflows & Actions

| Method | Returns | Description | |--------|---------|-------------| | db.executeAction(id, params?, options?) | Promise<ActionResult> | Execute a named action with optional parameters. | | db.workflowTrigger(workflowId, options?) | Promise<ActionResult> | Trigger a workflow (ephemeral or autonomous mode). | | db.workflowCancel(executionId) | Promise<void> | Cancel a running workflow execution. |

Simulation

| Method | Returns | Description | |--------|---------|-------------| | db.createSimulation(workflowId, config) | Promise<SimulationResult> | Create a simulation sandbox. Zero writes to production data. | | db.runSimulation(simulationId) | Promise<SimulationResult> | Execute a prepared simulation and return results. |

Journal & Secrets

| Method | Returns | Description | |--------|---------|-------------| | db.journalAppend(entry) | Promise<JournalAppendResult> | Append to the bitemporal audit journal. | | db.journalRead(topic, options?) | Promise<JournalReadResult> | Read journal entries by topic with cursor pagination. | | db.secretAccess(operation, name, options?) | Promise<SecretAccessResult> | Access secrets with TTL handles and one-time read support. |

Real-Time

| Method | Returns | Description | |--------|---------|-------------| | db.subscribe(filter, callback, options?) | SubscriptionHandle | Push-based entity change events. Returns { id, cursor, unsubscribe() }. | | db.cancel(requestId) | Promise<void> | Cancel an in-flight request by ID. |

Integrations

| Method | Returns | Description | |--------|---------|-------------| | db.callExternal(url, options?) | Promise<CallExternalResult> | Call external services through the engine's managed HTTP pipeline. | | db.runWasm(request) | Promise<RunWasmResult> | Execute custom WASM plugin functions with timeout control. | | db.invoke(request) | AsyncIterable<JobEvent> | Execute a job on an Execution Node — compute, storage, or network. |

Connection Lifecycle

| Method | Returns | Description | |--------|---------|-------------| | db.close() | Promise<void> | Close the connection and release resources. | | db.isConnected() | boolean | Check if the connection is still open. | | db.updateToken(token) | Promise<void> | Rotate Turso JWT without reconnecting. | | db.terminateSync() | void | Synchronous teardown for beforeunload handlers. |

React Hooks (@architect-engine/sdk/react)

| Hook | Returns | Description | |------|---------|-------------| | useArchitect(config?) | { connection, status, error, retry } | Connection with full lifecycle. | | useArchitectSuspense(config?) | ArchitectConnection | Suspense-based connection (React 18+). | | useEntity(entityId) | Entity \| null | Real-time single entity (WebSocket push). | | useEntities(filter?) | Entity[] | Real-time entity list by filter. | | useEntityIds(typeId) | string[] | Real-time entity IDs by type. | | useEvents(filter?) | PushEvent[] | Real-time event stream. | | useRelationships(entityId) | Entity[] | Real-time related entities. |

Configuration

// Boot options
Architect.boot({
  licenseKey: process.env.ARCHITECT_LICENSE_KEY, // optional
});

// Connect options
architect.connect({
  database: 'my-app',          // required — database name (becomes the OPFS filename)
  tursoUrl: '...',             // optional — Turso sync URL for cloud replication
  tursoToken: '...',           // optional — Turso auth token
});

Multi-Database

Boot is expensive (loads the engine). Connect is cheap (opens a database). Multiple databases share one engine instance:

const architect = await Architect.boot();

const appDb = await architect.connect({ database: 'app' });
const analyticsDb = await architect.connect({ database: 'analytics' });

// Queries and transactions are scoped to each database
const users = await appDb.query({ filter: { type_id: 'type:user' } });
const events = await analyticsDb.query({ filter: { type_id: 'type:event' }, limit: 100 });

// Optional: cloud sync via Turso
const syncedDb = await architect.connect({
  database: 'synced-app',
  tursoUrl: 'libsql://your-db.turso.io',
  tursoToken: process.env.TURSO_TOKEN,
});

Simulation Example

Test workflows without touching production data:

// Create a simulation sandbox
const sim = await db.createSimulation('workflow:onboarding', {
  seed: 42,
  parameters: { userId: 'user:test' },
});

// Run it — all writes go to an in-memory backend
const result = await db.runSimulation(sim.simulationId);

console.log(result.statistics); // { stepsExecuted: 5, duration: 120 }
console.log(result.results);    // step-by-step execution trace
// Production database is untouched

Real-Time Subscriptions

const handle = db.subscribe(
  { typeIds: ['type:task'] },
  (event) => {
    console.log('Change:', event.data);
    console.log('WriteSet:', event.writeset?.changes);
  },
  { cursor: lastKnownCursor } // resume from where you left off
);

// Later
handle.unsubscribe();

Execution Node Example

Run arbitrary compute, storage, or network jobs on any connected device via the AEP wire protocol:

// Run a shell command on a connected Execution Node
for await (const event of db.invoke({
  tool: 'compute.process',
  args: { argv: ['npm', 'install'], cwd: '/workspace' },
})) {
  if (event.kind === 'stdout') console.log(event.data);
  if (event.kind === 'terminal') console.log('Exit:', event.data);
}

The Embodiment layer exposes three universal primitives — compute, storage, and network — that cover 100% of real-world actions on any device (macOS, Linux, Windows, iOS, Android, Web, and more). New capabilities are always recipes/plugins (data), never new code.

| Primitive | Example Tools | What It Does | |-----------|--------------|--------------| | compute | compute.process, compute.container, compute.wasm | Shell commands, Docker, WASM execution | | storage | storage.read, storage.write, storage.list | File system reads, writes, enumeration | | network | network.http, network.tunnel | HTTP calls, protocol tunnels (CDP, databases) |

Error Handling

Every error includes a machine-readable code and a remediation telling you exactly how to fix it. Here's what you see in the console when something goes wrong:

ArchitectSdkError [NOT_BOOTED]: Architect.boot() has not been called.
    Remediation: Call Architect.boot() before connect().
    at ArchitectConnection.connect (architect.js:42)

Catching errors in code:

import { Architect, ArchitectSdkError } from '@architect-engine/sdk';

try {
  const db = await architect.connect({ database: 'my-app' });
} catch (error) {
  if (error instanceof ArchitectSdkError) {
    console.error(error.code);        // 'NOT_BOOTED'
    console.error(error.message);     // 'Architect.boot() has not been called'
    console.error(error.remediation); // 'Call Architect.boot() before connect()'
    console.error(error.cause);       // original underlying error, if any
  }
}

Error Codes

| Code | When | Remediation | |------|------|-------------| | ENGINE_NOT_VENDORED | Engine binary not found at expected path. | Run npx architect-sync to download the engine. | | BOOT_FAILED | Engine initialization failed (WASM load, verification). | Check console for underlying cause. Ensure COOP/COEP headers are set. | | NOT_BOOTED | connect() called before boot() completed. | Call await Architect.boot() before any connect() call. | | NOT_CONNECTED | Operation on a closed connection. | Check db.isConnected() or call connect() again. | | QUERY_FAILED | Query execution error (bad filter, missing table). | Check filter format and entity type exists. | | TRANSACT_FAILED | Transaction execution error (constraint violation, conflict). | Check operation data matches schema. | | ACTION_FAILED | Action execution error. | Check action ID exists and parameters are valid. |

Common Gotchas

Forgetting cross-origin isolation headers. The engine uses SharedArrayBuffer which requires COOP/COEP headers. Without them, boot() throws MissingCrossOriginIsolationError with the exact headers to add. In Vite dev mode, the plugin handles this automatically.

Calling connect() before boot() resolves. boot() is async and takes a moment to load the WASM engine. Always await it. If you forget, you get NOT_BOOTED with a clear remediation message.

Opening the same database in multiple tabs without the SDK. The SDK handles multi-tab coordination via Web Locks automatically. If you bypass the SDK and access OPFS directly, you risk database corruption.

Not closing connections. Each connect() allocates a database slot with a WASM worker. Call db.close() when done, or the slot stays open until the page unloads. Idle slots auto-suspend after 30 seconds, but explicit cleanup is better.

Not For

• Server-only workloads with no browser component — the engine is optimized for browser OPFS. For pure server-side database needs, use Turso/libSQL directly.
• Sub-100KB bundle budgets — the engine WASM binary is ~2MB (fetched once, cached). If your total bundle budget is tiny, this adds meaningful weight.
• Legacy browser support (IE11, older Safari) — requires OPFS, Web Workers, and SharedArrayBuffer. No polyfill path exists for these APIs.

Why Boot/Connect?

Most SDKs make you repeat expensive setup on every connection. Architect separates the two concerns:

• boot() — loads the WASM engine, verifies entitlements, sets up the kernel bridge. Expensive. Happens once.
• connect() — opens a named database slot. Cheap. Happens per database.

Your app pays the boot cost once, then opens as many databases as it needs with near-zero overhead. Concurrent boot() calls are deduplicated — the engine is truly initialized only once regardless of how many components call boot() simultaneously.

Engine Performance

The SDK connects to an engine operating at game engine speeds. All UI lives in the database as EEAF entities — the composition engine is a generic renderer with zero knowledge of what it renders. Changes produce incremental delta patches; the scene tree is never fully redrawn.

Measured pipeline timings (production WASM, Chrome, OPFS):

| Operation | Time | |-----------|------| | Full pipeline warm cache (projection → composition → delta snapshot) | 1.82ms | | Template insert end-to-end (average across all types) | 3.63ms | | Binding evaluation (compute phase) | 0.59ms | | Layout algorithm | 0.17ms | | FSM dispatch / tab changes | 0.95ms (sub-1ms) |

The SDK transport adds approximately 1ms of serialization overhead. Total latency from action to visual update remains well under one frame (16ms).

SDK-First Architecture

Architect follows the same SDK-first pattern as Stripe (whose dashboard consumes the public API), Amazon (Bezos API mandate), and Turso (cloud product consumes the open-source engine). Every first-party Architect application — iOS, Android, web, and desktop — connects to the engine through the same SDK that third-party developers use. There is no "internal API" with more capabilities. The SDK is the complete interface.

This has two consequences:

1. The SDK is battle-tested at the highest fidelity. Every feature in a first-party Architect app was built through Architect.boot() and architect.connect(). If the SDK can't do it, Architect can't do it — so the SDK stays complete.
2. Third-party developers start from parity, not a subset. You have access to the same primitives as the engine's own authors. No hidden capabilities, no restricted APIs.

License

UNLICENSED — All rights reserved.