@4fu/arbor-journal-sqlite 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4fuu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# arbor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+arbor is a framework for an agent without sessions: many context windows run
+at once over one shared record, so work moves in parallel, replies come fast,
+and every window can find everything that was ever done.
+
+A deployment composes the pieces it wants and registers plugins for the domains
+it serves. The framework guarantees what an agent cannot guarantee for itself -
+the record, isolation, exactly-once effects, the checks, dispatch - and leaves
+everything that takes judgment, such as git, merges and conflicts, to the agent.
+
+## Core ideas
+
+- **No sessions to manage.** Work runs in disposable context windows. Any
+  number run at the same time; none of them owns anything, and a window that
+  ends loses nothing. The model looks up what it needs instead of carrying it.
+- **One record, shared live.** Every input, tool call, result, send and note
+  revision goes into one journal and is visible to every window as
+  soon as it is written. Records never merge and are never lost.
+- **Dispatch by a judge.** A judge (Jev by default, replaceable) decides which
+  live window takes a new input, or opens a new one. There is no router session
+  and no main line.
+- **Current without locks.** Windows run in parallel. New events on a
+  conversation a window is in are steered into it as they arrive; only a note
+  write is checked against the revision the window read.
+- **Mechanisms in the framework, policy in the agent.** The framework
+  guarantees what an agent cannot guarantee for itself - the record, isolation,
+  exactly-once effects, the checks, dispatch. Everything that takes judgment,
+  such as git, merges and conflicts, is the agent's.
+- **A directory per window.** Each window gets its own directory, and a
+  continuation keeps working in its predecessor's directory in place. It is not
+  bound to a repository; the agent clones and pushes what it needs.
+- **A self-changing environment.** The model adds and changes skills, MCP
+  servers and resident services itself; a `reload` validates the change and
+  broadcasts it to every live window as a delta of names and descriptions.
+- **Minimal limits.** The framework sets no policy. Permissions, privacy
+  review, budgets and approvals belong to deployments built on it, through
+  hooks.
+- **Direct tools plus code mode.** Decisions are direct tools; everything else
+  is a module called from `code_exec`. There is no CLI.
+- **Every module is replaceable.** The agent backend (pi by default), the
+  journal, notes, workspaces, the judge, channels and the rest are interfaces
+  ([docs/architecture.md](docs/architecture.md#interfaces)).
+
+## Install
+
+Node 24 or newer. Every package is published separately, so a deployment
+installs the core and the defaults it wants:
+
+```sh
+npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
+  @4fu/arbor-environment-dir @4fu/arbor-supervisor-process @4fu/arbor-agent-pi \
+  @4fu/arbor-workspace-dir
+```
+
+`@4fu/arbor-plugin-http` is optional; it is the example plugin below.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+
+## A minimal host
+
+The smallest host needs a journal and a backend. Adding the defaults and one
+plugin is what a deployment usually starts from:
+
+```js
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Arbor } from "@4fu/arbor-core";
+import { DirectoryEnvironment } from "@4fu/arbor-environment-dir";
+import { SqliteJournal } from "@4fu/arbor-journal-sqlite";
+import { SqliteNoteStore } from "@4fu/arbor-notes-sqlite";
+import { ProcessSupervisor } from "@4fu/arbor-supervisor-process";
+import { DirectoryWorkspace } from "@4fu/arbor-workspace-dir";
+import { PiAgentBackend } from "@4fu/arbor-agent-pi";
+import { HttpChannel, httpPlugin } from "@4fu/arbor-plugin-http";
+
+const root = await mkdtemp(join(tmpdir(), "arbor-"));
+
+// Every module below is a default implementation of an interface. Replace any
+// one by passing your own; the host does not change.
+const journal = new SqliteJournal({ path: join(root, "journal.sqlite") });
+const notes = new SqliteNoteStore({ path: join(root, "notes.sqlite"), journal });
+const supervisor = new ProcessSupervisor({ root: join(root, "services") });
+const environment = new DirectoryEnvironment({ root: join(root, "env"), supervisor });
+const workspace = new DirectoryWorkspace({ root: join(root, "workspaces") });
+
+// A plugin adds; it never patches the core. This one is a chat channel: a
+// webhook in, a window's sends out, and a page that drives the whole host.
+let arbor;
+const channel = new HttpChannel({ host: "127.0.0.1", port: 8787, board: () => arbor.boardLines() });
+arbor = new Arbor({
+  journal,
+  notes,
+  backend: new PiAgentBackend(),
+  workspace,
+  environment,
+  supervisor,
+  plugins: [httpPlugin({ channel })],
+});
+
+await arbor.start();
+await channel.listen();
+```
+
+`arbor.open(task)` dispatches one task, and the journal is where everything that
+happened can be read back ([docs/journal.md](docs/journal.md)). The workspace a
+window gets, and how a continuation keeps working in it, are in
+[docs/workspaces.md](docs/workspaces.md).
+
+## Packages
+
+| Package | What it is |
+| --- | --- |
+| [`@4fu/arbor-interfaces`](packages/interfaces) | every replaceable interface, plus the core's own shapes. Types only. |
+| [`@4fu/arbor-errors`](packages/errors) | the error shape every refusal uses: the rule and the next action |
+| [`@4fu/arbor-prompt`](packages/prompt) | typed blocks, the one deterministic renderer and the replaceable text table |
+| [`@4fu/arbor-tools`](packages/tools) | the entry points: direct tools, code mode modules, the host API |
+| [`@4fu/arbor-journal-sqlite`](packages/journal-sqlite) | the default `Journal` and `BlobStore` on SQLite |
+| [`@4fu/arbor-notes-sqlite`](packages/notes-sqlite) | the default `NoteStore` on SQLite, beside the journal |
+| [`@4fu/arbor-segmenter-jieba`](packages/segmenter-jieba) | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
+| [`@4fu/arbor-environment-dir`](packages/environment-dir) | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
+| [`@4fu/arbor-supervisor-process`](packages/supervisor-process) | the default `Supervisor`: one host process per service, restart with backoff, logs |
+| [`@4fu/arbor-judge-jev`](packages/judge-jev) | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
+| [`@4fu/arbor-agent-pi`](packages/agent-pi) | the default `AgentBackend`: pi-agent-core in process |
+| [`@4fu/arbor-plugin-http`](packages/plugin-http) | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| [`@4fu/arbor-core`](packages/core) | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects and schedules |
+
+### Defaults are examples
+
+Every default above is a reference implementation of its interface, written to
+be read and replaced. A real deployment is expected to swap out the ones that do
+not fit: the SQLite journal and notes, the directory workspace, the process
+supervisor, the environment directory, the HTTP test plugin and the Jev judge
+are all examples of what an interface can be satisfied by, not commitments.
+What a deployment keeps is its own choice, and the interfaces are the contract
+([docs/architecture.md](docs/architecture.md#interfaces)).
+
+Each package's own documentation holds the limits of that default, so a
+deployment can see what it would be taking on before it adopts one.
+
+## Documents
+
+| Page | Contents |
+| --- | --- |
+| [docs/overview.md](docs/overview.md) | goals, concepts, principles, routes considered |
+| [docs/architecture.md](docs/architecture.md) | layers, interfaces, stack, models, plugins, hooks, data placement |
+| [docs/journal.md](docs/journal.md) | events and their order, targets, watermarks, external ids, refs, tracing, media, redaction |
+| [docs/windows.md](docs/windows.md) | window lifecycle, prompt layout, reminders, continuation |
+| [docs/dispatch.md](docs/dispatch.md) | task sources, judge decisions, insertion timing, backpressure, scheduled tasks |
+| [docs/coordination.md](docs/coordination.md) | the board, expectations, deliveries and broadcasts, staying current, effects |
+| [docs/environment.md](docs/environment.md) | skills, MCP servers and services: using, changing, reload, built-in skills, deltas |
+| [docs/memory.md](docs/memory.md) | notes, the active set, anchors, links |
+| [docs/workspaces.md](docs/workspaces.md) | per-window directories: isolation, continuity, what the agent does |
+| [docs/tools.md](docs/tools.md) | direct tools and code mode modules |
+| [docs/prompting.md](docs/prompting.md) | how every model-facing text is written: layers, notes, deliveries, errors, judge questions, terms |
+| [docs/release.md](docs/release.md) | calendar versioning, the manual release steps, how a package is published |
+
+## Repository layout
+
+`pnpm check` typechecks and tests every package on its TypeScript sources.
+`pnpm build` emits the `dist` publishing needs, and `pnpm pack` shows what each
+tarball would contain ([docs/release.md](docs/release.md)).
+
+| Path | Layer |
+| --- | --- |
+| `packages/interfaces` | the interfaces layer: every replaceable interface, plus the core's own shapes. Types only. |
+| `packages/errors` | the error shape every refusal uses: the rule and the next action |
+| `packages/journal-sqlite` | the default `Journal` and `BlobStore` on SQLite |
+| `packages/segmenter-jieba` | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| `packages/notes-sqlite` | the default `NoteStore` on SQLite, beside the journal |
+| `packages/judge-jev` | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
+| `packages/workspace-dir` | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |
+| `packages/environment-dir` | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
+| `packages/supervisor-process` | the default `Supervisor`: one host process per service, restart with backoff, logs |
+| `packages/plugin-http` | the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
+| `packages/prompt` | typed blocks, the one deterministic renderer and the replaceable text table |
+| `packages/agent-pi` | the default `AgentBackend`: pi-agent-core in process |
+| `packages/tools` | the entry points: direct tools, code mode modules, the host API |
+| `packages/core` | the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects, schedules and the snapshot epochs |
+
+`mise.toml` pins the toolchain - Node and pnpm - installed under
+`~/.local/share/mise`, and `.agents/setup` prepares a machine from it. A machine
+without mise is expected to carry Node 24 or newer and pnpm 12 already.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/blob-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Media and files are stored once by content beside the journal; events hold
+ * their refs (docs/journal.md#media). The journal never keeps the bytes.
+ *
+ * `FsBlobStore` keeps the bytes in one directory. Which id a piece of content
+ * has is the journal's business - the ref an event carries is `b7`, and the
+ * content hash decides whether two writes are the same content - so the store
+ * takes a registry that the journal implements against its own database. A
+ * deployment that keeps media elsewhere implements `BlobStore` itself.
+ */
+import type { BlobContent, BlobInfo, BlobInput, BlobRef, BlobStore } from "@4fu/arbor-interfaces";
+/** What a store needs to know about one stored blob. */
+export interface BlobEntry {
+    path: string;
+    size: number;
+    mime?: string;
+    time: number;
+}
+/** The id space, owned by the journal's database. */
+export interface BlobRegistry {
+    /** The id this content hash already has, when it is stored. */
+    idFor(sha256: string): number | null;
+    /** Record a new blob and return its id. */
+    allocate(sha256: string, size: number, mime?: string, time?: number): number;
+    /** The stored entry for an id. */
+    entryFor(id: number): BlobEntry | null;
+    /** Forget an id, so the bytes may be erased. */
+    forget(id: number): void;
+}
+export declare function blobRefOf(id: number): BlobRef;
+export declare function blobIdOf(ref: string): number | null;
+export declare class FsBlobStore implements BlobStore {
+    private readonly directory;
+    private readonly registry;
+    /** One write at a time, so two writes of the same content share one id. */
+    private queue;
+    constructor(directory: string, registry: BlobRegistry);
+    put(input: BlobInput): Promise<BlobRef>;
+    private write;
+    get(ref: BlobRef): Promise<BlobContent | null>;
+    has(ref: BlobRef): Promise<boolean>;
+    stat(ref: BlobRef): Promise<BlobInfo | null>;
+    delete(ref: BlobRef): Promise<void>;
+    private pathFor;
+}

package/blob-store.js

@@ -0,0 +1,104 @@
+/**
+ * Media and files are stored once by content beside the journal; events hold
+ * their refs (docs/journal.md#media). The journal never keeps the bytes.
+ *
+ * `FsBlobStore` keeps the bytes in one directory. Which id a piece of content
+ * has is the journal's business - the ref an event carries is `b7`, and the
+ * content hash decides whether two writes are the same content - so the store
+ * takes a registry that the journal implements against its own database. A
+ * deployment that keeps media elsewhere implements `BlobStore` itself.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function blobRefOf(id) {
+    return `b${id}`;
+}
+export function blobIdOf(ref) {
+    const match = /^b(\d+)$/.exec(ref);
+    return match === null ? null : Number(match[1]);
+}
+function toBuffer(data) {
+    if (typeof data === "string")
+        return Buffer.from(data, "utf8");
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+export class FsBlobStore {
+    directory;
+    registry;
+    /** One write at a time, so two writes of the same content share one id. */
+    queue = Promise.resolve();
+    constructor(directory, registry) {
+        this.directory = directory;
+        this.registry = registry;
+    }
+    async put(input) {
+        const run = this.queue.then(() => this.write(input));
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    async write(input) {
+        const data = toBuffer(input.data);
+        const sha256 = createHash("sha256").update(data).digest("hex");
+        const existing = this.registry.idFor(sha256);
+        if (existing !== null)
+            return blobRefOf(existing);
+        await mkdir(this.directory, { recursive: true });
+        const id = this.registry.allocate(sha256, data.byteLength, input.mime);
+        const entry = this.registry.entryFor(id);
+        const path = entry?.path ?? this.pathFor(id);
+        await writeFile(path, data);
+        return blobRefOf(id);
+    }
+    async get(ref) {
+        const id = blobIdOf(ref);
+        if (id === null)
+            return null;
+        const entry = this.registry.entryFor(id);
+        if (entry === null)
+            return null;
+        try {
+            const data = await readFile(entry.path);
+            return { data: new Uint8Array(data), ...(entry.mime === undefined ? {} : { mime: entry.mime }) };
+        }
+        catch {
+            return null;
+        }
+    }
+    async has(ref) {
+        const id = blobIdOf(ref);
+        return id !== null && this.registry.entryFor(id) !== null;
+    }
+    async stat(ref) {
+        const id = blobIdOf(ref);
+        if (id === null)
+            return null;
+        const entry = this.registry.entryFor(id);
+        if (entry === null)
+            return null;
+        return {
+            ref: blobRefOf(id),
+            size: entry.size,
+            time: entry.time,
+            ...(entry.mime === undefined ? {} : { mime: entry.mime }),
+        };
+    }
+    async delete(ref) {
+        const id = blobIdOf(ref);
+        if (id === null)
+            return;
+        const entry = this.registry.entryFor(id);
+        if (entry === null)
+            return;
+        this.registry.forget(id);
+        try {
+            await unlink(entry.path);
+        }
+        catch {
+            // The bytes are already gone; the id is what an event holds.
+        }
+    }
+    pathFor(id) {
+        return join(this.directory, String(id));
+    }
+}

package/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @4fu/arbor-journal-sqlite - the default `Journal` and `BlobStore`.
+ */
+export { SqliteJournal, deriveLinks, parseEventRef, eventRefOf, summaryOf } from "./sqlite-journal.ts";
+export type { SqliteJournalOptions } from "./sqlite-journal.ts";
+export { FsBlobStore, blobIdOf, blobRefOf } from "./blob-store.ts";
+export type { BlobEntry, BlobRegistry } from "./blob-store.ts";
+export { fallbackSegmenter, resolveSegmenter, indexText } from "./segmenter.ts";
+export { SCHEMA_VERSION, IMPLICIT_CITE_WEIGHT, TRIGRAM_TABLE, WORD_TABLE, createSchema, } from "./schema.ts";
+export { buildFilters, escapeLike, likePattern, quoteFts, ranked, substring, trigramMatch, wordMatch, } from "./search.ts";
+export type { FilterSql, Ranked, SearchFilters } from "./search.ts";
+export { MIN_TRIGRAM_CHARS } from "./sqlite-journal.ts";

package/index.js

@@ -0,0 +1,9 @@
+/**
+ * @4fu/arbor-journal-sqlite - the default `Journal` and `BlobStore`.
+ */
+export { SqliteJournal, deriveLinks, parseEventRef, eventRefOf, summaryOf } from "./sqlite-journal.js";
+export { FsBlobStore, blobIdOf, blobRefOf } from "./blob-store.js";
+export { fallbackSegmenter, resolveSegmenter, indexText } from "./segmenter.js";
+export { SCHEMA_VERSION, IMPLICIT_CITE_WEIGHT, TRIGRAM_TABLE, WORD_TABLE, createSchema, } from "./schema.js";
+export { buildFilters, escapeLike, likePattern, quoteFts, ranked, substring, trigramMatch, wordMatch, } from "./search.js";
+export { MIN_TRIGRAM_CHARS } from "./sqlite-journal.js";

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@4fu/arbor-journal-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The default Journal: append-only events with a global sequence, targets, native ids, refs, blobs and lexical search on SQLite.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "blob-store.d.ts",
+    "blob-store.js",
+    "index.d.ts",
+    "index.js",
+    "schema.d.ts",
+    "schema.js",
+    "search.d.ts",
+    "search.js",
+    "segmenter.d.ts",
+    "segmenter.js",
+    "sqlite-journal.d.ts",
+    "sqlite-journal.js",
+    "stored.d.ts",
+    "stored.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/journal-sqlite"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "0.1.0",
+    "@4fu/arbor-interfaces": "0.1.0"
+  },
+  "peerDependencies": {
+    "@4fu/arbor-segmenter-jieba": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@4fu/arbor-segmenter-jieba": {
+      "optional": true
+    }
+  }
+}

package/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The SQLite schema for the journal (docs/journal.md).
+ *
+ * The journal is append-only: nothing is edited, nothing is deleted, nothing
+ * merges. The one exception is a redaction, which erases content in place and
+ * records, in its own event, that it did.
+ *
+ * Layout:
+ *
+ * - `events` - one row per event. `seq` is the one global order, assigned at
+ *   append and only growing; the ref is `r` + `seq`. `time` is for display.
+ * - `event_targets` - what an event touches, one row per target, indexed by
+ *   target for dispatch candidates, steering and notices.
+ * - `event_refs` - the refs an event names.
+ * - `event_blobs` - the media an event holds, by id; the bytes live in the
+ *   blob store beside the journal.
+ * - `links` - the links the host records between refs.
+ * - `watermarks` - the newest event on a target a window has seen.
+ * - `redactions` - which event redacted which, and why.
+ * - `blobs` - media stored once by content.
+ * - `events_fts` - trigram index for exact substrings.
+ * - `events_words` - word index for BM25.
+ */
+import type { DatabaseSync } from "node:sqlite";
+/** Bumped when a change makes an existing database unusable. */
+export declare const SCHEMA_VERSION = 2;
+/** A bare cite is weaker than a link the host declared. */
+export declare const IMPLICIT_CITE_WEIGHT = 0.5;
+export declare const TRIGRAM_TABLE = "events_fts";
+export declare const WORD_TABLE = "events_words";
+/** Create the schema when it is missing, migrate an older one, and record the version. */
+export declare function createSchema(db: DatabaseSync): void;
+export declare function readMeta(db: DatabaseSync, key: string): string | null;

package/schema.js

@@ -0,0 +1,145 @@
+/**
+ * The SQLite schema for the journal (docs/journal.md).
+ *
+ * The journal is append-only: nothing is edited, nothing is deleted, nothing
+ * merges. The one exception is a redaction, which erases content in place and
+ * records, in its own event, that it did.
+ *
+ * Layout:
+ *
+ * - `events` - one row per event. `seq` is the one global order, assigned at
+ *   append and only growing; the ref is `r` + `seq`. `time` is for display.
+ * - `event_targets` - what an event touches, one row per target, indexed by
+ *   target for dispatch candidates, steering and notices.
+ * - `event_refs` - the refs an event names.
+ * - `event_blobs` - the media an event holds, by id; the bytes live in the
+ *   blob store beside the journal.
+ * - `links` - the links the host records between refs.
+ * - `watermarks` - the newest event on a target a window has seen.
+ * - `redactions` - which event redacted which, and why.
+ * - `blobs` - media stored once by content.
+ * - `events_fts` - trigram index for exact substrings.
+ * - `events_words` - word index for BM25.
+ */
+/** Bumped when a change makes an existing database unusable. */
+export const SCHEMA_VERSION = 2;
+/** A bare cite is weaker than a link the host declared. */
+export const IMPLICIT_CITE_WEIGHT = 0.5;
+export const TRIGRAM_TABLE = "events_fts";
+export const WORD_TABLE = "events_words";
+const STATEMENTS = [
+    `PRAGMA journal_mode = WAL`,
+    `PRAGMA foreign_keys = ON`,
+    `PRAGMA busy_timeout = 5000`,
+    `CREATE TABLE IF NOT EXISTS meta (
+     key TEXT PRIMARY KEY,
+     value TEXT NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS events (
+     seq INTEGER PRIMARY KEY AUTOINCREMENT,
+     window TEXT,
+     time INTEGER NOT NULL,
+     kind TEXT NOT NULL,
+     external TEXT,
+     body TEXT,
+     redacted TEXT
+   )`,
+    // A redelivered outside message is stored once.
+    `CREATE UNIQUE INDEX IF NOT EXISTS events_external ON events (external) WHERE external IS NOT NULL`,
+    `CREATE INDEX IF NOT EXISTS events_window ON events (window, seq)`,
+    `CREATE INDEX IF NOT EXISTS events_kind ON events (kind, seq)`,
+    `CREATE TABLE IF NOT EXISTS event_targets (
+     seq INTEGER NOT NULL,
+     target TEXT NOT NULL,
+     PRIMARY KEY (seq, target)
+   )`,
+    `CREATE INDEX IF NOT EXISTS event_targets_target ON event_targets (target, seq)`,
+    `CREATE TABLE IF NOT EXISTS event_refs (
+     seq INTEGER NOT NULL,
+     ref TEXT NOT NULL,
+     PRIMARY KEY (seq, ref)
+   )`,
+    `CREATE INDEX IF NOT EXISTS event_refs_ref ON event_refs (ref, seq)`,
+    `CREATE TABLE IF NOT EXISTS event_blobs (
+     seq INTEGER NOT NULL,
+     blob TEXT NOT NULL,
+     PRIMARY KEY (seq, blob)
+   )`,
+    `CREATE TABLE IF NOT EXISTS links (
+     seq INTEGER NOT NULL,
+     from_ref TEXT NOT NULL,
+     to_ref TEXT NOT NULL,
+     kind TEXT NOT NULL,
+     weight REAL NOT NULL,
+     time INTEGER NOT NULL,
+     PRIMARY KEY (seq, to_ref, kind)
+   )`,
+    `CREATE INDEX IF NOT EXISTS links_to ON links (to_ref, weight DESC, seq DESC)`,
+    `CREATE INDEX IF NOT EXISTS links_from ON links (from_ref, seq DESC)`,
+    `CREATE TABLE IF NOT EXISTS watermarks (
+     window TEXT NOT NULL,
+     target TEXT NOT NULL,
+     seq INTEGER NOT NULL,
+     PRIMARY KEY (window, target)
+   )`,
+    `CREATE TABLE IF NOT EXISTS redactions (
+     covers INTEGER PRIMARY KEY,
+     by INTEGER NOT NULL,
+     reason TEXT NOT NULL,
+     time INTEGER NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS blobs (
+     id INTEGER PRIMARY KEY AUTOINCREMENT,
+     sha256 TEXT NOT NULL UNIQUE,
+     size INTEGER NOT NULL,
+     mime TEXT,
+     path TEXT NOT NULL,
+     time INTEGER NOT NULL
+   )`,
+    // Exact substrings, for Chinese and mixed text.
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${TRIGRAM_TABLE} USING fts5(body, tokenize = 'trigram')`,
+    // Words, for BM25.
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${WORD_TABLE} USING fts5(body, tokenize = 'unicode61')`,
+];
+/**
+ * Version 2 dropped the `snapshot` column from `events`: the workspace
+ * snapshots it named are gone with the plain-directory workspace
+ * (docs/workspaces.md). Every event, every ref and every index that does not
+ * name the column stays, so a version-1 database opens where it left off
+ * instead of being rebuilt.
+ */
+function migrateToVersion2(db) {
+    const columns = db.prepare("PRAGMA table_info(events)").all();
+    if (!columns.some((column) => column.name === "snapshot"))
+        return;
+    // An index that names the column has to go before the column does.
+    const indexes = db.prepare("PRAGMA index_list(events)").all();
+    for (const index of indexes) {
+        const keys = db.prepare(`PRAGMA index_info(${JSON.stringify(index.name)})`).all();
+        if (!keys.some((key) => key.name === "snapshot"))
+            continue;
+        db.exec(`DROP INDEX ${JSON.stringify(index.name)}`);
+    }
+    db.exec("ALTER TABLE events DROP COLUMN snapshot");
+}
+/** Create the schema when it is missing, migrate an older one, and record the version. */
+export function createSchema(db) {
+    // The version lives in the one table that has to exist before anything else.
+    db.exec(`CREATE TABLE IF NOT EXISTS meta (
+       key TEXT PRIMARY KEY,
+       value TEXT NOT NULL
+     )`);
+    const version = readMeta(db, "schema_version");
+    if (version !== null && Number(version) > SCHEMA_VERSION) {
+        throw new Error(`journal schema ${version} is newer than this build (${SCHEMA_VERSION}); upgrade arbor, or migrate the database`);
+    }
+    if (Number(version) === SCHEMA_VERSION - 1)
+        migrateToVersion2(db);
+    for (const statement of STATEMENTS)
+        db.exec(statement);
+    db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+}
+export function readMeta(db, key) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row === undefined ? null : row.value;
+}