@typicalday/firegraph 0.14.0 → 0.15.0

package/README.md

@@ -833,6 +833,8 @@ const allAssignments = await g.findEdgesGlobal(
 
 This uses Firestore collection group queries and requires collection group indexes. The collection name defaults to the last segment of the client's collection path if omitted.
 
+Firestore-only: the SQLite backend uses a table-per-graph layout with no cross-table index, so it omits `findEdgesGlobal` entirely (calling it throws `UNSUPPORTED_OPERATION`).
+
 #### Multi-Hop Limitation
 
 Each hop carries its reader context forward — if hop 1 crosses into a subgraph, hop 2 stays in that subgraph. To return to the root or traverse a different subgraph, create a separate traversal from the desired client:
@@ -1140,18 +1142,36 @@ The match on `FIRESTORE_EMULATOR_EDITION` is case-insensitive and whitespace-tri
 
 ### SQLite Backend (`firegraph/sqlite`)
 
-Shared-table SQLite backend for Node.js (`better-sqlite3`) and Cloudflare D1. Supports all four core capabilities plus `query.aggregate`, `query.select`, `query.join`, and `query.dml`. Does not support `search.*`.
+Table-per-graph SQLite backend for Node.js (`better-sqlite3`) and Cloudflare D1. There is no `scope` column — the root graph lives in `tableName` itself and each subgraph gets its own physical table, tracked in a small `<tableName>_graphs` catalog. Schema (tables, indexes, catalog) is bootstrapped lazily on first use; no manual DDL step. Supports all four core capabilities plus `query.aggregate`, `query.select`, `query.join`, `query.dml`, and `raw.sql`. Does not support `search.*` or `findEdgesGlobal` (no cross-table index).
 
 ```typescript
 import { createSqliteBackend } from 'firegraph/sqlite';
-import { createGraphClientFromBackend } from 'firegraph';
+import { createGraphClient } from 'firegraph';
 
 const backend = createSqliteBackend(executor, 'graph');
-const g = createGraphClientFromBackend(backend, { registry });
+const g = createGraphClient(backend, { registry });
 ```
 
 Note: `core.transactions` is only declared when `executor.transaction` is defined — `better-sqlite3` provides this, but Cloudflare D1 does not.
 
+### Local SQLite Files (`firegraph/sqlite-local`)
+
+For a local graph database in a single SQLite file, use the better-sqlite3 factory. It opens (or wraps) a database, applies `journal_mode = WAL` and a `busy_timeout`, and returns a ready-to-use backend. Requires the optional peer dependency `better-sqlite3` (loaded via dynamic `import()`, so this subpath is safe to reference from code that also targets D1/workerd — just don't bundle it there).
+
+```typescript
+import { createLocalSqliteBackend } from 'firegraph/sqlite-local';
+import { createGraphClient } from 'firegraph';
+
+const { backend, db, close } = await createLocalSqliteBackend('./graph.db', {
+  tableName: 'graph', // default 'firegraph'
+});
+const g = createGraphClient(backend, { registry });
+// ... use the client; `db` is the raw better-sqlite3 Database if needed ...
+close();
+```
+
+`createLocalSqliteBackend` also accepts an already-open better-sqlite3 `Database` (in which case `close()` is a no-op — the caller owns the lifecycle), `':memory:'` for ephemeral graphs, a `pragmas` map for extra tuning, and `fileMustExist: true` to refuse creating new files. `createBetterSqliteExecutor(db)` is exported separately for wiring `createSqliteBackend` directly.
+
 ### Cloudflare Durable Object Backend (`firegraph/cloudflare`)
 
 Runs inside a Durable Object via `state.storage.sql`. Same capability set as SQLite minus `core.transactions` (the DO's single-threaded executor cannot block on transaction callbacks) and `raw.sql` (the DO SQL surface is hidden behind RPC).

package/dist/{backend-DuvHGgK1.d.cts → backend-BpYLdwCW.d.cts}

@@ -1894,4 +1894,4 @@ interface StorageBackend<C extends Capability = Capability> {
     geoSearch?(params: GeoSearchParams): Promise<StoredGraphRecord[]>;
 }
 
-export { type DynamicRegistryConfig as $, type AggregateExtension as A, type BackendCapabilities as B, type BulkBatchError as C, DELETE_FIELD as D, type ExpandParams as E, type FindEdgesParams as F, type GraphRegistry as G, type BulkOptions as H, type IndexSpec as I, type JoinExtension as J, type BulkProgress as K, type BulkResult as L, type MigrationWriteBack as M, type Capability as N, type CascadeResult as O, type CoreGraphClient as P, type QueryPlan as Q, type RegistryEntry as R, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type DefineTypeOptions as V, type WritableRecord as W, type DiscoveredEntity as X, type DistanceMeasure as Y, type DynamicGraphClient as Z, type DynamicGraphMethods as _, type BatchBackend as a, type EdgeTopology as a0, type EdgeTypeData as a1, type FindEdgesProjectedParams as a2, type FindNearestParams as a3, type FiregraphConfig as a4, type FullTextSearchExtension as a5, type GeoExtension as a6, type GraphBatch as a7, type GraphClientOptions as a8, type GraphRecord as a9, type GraphTransaction as aa, type GraphWriter as ab, type HopDefinition as ac, type HopResult as ad, type IndexFieldSpec as ae, type NodeTypeData as af, type ProjectedRow as ag, type QueryMode as ah, type QueryOptions as ai, type RawFirestoreExtension as aj, type RawSqlExtension as ak, type RealtimeListenExtension as al, type ScanProtection as am, type SelectExtension as an, type TraversalOptions as ao, type TraversalResult as ap, type VectorExtension as aq, type ViewContext as ar, type ViewDefaultsConfig as as, type ViewResolverConfig as at, type WhereClause as au, defineConfig as av, resolveView as aw, type BulkUpdatePatch as b, type DataPathOp as c, type DmlExtension as d, type ExpandResult as e, type WriteMode as f, createCapabilities as g, deleteField as h, flattenPatch as i, intersectCapabilities as j, isDeleteSentinel as k, type DiscoveryResult as l, type StoredGraphRecord as m, type MigrationStep as n, type FindNodesParams as o, type QueryFilter as p, type MigrationExecutor as q, type MigrationFn as r, type StoredMigrationStep as s, type GraphClient as t, type GraphReader as u, type TraversalBuilder as v, type AggregateField as w, type AggregateOp as x, type AggregateResult as y, type AggregateSpec as z };
+export { type DiscoveredEntity as $, type AggregateSpec as A, type BackendCapabilities as B, type Capability as C, DELETE_FIELD as D, type ExpandParams as E, type FindEdgesParams as F, type GraphClientOptions as G, type MigrationWriteBack as H, type IndexSpec as I, type JoinExtension as J, type MigrationStep as K, type QueryPlan as L, type MigrationExecutor as M, type FindNodesParams as N, type MigrationFn as O, type StoredMigrationStep as P, type QueryFilter as Q, type RegistryEntry as R, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type TraversalBuilder as V, type WritableRecord as W, type BulkBatchError as X, type BulkProgress as Y, type CoreGraphClient as Z, type DefineTypeOptions as _, type BatchBackend as a, type DistanceMeasure as a0, type DynamicGraphMethods as a1, type EdgeTopology as a2, type EdgeTypeData as a3, type FindEdgesProjectedParams as a4, type FindNearestParams as a5, type FiregraphConfig as a6, type FullTextSearchExtension as a7, type GeoExtension as a8, type GraphBatch as a9, type GraphRecord as aa, type GraphTransaction as ab, type GraphWriter as ac, type HopDefinition as ad, type HopResult as ae, type IndexFieldSpec as af, type NodeTypeData as ag, type ProjectedRow as ah, type QueryMode as ai, type RawFirestoreExtension as aj, type RawSqlExtension as ak, type RealtimeListenExtension as al, type ScanProtection as am, type SelectExtension as an, type TraversalOptions as ao, type TraversalResult as ap, type VectorExtension as aq, type ViewContext as ar, type ViewDefaultsConfig as as, type ViewResolverConfig as at, type WhereClause as au, defineConfig as av, resolveView as aw, type BulkUpdatePatch as b, type DataPathOp as c, type DmlExtension as d, type ExpandResult as e, type WriteMode as f, createCapabilities as g, deleteField as h, flattenPatch as i, intersectCapabilities as j, isDeleteSentinel as k, type DiscoveryResult as l, type DynamicRegistryConfig as m, type DynamicGraphClient as n, type GraphClient as o, type GraphRegistry as p, type GraphReader as q, type QueryOptions as r, type CascadeResult as s, type BulkOptions as t, type BulkResult as u, type StoredGraphRecord as v, type AggregateExtension as w, type AggregateField as x, type AggregateOp as y, type AggregateResult as z };

package/dist/{backend-DuvHGgK1.d.ts → backend-BpYLdwCW.d.ts}

@@ -1894,4 +1894,4 @@ interface StorageBackend<C extends Capability = Capability> {
     geoSearch?(params: GeoSearchParams): Promise<StoredGraphRecord[]>;
 }
 
-export { type DynamicRegistryConfig as $, type AggregateExtension as A, type BackendCapabilities as B, type BulkBatchError as C, DELETE_FIELD as D, type ExpandParams as E, type FindEdgesParams as F, type GraphRegistry as G, type BulkOptions as H, type IndexSpec as I, type JoinExtension as J, type BulkProgress as K, type BulkResult as L, type MigrationWriteBack as M, type Capability as N, type CascadeResult as O, type CoreGraphClient as P, type QueryPlan as Q, type RegistryEntry as R, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type DefineTypeOptions as V, type WritableRecord as W, type DiscoveredEntity as X, type DistanceMeasure as Y, type DynamicGraphClient as Z, type DynamicGraphMethods as _, type BatchBackend as a, type EdgeTopology as a0, type EdgeTypeData as a1, type FindEdgesProjectedParams as a2, type FindNearestParams as a3, type FiregraphConfig as a4, type FullTextSearchExtension as a5, type GeoExtension as a6, type GraphBatch as a7, type GraphClientOptions as a8, type GraphRecord as a9, type GraphTransaction as aa, type GraphWriter as ab, type HopDefinition as ac, type HopResult as ad, type IndexFieldSpec as ae, type NodeTypeData as af, type ProjectedRow as ag, type QueryMode as ah, type QueryOptions as ai, type RawFirestoreExtension as aj, type RawSqlExtension as ak, type RealtimeListenExtension as al, type ScanProtection as am, type SelectExtension as an, type TraversalOptions as ao, type TraversalResult as ap, type VectorExtension as aq, type ViewContext as ar, type ViewDefaultsConfig as as, type ViewResolverConfig as at, type WhereClause as au, defineConfig as av, resolveView as aw, type BulkUpdatePatch as b, type DataPathOp as c, type DmlExtension as d, type ExpandResult as e, type WriteMode as f, createCapabilities as g, deleteField as h, flattenPatch as i, intersectCapabilities as j, isDeleteSentinel as k, type DiscoveryResult as l, type StoredGraphRecord as m, type MigrationStep as n, type FindNodesParams as o, type QueryFilter as p, type MigrationExecutor as q, type MigrationFn as r, type StoredMigrationStep as s, type GraphClient as t, type GraphReader as u, type TraversalBuilder as v, type AggregateField as w, type AggregateOp as x, type AggregateResult as y, type AggregateSpec as z };
+export { type DiscoveredEntity as $, type AggregateSpec as A, type BackendCapabilities as B, type Capability as C, DELETE_FIELD as D, type ExpandParams as E, type FindEdgesParams as F, type GraphClientOptions as G, type MigrationWriteBack as H, type IndexSpec as I, type JoinExtension as J, type MigrationStep as K, type QueryPlan as L, type MigrationExecutor as M, type FindNodesParams as N, type MigrationFn as O, type StoredMigrationStep as P, type QueryFilter as Q, type RegistryEntry as R, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type TraversalBuilder as V, type WritableRecord as W, type BulkBatchError as X, type BulkProgress as Y, type CoreGraphClient as Z, type DefineTypeOptions as _, type BatchBackend as a, type DistanceMeasure as a0, type DynamicGraphMethods as a1, type EdgeTopology as a2, type EdgeTypeData as a3, type FindEdgesProjectedParams as a4, type FindNearestParams as a5, type FiregraphConfig as a6, type FullTextSearchExtension as a7, type GeoExtension as a8, type GraphBatch as a9, type GraphRecord as aa, type GraphTransaction as ab, type GraphWriter as ac, type HopDefinition as ad, type HopResult as ae, type IndexFieldSpec as af, type NodeTypeData as ag, type ProjectedRow as ah, type QueryMode as ai, type RawFirestoreExtension as aj, type RawSqlExtension as ak, type RealtimeListenExtension as al, type ScanProtection as am, type SelectExtension as an, type TraversalOptions as ao, type TraversalResult as ap, type VectorExtension as aq, type ViewContext as ar, type ViewDefaultsConfig as as, type ViewResolverConfig as at, type WhereClause as au, defineConfig as av, resolveView as aw, type BulkUpdatePatch as b, type DataPathOp as c, type DmlExtension as d, type ExpandResult as e, type WriteMode as f, createCapabilities as g, deleteField as h, flattenPatch as i, intersectCapabilities as j, isDeleteSentinel as k, type DiscoveryResult as l, type DynamicRegistryConfig as m, type DynamicGraphClient as n, type GraphClient as o, type GraphRegistry as p, type GraphReader as q, type QueryOptions as r, type CascadeResult as s, type BulkOptions as t, type BulkResult as u, type StoredGraphRecord as v, type AggregateExtension as w, type AggregateField as x, type AggregateOp as y, type AggregateResult as z };

package/dist/backend-CvImIwTY.d.cts

@@ -0,0 +1,137 @@
+import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-BpYLdwCW.cjs';
+
+/**
+ * Driver-level SQLite abstraction.
+ *
+ * The `SqliteBackend` only depends on this interface, not on any particular
+ * SQLite driver. Callers wire up whichever driver suits their runtime —
+ * `better-sqlite3` in Node tests, D1 in Workers, DO SQLite inside a Durable
+ * Object, etc. — and `createSqliteBackend` composes the rest.
+ *
+ * Some drivers are fully async with native atomic batches (e.g. D1); others
+ * are synchronous and wrap `run`/`all` in immediately-resolved promises while
+ * providing interactive transactions via a sync primitive (e.g. DO SQLite's
+ * `transactionSync`). Both shapes fit behind this interface.
+ */
+interface SqliteExecutor {
+    /** Run a query and return all rows. */
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    /** Run a write statement. */
+    run(sql: string, params: unknown[]): Promise<void>;
+    /**
+     * Execute a list of write statements atomically. Drivers that lack
+     * native batch support (e.g., a wrapped synchronous SQLite) should still
+     * implement this so `BatchBackend.commit()` works.
+     */
+    batch(statements: ReadonlyArray<{
+        sql: string;
+        params: unknown[];
+    }>): Promise<void>;
+    /**
+     * Run an interactive transaction. Optional — if absent, the SqliteBackend
+     * throws on `runTransaction()`. D1 has no interactive transactions.
+     */
+    transaction?<T>(fn: (tx: SqliteTxExecutor) => Promise<T>): Promise<T>;
+    /**
+     * Maximum statements the driver will accept in a single `batch()` call.
+     * The backend uses this to chunk large bulk operations (cascade delete,
+     * bulkRemoveEdges) so a hub node with thousands of edges doesn't trip the
+     * driver's hard limit. D1 caps at ~100 statements per batch; DO SQLite has
+     * no documented cap (a single `transactionSync` over many statements is
+     * fine). When `undefined`, the backend submits all statements in one batch
+     * (preserving cross-batch atomicity for drivers that support it).
+     */
+    readonly maxBatchSize?: number;
+    /**
+     * Maximum total bound parameters the driver will accept across one
+     * `batch()` call. D1 caps at ~1000 bound parameters per batch — separate
+     * from `maxBatchSize`. Most cascade/bulk batches consist of 2-param
+     * `DELETE` statements so this rarely triggers, but driver authors should
+     * declare it for safety. When `undefined`, the backend doesn't split on
+     * parameter count.
+     */
+    readonly maxBatchParams?: number;
+}
+interface SqliteTxExecutor {
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    run(sql: string, params: unknown[]): Promise<void>;
+}
+
+/**
+ * SQLite implementation of `StorageBackend`.
+ *
+ * Table-per-graph design: the root graph lives in `tableName`, and each
+ * subgraph lives in its own physical table (`<tableName>_g_<mangled scope>`,
+ * see `tableForScope`). There is no `scope` column — the table a row lives
+ * in *is* its scope, exactly like the Cloudflare DO edition where each
+ * subgraph is its own Durable Object.
+ *
+ * A small catalog table (`<tableName>_graphs`) records every graph's
+ * storage scope → table mapping. Cascade delete prefix-matches descendant
+ * scopes in the catalog and drops each listed table — no registry topology
+ * required.
+ *
+ * Schema is ensured lazily: the first operation on a backend instance runs
+ * `CREATE TABLE IF NOT EXISTS` for the graph's table, its indexes, and the
+ * catalog, then registers the graph in the catalog. Callers no longer
+ * pre-create tables.
+ */
+
+interface SqliteBackendOptions {
+    /** Logical scope path (chained subgraph names) — used for `allowedIn` matching. */
+    scopePath?: string;
+    /**
+     * Internal storage scope (interleaved parent-uid/name path). Determines
+     * which physical table this backend reads and writes — `''` (the default)
+     * is the root graph in `tableName` itself.
+     *
+     * @internal Used by `subgraph()` to derive child backends. Setting it
+     * directly bypasses catalog registration consistency checks (the graph
+     * still self-registers, but ancestors are not validated) — always derive
+     * subgraph backends via `subgraph()` instead.
+     */
+    storageScope?: string;
+    /**
+     * Registry contributing per-entry `indexes` declarations, applied to
+     * every graph table this backend (and its subgraphs) lazily creates.
+     */
+    registry?: GraphRegistry;
+    /**
+     * Replaces the built-in core index preset for lazily created tables.
+     * Pass `[]` to disable core indexes entirely.
+     */
+    coreIndexes?: IndexSpec[];
+}
+/**
+ * Capability union declared by the SQLite-backed `StorageBackend`.
+ *
+ * `core.transactions` is part of the static union because `runTransaction`
+ * is always present as a method on the class. The runtime cap-set determines
+ * whether that method is *functional*: D1 leaves `executor.transaction`
+ * undefined and the call throws `UNSUPPORTED_OPERATION`; DO SQLite and
+ * better-sqlite3 wire the executor and the call works. The static type
+ * therefore promises only that the method exists — callers that care about
+ * portability check `client.capabilities.has('core.transactions')` before
+ * opening a tx, and code that runs against an unknown driver can rely on the
+ * runtime guard inside `runTransaction`.
+ *
+ * The `query.*` extension capabilities follow the same conservative
+ * declaration rule as the cap descriptor itself — only land in the union
+ * when the corresponding method is actually wired up. Today that's
+ * `query.aggregate` (Phase 4), `query.dml` (Phase 5), `query.join`
+ * (Phase 6 — fan-out via `IN (…)` in one statement), and `query.select`
+ * (Phase 7 — server-side projection via `json_extract`).
+ */
+type SqliteCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.dml' | 'query.join' | 'query.select' | 'raw.sql';
+/**
+ * Create a SQLite-backed `StorageBackend`.
+ *
+ * `tableName` is the root graph's table; subgraphs get their own tables
+ * derived from it (see `tableForScope`). Schema (tables, indexes, and the
+ * graph catalog) is created lazily on first use — no manual DDL step.
+ * Pass `options.registry` so per-entry `indexes` declarations land in
+ * every lazily created table.
+ */
+declare function createSqliteBackend(executor: SqliteExecutor, tableName: string, options?: SqliteBackendOptions): StorageBackend<SqliteCapability>;
+
+export { type SqliteBackendOptions as S, type SqliteCapability as a, type SqliteExecutor as b, createSqliteBackend as c };

package/dist/backend-YH5HtawN.d.ts

@@ -0,0 +1,137 @@
+import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-BpYLdwCW.js';
+
+/**
+ * Driver-level SQLite abstraction.
+ *
+ * The `SqliteBackend` only depends on this interface, not on any particular
+ * SQLite driver. Callers wire up whichever driver suits their runtime —
+ * `better-sqlite3` in Node tests, D1 in Workers, DO SQLite inside a Durable
+ * Object, etc. — and `createSqliteBackend` composes the rest.
+ *
+ * Some drivers are fully async with native atomic batches (e.g. D1); others
+ * are synchronous and wrap `run`/`all` in immediately-resolved promises while
+ * providing interactive transactions via a sync primitive (e.g. DO SQLite's
+ * `transactionSync`). Both shapes fit behind this interface.
+ */
+interface SqliteExecutor {
+    /** Run a query and return all rows. */
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    /** Run a write statement. */
+    run(sql: string, params: unknown[]): Promise<void>;
+    /**
+     * Execute a list of write statements atomically. Drivers that lack
+     * native batch support (e.g., a wrapped synchronous SQLite) should still
+     * implement this so `BatchBackend.commit()` works.
+     */
+    batch(statements: ReadonlyArray<{
+        sql: string;
+        params: unknown[];
+    }>): Promise<void>;
+    /**
+     * Run an interactive transaction. Optional — if absent, the SqliteBackend
+     * throws on `runTransaction()`. D1 has no interactive transactions.
+     */
+    transaction?<T>(fn: (tx: SqliteTxExecutor) => Promise<T>): Promise<T>;
+    /**
+     * Maximum statements the driver will accept in a single `batch()` call.
+     * The backend uses this to chunk large bulk operations (cascade delete,
+     * bulkRemoveEdges) so a hub node with thousands of edges doesn't trip the
+     * driver's hard limit. D1 caps at ~100 statements per batch; DO SQLite has
+     * no documented cap (a single `transactionSync` over many statements is
+     * fine). When `undefined`, the backend submits all statements in one batch
+     * (preserving cross-batch atomicity for drivers that support it).
+     */
+    readonly maxBatchSize?: number;
+    /**
+     * Maximum total bound parameters the driver will accept across one
+     * `batch()` call. D1 caps at ~1000 bound parameters per batch — separate
+     * from `maxBatchSize`. Most cascade/bulk batches consist of 2-param
+     * `DELETE` statements so this rarely triggers, but driver authors should
+     * declare it for safety. When `undefined`, the backend doesn't split on
+     * parameter count.
+     */
+    readonly maxBatchParams?: number;
+}
+interface SqliteTxExecutor {
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    run(sql: string, params: unknown[]): Promise<void>;
+}
+
+/**
+ * SQLite implementation of `StorageBackend`.
+ *
+ * Table-per-graph design: the root graph lives in `tableName`, and each
+ * subgraph lives in its own physical table (`<tableName>_g_<mangled scope>`,
+ * see `tableForScope`). There is no `scope` column — the table a row lives
+ * in *is* its scope, exactly like the Cloudflare DO edition where each
+ * subgraph is its own Durable Object.
+ *
+ * A small catalog table (`<tableName>_graphs`) records every graph's
+ * storage scope → table mapping. Cascade delete prefix-matches descendant
+ * scopes in the catalog and drops each listed table — no registry topology
+ * required.
+ *
+ * Schema is ensured lazily: the first operation on a backend instance runs
+ * `CREATE TABLE IF NOT EXISTS` for the graph's table, its indexes, and the
+ * catalog, then registers the graph in the catalog. Callers no longer
+ * pre-create tables.
+ */
+
+interface SqliteBackendOptions {
+    /** Logical scope path (chained subgraph names) — used for `allowedIn` matching. */
+    scopePath?: string;
+    /**
+     * Internal storage scope (interleaved parent-uid/name path). Determines
+     * which physical table this backend reads and writes — `''` (the default)
+     * is the root graph in `tableName` itself.
+     *
+     * @internal Used by `subgraph()` to derive child backends. Setting it
+     * directly bypasses catalog registration consistency checks (the graph
+     * still self-registers, but ancestors are not validated) — always derive
+     * subgraph backends via `subgraph()` instead.
+     */
+    storageScope?: string;
+    /**
+     * Registry contributing per-entry `indexes` declarations, applied to
+     * every graph table this backend (and its subgraphs) lazily creates.
+     */
+    registry?: GraphRegistry;
+    /**
+     * Replaces the built-in core index preset for lazily created tables.
+     * Pass `[]` to disable core indexes entirely.
+     */
+    coreIndexes?: IndexSpec[];
+}
+/**
+ * Capability union declared by the SQLite-backed `StorageBackend`.
+ *
+ * `core.transactions` is part of the static union because `runTransaction`
+ * is always present as a method on the class. The runtime cap-set determines
+ * whether that method is *functional*: D1 leaves `executor.transaction`
+ * undefined and the call throws `UNSUPPORTED_OPERATION`; DO SQLite and
+ * better-sqlite3 wire the executor and the call works. The static type
+ * therefore promises only that the method exists — callers that care about
+ * portability check `client.capabilities.has('core.transactions')` before
+ * opening a tx, and code that runs against an unknown driver can rely on the
+ * runtime guard inside `runTransaction`.
+ *
+ * The `query.*` extension capabilities follow the same conservative
+ * declaration rule as the cap descriptor itself — only land in the union
+ * when the corresponding method is actually wired up. Today that's
+ * `query.aggregate` (Phase 4), `query.dml` (Phase 5), `query.join`
+ * (Phase 6 — fan-out via `IN (…)` in one statement), and `query.select`
+ * (Phase 7 — server-side projection via `json_extract`).
+ */
+type SqliteCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.dml' | 'query.join' | 'query.select' | 'raw.sql';
+/**
+ * Create a SQLite-backed `StorageBackend`.
+ *
+ * `tableName` is the root graph's table; subgraphs get their own tables
+ * derived from it (see `tableForScope`). Schema (tables, indexes, and the
+ * graph catalog) is created lazily on first use — no manual DDL step.
+ * Pass `options.registry` so per-entry `indexes` declarations land in
+ * every lazily created table.
+ */
+declare function createSqliteBackend(executor: SqliteExecutor, tableName: string, options?: SqliteBackendOptions): StorageBackend<SqliteCapability>;
+
+export { type SqliteBackendOptions as S, type SqliteCapability as a, type SqliteExecutor as b, createSqliteBackend as c };

package/dist/backend.cjs

@@ -422,7 +422,6 @@ function isTerminalValue(value) {
   if (ctor && typeof ctor.name === "string" && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;
   return true;
 }
-var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 function walkForDeleteSentinels(node, path, parent, visit) {
   if (node === null || node === void 0) return;
   if (isDeleteSentinel(node)) {
@@ -446,9 +445,9 @@ function walkForDeleteSentinels(node, path, parent, visit) {
 }
 function assertSafePath(path) {
   for (const seg of path) {
-    if (!SAFE_KEY_RE.test(seg)) {
+    if (seg === "") {
       throw new Error(
-        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Keys used inside update payloads must match /^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in SQLite JSON paths.`
+        `firegraph: empty object key at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Object keys in update payloads must be non-empty.`
       );
     }
   }