@kar-mi/spirit-vale-tools-sqlite 0.2.1

package/README.md

@@ -0,0 +1,79 @@
+# @kar-mi/spirit-vale-tools-sqlite
+
+Disposable SQLite read-model infrastructure for Spirit Vale session logs.
+
+> **Internal package.** This package is published only because the domain
+> packages depend on it at runtime; it is installed automatically alongside them
+> and is not a supported public API.
+
+## Install
+
+```sh
+bun add @kar-mi/spirit-vale-tools-sqlite
+```
+
+## What it is
+
+JSON Lines session logs stay the canonical record. This package maintains a
+**cache** derived from them, by default at `<logDirectory>/cache/read-model.sqlite`.
+The cache is never migrated: anything unusable is deleted and rebuilt from the
+logs. Nothing here writes to, renames, or deletes a log file.
+
+## Usage
+
+A domain package owns its own tables and importer; this package owns the
+database, its metadata, and how far each log has been indexed.
+
+```ts
+import { openReadModel } from "@kar-mi/spirit-vale-tools-sqlite";
+
+const model = await openReadModel({
+  logDirectory,
+  domains: [{
+    name: "example",
+    version: 1,
+    createSchema: (db) => db.exec("create table if not exists example_rows (sequence integer primary key)"),
+    dropSchema: (db) => db.exec("drop table if exists example_rows"),
+  }],
+  onRebuild: (event) => console.error(`read model rebuilt: ${event.reason}`),
+});
+
+await model.indexStream({
+  sessionId,
+  stream: "combat",
+  domain: "example",
+  sourcePath,
+  apply(records, db) {
+    for (const record of records) {
+      db.query("insert or replace into example_rows (sequence) values ($sequence)").run({ sequence: record.sequence });
+    }
+  },
+  clear(scope, db) {
+    db.query("delete from example_rows").run();
+  },
+});
+
+model.close();
+```
+
+`indexStream` reads only what the log has gained since the recorded byte offset,
+so it is cheap to call repeatedly and resumes across process restarts.
+
+## Guarantees
+
+- Rows and indexing progress commit in the same transaction, so an interrupted
+  pass resumes exactly rather than double-counting.
+- Each transaction covers at most `batchBytes` of source (1 MiB by default) and
+  always ends on a record boundary.
+- A truncated, replaced, or rewound log rebuilds that stream; a corrupt database
+  or a changed infrastructure schema rebuilds the whole file; a changed domain
+  `version` rebuilds only that domain.
+- Use `model.bigintStatement(...)` for 64-bit values such as reward coins. A
+  plain read rounds anything past `Number.MAX_SAFE_INTEGER`.
+- Prefer `model.statement(...)` / `model.bigintStatement(...)` for your own reads.
+  They reuse one prepared statement for the model's lifetime and provide the
+  per-statement bigint mode. Direct `database.query()` / `database.prepare()`
+  access remains available for advanced cases; `model.close()` force-finalizes
+  every outstanding statement.
+
+See the [package guide](https://github.com/kar-mi/spirit-vale-tools/blob/main/docs/packages.md) for registry setup and usage.

package/dist/fingerprint.d.ts

@@ -0,0 +1,3 @@
+/** Identifies a log file by its first line, which is immutable for an append-only log and carries the session id, sequence 1, and a timestamp. */
+export declare function fingerprintSource(sourcePath: string): Promise<string | undefined>;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAOA,kJAAkJ;AAClJ,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqBvF"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { deleteReadModel, openReadModel } from "./read-model.ts";
+export type { OpenReadModelOptions, ReadModel } from "./read-model.ts";
+export { READ_MODEL_SCHEMA_VERSION } from "./schema.ts";
+export { readModelDirectory, readModelFiles, readModelPath } from "./paths.ts";
+export type { IndexStreamRequest, IndexStreamResult, IndexedStreamStatus, ReadModelDomain, ReadModelHealth, ReadModelRebuild, RebuildReason, StreamRebuildReason, } from "./types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/E,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,427 @@
+// @bun
+// src/read-model.ts
+import { mkdir, rm } from "fs/promises";
+import path2 from "path";
+import { Database } from "bun:sqlite";
+import { defaultLogDirectory as defaultLogDirectory2 } from "@kar-mi/spirit-vale-tools-logging";
+
+// src/indexer.ts
+import { stat } from "fs/promises";
+import { JsonlTailReader, isLogStreamHeader, isMissing as isMissing2, parseLogRecord } from "@kar-mi/spirit-vale-tools-logging";
+
+// src/fingerprint.ts
+import { open } from "fs/promises";
+import { isMissing } from "@kar-mi/spirit-vale-tools-logging";
+var FINGERPRINT_BYTES = 8192;
+async function fingerprintSource(sourcePath) {
+  let handle;
+  try {
+    handle = await open(sourcePath, "r");
+  } catch (error) {
+    if (isMissing(error))
+      return;
+    throw error;
+  }
+  try {
+    const bytes = Buffer.allocUnsafe(FINGERPRINT_BYTES);
+    const { bytesRead } = await handle.read(bytes, 0, FINGERPRINT_BYTES, 0);
+    if (bytesRead === 0)
+      return;
+    const read = bytes.subarray(0, bytesRead);
+    const newline = read.indexOf(10);
+    const line = newline === -1 ? read : read.subarray(0, newline + 1);
+    const hasher = new Bun.CryptoHasher("sha256");
+    hasher.update(line);
+    return hasher.digest("hex");
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/indexer.ts
+var DEFAULT_BATCH_BYTES = 1024 * 1024;
+async function indexStream(database, request, transaction) {
+  const { sessionId, stream, domain, sourcePath } = request;
+  const batchBytes = request.batchBytes ?? DEFAULT_BATCH_BYTES;
+  if (!Number.isSafeInteger(batchBytes) || batchBytes < 1)
+    throw new RangeError("batchBytes must be a positive integer");
+  const row = selectProgress(database, sessionId, stream, domain);
+  let size;
+  let modifiedAt;
+  try {
+    const info = await stat(sourcePath);
+    size = info.size;
+    modifiedAt = info.mtime.toISOString();
+  } catch (error) {
+    if (!isMissing2(error))
+      throw error;
+    return unchanged(request, row, { missing: true });
+  }
+  if (row && row.byte_offset === size && row.source_modified_at === modifiedAt) {
+    return unchanged(request, row, { missing: false });
+  }
+  const source = { size, modifiedAt, fingerprint: await fingerprintSource(sourcePath) };
+  const reason = decideRebuild(row, source);
+  if (reason && reason !== "new")
+    rebuild(database, request, source, transaction);
+  const pass = await indexFrom(database, request, startOf(reason, row), source, batchBytes, transaction);
+  if (!pass.regressed) {
+    return {
+      sessionId,
+      stream,
+      missing: false,
+      rebuilt: reason !== undefined && reason !== "new",
+      ...reason ? { rebuildReason: reason } : {},
+      recordsIndexed: pass.recordsIndexed,
+      invalidLines: pass.invalidLines,
+      byteOffset: pass.byteOffset,
+      lastSequence: pass.lastSequence
+    };
+  }
+  rebuild(database, request, source, transaction);
+  const retry = await indexFrom(database, request, { byteOffset: 0, lastSequence: 0 }, source, batchBytes, transaction, false);
+  return {
+    sessionId,
+    stream,
+    missing: false,
+    rebuilt: true,
+    rebuildReason: "sequence-regression",
+    recordsIndexed: retry.recordsIndexed,
+    invalidLines: retry.invalidLines,
+    byteOffset: retry.byteOffset,
+    lastSequence: retry.lastSequence
+  };
+}
+async function indexFrom(database, request, start, source, batchBytes, transaction, allowRegression = true) {
+  const reader = new JsonlTailReader(request.sourcePath, { startOffset: start.byteOffset, maxReadBytes: batchBytes });
+  let recordsIndexed = 0;
+  let invalidLines = 0;
+  let lastSequence = start.lastSequence;
+  for (;; ) {
+    const { missing, bytesRead, lines } = await reader.read();
+    if (missing || bytesRead === 0)
+      break;
+    const batch = [];
+    for (const line of lines) {
+      if (!line.trim())
+        continue;
+      let value;
+      try {
+        value = JSON.parse(line);
+      } catch {
+        invalidLines += 1;
+        continue;
+      }
+      if (isLogStreamHeader(value))
+        continue;
+      const record = parseLogRecord(value);
+      if (!record) {
+        invalidLines += 1;
+        continue;
+      }
+      if (record.sequence <= lastSequence) {
+        if (allowRegression)
+          return { recordsIndexed, invalidLines, ...start, regressed: true };
+        invalidLines += 1;
+        continue;
+      }
+      lastSequence = record.sequence;
+      batch.push(record);
+    }
+    const position = { byteOffset: reader.offset, lastSequence };
+    transaction(() => {
+      if (batch.length > 0)
+        invalidLines += request.apply(batch, database) ?? 0;
+      writeProgress(database, request, position, source);
+    });
+    recordsIndexed += batch.length;
+  }
+  return { recordsIndexed, invalidLines, byteOffset: reader.offset, lastSequence, regressed: false };
+}
+function decideRebuild(row, source) {
+  if (!row)
+    return "new";
+  if (source.size < row.byte_offset)
+    return "truncated";
+  if (source.fingerprint !== undefined && row.source_fingerprint !== "" && source.fingerprint !== row.source_fingerprint) {
+    return "replaced";
+  }
+  return;
+}
+function startOf(reason, row) {
+  if (reason || !row)
+    return { byteOffset: 0, lastSequence: 0 };
+  return { byteOffset: row.byte_offset, lastSequence: row.last_sequence };
+}
+function rebuild(database, request, source, transaction) {
+  transaction(() => {
+    request.clear({ sessionId: request.sessionId, stream: request.stream }, database);
+    writeProgress(database, request, { byteOffset: 0, lastSequence: 0 }, source);
+  });
+}
+function unchanged(request, row, state) {
+  return {
+    sessionId: request.sessionId,
+    stream: request.stream,
+    missing: state.missing,
+    rebuilt: false,
+    recordsIndexed: 0,
+    invalidLines: 0,
+    byteOffset: row?.byte_offset ?? 0,
+    lastSequence: row?.last_sequence ?? 0
+  };
+}
+function selectProgress(database, sessionId, stream, domain) {
+  return database.query("select * from indexed_streams where session_id = $sessionId and stream = $stream and domain = $domain").get({ sessionId, stream, domain }) ?? undefined;
+}
+function writeProgress(database, request, position, source) {
+  database.query(`insert or replace into indexed_streams
+      (session_id, stream, domain, source_path, source_fingerprint, byte_offset, last_sequence, source_size, source_modified_at, indexed_at)
+      values ($sessionId, $stream, $domain, $sourcePath, $fingerprint, $byteOffset, $lastSequence, $size, $modifiedAt, $indexedAt)`).run({
+    sessionId: request.sessionId,
+    stream: request.stream,
+    domain: request.domain,
+    sourcePath: request.sourcePath,
+    fingerprint: source.fingerprint ?? "",
+    byteOffset: position.byteOffset,
+    lastSequence: position.lastSequence,
+    size: Math.max(source.size, position.byteOffset),
+    modifiedAt: source.modifiedAt,
+    indexedAt: new Date().toISOString()
+  });
+}
+
+// src/paths.ts
+import path from "path";
+import { defaultLogDirectory } from "@kar-mi/spirit-vale-tools-logging";
+function readModelDirectory(logDirectory = defaultLogDirectory()) {
+  return path.join(logDirectory, "cache");
+}
+function readModelPath(logDirectory = defaultLogDirectory()) {
+  return path.join(readModelDirectory(logDirectory), "read-model.sqlite");
+}
+function readModelFiles(databasePath) {
+  return [databasePath, `${databasePath}-wal`, `${databasePath}-shm`];
+}
+
+// src/schema.ts
+var READ_MODEL_SCHEMA_VERSION = 1;
+var METADATA_SCHEMA = `
+create table if not exists read_model_metadata (
+  id integer primary key check (id = 1),
+  schema_version integer not null,
+  created_at text not null,
+  last_rebuild_at text
+);
+
+create table if not exists read_model_domains (
+  domain text primary key,
+  version integer not null
+);
+
+create table if not exists indexed_streams (
+  session_id text not null,
+  stream text not null,
+  domain text not null,
+  source_path text not null,
+  source_fingerprint text not null,
+  byte_offset integer not null,
+  last_sequence integer not null,
+  source_size integer not null,
+  source_modified_at text not null,
+  indexed_at text not null,
+  primary key (session_id, stream, domain)
+);
+
+create index if not exists indexed_streams_by_domain on indexed_streams (domain);
+`;
+function createMetadataSchema(database) {
+  database.exec(METADATA_SCHEMA);
+}
+function readMetadata(database) {
+  return database.query("select schema_version, created_at, last_rebuild_at from read_model_metadata where id = 1").get() ?? undefined;
+}
+function writeMetadata(database, createdAt) {
+  database.query("insert or replace into read_model_metadata (id, schema_version, created_at, last_rebuild_at) values (1, $version, $createdAt, null)").run({ version: READ_MODEL_SCHEMA_VERSION, createdAt });
+}
+function markRebuilt(database, at) {
+  database.query("update read_model_metadata set last_rebuild_at = $at where id = 1").run({ at });
+}
+
+// src/read-model.ts
+async function openReadModel(options) {
+  const databasePath = options.path ?? readModelPath(options.logDirectory ?? defaultLogDirectory2());
+  await mkdir(path2.dirname(databasePath), { recursive: true });
+  const duplicate = findDuplicateDomain(options.domains);
+  if (duplicate)
+    throw new Error(`domain ${duplicate} is registered more than once`);
+  const rebuilds = [];
+  let database = await openDatabase(databasePath, rebuilds);
+  createMetadataSchema(database);
+  let metadata = readMetadata(database);
+  if (metadata && metadata.schema_version !== READ_MODEL_SCHEMA_VERSION) {
+    closeQuietly(database);
+    await deleteReadModel(databasePath);
+    rebuilds.push({
+      reason: "metadata-version",
+      detail: `stored schema ${metadata.schema_version}, expected ${READ_MODEL_SCHEMA_VERSION}`
+    });
+    database = await openDatabase(databasePath, rebuilds, { skipCreatedNotice: true });
+    createMetadataSchema(database);
+    metadata = undefined;
+  }
+  if (!metadata) {
+    writeMetadata(database, new Date().toISOString());
+    metadata = readMetadata(database);
+  }
+  applyDomains(database, options.domains, rebuilds);
+  if (rebuilds.length > 0)
+    markRebuilt(database, new Date().toISOString());
+  for (const rebuild2 of rebuilds)
+    options.onRebuild?.(rebuild2);
+  const statements = new Map;
+  const openedWith = rebuilds[0];
+  let pending;
+  const runPending = database.transaction(() => pending());
+  const model = {
+    path: databasePath,
+    database,
+    statement(sql) {
+      return cached(statements, sql, false, database);
+    },
+    bigintStatement(sql) {
+      return cached(statements, sql, true, database);
+    },
+    transaction(run) {
+      const previous = pending;
+      pending = run;
+      try {
+        return runPending();
+      } finally {
+        pending = previous;
+      }
+    },
+    indexStream(request) {
+      return indexStream(database, request, (run) => model.transaction(run));
+    },
+    health() {
+      const stored = readMetadata(database);
+      return {
+        path: databasePath,
+        schemaVersion: stored.schema_version,
+        createdAt: stored.created_at,
+        ...stored.last_rebuild_at ? { lastRebuildAt: stored.last_rebuild_at } : {},
+        ...openedWith ? { openedWith } : {},
+        domains: database.query("select domain, version from read_model_domains order by domain").all().map((row) => ({ name: row.domain, version: row.version })),
+        streams: database.query("select * from indexed_streams order by session_id, stream, domain").all().map(toStatus)
+      };
+    },
+    close() {
+      for (const statement of statements.values())
+        statement.finalize();
+      statements.clear();
+      database.close(true);
+    }
+  };
+  return model;
+}
+async function deleteReadModel(databasePath) {
+  for (const file of readModelFiles(databasePath))
+    await rm(file, { force: true });
+}
+async function openDatabase(databasePath, rebuilds, options = {}) {
+  const existed = await Bun.file(databasePath).exists();
+  let candidate;
+  try {
+    candidate = new Database(databasePath, { create: true, strict: true });
+    configure(candidate);
+    const integrity = candidate.query("pragma integrity_check").get();
+    if (integrity?.integrity_check !== "ok") {
+      throw new Error(`integrity check reported ${integrity?.integrity_check ?? "no result"}`);
+    }
+    if (!existed && !options.skipCreatedNotice)
+      rebuilds.push({ reason: "created" });
+    const opened = candidate;
+    candidate = undefined;
+    return opened;
+  } catch (error) {
+    if (candidate)
+      closeQuietly(candidate);
+    await deleteReadModel(databasePath);
+    rebuilds.push({
+      reason: existed ? "corrupt" : "unreadable",
+      detail: error instanceof Error ? error.message : String(error)
+    });
+    const replacement = new Database(databasePath, { create: true, strict: true });
+    configure(replacement);
+    return replacement;
+  }
+}
+function configure(database) {
+  database.exec("pragma journal_mode = wal");
+  database.exec("pragma synchronous = normal");
+  database.exec("pragma foreign_keys = on");
+}
+function closeQuietly(database) {
+  try {
+    database.close(true);
+  } catch {}
+}
+function applyDomains(database, domains, rebuilds) {
+  const stored = new Map(database.query("select domain, version from read_model_domains").all().map((row) => [row.domain, row.version]));
+  database.transaction(() => {
+    for (const domain of domains) {
+      const current = stored.get(domain.name);
+      if (current === domain.version)
+        continue;
+      if (current !== undefined) {
+        domain.dropSchema(database);
+        database.query("delete from indexed_streams where domain = $domain").run({ domain: domain.name });
+        rebuilds.push({ reason: "domain-version", domain: domain.name, detail: `version ${current} -> ${domain.version}` });
+      }
+      domain.createSchema(database);
+      database.query("insert or replace into read_model_domains (domain, version) values ($domain, $version)").run({ domain: domain.name, version: domain.version });
+    }
+  })();
+}
+function cached(statements, sql, bigints, database) {
+  const key = bigints ? `bigint:${sql}` : sql;
+  let statement = statements.get(key);
+  if (!statement) {
+    statement = database.prepare(sql);
+    if (bigints)
+      statement.safeIntegers(true);
+    statements.set(key, statement);
+  }
+  return statement;
+}
+function findDuplicateDomain(domains) {
+  const seen = new Set;
+  for (const domain of domains) {
+    if (seen.has(domain.name))
+      return domain.name;
+    seen.add(domain.name);
+  }
+  return;
+}
+function toStatus(row) {
+  return {
+    sessionId: row.session_id,
+    stream: row.stream,
+    domain: row.domain,
+    sourcePath: row.source_path,
+    byteOffset: row.byte_offset,
+    lastSequence: row.last_sequence,
+    sourceSize: row.source_size,
+    sourceModifiedAt: row.source_modified_at,
+    indexedAt: row.indexed_at
+  };
+}
+export {
+  READ_MODEL_SCHEMA_VERSION,
+  deleteReadModel,
+  openReadModel,
+  readModelDirectory,
+  readModelFiles,
+  readModelPath
+};

package/dist/indexer.d.ts

@@ -0,0 +1,7 @@
+import type { Database } from "bun:sqlite";
+import type { IndexStreamRequest, IndexStreamResult } from "./types.ts";
+type Transactional = <T>(run: () => T) => T;
+/** Indexes whatever the source has gained since the recorded byte offset, rebuilding the stream from scratch when the source was truncated, replaced, or rewound. */
+export declare function indexStream(database: Database, request: IndexStreamRequest, transaction: Transactional): Promise<IndexStreamResult>;
+export {};
+//# sourceMappingURL=indexer.d.ts.map

package/dist/indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAuB,MAAM,YAAY,CAAC;AAI7F,KAAK,aAAa,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;AAQ5C,qKAAqK;AACrK,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,aAAa,GACzB,OAAO,CAAC,iBAAiB,CAAC,CA+C5B"}

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+/** Cache directory beside the canonical logs. Everything here is disposable and rebuildable. */
+export declare function readModelDirectory(logDirectory?: string): string;
+export declare function readModelPath(logDirectory?: string): string;
+/** The database file plus the write-ahead-log sidecars SQLite keeps next to it. */
+export declare function readModelFiles(databasePath: string): string[];
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAIA,gGAAgG;AAChG,wBAAgB,kBAAkB,CAAC,YAAY,SAAwB,GAAG,MAAM,CAE/E;AAED,wBAAgB,aAAa,CAAC,YAAY,SAAwB,GAAG,MAAM,CAE1E;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7D"}

package/dist/read-model.d.ts

@@ -0,0 +1,29 @@
+import { Database } from "bun:sqlite";
+import type { Statement } from "bun:sqlite";
+import type { IndexStreamRequest, IndexStreamResult, ReadModelDomain, ReadModelHealth, ReadModelRebuild } from "./types.ts";
+export interface OpenReadModelOptions {
+    domains: readonly ReadModelDomain[];
+    /** Used to derive the default database path. Defaults to the shared log directory. */
+    logDirectory?: string;
+    /** Overrides the derived `<logDirectory>/cache/read-model.sqlite` path. */
+    path?: string;
+    /** Reports each rebuild performed while opening. */
+    onRebuild?: (event: ReadModelRebuild) => void;
+}
+export interface ReadModel {
+    readonly path: string;
+    readonly database: Database;
+    /** Prepared statement, cached for the model's lifetime and finalized by {@link close}. */
+    statement(sql: string): Statement;
+    /** As {@link statement}, but returns 64-bit integers as bigint instead of rounding them. */
+    bigintStatement(sql: string): Statement;
+    transaction<T>(run: () => T): T;
+    indexStream(request: IndexStreamRequest): Promise<IndexStreamResult>;
+    health(): ReadModelHealth;
+    close(): void;
+}
+/** Opens the disposable read model, recreating or repairing whatever is unusable. */
+export declare function openReadModel(options: OpenReadModelOptions): Promise<ReadModel>;
+/** Removes the database and the write-ahead-log sidecars SQLite keeps beside it. */
+export declare function deleteReadModel(databasePath: string): Promise<void>;
+//# sourceMappingURL=read-model.d.ts.map

package/dist/read-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-model.d.ts","sourceRoot":"","sources":["../src/read-model.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAc5C,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAEjB,eAAe,EACf,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,0FAA0F;IAC1F,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4FAA4F;IAC5F,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrE,MAAM,IAAI,eAAe,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,qFAAqF;AACrF,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CA0FrF;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}

package/dist/schema.d.ts

@@ -0,0 +1,25 @@
+import type { Database } from "bun:sqlite";
+/** Version of the infrastructure's own tables. */
+export declare const READ_MODEL_SCHEMA_VERSION = 1;
+export declare function createMetadataSchema(database: Database): void;
+export interface ReadModelMetadataRow {
+    schema_version: number;
+    created_at: string;
+    last_rebuild_at: string | null;
+}
+export declare function readMetadata(database: Database): ReadModelMetadataRow | undefined;
+export declare function writeMetadata(database: Database, createdAt: string): void;
+export declare function markRebuilt(database: Database, at: string): void;
+export interface IndexedStreamRow {
+    session_id: string;
+    stream: string;
+    domain: string;
+    source_path: string;
+    source_fingerprint: string;
+    byte_offset: number;
+    last_sequence: number;
+    source_size: number;
+    source_modified_at: string;
+    indexed_at: string;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,kDAAkD;AAClD,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAgC3C,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE7D;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,oBAAoB,GAAG,SAAS,CAIjF;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAIzE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+import type { Database } from "bun:sqlite";
+import type { LogRecord, LogStream } from "@kar-mi/spirit-vale-tools-logging";
+/** A set of tables owned by one domain package. */
+export interface ReadModelDomain {
+    /** Stable key, e.g. "combat". Scopes rebuilds and indexing progress. */
+    readonly name: string;
+    /** Bump whenever {@link createSchema} changes; this domain is then dropped and re-indexed. */
+    readonly version: number;
+    createSchema(database: Database): void;
+    dropSchema(database: Database): void;
+}
+export type RebuildReason = 
+/** No database existed yet. */
+"created"
+/** The file failed an integrity check. */
+ | "corrupt"
+/** The file could not be opened or configured at all. */
+ | "unreadable"
+/** The infrastructure's own schema version moved. */
+ | "metadata-version"
+/** One domain's registered version moved; only that domain is rebuilt. */
+ | "domain-version";
+export interface ReadModelRebuild {
+    reason: RebuildReason;
+    /** Set only for a single-domain rebuild; absent when the whole database was recreated. */
+    domain?: string;
+    detail?: string;
+}
+export type StreamRebuildReason = 
+/** No progress was recorded for this stream yet. */
+"new"
+/** The source shrank below the recorded offset. */
+ | "truncated"
+/** A different file now occupies the same path. */
+ | "replaced"
+/** A record arrived at or below the last indexed sequence. */
+ | "sequence-regression";
+export interface IndexStreamRequest {
+    sessionId: string;
+    stream: LogStream;
+    sourcePath: string;
+    /** The domain whose tables {@link apply} writes to. */
+    domain: string;
+    /** Applies one batch of records. */
+    apply: (records: readonly LogRecord[], database: Database) => void | number;
+    /** Removes this domain's rows for one session/stream, so a rebuild starts from empty. */
+    clear: (scope: {
+        sessionId: string;
+        stream: LogStream;
+    }, database: Database) => void;
+    /** Most source bytes read — and so most rows applied — per transaction. */
+    batchBytes?: number;
+}
+export interface IndexStreamResult {
+    sessionId: string;
+    stream: LogStream;
+    /** The source file does not exist; recorded progress was left untouched. */
+    missing: boolean;
+    /** The stream was re-read from byte 0. */
+    rebuilt: boolean;
+    rebuildReason?: StreamRebuildReason;
+    recordsIndexed: number;
+    /** Lines that were not a valid log record. Counted, never fatal. */
+    invalidLines: number;
+    byteOffset: number;
+    lastSequence: number;
+}
+export interface IndexedStreamStatus {
+    sessionId: string;
+    stream: LogStream;
+    domain: string;
+    sourcePath: string;
+    byteOffset: number;
+    lastSequence: number;
+    sourceSize: number;
+    sourceModifiedAt: string;
+    indexedAt: string;
+}
+export interface ReadModelHealth {
+    path: string;
+    schemaVersion: number;
+    createdAt: string;
+    lastRebuildAt?: string;
+    /** Set when opening the database had to rebuild something. */
+    openedWith?: ReadModelRebuild;
+    domains: {
+        name: string;
+        version: number;
+    }[];
+    streams: IndexedStreamStatus[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@kar-mi/spirit-vale-tools-sqlite",
+  "version": "0.2.1",
+  "description": "Disposable SQLite read-model infrastructure for Spirit Vale session logs.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kar-mi/spirit-vale-tools.git",
+    "directory": "packages/sqlite"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm --external '@kar-mi/spirit-vale-tools-*' && bunx tsc --project ./tsconfig.build.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@kar-mi/spirit-vale-tools-logging": "^0.9.0"
+  }
+}