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/           │   │ database                   │
│ capabilities/ i18n/           │   │ (one artifact)             │   │ apps load and run          │
│ +agents.md                    │   └────────────────────────────┘   └────────────────────────────┘
│ (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

Collection transforms, automations, pipelines, functions, 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 — a collection’s transform runs once per admitted batch of creates and updates; automations run on a schedule or collection change and receive the triggering row as scope.incoming_record ; import/export pipelines and functions serve requests. Validation stays in ~standard , so there is no zod in authoring.

handler: ({ input, api }) =>
	Effect.gen(function* () {
		const site = yield* api.db.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, and the browser client; bolt sync builds the server artifact separately, and bolt migrate writes schema SQL
• Collection runtime — SQL compilation, policy evaluation, approvals, collection transforms, and functions
• Sync engine — live queries , optimistic writes, and in-memory query state updated by SSE
• Application shell — generated app loaders, typed client access, and the device seam (client.device: location, share, copy, haptics, online) with typed refusals
• 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 — server-registered live queries, mutation pushes, and SSE apply frames
• Durable automations — scheduled, collection-event, and manually invoked functions the host admits — not the infrastructure task queue
• 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 is the .norbital/artifact/ directory a host like Colony loads — bundle.mjs, its code/*.mjs graph, release.json, and digest-addressed assets carrying the schema, migration lineage, browser and server assets, lockfile, and code.

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 register server-authoritative live queries and push optimistic writes with client.collection.<collection>.create(input) — 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 commit a write provisionally under a hold, then seal or restore it. 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 — collection surfaces, 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