@haverstack/record-adapter-sqlite 0.1.0

package/dist/index.js

@@ -0,0 +1,1203 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { StackVersionConflictError, StackNotFoundError, StackConflictError, applyMergePatch, StackQueryError } from '@haverstack/core';
+import { randomBytes, createHash } from 'crypto';
+
+// src/node-sqlite.ts
+var { DatabaseSync } = process.getBuiltinModule(
+  "node:sqlite"
+);
+
+// ../sqlite-shared/dist/schema.js
+var RECORD_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS records (
+    id          TEXT PRIMARY KEY,
+    type_id     TEXT NOT NULL,
+    created_at  INTEGER NOT NULL,
+    updated_at  INTEGER NOT NULL,
+    content     TEXT NOT NULL CHECK (json_valid(content)),
+    version     INTEGER NOT NULL DEFAULT 1,
+    parent_id   TEXT,
+    entity_id   TEXT,
+    app_id      TEXT,
+    principal_id TEXT,
+    deleted_at  INTEGER,
+    permissions TEXT CHECK (permissions IS NULL OR json_valid(permissions))
+  ) STRICT;
+
+  CREATE TABLE IF NOT EXISTS associations (
+    record_id  TEXT NOT NULL REFERENCES records(id),
+    kind       TEXT NOT NULL CHECK (kind IN ('tag', 'attachment', 'relationship')),
+    label      TEXT NOT NULL,
+    file_id    TEXT NOT NULL DEFAULT '',
+    related_id TEXT NOT NULL DEFAULT '',
+    PRIMARY KEY (record_id, kind, label, file_id, related_id)
+  ) STRICT;
+
+  CREATE TABLE IF NOT EXISTS versions (
+    record_id   TEXT NOT NULL REFERENCES records(id),
+    version     INTEGER NOT NULL,
+    type_id     TEXT NOT NULL,
+    content     TEXT NOT NULL CHECK (json_valid(content)),
+    updated_at  INTEGER NOT NULL,
+    entity_id   TEXT,
+    associations TEXT CHECK (associations IS NULL OR json_valid(associations)),
+    permissions  TEXT CHECK (permissions IS NULL OR json_valid(permissions)),
+    PRIMARY KEY (record_id, version)
+  ) STRICT;
+
+  CREATE TABLE IF NOT EXISTS types (
+    id            TEXT PRIMARY KEY,
+    base_id       TEXT NOT NULL,
+    version       INTEGER NOT NULL,
+    name          TEXT NOT NULL,
+    schema        TEXT NOT NULL CHECK (json_valid(schema)),
+    schema_hash   TEXT NOT NULL,
+    migrates_from TEXT,
+    created_at    INTEGER NOT NULL
+  ) STRICT;
+
+  -- One row per top-level file-ref content field on a record, kept in sync
+  -- on every content/typeId write. Lets the attachmentFileId query filter
+  -- and deleteAttachment()'s reference check see content-held file
+  -- references, not just attachment associations.
+  CREATE TABLE IF NOT EXISTS file_refs (
+    record_id TEXT NOT NULL REFERENCES records(id),
+    field     TEXT NOT NULL,
+    file_id   TEXT NOT NULL,
+    PRIMARY KEY (record_id, field)
+  ) STRICT;
+
+  -- Indexes
+  CREATE INDEX IF NOT EXISTS idx_records_type_id    ON records(type_id);
+  CREATE INDEX IF NOT EXISTS idx_records_parent_id  ON records(parent_id);
+  CREATE INDEX IF NOT EXISTS idx_records_entity_id  ON records(entity_id);
+  CREATE INDEX IF NOT EXISTS idx_records_app_id     ON records(app_id);
+  CREATE INDEX IF NOT EXISTS idx_records_principal_id ON records(principal_id);
+  CREATE INDEX IF NOT EXISTS idx_records_deleted_at ON records(deleted_at);
+  CREATE INDEX IF NOT EXISTS idx_records_created_at ON records(created_at);
+  CREATE INDEX IF NOT EXISTS idx_records_updated_at ON records(updated_at);
+  CREATE INDEX IF NOT EXISTS idx_assoc_record_id    ON associations(record_id);
+  CREATE INDEX IF NOT EXISTS idx_assoc_kind_label   ON associations(kind, label);
+  CREATE INDEX IF NOT EXISTS idx_assoc_kind_file_id ON associations(kind, file_id);
+  CREATE INDEX IF NOT EXISTS idx_types_base_id      ON types(base_id);
+  CREATE INDEX IF NOT EXISTS idx_file_refs_file_id  ON file_refs(file_id);
+`;
+var TOKENS_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS tokens (
+    id           TEXT PRIMARY KEY,
+    token_hash   TEXT NOT NULL UNIQUE,
+    principal_id TEXT NOT NULL,
+    subject_id   TEXT NOT NULL,
+    label        TEXT,
+    created_at   INTEGER NOT NULL,
+    expires_at   INTEGER
+  ) STRICT;
+
+  CREATE INDEX IF NOT EXISTS idx_tokens_hash ON tokens(token_hash);
+`;
+var FTS5_SCHEMA_SQL = `
+  CREATE VIRTUAL TABLE IF NOT EXISTS records_fts USING fts5(
+    content,
+    content='records',
+    content_rowid='rowid'
+  );
+`;
+var PRAGMA_FOREIGN_KEYS_ON = `PRAGMA foreign_keys = ON;`;
+var PRAGMA_JOURNAL_MODE_WAL = `PRAGMA journal_mode = WAL;`;
+var SORT_FIELDS = ["createdAt", "updatedAt", "version"];
+var encodeCursor = (field, value, id) => btoa(`${field}|${value}|${id}`);
+var decodeCursor = (cursor) => {
+  let decoded;
+  try {
+    decoded = atob(cursor);
+  } catch {
+    throw new StackQueryError(`Invalid cursor: malformed "${cursor}"`);
+  }
+  const parts = decoded.split("|");
+  if (parts.length !== 3) {
+    throw new StackQueryError(`Invalid cursor: malformed "${cursor}"`);
+  }
+  const [field, value, id] = parts;
+  if (!SORT_FIELDS.includes(field)) {
+    throw new StackQueryError(`Invalid cursor: unknown sort field "${field}"`);
+  }
+  const numericValue = Number(value);
+  if (!isFinite(numericValue)) {
+    throw new StackQueryError(`Invalid cursor: non-numeric sort value`);
+  }
+  return { field, value: numericValue, id };
+};
+var getSortField = (query) => query.sort?.field ?? "createdAt";
+var getSortColumn = (field) => field === "createdAt" ? "created_at" : field === "updatedAt" ? "updated_at" : "version";
+var makeCursor = (record, field) => {
+  const value = field === "updatedAt" ? record.updatedAt.getTime() : field === "version" ? record.version : record.createdAt.getTime();
+  return encodeCursor(field, value, record.id);
+};
+
+// ../sqlite-shared/dist/fts5.js
+var sanitizeFts5Query = (query, maxDepth = 2) => {
+  if (!query)
+    return "";
+  let clean = query.replace(/\*/g, "");
+  clean = clean.replace(/\bNEAR\s*\(\s*([^,)]*)(?:,[^)]*)?\)/gi, "$1");
+  clean = clean.replace(/:/g, " ");
+  clean = clean.replace(/(?:^|\(\s*)NOT\s+/gi, (m) => m.replace(/NOT\s+/i, ""));
+  let currentDepth = 0;
+  let result = "";
+  for (const char of clean) {
+    if (char === "(") {
+      if (currentDepth < maxDepth) {
+        currentDepth++;
+        result += char;
+      } else
+        result += " ";
+    } else if (char === ")") {
+      if (currentDepth > 0) {
+        currentDepth--;
+        result += char;
+      } else
+        result += " ";
+    } else {
+      result += char;
+    }
+  }
+  if (currentDepth > 0)
+    result += ")".repeat(currentDepth);
+  let prev;
+  do {
+    prev = result;
+    result = result.replace(/\(\s*\)/g, " ");
+  } while (result !== prev);
+  return result.replace(/\s+/g, " ").replace(/\(\s+/g, "(").replace(/\s+\)/g, ")").trim();
+};
+var fts5Strategy = {
+  /** Index a record that has no FTS entry yet (used right after an INSERT). */
+  insert(exec, recordId, content) {
+    exec.run(`INSERT INTO records_fts(rowid, content) SELECT rowid, ? FROM records WHERE id = ?`, [
+      content,
+      recordId
+    ]);
+  },
+  /**
+   * Remove a record's FTS entry. MUST be called before the records row's
+   * content changes or the row is deleted — see the note above.
+   */
+  remove(exec, recordId) {
+    const row = exec.get("SELECT rowid, content FROM records WHERE id = ?", [recordId]);
+    if (!row)
+      return;
+    exec.run(`INSERT INTO records_fts(records_fts, rowid, content) VALUES('delete', ?, ?)`, [
+      row.rowid,
+      row.content
+    ]);
+  }
+};
+
+// ../sqlite-shared/dist/query.js
+var buildWhereClause = (query) => {
+  const conditions = ["r.id != '_config'"];
+  const params = [];
+  const f = query.filter ?? {};
+  if (!f.includeDeleted) {
+    conditions.push("r.deleted_at IS NULL");
+  }
+  if (f.typeId !== void 0) {
+    const ids = Array.isArray(f.typeId) ? f.typeId : [f.typeId];
+    conditions.push(`r.type_id IN (${ids.map(() => "?").join(",")})`);
+    params.push(...ids);
+  }
+  if (f.parentId !== void 0) {
+    if (f.parentId === null) {
+      conditions.push("r.parent_id IS NULL");
+    } else {
+      conditions.push("r.parent_id = ?");
+      params.push(f.parentId);
+    }
+  }
+  if (f.appId !== void 0) {
+    const ids = Array.isArray(f.appId) ? f.appId : [f.appId];
+    conditions.push(`r.app_id IN (${ids.map(() => "?").join(",")})`);
+    params.push(...ids);
+  }
+  if (f.entityId !== void 0) {
+    const ids = Array.isArray(f.entityId) ? f.entityId : [f.entityId];
+    conditions.push(`r.entity_id IN (${ids.map(() => "?").join(",")})`);
+    params.push(...ids);
+  }
+  if (f.principalId !== void 0) {
+    const ids = Array.isArray(f.principalId) ? f.principalId : [f.principalId];
+    conditions.push(`r.principal_id IN (${ids.map(() => "?").join(",")})`);
+    params.push(...ids);
+  }
+  if (f.createdAt?.after) {
+    conditions.push("r.created_at > ?");
+    params.push(f.createdAt.after.getTime());
+  }
+  if (f.createdAt?.before) {
+    conditions.push("r.created_at < ?");
+    params.push(f.createdAt.before.getTime());
+  }
+  if (f.updatedAt?.after) {
+    conditions.push("r.updated_at > ?");
+    params.push(f.updatedAt.after.getTime());
+  }
+  if (f.updatedAt?.before) {
+    conditions.push("r.updated_at < ?");
+    params.push(f.updatedAt.before.getTime());
+  }
+  if (f.tags?.length) {
+    for (const tag of f.tags) {
+      conditions.push(`EXISTS (SELECT 1 FROM associations a WHERE a.record_id = r.id AND a.kind = 'tag' AND a.label = ?)`);
+      params.push(tag);
+    }
+  }
+  if (f.hasAttachment) {
+    conditions.push(`EXISTS (SELECT 1 FROM associations a WHERE a.record_id = r.id AND a.kind = 'attachment' AND a.label = ?)`);
+    params.push(f.hasAttachment);
+  }
+  if (f.attachmentFileId) {
+    conditions.push(`(EXISTS (SELECT 1 FROM associations a WHERE a.record_id = r.id AND a.kind = 'attachment' AND a.file_id = ?)
+        OR EXISTS (SELECT 1 FROM file_refs fr WHERE fr.record_id = r.id AND fr.file_id = ?))`);
+    params.push(f.attachmentFileId, f.attachmentFileId);
+  }
+  if (f.relatedTo) {
+    conditions.push(`EXISTS (SELECT 1 FROM associations a WHERE a.record_id = r.id AND a.kind = 'relationship' AND a.related_id = ?` + (f.relatedTo.label ? ` AND a.label = ?` : "") + `)`);
+    params.push(f.relatedTo.recordId);
+    if (f.relatedTo.label)
+      params.push(f.relatedTo.label);
+  }
+  if (f.content) {
+    for (const [key, value] of Object.entries(f.content)) {
+      if (value === null) {
+        conditions.push(`json_extract(r.content, ?) IS NULL`);
+        params.push(`$.${key}`);
+      } else {
+        conditions.push(`json_extract(r.content, ?) = ?`);
+        params.push(`$.${key}`, value);
+      }
+    }
+  }
+  if (f.search) {
+    const sanitized = sanitizeFts5Query(f.search);
+    if (sanitized) {
+      conditions.push(`r.rowid IN (SELECT rowid FROM records_fts WHERE records_fts MATCH ?)`);
+      params.push(sanitized);
+    } else {
+      conditions.push("0");
+    }
+  }
+  if (query.cursor) {
+    const { field: cursorField, value: numericValue, id: cursorId } = decodeCursor(query.cursor);
+    const sortField = getSortField(query);
+    if (cursorField !== sortField) {
+      throw new StackQueryError(`Cursor sort field "${cursorField}" does not match query sort field "${sortField}"`);
+    }
+    const col = getSortColumn(cursorField);
+    const sortDir = query.sort?.direction ?? "desc";
+    const op = sortDir === "asc" ? ">" : "<";
+    conditions.push(`(r.${col} ${op} ? OR (r.${col} = ? AND r.id ${op} ?))`);
+    params.push(numericValue, numericValue, cursorId);
+  }
+  return {
+    sql: conditions.length ? `WHERE ${conditions.join(" AND ")}` : "",
+    params
+  };
+};
+var buildOrderClause = (query) => {
+  const field = getSortField(query);
+  const dir = (query.sort?.direction ?? "desc").toUpperCase();
+  return `ORDER BY r.${getSortColumn(field)} ${dir}, r.id ${dir}`;
+};
+
+// ../sqlite-shared/dist/mappers.js
+var toMs = (d) => d.getTime();
+var fromMs = (ms) => new Date(ms);
+var rowToRecord = (row, associations) => {
+  const record = {
+    id: row.id,
+    typeId: row.type_id,
+    createdAt: fromMs(row.created_at),
+    updatedAt: fromMs(row.updated_at),
+    content: JSON.parse(row.content),
+    version: row.version
+  };
+  if (row.parent_id)
+    record.parentId = row.parent_id;
+  if (row.entity_id)
+    record.entityId = row.entity_id;
+  if (row.app_id)
+    record.appId = row.app_id;
+  if (row.principal_id)
+    record.principalId = row.principal_id;
+  if (row.deleted_at)
+    record.deletedAt = fromMs(row.deleted_at);
+  if (row.permissions)
+    record.permissions = JSON.parse(row.permissions);
+  if (associations.length)
+    record.associations = associations;
+  return record;
+};
+var rowToAssociation = (row) => {
+  if (row.kind === "tag") {
+    return { kind: "tag", label: row.label };
+  }
+  if (row.kind === "attachment") {
+    return {
+      kind: "attachment",
+      label: row.label,
+      fileId: row.file_id
+    };
+  }
+  return {
+    kind: "relationship",
+    label: row.label,
+    recordId: row.related_id
+  };
+};
+var rowToType = (row) => {
+  const t = {
+    id: row.id,
+    baseId: row.base_id,
+    version: row.version,
+    name: row.name,
+    schema: JSON.parse(row.schema),
+    schemaHash: row.schema_hash,
+    createdAt: fromMs(row.created_at)
+  };
+  if (row.migrates_from)
+    t.migratesFrom = row.migrates_from;
+  return t;
+};
+var rowToVersion = (row) => {
+  const v = {
+    version: row.version,
+    typeId: row.type_id,
+    content: JSON.parse(row.content),
+    updatedAt: fromMs(row.updated_at)
+  };
+  if (row.entity_id)
+    v.entityId = row.entity_id;
+  if (row.associations)
+    v.associations = JSON.parse(row.associations);
+  if (row.permissions)
+    v.permissions = JSON.parse(row.permissions);
+  return v;
+};
+var lockPathFor = (dbPath) => `${dbPath}.lock`;
+var isProcessAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code !== "ESRCH";
+  }
+};
+var acquireLock = (dbPath, force) => {
+  const lockPath = lockPathFor(dbPath);
+  if (existsSync(lockPath)) {
+    const info = JSON.parse(readFileSync(lockPath, "utf-8"));
+    const ownedBySelf = info.pid === process.pid;
+    if (!ownedBySelf && !force && isProcessAlive(info.pid)) {
+      throw new Error(`Stack database at "${dbPath}" is in use by another process (pid ${info.pid}). Connect via its server instead, or pass { force: true } to override.`);
+    }
+  }
+  writeFileSync(lockPath, JSON.stringify({ pid: process.pid }));
+};
+var releaseLock = (dbPath) => {
+  const lockPath = lockPathFor(dbPath);
+  if (!existsSync(lockPath))
+    return;
+  try {
+    const info = JSON.parse(readFileSync(lockPath, "utf-8"));
+    if (info.pid === process.pid)
+      unlinkSync(lockPath);
+  } catch {
+    unlinkSync(lockPath);
+  }
+};
+
+// ../sqlite-shared/dist/executor.js
+var isForeignKeyViolation = (err) => err instanceof Error && err.message.includes("FOREIGN KEY constraint failed");
+var isUniqueConstraintViolation = (err) => err instanceof Error && err.message.includes("UNIQUE constraint failed");
+
+// ../sqlite-shared/dist/config.js
+var insertConfigRecord = (exec, entityId, timezone) => {
+  const now = Date.now();
+  exec.run(`INSERT INTO records (id, type_id, created_at, updated_at, content, version)
+     VALUES ('_config', '_config@1', ?, ?, ?, 1)`, [now, now, JSON.stringify({ entityId, timezone })]);
+};
+var readStackConfig = (exec) => {
+  const row = exec.get(`SELECT content FROM records WHERE id = '_config'`);
+  if (!row)
+    throw new Error("Stack database is missing its config record.");
+  const content = JSON.parse(row.content);
+  return { entityId: content.entityId, timezone: content.timezone };
+};
+var fileRefFieldNames = (schema) => Object.keys(schema).filter((field) => schema[field].kind === "file-ref");
+var SharedSqlRecordLogic = class {
+  deps;
+  /**
+   * Per-typeId cache of file-ref field names, so syncFileRefs() doesn't
+   * hit the `types` table and re-parse schema JSON on every write.
+   * Populated eagerly in saveType() and lazily via getFileRefFields().
+   */
+  fileRefFieldsByType = /* @__PURE__ */ new Map();
+  constructor(deps) {
+    this.deps = deps;
+  }
+  get exec() {
+    return this.deps.exec;
+  }
+  /**
+   * SQL fragment (plus its bind params) that gates a records-table
+   * UPDATE/DELETE on the opt-in `expectedVersion` precondition. Empty when
+   * expectedVersion is omitted, keeping today's unconditional behavior.
+   */
+  versionGuard(expectedVersion) {
+    return expectedVersion === void 0 ? { clause: "", params: [] } : { clause: " AND version = ?", params: [expectedVersion] };
+  }
+  /**
+   * Precondition check for mutations that can't fold expectedVersion into
+   * their primary UPDATE's WHERE clause: patchContent/restoreVersion need
+   * fts.remove() to run *before* the records-table content changes, so
+   * the check happens first, standalone.
+   */
+  checkExpectedVersion(record, expectedVersion) {
+    if (expectedVersion === void 0 || record.version === expectedVersion)
+      return;
+    throw new StackVersionConflictError(`Record "${record.id}" is at version ${record.version}, expected ${expectedVersion}`, record.id, expectedVersion, record.version);
+  }
+  /**
+   * Called after a versionGuard()-gated statement affected zero rows.
+   * Distinguishes "record doesn't exist" (StackNotFoundError) from "it
+   * exists but isn't at expectedVersion" (StackVersionConflictError, with
+   * the actual current version for the caller to act on).
+   */
+  throwVersionConflict(id, expectedVersion) {
+    const row = this.exec.get("SELECT version FROM records WHERE id = ?", [
+      id
+    ]);
+    if (!row)
+      throw new StackNotFoundError(`Record not found: "${id}"`);
+    throw new StackVersionConflictError(`Record "${id}" is at version ${row.version}, expected ${expectedVersion}`, id, expectedVersion, row.version);
+  }
+  // -------------------------------------------------------
+  // Records
+  // -------------------------------------------------------
+  /**
+   * A duplicate id hits the `records` PK — mapped to StackConflictError
+   * instead of surfacing the raw engine exception, mirroring saveVersion's
+   * collision mapping below.
+   */
+  async createRecord(record) {
+    try {
+      this.exec.run(`INSERT INTO records
+          (id, type_id, created_at, updated_at, content, version,
+           parent_id, entity_id, app_id, principal_id, deleted_at, permissions)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        record.id,
+        record.typeId,
+        toMs(record.createdAt),
+        toMs(record.updatedAt),
+        JSON.stringify(record.content),
+        record.version,
+        record.parentId ?? null,
+        record.entityId ?? null,
+        record.appId ?? null,
+        record.principalId ?? null,
+        record.deletedAt ? toMs(record.deletedAt) : null,
+        record.permissions ? JSON.stringify(record.permissions) : null
+      ]);
+    } catch (err) {
+      if (isUniqueConstraintViolation(err)) {
+        throw new StackConflictError(`Record already exists: "${record.id}"`);
+      }
+      throw err;
+    }
+    if (record.associations?.length) {
+      this.insertAssociations(record.id, record.associations);
+    }
+    fts5Strategy.insert(this.exec, record.id, JSON.stringify(record.content));
+    this.syncFileRefs(record.id, record.typeId, record.content);
+    return record;
+  }
+  async getRecord(id) {
+    const row = this.exec.get("SELECT * FROM records WHERE id = ?", [id]);
+    if (!row)
+      return null;
+    const associations = this.getAssociationsForRecord(id);
+    return rowToRecord(row, associations);
+  }
+  async patchContent(id, patch, opts = {}) {
+    const existing = await this.getRecord(id);
+    if (!existing)
+      throw new Error(`Record not found: "${id}"`);
+    this.checkExpectedVersion(existing, opts.expectedVersion);
+    const merged = applyMergePatch(existing.content, patch);
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(id, opts.snapshot);
+      fts5Strategy.remove(this.exec, id);
+      this.exec.run("UPDATE records SET content = ?, version = version + 1, updated_at = ? WHERE id = ?", [JSON.stringify(merged), toMs(/* @__PURE__ */ new Date()), id]);
+      fts5Strategy.insert(this.exec, id, JSON.stringify(merged));
+      this.syncFileRefs(id, existing.typeId, merged);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+    const updated = await this.getRecord(id);
+    if (!updated)
+      throw new Error(`Record not found after patchContent: "${id}"`);
+    return updated;
+  }
+  async deleteRecord(id, opts = {}) {
+    if (opts.hard) {
+      this.hardDeleteRecord(id, opts.expectedVersion);
+    } else {
+      this.exec.exec("BEGIN");
+      try {
+        if (opts.snapshot)
+          this.snapshotBeforeMutation(id, opts.snapshot);
+        const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
+        const changed = this.exec.run(`UPDATE records SET deleted_at = ?, version = version + 1, updated_at = ? WHERE id = ?${clause}`, [toMs(/* @__PURE__ */ new Date()), toMs(/* @__PURE__ */ new Date()), id, ...verParams]);
+        if (changed === 0)
+          this.throwVersionConflict(id, opts.expectedVersion);
+        this.exec.exec("COMMIT");
+      } catch (err) {
+        this.exec.exec("ROLLBACK");
+        throw err;
+      }
+    }
+  }
+  /**
+   * Deletes a record's FTS entry, associations, versions, file-refs, and
+   * row. No write() call — callers batch it. expectedVersion is checked
+   * first so a lost CAS race leaves nothing touched (children reference
+   * the row, so the check can't fold into the final DELETE).
+   */
+  hardDeleteRecord(id, expectedVersion) {
+    if (expectedVersion !== void 0) {
+      const row = this.exec.get("SELECT version FROM records WHERE id = ?", [
+        id
+      ]);
+      if (!row)
+        throw new StackNotFoundError(`Record not found: "${id}"`);
+      if (row.version !== expectedVersion) {
+        throw new StackVersionConflictError(`Record "${id}" is at version ${row.version}, expected ${expectedVersion}`, id, expectedVersion, row.version);
+      }
+    }
+    fts5Strategy.remove(this.exec, id);
+    this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
+    this.exec.run("DELETE FROM versions WHERE record_id = ?", [id]);
+    this.exec.run("DELETE FROM file_refs WHERE record_id = ?", [id]);
+    this.exec.run("DELETE FROM records WHERE id = ?", [id]);
+  }
+  async undeleteRecord(id, opts = {}) {
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(id, opts.snapshot);
+      const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
+      const changed = this.exec.run(`UPDATE records SET deleted_at = NULL, version = version + 1, updated_at = ? WHERE id = ?${clause}`, [toMs(/* @__PURE__ */ new Date()), id, ...verParams]);
+      if (changed === 0)
+        this.throwVersionConflict(id, opts.expectedVersion);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+    const updated = await this.getRecord(id);
+    if (!updated)
+      throw new Error(`Record not found after undelete: "${id}"`);
+    return updated;
+  }
+  async setPermissions(id, permissions, opts = {}) {
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(id, opts.snapshot);
+      const { clause, params: verParams } = this.versionGuard(opts.expectedVersion);
+      const changed = this.exec.run(`UPDATE records SET permissions = ?, version = version + 1, updated_at = ? WHERE id = ?${clause}`, [
+        permissions.length ? JSON.stringify(permissions) : null,
+        toMs(/* @__PURE__ */ new Date()),
+        id,
+        ...verParams
+      ]);
+      if (changed === 0)
+        this.throwVersionConflict(id, opts.expectedVersion);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  async restoreVersion(id, version, opts = {}) {
+    const existing = await this.getRecord(id);
+    if (!existing)
+      throw new Error(`Record not found: "${id}"`);
+    this.checkExpectedVersion(existing, opts.expectedVersion);
+    const target = await this.getVersion(id, version);
+    if (!target)
+      throw new Error(`Version not found: ${id}@${version}`);
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(id, opts.snapshot);
+      fts5Strategy.remove(this.exec, id);
+      this.exec.run("UPDATE records SET type_id = ?, content = ?, version = version + 1, updated_at = ? WHERE id = ?", [target.typeId, JSON.stringify(target.content), toMs(/* @__PURE__ */ new Date()), id]);
+      if (target.associations !== void 0) {
+        this.exec.run("DELETE FROM associations WHERE record_id = ?", [id]);
+        if (target.associations.length)
+          this.insertAssociations(id, target.associations);
+      }
+      fts5Strategy.insert(this.exec, id, JSON.stringify(target.content));
+      this.syncFileRefs(id, target.typeId, target.content);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+    const updated = await this.getRecord(id);
+    if (!updated)
+      throw new Error(`Record not found after restoreVersion: "${id}"`);
+    return updated;
+  }
+  async commitMigration(id, toTypeId, content, opts = {}) {
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(id, opts.snapshot);
+      fts5Strategy.remove(this.exec, id);
+      this.exec.run("UPDATE records SET type_id = ?, content = ?, version = version + 1, updated_at = ? WHERE id = ?", [toTypeId, JSON.stringify(content), toMs(/* @__PURE__ */ new Date()), id]);
+      fts5Strategy.insert(this.exec, id, JSON.stringify(content));
+      this.syncFileRefs(id, toTypeId, content);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+    const updated = await this.getRecord(id);
+    if (!updated)
+      throw new Error(`Record not found after commitMigration: "${id}"`);
+    return updated;
+  }
+  async queryRecords(query) {
+    const { sql: where, params } = buildWhereClause(query);
+    const order = buildOrderClause(query);
+    const limit = query.limit ?? 50;
+    const rows = this.exec.all(`SELECT r.* FROM records r ${where} ${order} LIMIT ?`, [...params, limit + 1]);
+    const hasMore = rows.length > limit;
+    const page = hasMore ? rows.slice(0, limit) : rows;
+    const records = page.map((row) => {
+      const associations = this.getAssociationsForRecord(row.id);
+      return rowToRecord(row, associations);
+    });
+    const countRows = this.exec.all(`SELECT COUNT(*) as total FROM records r ${where}`, params);
+    const total = countRows[0]?.total ?? 0;
+    const lastRecord = records[records.length - 1];
+    const cursor = hasMore && lastRecord ? makeCursor(lastRecord, getSortField(query)) : null;
+    return { records, cursor, total };
+  }
+  /**
+   * Atomically verify fileId is unreferenced, then hard-delete its
+   * metadata records (see deleteUnreferencedAttachmentRecords on the
+   * adapter contract). A real SQL transaction of synchronous calls — no
+   * `await` between the check and the deletes, so nothing interleaves.
+   */
+  async deleteUnreferencedAttachmentRecords(fileId, metadataTypeId) {
+    this.exec.exec("BEGIN");
+    try {
+      const referenced = this.exec.all(`SELECT 1 as found FROM associations WHERE kind = 'attachment' AND file_id = ?
+         UNION ALL
+         SELECT 1 FROM file_refs WHERE file_id = ?
+         LIMIT 1`, [fileId, fileId]);
+      if (referenced.length) {
+        throw new StackConflictError("Attachment is still referenced by one or more records");
+      }
+      const metaRows = this.exec.all(`SELECT id FROM records WHERE type_id = ? AND json_extract(content, '$.fileId') = ?`, [metadataTypeId, fileId]);
+      const deletedIds = metaRows.map((row) => row.id);
+      for (const id of deletedIds) {
+        this.hardDeleteRecord(id);
+      }
+      this.exec.exec("COMMIT");
+      return deletedIds;
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  // -------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------
+  async getVersions(id) {
+    const rows = this.exec.all("SELECT * FROM versions WHERE record_id = ? ORDER BY version DESC", [id]);
+    return rows.map(rowToVersion);
+  }
+  async getVersion(id, version) {
+    const rows = this.exec.all("SELECT * FROM versions WHERE record_id = ? AND version = ?", [id, version]);
+    return rows.length ? rowToVersion(rows[0]) : null;
+  }
+  /**
+   * A (record_id, version) collision is rejected loudly via the UNIQUE
+   * constraint, mapped to StackConflictError — never a silently discarded
+   * snapshot leaving a hole in rollback history. See
+   * docs/spec/versioning.md § Optimistic concurrency (`ifVersion`).
+   */
+  insertVersionRow(id, version) {
+    try {
+      this.exec.run(`INSERT INTO versions
+          (record_id, version, type_id, content, updated_at, entity_id, associations, permissions)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+        id,
+        version.version,
+        version.typeId,
+        JSON.stringify(version.content),
+        toMs(version.updatedAt),
+        version.entityId ?? null,
+        version.associations ? JSON.stringify(version.associations) : null,
+        version.permissions ? JSON.stringify(version.permissions) : null
+      ]);
+    } catch (err) {
+      if (isUniqueConstraintViolation(err)) {
+        throw new StackConflictError(`Version ${version.version} already exists for record "${id}" \u2014 a concurrent writer raced past this version. Use ifVersion to detect this before it happens.`);
+      }
+      throw err;
+    }
+  }
+  overwriteVersionRow(id, version) {
+    this.exec.run(`UPDATE versions
+         SET type_id = ?, content = ?, updated_at = ?, entity_id = ?, associations = ?, permissions = ?
+       WHERE record_id = ? AND version = ?`, [
+      version.typeId,
+      JSON.stringify(version.content),
+      toMs(version.updatedAt),
+      version.entityId ?? null,
+      version.associations ? JSON.stringify(version.associations) : null,
+      version.permissions ? JSON.stringify(version.permissions) : null,
+      id,
+      version.version
+    ]);
+  }
+  /**
+   * Standalone snapshot write for tooling and tests — loud on any
+   * collision, since nothing here is about to bump the version. Mutating
+   * methods take a `snapshot` option instead; see snapshotBeforeMutation.
+   */
+  async saveVersion(id, version) {
+    this.insertVersionRow(id, version);
+  }
+  /**
+   * The snapshot half of a mutating method's atomic snapshot-then-mutate
+   * transaction. A collision is a racing-writer conflict, except an orphan
+   * row at the record's *current* version — recognized by version number
+   * alone, never content — which is overwritten so the interrupted write
+   * can complete. See docs/spec/versioning.md § Snapshot atomicity.
+   */
+  snapshotBeforeMutation(id, version) {
+    try {
+      this.insertVersionRow(id, version);
+    } catch (err) {
+      if (!(err instanceof StackConflictError))
+        throw err;
+      const row = this.exec.get("SELECT version FROM records WHERE id = ?", [
+        id
+      ]);
+      if (!row || row.version !== version.version)
+        throw err;
+      this.overwriteVersionRow(id, version);
+    }
+  }
+  // -------------------------------------------------------
+  // Types
+  // -------------------------------------------------------
+  async saveType(type) {
+    this.exec.run(`INSERT OR REPLACE INTO types
+        (id, base_id, version, name, schema, schema_hash, migrates_from, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+      type.id,
+      type.baseId,
+      type.version,
+      type.name,
+      JSON.stringify(type.schema),
+      type.schemaHash,
+      type.migratesFrom ?? null,
+      toMs(type.createdAt)
+    ]);
+    this.fileRefFieldsByType.set(type.id, fileRefFieldNames(type.schema));
+  }
+  async getType(id) {
+    const rows = this.exec.all("SELECT * FROM types WHERE id = ?", [id]);
+    return rows.length ? rowToType(rows[0]) : null;
+  }
+  async listTypes() {
+    const rows = this.exec.all("SELECT * FROM types ORDER BY base_id, version");
+    return rows.map(rowToType);
+  }
+  // -------------------------------------------------------
+  // Associations
+  // -------------------------------------------------------
+  async associate(recordId, association, opts = {}) {
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(recordId, opts.snapshot);
+      this.bumpVersion(recordId, opts.expectedVersion);
+      this.insertAssociations(recordId, [association]);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  async dissociate(recordId, association, opts = {}) {
+    this.exec.exec("BEGIN");
+    try {
+      if (opts.snapshot)
+        this.snapshotBeforeMutation(recordId, opts.snapshot);
+      this.bumpVersion(recordId, opts.expectedVersion);
+      this.exec.run(`DELETE FROM associations
+       WHERE record_id = ?
+         AND kind = ?
+         AND label = ?
+         AND file_id    = ?
+         AND related_id = ?`, [
+        recordId,
+        association.kind,
+        association.label,
+        association.kind === "attachment" ? association.fileId : "",
+        association.kind === "relationship" ? association.recordId : ""
+      ]);
+      this.exec.exec("COMMIT");
+    } catch (err) {
+      this.exec.exec("ROLLBACK");
+      throw err;
+    }
+  }
+  bumpVersion(id, expectedVersion) {
+    const { clause, params: verParams } = this.versionGuard(expectedVersion);
+    const changed = this.exec.run(`UPDATE records SET version = version + 1, updated_at = ? WHERE id = ?${clause}`, [toMs(/* @__PURE__ */ new Date()), id, ...verParams]);
+    if (changed === 0)
+      this.throwVersionConflict(id, expectedVersion);
+  }
+  /**
+   * FK enforcement (PRAGMA_FOREIGN_KEYS_ON) means inserting an
+   * association against a record that doesn't exist throws — mapped
+   * here to StackNotFoundError so associate() on a nonexistent record
+   * fails loudly instead of silently creating an orphan row.
+   */
+  insertAssociations(recordId, associations) {
+    for (const assoc of associations) {
+      try {
+        this.exec.run(`INSERT OR IGNORE INTO associations
+            (record_id, kind, label, file_id, related_id)
+           VALUES (?, ?, ?, ?, ?)`, [
+          recordId,
+          assoc.kind,
+          assoc.label,
+          assoc.kind === "attachment" ? assoc.fileId : "",
+          assoc.kind === "relationship" ? assoc.recordId : ""
+        ]);
+      } catch (err) {
+        if (isForeignKeyViolation(err)) {
+          throw new StackNotFoundError(`Record not found: "${recordId}"`);
+        }
+        throw err;
+      }
+    }
+  }
+  getAssociationsForRecord(recordId) {
+    const rows = this.exec.all("SELECT * FROM associations WHERE record_id = ?", [recordId]);
+    return rows.map(rowToAssociation);
+  }
+  /**
+   * File-ref field names for typeId, from the in-memory cache — falling
+   * back to a `types` lookup (and populating the cache) only for a typeId
+   * this process hasn't seen via saveType() yet, e.g. right after open().
+   */
+  getFileRefFields(typeId) {
+    const cached = this.fileRefFieldsByType.get(typeId);
+    if (cached)
+      return cached;
+    const typeRow = this.exec.get("SELECT schema FROM types WHERE id = ?", [
+      typeId
+    ]);
+    const fields = typeRow ? fileRefFieldNames(JSON.parse(typeRow.schema)) : [];
+    this.fileRefFieldsByType.set(typeId, fields);
+    return fields;
+  }
+  /**
+   * Replace a record's file_refs rows with whatever its content currently
+   * holds in top-level file-ref fields, on every write that can change
+   * content or typeId, so the index never drifts. Only top-level scalars
+   * are indexed; the schema lookup is cached (fileRefFieldsByType).
+   */
+  syncFileRefs(recordId, typeId, content) {
+    this.exec.run("DELETE FROM file_refs WHERE record_id = ?", [recordId]);
+    const fields = this.getFileRefFields(typeId);
+    for (const field of fields) {
+      const value = content[field];
+      if (typeof value === "string") {
+        this.exec.run("INSERT OR IGNORE INTO file_refs (record_id, field, file_id) VALUES (?, ?, ?)", [recordId, field, value]);
+      }
+    }
+  }
+};
+var SharedTokenLogic = class {
+  deps;
+  constructor(deps) {
+    this.deps = deps;
+  }
+  get exec() {
+    return this.deps.exec;
+  }
+  async createToken(principalId, opts = {}) {
+    const id = randomBytes(8).toString("hex");
+    const token = randomBytes(32).toString("hex");
+    const tokenHash = createHash("sha256").update(token).digest("hex");
+    this.exec.run("INSERT INTO tokens (id, token_hash, principal_id, subject_id, label, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?)", [
+      id,
+      tokenHash,
+      principalId,
+      // Stored rather than left null for an undelegated token, so a
+      // reader never has to know which column stands in for the other.
+      opts.onBehalfOf ?? principalId,
+      opts.label ?? null,
+      toMs(/* @__PURE__ */ new Date()),
+      opts.expiresAt ? toMs(opts.expiresAt) : null
+    ]);
+    return { id, token };
+  }
+  async lookupToken(token) {
+    const hash = createHash("sha256").update(token).digest("hex");
+    const row = this.exec.get("SELECT principal_id, subject_id, expires_at FROM tokens WHERE token_hash = ?", [hash]);
+    if (!row)
+      return null;
+    if (row.expires_at !== null && Date.now() > row.expires_at)
+      return null;
+    return { principalId: row.principal_id, subjectId: row.subject_id };
+  }
+  async listTokens() {
+    const rows = this.exec.all("SELECT id, principal_id, subject_id, label, created_at, expires_at FROM tokens ORDER BY created_at DESC");
+    return rows.map((row) => ({
+      id: row.id,
+      principalId: row.principal_id,
+      subjectId: row.subject_id,
+      ...row.label && { label: row.label },
+      createdAt: fromMs(row.created_at),
+      ...row.expires_at !== null && { expiresAt: fromMs(row.expires_at) }
+    }));
+  }
+  async revokeToken(id) {
+    this.exec.run("DELETE FROM tokens WHERE id = ?", [id]);
+  }
+};
+
+// src/executor.ts
+var NativeSqliteExecutor = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  exec(sql) {
+    this.db.exec(sql);
+  }
+  run(sql, params = []) {
+    const result = this.db.prepare(sql).run(...params);
+    return Number(result.changes);
+  }
+  get(sql, params = []) {
+    return this.db.prepare(sql).get(...params);
+  }
+  all(sql, params = []) {
+    return this.db.prepare(sql).all(...params);
+  }
+};
+
+// src/token-store.ts
+var defaultTokenStorePath = (dbPath) => `${dbPath}.tokens`;
+var NativeTokenStore = class _NativeTokenStore {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  db;
+  tokens;
+  /** Opens the token store, creating the file and schema if needed. */
+  static async open(opts) {
+    acquireLock(opts.path, opts.force);
+    const store = new _NativeTokenStore(opts.path);
+    store.db = new DatabaseSync(opts.path);
+    store.db.exec(PRAGMA_JOURNAL_MODE_WAL);
+    store.db.exec(TOKENS_SCHEMA_SQL);
+    store.tokens = new SharedTokenLogic({ exec: new NativeSqliteExecutor(store.db) });
+    return store;
+  }
+  createToken(principalId, opts) {
+    return this.tokens.createToken(principalId, opts);
+  }
+  lookupToken(token) {
+    return this.tokens.lookupToken(token);
+  }
+  listTokens() {
+    return this.tokens.listTokens();
+  }
+  revokeToken(id) {
+    return this.tokens.revokeToken(id);
+  }
+  async close() {
+    this.db.close();
+    releaseLock(this.path);
+  }
+};
+
+// src/index.ts
+var NativeSQLiteRecordAdapter = class _NativeSQLiteRecordAdapter {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  capabilities = {
+    fullTextSearch: true,
+    contentFieldQuery: true,
+    sortableFields: ["createdAt", "updatedAt", "version"],
+    maxAttachmentBytes: null,
+    maxContentBytes: null
+  };
+  ownerEntityId;
+  timezone;
+  db;
+  record;
+  wire() {
+    const exec = new NativeSqliteExecutor(this.db);
+    this.record = new SharedSqlRecordLogic({ exec });
+  }
+  /**
+   * Initialize a new stack database. Fails if the file already exists —
+   * use open() for existing databases.
+   */
+  static async initialize(opts) {
+    if (existsSync(opts.path)) {
+      throw new Error(
+        `Cannot initialize: database already exists at "${opts.path}". Use NativeSQLiteRecordAdapter.open() instead.`
+      );
+    }
+    acquireLock(opts.path, opts.force);
+    const adapter = new _NativeSQLiteRecordAdapter(opts.path);
+    adapter.db = new DatabaseSync(opts.path);
+    adapter.db.exec(PRAGMA_FOREIGN_KEYS_ON);
+    adapter.db.exec(PRAGMA_JOURNAL_MODE_WAL);
+    adapter.db.exec(RECORD_SCHEMA_SQL);
+    adapter.db.exec(FTS5_SCHEMA_SQL);
+    adapter.wire();
+    insertConfigRecord(new NativeSqliteExecutor(adapter.db), opts.entityId, opts.timezone);
+    adapter.ownerEntityId = opts.entityId;
+    adapter.timezone = opts.timezone;
+    return adapter;
+  }
+  /**
+   * Open an existing stack database. Fails if the file does not exist —
+   * use initialize() for new databases.
+   */
+  static async open(opts) {
+    if (!existsSync(opts.path)) {
+      throw new Error(
+        `Cannot open: no database found at "${opts.path}". Use NativeSQLiteRecordAdapter.initialize() to create one.`
+      );
+    }
+    acquireLock(opts.path, opts.force);
+    const adapter = new _NativeSQLiteRecordAdapter(opts.path);
+    adapter.db = new DatabaseSync(opts.path);
+    adapter.db.exec(PRAGMA_FOREIGN_KEYS_ON);
+    adapter.db.exec(PRAGMA_JOURNAL_MODE_WAL);
+    adapter.db.exec(RECORD_SCHEMA_SQL);
+    adapter.db.exec(FTS5_SCHEMA_SQL);
+    adapter.wire();
+    const config = readStackConfig(new NativeSqliteExecutor(adapter.db));
+    adapter.ownerEntityId = config.entityId;
+    adapter.timezone = config.timezone;
+    return adapter;
+  }
+  // -------------------------------------------------------
+  // Records
+  // -------------------------------------------------------
+  createRecord(record) {
+    return this.record.createRecord(record);
+  }
+  getRecord(id) {
+    return this.record.getRecord(id);
+  }
+  patchContent(id, patch, opts) {
+    return this.record.patchContent(id, patch, opts);
+  }
+  deleteRecord(id, opts) {
+    return this.record.deleteRecord(id, opts);
+  }
+  undeleteRecord(id, opts) {
+    return this.record.undeleteRecord(id, opts);
+  }
+  setPermissions(id, permissions, opts) {
+    return this.record.setPermissions(id, permissions, opts);
+  }
+  restoreVersion(id, version, opts) {
+    return this.record.restoreVersion(id, version, opts);
+  }
+  commitMigration(id, toTypeId, content, opts) {
+    return this.record.commitMigration(id, toTypeId, content, opts);
+  }
+  queryRecords(query) {
+    return this.record.queryRecords(query);
+  }
+  deleteUnreferencedAttachmentRecords(fileId, metadataTypeId) {
+    return this.record.deleteUnreferencedAttachmentRecords(fileId, metadataTypeId);
+  }
+  // -------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------
+  getVersions(id) {
+    return this.record.getVersions(id);
+  }
+  getVersion(id, version) {
+    return this.record.getVersion(id, version);
+  }
+  saveVersion(id, version) {
+    return this.record.saveVersion(id, version);
+  }
+  // -------------------------------------------------------
+  // Types
+  // -------------------------------------------------------
+  saveType(type) {
+    return this.record.saveType(type);
+  }
+  getType(id) {
+    return this.record.getType(id);
+  }
+  listTypes() {
+    return this.record.listTypes();
+  }
+  // -------------------------------------------------------
+  // Associations
+  // -------------------------------------------------------
+  associate(recordId, association, opts) {
+    return this.record.associate(recordId, association, opts);
+  }
+  dissociate(recordId, association, opts) {
+    return this.record.dissociate(recordId, association, opts);
+  }
+  // -------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------
+  /** Folds the WAL back into the main file — useful before copying/backing up the database. */
+  async flush() {
+    this.db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+  }
+  async close() {
+    this.db.close();
+    releaseLock(this.path);
+  }
+};
+
+export { NativeSQLiteRecordAdapter, NativeTokenStore, defaultTokenStorePath };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map