@pennixrv/trellis-core 0.6.17

package/dist/mem/internal/sqlite-readonly.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Zero-dependency read-only SQLite file parser.
+ *
+ * `@pennixrv/trellis-core` is intentionally free of runtime dependencies —
+ * `better-sqlite3` was tried for the OpenCode adapter and reverted because its
+ * native build chain broke `npm install` on Windows + restricted networks. This
+ * parser is the minimum viable reader needed by the ZCode `mem` adapter: list
+ * tables, full-scan one table, return rows as `{ [columnName]: value }`. It is
+ * NOT a SQL engine: no WHERE pushdown, no index lookup, no writes.
+ *
+ * Scope:
+ *   - Database header (page size, db size, text encoding, WAL flag)
+ *   - Table b-tree leaf (0x0d) + interior (0x05) traversal
+ *   - Record decode for TEXT / INTEGER / NULL / float64 / BLOB(serial only)
+ *   - Overflow page chains (long TEXT rows like ZCode `message.data`)
+ *   - WAL replay: stable main/WAL snapshot, WAL-index `mxFrame` end mark, and
+ *     cumulative header/frame checksum verification.
+ *
+ * Out of scope:
+ *   - WITHOUT ROWID tables (return [] — their rows live in index b-trees,
+ *     which this parser doesn't walk). ZCode's tables are normal rowid tables.
+ *
+ * Format references:
+ *   - https://www.sqlite.org/fileformat2.html
+ *   - https://www.sqlite.org/walformat.html
+ *
+ * All multi-byte integers are big-endian (SQLite's native byte order).
+ */
+/** One row from `scanTable`, keyed by column name. Values are decoded JS
+ * primitives. NULL → null, INTEGER → number, TEXT → string, BLOB →
+ * Uint8Array, float → number. Columns are keyed by the CREATE TABLE column
+ * order; if the column-name parse failed, keys fall back to `col0`, `col1`... */
+export type SqliteRow = Record<string, unknown>;
+export interface SqliteTableInfo {
+    name: string;
+    rootPgno: number;
+    /** The raw `CREATE TABLE` SQL (used to recover column names). */
+    sql: string;
+}
+export interface SqliteReadOnly {
+    /** List user tables (type='table') from sqlite_master. */
+    listTables(): SqliteTableInfo[];
+    /** Full-scan a table by name, yielding rows. Returns [] when the table is
+     * missing. Throws `SqliteParseError` on structural corruption. */
+    scanTable(tableName: string, predicate?: (row: SqliteRow) => boolean): SqliteRow[];
+    /** The db file path this reader was opened against. */
+    readonly dbPath: string;
+    close(): void;
+}
+/** Thrown when the SQLite file is structurally invalid. Adapters are expected
+ * to catch this and degrade to an empty result rather than crash the CLI. */
+export declare class SqliteParseError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when the database files do not remain stable across all snapshot
+ * capture attempts. This is deliberately distinct from a malformed database:
+ * callers must not parse a snapshot whose consistency they could not verify.
+ */
+export declare class SqliteSnapshotUnstableError extends SqliteParseError {
+    constructor(mainPath: string);
+}
+/**
+ * Open a SQLite database file for read-only access. Automatically loads the
+ * sibling `<db>-wal` file when present so active WAL-mode databases (e.g.
+ * ZCode's running store) return their latest committed data.
+ *
+ * Throws `SqliteParseError` if `mainPath` is not a SQLite file or is too
+ * corrupted to read the header. Adapters should catch and degrade.
+ */
+export declare function openSqliteReadOnly(mainPath: string): SqliteReadOnly;
+/** Convenience: open + scan + close in one call. Returns [] on any parse error
+ * or missing table, never throws. Useful for adapters that already decided to
+ * degrade silently. */
+export declare function scanTableSafe(mainPath: string, tableName: string): SqliteRow[];
+//# sourceMappingURL=sqlite-readonly.d.ts.map

package/dist/mem/internal/sqlite-readonly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-readonly.d.ts","sourceRoot":"","sources":["../../../src/mem/internal/sqlite-readonly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH;;;iFAGiF;AACjF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,UAAU,IAAI,eAAe,EAAE,CAAC;IAChC;sEACkE;IAClE,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,OAAO,GACtC,SAAS,EAAE,CAAC;IACf,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAID;6EAC6E;AAC7E,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBADxB,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,gBAAgB;gBACnD,QAAQ,EAAE,MAAM;CAM7B;AAyxBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CA2HnE;AAED;;uBAEuB;AACvB,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,SAAS,EAAE,CAWb"}