trajectories 0.0.0 → 0.1.1

package/legacy/src/schema-gate.ts

@@ -0,0 +1,263 @@
+import { existsSync, statSync } from "node:fs";
+import { Database } from "bun:sqlite";
+import { DERIVE_COUNTERS, REQUIRED_READ_SCHEMA, SCHEMA_VERSION } from "./schema.js";
+
+/**
+ * The typed read gate: one ladder, one implementation, shared by every way a
+ * read verb opens a store (`openReadOnlyStore` and `readStoreStatus`). Both
+ * used to test for a `sessions` table and a version, which let a foreign file
+ * through to die later on a raw `no such table: records` / `no such column:
+ * updated_at` — an error with no code, no payload, and no remedy.
+ *
+ * Order is deliberate: a store is classified as not initialized before it is
+ * opened, a file this build cannot read is diagnosed before its version is
+ * judged (the version is unreadable too), a newer version is refused before its
+ * shape is judged (it is expected to differ), and only then is the read schema
+ * checked. `user_version < SCHEMA_VERSION` with the read schema present stays
+ * `ok`: an old store keeps serving reads, and nothing here migrates it.
+ *
+ * The derive-rule counters (schema.ts) are judged in the same pass and on the
+ * same principle, one axis over: a stored counter *newer* than this build
+ * derives is refused (the index was produced by rules this build does not have),
+ * while an older counter — or none at all, which is every store written before
+ * the counter existed — stays `ok` beside it. A *pending re-derivation flag* is
+ * not a refusal either: the index is stale, not unreadable, and Wake's readers
+ * serve the same stale index while a scan is pending. Reads never write, so
+ * neither gate ever clears a flag or stamps a counter.
+ */
+export type ReadStoreClassification =
+  | { state: "not_initialized"; reason: "missing" | "zero_bytes" }
+  | { state: "unreadable"; phase: "open" | "read"; detail: string }
+  | { state: "foreign" }
+  | { state: "schema_mismatch"; schemaVersion: number }
+  | { state: "format_mismatch"; counter: string; stored: string; supported: string }
+  | { state: "incomplete"; firstGap: string; schemaVersion: number }
+  /** `db` is the caller's to close. */
+  | { state: "ok"; schemaVersion: number; db: Database };
+
+/**
+ * Every state in which a store exists but cannot serve a read: the four
+ * refusals both gates map to their own error type and wording.
+ */
+export type ReadStoreRefusal = Exclude<
+  ReadStoreClassification,
+  { state: "ok" } | { state: "not_initialized" }
+>;
+
+/**
+ * Classify the store at `dbPath`. A missing path and a zero-byte file both read
+ * as "not initialized" rather than as a foreign or damaged store.
+ */
+export function classifyReadStore(dbPath: string): ReadStoreClassification {
+  if (!existsSync(dbPath)) return { state: "not_initialized", reason: "missing" };
+
+  let db: Database;
+  try {
+    // A zero-byte file is what an interrupted creation leaves behind, and
+    // SQLite opens one as an empty database: classify it before the open.
+    if (statSync(dbPath).size === 0) return { state: "not_initialized", reason: "zero_bytes" };
+    db = new Database(dbPath, { readonly: true });
+  } catch (err) {
+    return {
+      state: "unreadable",
+      phase: "open",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  try {
+    // Bound the wait on a busy store instead of failing a read that would
+    // succeed moments later. Connection-local, so both gates inherit it.
+    db.run("PRAGMA busy_timeout = 5000;");
+    const classification = classifyOpenStore(db);
+    if (classification.state !== "ok") db.close();
+    return classification;
+  } catch (err) {
+    // The engine failed a probe: a corrupt file, or a WAL store whose sidecars
+    // are gone (a read-only connection may not create them).
+    db.close();
+    return {
+      state: "unreadable",
+      phase: "read",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+function classifyOpenStore(db: Database): ReadStoreClassification {
+  const schemaVersion =
+    db.query<{ user_version: number }, []>("PRAGMA user_version;").get()?.user_version ?? 0;
+  const hasSessionsTable = !!db
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='sessions' LIMIT 1;",
+    )
+    .get();
+
+  if (!hasSessionsTable) return { state: "foreign" };
+  if (schemaVersion > SCHEMA_VERSION) return { state: "schema_mismatch", schemaVersion };
+
+  const derivedByNewerRules = newerDerivedFormat(db);
+  if (derivedByNewerRules) return { state: "format_mismatch", ...derivedByNewerRules };
+
+  const firstGap = firstMissingPair(db);
+  if (firstGap !== null) return { state: "incomplete", firstGap, schemaVersion };
+
+  return { state: "ok", schemaVersion, db };
+}
+
+/**
+ * The first derive-rule counter this store records as newer than this build
+ * derives, or null when none does.
+ *
+ * Three answers here are decisions, not defaults:
+ *
+ * - A store with no `schema_meta` table, a differing table shape, or no row for
+ *   a counter records nothing and stays readable. Absence means "derived by a
+ *   build that had no counter", and every such build derived the index the same
+ *   way; refusing would refuse every store that predates the counter, which is
+ *   every store that exists when the counter lands.
+ * - A stored value that is *older* is tolerated: the index is stale, not
+ *   foreign, and Wake's readers serve a stale index while a re-scan is pending.
+ *   The next writer pass re-derives it.
+ * - A value this build cannot parse counts as newer. A counter that cannot be
+ *   compared cannot be vouched for; the writer's next open stamps a comparable
+ *   one, and until then the read refuses *by name* rather than serving an index
+ *   whose rules are unknown.
+ */
+function newerDerivedFormat(
+  db: Database,
+): { counter: string; stored: string; supported: string } | null {
+  if (!hasMetaColumns(db)) return null;
+  const read = db.query<{ value: string }, [string]>(
+    "SELECT value FROM schema_meta WHERE key = ?;",
+  );
+  for (const counter of DERIVE_COUNTERS) {
+    const stored = read.get(counter.format)?.value ?? null;
+    if (stored === null || stored === counter.current) continue;
+    if (isNewerCounter(stored, counter.current)) {
+      return { counter: counter.format, stored, supported: counter.current };
+    }
+  }
+  return null;
+}
+
+/** Decimal-integer counter values, per the contract in schema.ts. */
+const COUNTER_VALUE = /^[0-9]+$/;
+
+/**
+ * Whether a stored counter is newer than the one this build derives. The values
+ * are decimal integers by contract, so the comparison is numeric — a string
+ * comparison would call `"10"` older than `"2"`. Anything unparsable counts as
+ * newer: on the store's side that is the conservative direction (see above), and
+ * on ours it is a build bug that must fail loudly rather than tolerate silently.
+ */
+function isNewerCounter(stored: string, supported: string): boolean {
+  if (!COUNTER_VALUE.test(stored) || !COUNTER_VALUE.test(supported)) return true;
+  return Number(stored) > Number(supported);
+}
+
+/**
+ * Whether `schema_meta` is present with the two columns the counters are read
+ * through. A store that never had the table, or has one of another shape, is
+ * treated as recording no counters rather than as unreadable: the counter
+ * decides what a *derived index* is worth, and a store whose bookkeeping table
+ * is foreign can still satisfy the read schema below (which is what refuses a
+ * store that is genuinely malformed).
+ */
+function hasMetaColumns(db: Database): boolean {
+  const columns = db
+    .query<{ name: string }, []>("PRAGMA table_info(schema_meta);")
+    .all()
+    .map((column) => column.name);
+  return columns.includes("key") && columns.includes("value");
+}
+
+/**
+ * One line for both gates: the refusal names the counter, the value the store
+ * records, and the value this build derives. A genuinely newer value needs an
+ * upgrade; an unparsable one only needs any writer pass, which stamps a
+ * comparable counter and re-derives under this build's rules.
+ */
+export function formatMismatchMessage(
+  dbPath: string,
+  mismatch: { counter: string; stored: string; supported: string },
+): string {
+  const remedy = COUNTER_VALUE.test(mismatch.stored)
+    ? " Upgrade Trajectories to read this store."
+    : " Run any Ledger writer pass (for example `trajectories sync`) to re-stamp it.";
+  return (
+    `Database at ${dbPath} was derived under newer rules` +
+    ` (${mismatch.counter}: ${mismatch.stored}; this build derives ${mismatch.supported}).` +
+    remedy
+  );
+}
+
+/**
+ * One line per caller: the refusal has to name the store, the gap, and the way
+ * out, in the same words in both gates. A store carrying a Ledger user_version
+ * is an older Ledger store a writer pass will migrate; a zero version with
+ * missing shape is foreign or damaged, and rebuilding is the only way out.
+ */
+export function incompleteStoreMessage(
+  dbPath: string,
+  firstGap: string,
+  schemaVersion: number,
+): string {
+  if (schemaVersion > 0) {
+    return (
+      `Database at ${dbPath} has an older Ledger store schema (v${schemaVersion})` +
+      ` that predates some read paths: missing ${firstGap}.` +
+      " Run `trajectories sync` or `trajectories build` to migrate it, or point --db at a current store."
+    );
+  }
+  return (
+    `Database at ${dbPath} has an incomplete store schema: missing ${firstGap}.` +
+    " The store may be foreign or damaged — re-build it from sources (`trajectories sync`/`trajectories build`)" +
+    " or point --db at a Ledger store."
+  );
+}
+
+/**
+ * The first missing pair, in table-then-column order, so the same store always
+ * reports the same gap. Pairs are compared by code unit rather than locale, and
+ * a presence-only pair (null column) sorts first inside its table, which makes
+ * a missing table name itself instead of an arbitrary column of it.
+ */
+function firstMissingPair(db: Database): string | null {
+  const columnsByTable = new Map<string, Set<string>>();
+  for (const [table] of REQUIRED_READ_SCHEMA) {
+    if (!columnsByTable.has(table)) {
+      columnsByTable.set(
+        table,
+        new Set(
+          db
+            .query<{ name: string }, []>(`PRAGMA table_info(${table});`)
+            .all()
+            .map((row) => row.name),
+        ),
+      );
+    }
+  }
+
+  for (const [table, column] of GAP_ORDER) {
+    const present = columnsByTable.get(table)!;
+    if (!present.size) return table;
+    if (column !== null && !present.has(column)) return `${table}.${column}`;
+  }
+  return null;
+}
+
+/**
+ * `REQUIRED_READ_SCHEMA` in gap-report order: table, then column. Columns are
+ * compared by code unit rather than locale so every process reports the same
+ * gap for the same store.
+ */
+const GAP_ORDER = [...REQUIRED_READ_SCHEMA].sort(
+  (a, b) => {
+    if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+    const aColumn = a[1] ?? "";
+    const bColumn = b[1] ?? "";
+    if (aColumn === bColumn) return 0;
+    return aColumn < bColumn ? -1 : 1;
+  },
+);