Bolt framework

This page is the mental model for everything that follows — what Bolt is, what it owns, and where Colony begins. @norbital-ai/bolt is the filesystem compiler, authoring SDK, runtime, client, and Vite plugin for tenant workspaces. You never hand-wire it together — you place one declaration in each recognized role under src/ , and Bolt derives everything else. Colony is the host, not a Bolt dependency.

Author → Build → Run

┌────────── Author ───────────┐   ┌────────── Build ───────────┐   ┌─────────── Run ────────────┐
│ src/                         │   │ bolt sync                  │   │ Colony hosts the           │
│ collections/  apps/          │──►│ validates every role       │──►│ immutable artifact         │
│ automations/ functions/      │──►│ generates $types           │──►│ provisions the tenant      │
│ access/ capabilities/        │   │ builds the client          │   │ database                   │
│ envoys/ datatypes/           │   │ emits .norbital/           │   │ apps load and run          │
│ +agents.md  +seed.ts         │   │ (one artifact)             │   └────────────────────────────┘
│ (one declaration per role)   │   └────────────────────────────┘
└──────────────────────────────┘

1. Author — one declaration per recognized src/** filesystem role. No registration files, no hand-written assembly.
2. Build — bolt sync runs the Bolt plugin: it synchronizes the filesystem (generated types, registries, and the compiled client) and emits the portable artifact plus migrations under .norbital/ .
3. Run — Colony hosts the immutable artifact and provisions the tenant database. Bolt’s sync engine keeps every browser client live against that database.

Effect-based authoring

Hooks, automations, pipelines, remotes, and agent tools are Effect-native : handlers are Effect.gen(function* () { … }) functions, and every api.db.* / api.infer / api.readFileAsset call is an Effect you yield* . The runtime executes them — before/after hooks wrap create, update, and delete; automations run on a schedule or collection change and receive the triggering row as scope.incoming_record ; import/export pipelines and remotes serve requests. Validation stays in ~standard , so there is no zod in authoring.

handler: ({ input, api }) =>
	Effect.gen(function* () {
		const site = yield* api.db.query.sites.findFirst({
			where: { id: { eq: input.site_id } }
		});
		if (site == null) refuse('Referenced site does not exist.');
		return input;
	})

Custom types with Effect Schema

Custom-type schemas are Effect Schema ( Schema.Struct , Schema.Union , Schema.Literals , Schema.NullOr ) composed from effect , validated through ~standard via Schema.toStandardSchemaV1 . There is no zod in authoring.

The bolt CLI

The bolt binary drives the workspace lifecycle from any checkout:

• bolt sync — regenerate workspace types, build the client, and emit a portable artifact
• bolt migrate — diff the authored models against the migration lineage and write the next entry
• bolt audit — run the static code-quality audit over the workspace

What Bolt owns

• Filesystem compiler — role discovery, validation, generated modules, and local types
• Vite plugin — Svelte, Tailwind, server/client builds, migrations, and DDL
• Collection runtime — SQL compilation, policy evaluation, approvals, hooks, and remotes
• Sync engine — live queries , optimistic writes, and a policy-scoped local replica
• Application shell — generated app loaders and typed client access
• Facility ports — database, files, AI, messaging, tasks, and host tools

Subsystems at a glance

Everything a workspace can do flows through a small set of subsystems, each documented on its own page:

• Client — the typed surface apps use to read, write, and invoke
• Sync engine — live queries, optimistic writes, and the local replica
• Durable automations — scheduled, collection-event, and agent-loop functions the host admits — not the infrastructure queue facility
• UI libraries — the layout primitives and collection surfaces apps compose
• Facilities — how hosts provide database, storage, models, and queues

One generated root

Bolt writes diagnostics, build output, generated modules, role types, migration history, and one generated TypeScript config under .norbital/ . Only .norbital/migrations/ is committed. Build output lives in .norbital/dist/ : the compiled browser client. The portable server artifact — the compiled runtime, tenant apps, assets, and migrations — is .norbital/artifact/bundle.mjs, the file a host like Colony loads.

System collections

Runtime-owned collections (user, session, account, verification, auth_config, team, approval_request, requestor) are merged into the manifest at build time; you never redefine them. Identity is the user, session, account, verification, and auth_config rows, and a subject belongs to exactly one team row. A policy is not a row either: it is a src/access/policies/+<name>.ts module in workspace source, compiled into the manifest beside the collections it grants. Tenant authors add domain collections on top. See System collections.

Data sync

Bolt includes a native sync engine : tenant apps read through live queries against a policy-scoped local replica and write optimistically with client.db.<collection>.mutate(values) — app code never calls invalidate , refetch , or revalidate . The read and write API authors use is documented in Live data .

Policies

Access is policy-based: reusable grants carried by teams, envoys, and automations, evaluated inside the bolt runtime on every read and mutation. Approval gates use write-then-lock. See Policies.

Facilities

Workspace code reaches Postgres, storage, AI, and secrets only through host-provided bindings — never direct credentials. Bolt exposes an ai facility port; the host binds the concrete provider at runtime.

What the host owns

A host supplies concrete facilities and operational isolation:

• Tenant database pools, object storage, model APIs, and credential storage
• Immutable artifact storage and bundle serving
• DDL validation, migration application, sign-in code delivery, and billing

Workspace source declares requirements, never secret values. Client code cannot access private runtime facilities.

Authoring contracts

Bolt seals a small set of public authoring surfaces for operational UI. These guides describe the contracts tenant authors rely on:

• UI components — schema-derived forms, custom types, and +representation.svelte overrides
• Navigation state — record-detail stacks in ?stack= and the sidesheet shell
• Layout — the layout primitives and the app body contract
• Live data — live queries, optimistic writes, and no manual cache invalidation

Workspace boundaries

• No SvelteKit dependencies, routes, +page files, or svelte.config.*
• No authored assembly registries or generated declarations
• No direct credentials, host internals, or custom bundling scripts
• No duplicate base CSS or Tailwind integration