@cavelang/store 0.1.0

package/dist/src/store.js

@@ -0,0 +1,266 @@
+/**
+ * The CAVE store (spec §13) — append-only claim persistence on the Node.js
+ * builtin `node:sqlite`.
+ *
+ * - one row per fact, canonical direction; inverses are query-time views
+ *   over existing indexes, never materialized rows (spec §13.3);
+ * - current belief = latest tx per claim key (spec §9.1, §13.5);
+ * - the verb registry is rebuilt from stored in-band declaration claims on
+ *   open, so a reopened database keeps its inverse vocabulary;
+ * - full-text search over subjects, objects, values, comments and raw
+ *   lines via FTS5.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { Claim, Key, Uuidv7, Verb } from '@cavelang/core';
+import * as Canonical from '@cavelang/canonical';
+import * as Row from "./row.js";
+import * as Schema from "./schema.js";
+const currentSql = `
+SELECT c.* FROM cave_claim c
+JOIN (
+  SELECT claim_key, MAX(tx) AS max_tx
+  FROM cave_claim GROUP BY claim_key
+) latest ON c.claim_key = latest.claim_key AND c.tx = latest.max_tx
+`;
+/**
+ * Opens (creating if necessary) a CAVE store. The registry defaults to the
+ * standard §5.5 prelude pairs and is extended by any declaration claims
+ * already stored; pass `Canonical.Registry.empty` for a declaration-free
+ * start.
+ */
+export const open = (path = ':memory:', options = {}) => {
+    const db = new DatabaseSync(path);
+    db.exec('PRAGMA foreign_keys = ON');
+    Schema.init(db);
+    let registry = options.registry ?? Canonical.standardRegistry;
+    const insertClaim = db.prepare(`
+    INSERT INTO cave_claim (
+      id, tx, subject, verb, negated, object, attribute,
+      value_text, value_num, value_unit, value_approx,
+      delta_text, delta_num, delta_unit, sigma_level,
+      conf, importance, comment, raw_line, claim_key
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const insertContext = db.prepare('INSERT INTO cave_context (claim_id, context) VALUES (?, ?)');
+    const insertTag = db.prepare('INSERT INTO cave_tag (claim_id, key, value) VALUES (?, ?, ?)');
+    const insertEdge = db.prepare('INSERT INTO cave_edge (parent_id, role, child_id) VALUES (?, ?, ?)');
+    const insertFts = db.prepare(`
+    INSERT INTO cave_fts (claim_id, subject, verb, object, attribute, value_text, comment, raw_line)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    /**
+     * Rebuilds in-band declarations from stored claims (ordered by tx),
+     * mirroring `@cavelang/canonical`'s `applyDeclarations` predicate exactly —
+     * the registry after reopen must equal the registry at close. Qualifier
+     * condition rows (children of WHEN/VIA/BECAUSE edges) never declared
+     * in-session, so they are excluded here too; `X IS verb` needs a
+     * verb-shaped plain-entity subject.
+     */
+    const rebuildRegistry = () => {
+        const declarations = db.prepare(`
+      SELECT subject, verb, object FROM cave_claim
+      WHERE negated = 0 AND object IS NOT NULL AND verb IN ('REVERSE', 'IS')
+        AND id NOT IN (SELECT child_id FROM cave_edge WHERE role IN ('WHEN', 'VIA', 'BECAUSE'))
+      ORDER BY tx
+    `).all();
+        for (const declaration of declarations) {
+            if (!Verb.isVerbToken(declaration.subject)) {
+                continue;
+            }
+            if (declaration.verb === 'REVERSE' && Verb.isVerbToken(declaration.object)) {
+                registry = Canonical.Registry.declareReverse(registry, declaration.subject, declaration.object).registry;
+            }
+            else if (declaration.verb === 'IS' && declaration.object === 'verb') {
+                registry = Canonical.Registry.declareVerb(registry, declaration.subject);
+            }
+        }
+    };
+    rebuildRegistry();
+    const transaction = (body) => {
+        db.exec('BEGIN');
+        try {
+            const result = body();
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    };
+    /** Appends a canonicalization result — one row per claim, per-row tx. */
+    const insertResult = (result) => transaction(() => {
+        const ids = [];
+        for (const entry of result.claims) {
+            const claim = entry.claim;
+            const id = Uuidv7.next();
+            const columns = Row.toColumns(claim);
+            const rawLine = columns.rawLine === '' ? Canonical.emitClaim(claim) : columns.rawLine;
+            insertClaim.run(id, id, columns.subject, columns.verb, columns.negated, columns.object, columns.attribute, columns.valueText, columns.valueNum, columns.valueUnit, columns.valueApprox, columns.deltaText, columns.deltaNum, columns.deltaUnit, columns.sigmaLevel, columns.conf, columns.importance, columns.comment, rawLine, Key.of(claim));
+            for (const context of claim.contexts) {
+                insertContext.run(id, context);
+            }
+            for (const tag of claim.tags) {
+                insertTag.run(id, tag.key, tag.value ?? null);
+            }
+            insertFts.run(id, columns.subject, columns.verb, columns.object, columns.attribute, columns.valueText, columns.comment, rawLine);
+            ids.push(id);
+        }
+        for (const edge of result.edges) {
+            insertEdge.run(ids[edge.parent], edge.role, ids[edge.child]);
+        }
+        registry = result.registry;
+        return { ids, edges: result.edges.length, problems: result.problems };
+    });
+    const rows = (sql, ...params) => db.prepare(sql).all(...params);
+    const contextsOf = (id) => db.prepare('SELECT context FROM cave_context WHERE claim_id = ?').all(id)
+        .map(row => row.context);
+    const tagsOf = (id) => db.prepare('SELECT key, value FROM cave_tag WHERE claim_id = ?').all(id);
+    const toClaim = (row) => Row.toClaim(row, contextsOf(row.id), tagsOf(row.id));
+    const traversalFilter = (options) => (options.negated === true ? '' : ' AND negated = 0') +
+        (options.retracted === true ? '' : ' AND conf > 0');
+    return {
+        /** Raw database handle — used by `@cavelang/query`; treat as read-only. */
+        db,
+        /** Current verb registry (input registry + stored + ingested declarations). */
+        registry: () => registry,
+        /**
+         * Parses, canonicalizes and appends CAVE text. Lenient by default —
+         * problems are returned, valid lines still land (spec §1.6); pass
+         * `strict` to throw instead.
+         */
+        ingest(text, options_ = {}) {
+            const result = Canonical.canonicalizeText(text, registry);
+            if (options_.strict === true && result.problems.length > 0) {
+                const detail = result.problems.map(problem => `  line ${problem.line}: ${problem.message}`).join('\n');
+                throw new Error(`CAVE ingest failed with ${result.problems.length} problem(s):\n${detail}`);
+            }
+            return insertResult(result);
+        },
+        /** Appends an already-canonicalized result. */
+        insertResult,
+        /** Latest row per claim key (spec §13.5), oldest first. */
+        currentBeliefs(options_ = {}) {
+            return options_.minConf === undefined ?
+                rows(`${currentSql} ORDER BY c.tx`) :
+                rows(`${currentSql} WHERE c.conf >= ? ORDER BY c.tx`, options_.minConf);
+        },
+        /** Current belief for one claim key, `undefined` if the fact is unknown. */
+        currentBelief(claimKey) {
+            const row = db.prepare('SELECT * FROM cave_claim WHERE claim_key = ? ORDER BY tx DESC LIMIT 1').get(claimKey);
+            return row;
+        },
+        /** Full belief series of one claim key, oldest first (spec §9.1). */
+        history(claimKey) {
+            return rows('SELECT * FROM cave_claim WHERE claim_key = ? ORDER BY tx', claimKey);
+        },
+        /** All rows about an entity, both directions, newest first (spec §13.5). */
+        claimsAbout(entity) {
+            return rows('SELECT * FROM cave_claim WHERE subject = ? OR object = ? ORDER BY tx DESC', entity, entity);
+        },
+        /** Forward reads: current relational facts with `entity` as subject (spec §13.3). */
+        forward(entity, options_ = {}) {
+            return rows(`SELECT * FROM (${currentSql}) WHERE subject = ? AND object IS NOT NULL${traversalFilter(options_)} ORDER BY tx`, entity).map(row => ({ verb: row.verb, target: row.object, row }));
+        },
+        /**
+         * Inverse reads (spec §13.3): current relational facts
+         * with `entity` as object, relation named via the registry's inverse
+         * when one is declared.
+         */
+        reverse(entity, options_ = {}) {
+            return rows(`SELECT * FROM (${currentSql}) WHERE object = ? AND object IS NOT NULL${traversalFilter(options_)} ORDER BY tx`, entity).map(row => {
+                const rel = Canonical.Registry.inverseOf(registry, row.verb);
+                return { verb: row.verb, ...rel === undefined ? {} : { rel }, source: row.subject, row };
+            });
+        },
+        /** Flat tag (`value` omitted → `value IS NULL`) or scoped tag rows (spec §13.5). */
+        byTag(key, value) {
+            return value === undefined ?
+                rows(`
+          SELECT c.* FROM cave_claim c JOIN cave_tag t ON c.id = t.claim_id
+          WHERE t.key = ? AND t.value IS NULL ORDER BY c.tx`, key) :
+                rows(`
+          SELECT c.* FROM cave_claim c JOIN cave_tag t ON c.id = t.claim_id
+          WHERE t.key = ? AND t.value = ? ORDER BY c.tx`, key, value);
+        },
+        /** Rows carrying a context (spec §13.5), newest first. */
+        byContext(context) {
+            return rows(`
+        SELECT c.* FROM cave_claim c JOIN cave_context ctx ON c.id = ctx.claim_id
+        WHERE ctx.context = ? ORDER BY c.tx DESC`, context);
+        },
+        /** Members of a topic — forward `CONTAINS` traversal (spec §11.2). */
+        topicMembers(topic, options_ = {}) {
+            return rows(`SELECT * FROM (${currentSql}) WHERE subject = ? AND verb = 'CONTAINS' AND object IS NOT NULL${traversalFilter(options_)} ORDER BY tx`, topic).map(row => row.object);
+        },
+        /** Topics containing an entity — the inverse `CONTAINS` read (spec §11.2). */
+        topicsOf(entity, options_ = {}) {
+            return rows(`SELECT * FROM (${currentSql}) WHERE object = ? AND verb = 'CONTAINS'${traversalFilter(options_)} ORDER BY tx`, entity).map(row => row.subject);
+        },
+        /**
+         * Full-text search, newest first. The query is treated as a literal
+         * phrase by default (safe for terms like `token-expiry`, which FTS5
+         * would otherwise parse as a column filter); pass `raw` to use full
+         * FTS5 MATCH syntax.
+         */
+        search(query, options_ = {}) {
+            const match = options_.raw === true ? query : `"${query.replaceAll('"', '""')}"`;
+            return rows(`
+        SELECT c.* FROM cave_claim c JOIN cave_fts f ON c.id = f.claim_id
+        WHERE cave_fts MATCH ? ORDER BY c.tx DESC`, match);
+        },
+        /** Qualifier/grouping edges of a claim row (spec §13.2). */
+        edgesOf(parentId) {
+            return db.prepare(`
+        SELECT e.role AS role, c.* FROM cave_edge e JOIN cave_claim c ON c.id = e.child_id
+        WHERE e.parent_id = ?`).all(parentId).map(({ role, ...child }) => ({ role, child: child }));
+        },
+        /** Reconstructs the full canonical claim of a row (side tables included). */
+        toClaim,
+        /**
+         * Emits the store as canonical CAVE text — all rows in transaction
+         * order, or only current beliefs with `current`.
+         *
+         * In current-only export an edge endpoint may be a superseded row;
+         * dropping such edges would silently un-condition current claims and
+         * promote orphaned WHEN conditions to top-level facts. Instead each
+         * endpoint resolves to the *current row of its claim key*, and the
+         * resulting edges are deduplicated.
+         */
+        exportText(options_ = {}) {
+            const current = options_.current === true;
+            const claimRows = current ?
+                rows(`${currentSql} ORDER BY c.tx`) :
+                rows('SELECT * FROM cave_claim ORDER BY tx');
+            const indexById = new Map(claimRows.map((row, index) => [row.id, index]));
+            let resolve = (id) => indexById.get(id);
+            if (current) {
+                const indexByKey = new Map(claimRows.map((row, index) => [row.claim_key, index]));
+                const keyById = new Map(db.prepare('SELECT id, claim_key FROM cave_claim').all()
+                    .map(row => [row.id, row.claim_key]));
+                resolve = id => indexById.get(id) ?? indexByKey.get(keyById.get(id) ?? '');
+            }
+            const claims = claimRows.map(row => ({ claim: toClaim(row), line: 0 }));
+            const edgeRows = db.prepare('SELECT parent_id, role, child_id FROM cave_edge').all();
+            const seen = new Set();
+            const edges = edgeRows.flatMap(edge => {
+                const parent = resolve(edge.parent_id);
+                const child = resolve(edge.child_id);
+                if (parent === undefined || child === undefined || parent === child) {
+                    return [];
+                }
+                const dedupe = `${parent}|${edge.role}|${child}`;
+                if (seen.has(dedupe)) {
+                    return [];
+                }
+                seen.add(dedupe);
+                return [{ parent, role: edge.role, child }];
+            });
+            return Canonical.emit({ claims, edges });
+        },
+        close() {
+            db.close();
+        }
+    };
+};
+//# sourceMappingURL=store.js.map

package/dist/src/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cavelang/store",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CAVE persistence on node:sqlite — §13 storage model, append-only belief series, inverse-aware reads.",
+  "license": "CC0-1.0",
+  "author": "Mirek Rusin (https://github.com/mirek)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mirek/cave.git",
+    "directory": "packages/store"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "!dist/tsconfig.tsbuildinfo",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "License.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cavelang/core": "0.1.0",
+    "@cavelang/canonical": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --disable-warning=ExperimentalWarning --test 'test/*.test.ts'",
+    "typecheck": "tsc -b"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * `@cavelang/store` — CAVE persistence on the Node.js builtin `node:sqlite`
+ * (spec §13).
+ *
+ * ```ts
+ * import { open } from '@cavelang/store'
+ *
+ * const store = open('knowledge.db')
+ * store.ingest('monorepo CONTAINS packages/api')
+ * store.reverse('packages/api')
+ * // → [{ verb: 'CONTAINS', rel: 'PART-OF', source: 'monorepo', … }]
+ * ```
+ */
+
+export * as Row from './row.ts'
+export * as Schema from './schema.ts'
+export { open } from './store.ts'
+export type { ForwardFact, IngestResult, ReverseFact, Store, TraverseOptions } from './store.ts'

package/src/row.ts

@@ -0,0 +1,136 @@
+/**
+ * Row mapping — canonical claims ↔ `cave_claim` rows.
+ *
+ * Terms are stored *formatted* (delimiters preserved): entities as plain
+ * text so §13.5 queries like `WHERE subject = 'auth/middleware'` work, code
+ * literals as `` `<=` `` and text literals as `"…"` so a literal never
+ * collides with a same-spelled entity. Values are stored as written
+ * (`value_text`, incl. `~`, multiplier letters and delimiters) alongside
+ * the normalized numeric value and unit (spec §13.4 step 9).
+ */
+
+import { Claim, Value } from '@cavelang/core'
+
+/** A `cave_claim` row. */
+export type Row = {
+  readonly id: string
+  readonly tx: string
+  readonly subject: string
+  readonly verb: string
+  readonly negated: number
+  readonly object: null | string
+  readonly attribute: null | string
+  readonly value_text: null | string
+  readonly value_num: null | number
+  readonly value_unit: null | string
+  readonly value_approx: number
+  readonly delta_text: null | string
+  readonly delta_num: null | number
+  readonly delta_unit: null | string
+  readonly sigma_level: null | number
+  readonly conf: number
+  readonly importance: number
+  readonly comment: null | string
+  readonly raw_line: string
+  readonly claim_key: string
+}
+
+export type t = Row
+
+/** @returns term parsed back from its stored formatted text. */
+export const parseTerm = (text: string): Claim.Term => {
+  if (text.length >= 2 && text.startsWith('`') && text.endsWith('`')) {
+    return Claim.code(text.slice(1, -1))
+  }
+  if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+    return Claim.text(text.slice(1, -1))
+  }
+  return Claim.entity(text)
+}
+
+/** @returns value parsed back from its stored as-written text. */
+export const parseValue = (text: string): Value.t => {
+  if (text.length >= 2 && text.startsWith('`') && text.endsWith('`')) {
+    return Value.ofCode(text.slice(1, -1))
+  }
+  if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+    return Value.ofText(text.slice(1, -1))
+  }
+  return Value.parse(text)
+}
+
+/** Column values of a claim, in `cave_claim` insert order (id/tx excluded). */
+export const toColumns = (claim: Claim.t): {
+  subject: string
+  verb: string
+  negated: number
+  object: null | string
+  attribute: null | string
+  valueText: null | string
+  valueNum: null | number
+  valueUnit: null | string
+  valueApprox: number
+  deltaText: null | string
+  deltaNum: null | number
+  deltaUnit: null | string
+  sigmaLevel: number
+  conf: number
+  importance: number
+  comment: null | string
+  rawLine: string
+  claimKey: string
+} => {
+  const payload = claim.payload
+  const value =
+    payload.kind === 'attribute' ? payload.value :
+    payload.kind === 'metric' ? payload.value :
+    undefined
+  return {
+    subject: Claim.formatTerm(claim.subject),
+    verb: claim.verb,
+    negated: claim.negated ? 1 : 0,
+    object: payload.kind === 'relation' ? Claim.formatTerm(payload.object) : null,
+    attribute: payload.kind === 'attribute' ? payload.attribute : null,
+    valueText: value === undefined ? null : Value.format(value),
+    valueNum: value?.num ?? null,
+    valueUnit: value?.unit ?? null,
+    valueApprox: value?.approx === true ? 1 : 0,
+    deltaText: claim.delta === undefined ? null : Value.format(claim.delta),
+    deltaNum: claim.delta?.num ?? null,
+    deltaUnit: claim.delta?.unit ?? null,
+    sigmaLevel: claim.sigmaLevel ?? 2,
+    conf: claim.conf,
+    importance: claim.importance ? 1 : 0,
+    comment: claim.comment ?? null,
+    rawLine: claim.raw,
+    claimKey: '' // filled by the store with Key.of on the canonical claim
+  }
+}
+
+/**
+ * @returns canonical claim reconstructed from a row plus its side tables.
+ * `sigmaLevel` collapses to `undefined` at the semantic default of 2.
+ */
+export const toClaim = (
+  row: Row,
+  contexts: readonly string[],
+  tags: readonly { key: string, value: null | string }[]
+): Claim.t =>
+  Claim.of({
+    subject: parseTerm(row.subject),
+    verb: row.verb,
+    negated: row.negated !== 0,
+    payload:
+      row.object !== null ? Claim.relation(parseTerm(row.object)) :
+      row.attribute !== null && row.value_text !== null ? Claim.attribute(row.attribute, parseValue(row.value_text)) :
+      row.value_text !== null ? Claim.metric(parseValue(row.value_text)) :
+      Claim.none,
+    contexts,
+    tags: tags.map(tag => tag.value === null ? { key: tag.key } : { key: tag.key, value: tag.value }),
+    conf: row.conf,
+    importance: row.importance !== 0,
+    ...row.delta_text !== null ? { delta: parseValue(row.delta_text) } : {},
+    ...row.sigma_level !== null && row.sigma_level !== 2 ? { sigmaLevel: row.sigma_level } : {},
+    ...row.comment !== null ? { comment: row.comment } : {},
+    raw: row.raw_line
+  })

package/src/schema.ts

@@ -0,0 +1,79 @@
+/**
+ * Storage schema (spec §13.1, §13.2) — verbatim from the specification,
+ * with `IF NOT EXISTS` added so opening an existing database is idempotent.
+ */
+
+import type { DatabaseSync } from 'node:sqlite'
+
+export const ddl = `
+CREATE TABLE IF NOT EXISTS cave_claim (
+  id            TEXT PRIMARY KEY,      -- UUIDv7
+  tx            TEXT NOT NULL,         -- UUIDv7, lexicographic = transaction order
+
+  subject       TEXT NOT NULL,         -- canonical (primary) direction
+  verb          TEXT NOT NULL,         -- canonical (primary) verb
+  negated       INTEGER NOT NULL DEFAULT 0,
+
+  object        TEXT,                  -- relation object, entity, literal
+  attribute     TEXT,                  -- for HAS attr: value
+  value_text    TEXT,                  -- value as written (incl. ~, multiplier, delimiters)
+  value_num     REAL,                  -- parsed numeric value when possible
+  value_unit    TEXT,                  -- normalized unit string
+  value_approx  INTEGER NOT NULL DEFAULT 0,
+
+  delta_text    TEXT,
+  delta_num     REAL,
+  delta_unit    TEXT,
+  sigma_level   REAL DEFAULT 2.0,
+
+  conf          REAL NOT NULL DEFAULT 1.0,
+  importance    INTEGER NOT NULL DEFAULT 0,
+
+  comment       TEXT,
+  raw_line      TEXT NOT NULL,         -- exactly as written, incl. inverse form
+
+  claim_key     TEXT NOT NULL          -- normalized key; shared by forward/inverse readings
+);
+
+CREATE INDEX IF NOT EXISTS idx_cave_claim_key_tx ON cave_claim (claim_key, tx);
+CREATE INDEX IF NOT EXISTS idx_cave_subject   ON cave_claim (subject);
+CREATE INDEX IF NOT EXISTS idx_cave_verb      ON cave_claim (verb);
+CREATE INDEX IF NOT EXISTS idx_cave_object    ON cave_claim (object);
+CREATE INDEX IF NOT EXISTS idx_cave_attribute ON cave_claim (attribute);
+CREATE INDEX IF NOT EXISTS idx_cave_conf      ON cave_claim (conf);
+
+CREATE TABLE IF NOT EXISTS cave_context (
+  claim_id TEXT NOT NULL,
+  context  TEXT NOT NULL,
+  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_context ON cave_context (context);
+
+CREATE TABLE IF NOT EXISTS cave_tag (
+  claim_id TEXT NOT NULL,
+  key      TEXT NOT NULL,
+  value    TEXT,                       -- NULL for flat tags (spec §13.2)
+  FOREIGN KEY (claim_id) REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_tag_key ON cave_tag (key, value);
+
+CREATE TABLE IF NOT EXISTS cave_edge (
+  parent_id TEXT NOT NULL,
+  role      TEXT NOT NULL,             -- WHEN, VIA, BECAUSE, QUALIFIES
+  child_id  TEXT NOT NULL,
+  FOREIGN KEY (parent_id) REFERENCES cave_claim(id),
+  FOREIGN KEY (child_id)  REFERENCES cave_claim(id)
+);
+CREATE INDEX IF NOT EXISTS idx_cave_edge_parent ON cave_edge (parent_id);
+CREATE INDEX IF NOT EXISTS idx_cave_edge_child  ON cave_edge (child_id);
+CREATE INDEX IF NOT EXISTS idx_cave_edge_role   ON cave_edge (role);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS cave_fts USING fts5(
+  claim_id, subject, verb, object, attribute, value_text, comment, raw_line
+);
+`
+
+/** Creates all tables and indexes. */
+export const init = (db: DatabaseSync): void => {
+  db.exec(ddl)
+}