@typicalday/firegraph 0.14.1 → 0.16.0

package/README.md

@@ -129,21 +129,21 @@ if (client.capabilities.has('query.join')) {
 
 **Capability values:**
 
-| Capability                                                  | Methods unlocked                                                 | Backends                                                                                                                                 |
-| ----------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `core.read` / `core.write` / `core.batch` / `core.subgraph` | `getNode`, `putNode`, `findEdges`, `batch()`, `subgraph()`, etc. | All                                                                                                                                      |
-| `core.transactions`                                         | `runTransaction(fn)`                                             | Firestore (both), SQLite (`better-sqlite3` only; absent on D1); **absent on Cloudflare DO**                                              |
-| `query.aggregate`                                           | `aggregate(spec)`                                                | All; `min`/`max` only on SQLite + DO (both Firestore editions reject `min`/`max` — classic `Query.aggregate` exposes only count/sum/avg) |
-| `query.select`                                              | `findEdgesProjected(params)`                                     | All                                                                                                                                      |
-| `query.join`                                                | `expand(params)`                                                 | All                                                                                                                                      |
-| `query.dml`                                                 | `bulkDelete(params)`, `bulkUpdate(params)`                       | Enterprise (requires `previewDml: true`), SQLite, DO                                                                                     |
-| `traversal.serverSide`                                      | `runEngineTraversal(params)`                                     | Enterprise                                                                                                                               |
-| `search.vector`                                             | `findNearest(params)`                                            | Firestore (both)                                                                                                                         |
-| `search.fullText`                                           | `fullTextSearch(params)`                                         | Enterprise. **Note:** the `fields` option is not yet supported — passing a non-empty `fields` array throws `INVALID_QUERY`.              |
-| `search.geo`                                                | `geoSearch(params)`                                              | Enterprise                                                                                                                               |
-| `raw.firestore`                                             | _(reserved — no methods yet)_                                    | Firestore (both)                                                                                                                         |
-| `raw.sql`                                                   | _(reserved — no methods yet)_                                    | SQLite                                                                                                                                   |
-| `realtime.listen`                                           | _(reserved — no methods yet)_                                    | _(none currently)_                                                                                                                       |
+| Capability                                                  | Methods unlocked                                                 | Backends                                                                                                                                                                                 |
+| ----------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `core.read` / `core.write` / `core.batch` / `core.subgraph` | `getNode`, `putNode`, `findEdges`, `batch()`, `subgraph()`, etc. | All                                                                                                                                                                                      |
+| `core.transactions`                                         | `runTransaction(fn)`                                             | Firestore (both), SQLite (`better-sqlite3` only; absent on D1); **absent on Cloudflare DO**                                                                                              |
+| `query.aggregate`                                           | `aggregate(spec)`                                                | All; `min`/`max` only on SQLite + DO (both Firestore editions reject `min`/`max` — classic `Query.aggregate` exposes only count/sum/avg)                                                 |
+| `query.select`                                              | `findEdgesProjected(params)`                                     | All                                                                                                                                                                                      |
+| `query.join`                                                | `expand(params)`                                                 | All                                                                                                                                                                                      |
+| `query.dml`                                                 | `bulkDelete(params)`, `bulkUpdate(params)`                       | Enterprise (requires `previewDml: true`), SQLite, DO                                                                                                                                     |
+| `traversal.serverSide`                                      | `runEngineTraversal(params)`                                     | Enterprise                                                                                                                                                                               |
+| `search.vector`                                             | `findNearest(params)`                                            | Firestore (both), local SQLite (`firegraph/sqlite-local` — exact brute-force scan via a SQL distance function)                                                                           |
+| `search.fullText`                                           | `fullTextSearch(params)`                                         | Enterprise, local SQLite (`firegraph/sqlite-local` — FTS5, bm25-ranked). **Note:** the `fields` option is not yet supported — passing a non-empty `fields` array throws `INVALID_QUERY`. |
+| `search.geo`                                                | `geoSearch(params)`                                              | Enterprise                                                                                                                                                                               |
+| `raw.firestore`                                             | _(reserved — no methods yet)_                                    | Firestore (both)                                                                                                                                                                         |
+| `raw.sql`                                                   | _(reserved — no methods yet)_                                    | SQLite                                                                                                                                                                                   |
+| `realtime.listen`                                           | _(reserved — no methods yet)_                                    | _(none currently)_                                                                                                                                                                       |
 
 ### Extension Methods
 
@@ -200,7 +200,7 @@ const tree = await (client as TraversalExtension).runEngineTraversal({
   hops: [{ axbType: 'hasDeparture', bType: 'departure', limitPerSource: 10 }],
 });
 
-// search.vector — approximate nearest-neighbour (Firestore both editions)
+// search.vector — nearest-neighbour (Firestore both editions; local SQLite via firegraph/sqlite-local)
 const similar = await (client as VectorExtension).findNearest({
   aType: 'tour',
   axbType: 'is',
@@ -210,7 +210,7 @@ const similar = await (client as VectorExtension).findNearest({
   limit: 5,
 });
 
-// search.fullText — full-text search (Enterprise; `fields` throws INVALID_QUERY if non-empty)
+// search.fullText — full-text search (Enterprise + firegraph/sqlite-local; `fields` throws INVALID_QUERY if non-empty)
 const results = await (client as FullTextExtension).fullTextSearch({
   aType: 'tour',
   axbType: 'is',
@@ -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,58 @@ 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.
+
+On top of the shared SQLite capability set, the local factory declares `search.fullText` and `search.vector`:
+
+- **`fullTextSearch(params)`** — every graph table gets a contentless FTS5 index kept in sync by pure-SQL triggers (`json_tree` extracts all string leaves from `data`, so nested fields are searchable). Results are ranked by bm25. FTS5 query syntax (`AND` / `OR` / `NOT`, `"phrase"` quoting, `prefix*`) passes through; malformed queries throw `INVALID_QUERY`. The `fields` option is not supported (the index is one combined text column) — a non-empty `fields` array throws `INVALID_QUERY`, matching Firestore Enterprise. Because the triggers are plain SQL, writes from _any_ connection or process stay indexed, and rows written before the index existed are backfilled on bootstrap.
+- **`findNearest(params)`** — exact (not approximate) nearest-neighbour via a brute-force scan scored by a connection-local SQL distance function. Supports `EUCLIDEAN`, `COSINE`, and `DOT_PRODUCT`, plus `distanceThreshold` and `distanceResultField`, mirroring Firestore semantics (rows with a missing field, wrong dimension, or non-finite values are silently skipped). Vector queries must run through the factory-created backend — the distance function is registered per connection.
+
+```typescript
+const hits = await g.fullTextSearch({
+  aType: 'tour',
+  axbType: 'is',
+  bType: 'tour',
+  query: 'dolomites OR alps',
+});
+const similar = await g.findNearest({
+  aType: 'tour',
+  axbType: 'is',
+  bType: 'tour',
+  queryVector: [0.1, 0.2, 0.3],
+  vectorField: 'embedding',
+  limit: 5,
+});
+```
+
 ### 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-CE3pM9-T.d.ts

@@ -0,0 +1,167 @@
+import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-DNzv8KSR.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[];
+    /**
+     * Extra DDL statements appended to every graph table's lazy bootstrap.
+     * Called with the physical table name; the returned statements run after
+     * the core table/index DDL inside the same chunked batch. Statements MUST
+     * be idempotent (`IF NOT EXISTS` / `INSERT OR IGNORE` / re-runnable DML)
+     * — the bootstrap re-runs after self-heal and once per backend instance,
+     * including every lazily created subgraph table.
+     *
+     * @internal Used by `firegraph/sqlite-local` to install FTS5 index
+     * tables, sync triggers, and backfill statements. Propagated to subgraph
+     * backends derived via `subgraph()`.
+     */
+    extraTableDDL?: (tableName: string) => string[];
+}
+/**
+ * The shape `createSqliteBackend` actually returns: `StorageBackend` plus
+ * internal hooks the `firegraph/sqlite-local` search wrapper needs.
+ */
+interface SqliteStorageBackend extends StorageBackend<SqliteCapability> {
+    /**
+     * Force the lazy schema bootstrap (table + indexes + catalog + any
+     * `extraTableDDL` artifacts). Pass `force: true` to reset the bootstrap
+     * cache first — mirrors the self-heal path in `withSchema` for callers
+     * that issue their own SQL against this graph's table and hit a
+     * "no such table" error after a parent cascade dropped it.
+     *
+     * @internal Used by the `firegraph/sqlite-local` search wrapper.
+     */
+    ensureReady(force?: boolean): Promise<void>;
+    subgraph(parentNodeUid: string, name: string): SqliteStorageBackend;
+}
+/**
+ * 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): SqliteStorageBackend;
+
+export { type SqliteBackendOptions as S, type SqliteCapability as a, type SqliteExecutor as b, createSqliteBackend as c };

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

@@ -1095,9 +1095,14 @@ interface FullTextSearchParams {
  *     Enterprise product feature, not a free-tier feature).
  *   - **Firestore Standard** — not supported. FTS is an Enterprise-only
  *     product feature; this row will never become "✓".
- *   - **SQLite / Cloudflare DO** — not supported. No native FTS index;
- *     emulating it over `json_extract` is not viable for any realistic
- *     dataset.
+ *   - **Local SQLite (`firegraph/sqlite-local`)** ✓ — backed by one FTS5
+ *     table per graph table, kept in sync by pure-SQL triggers and ranked
+ *     by `bm25()`. The whole `data` payload is indexed as one combined
+ *     text column, so a non-empty `fields` list is rejected with
+ *     `INVALID_QUERY`.
+ *   - **Shared SQLite (D1) / Cloudflare DO** — not supported. No FTS5
+ *     trigger infrastructure on those runtimes; emulating FTS over
+ *     `json_extract` is not viable for any realistic dataset.
  *
  * Migrations are NOT applied to the result. The search index walked
  * the raw stored shape; rehydrating each row through the migration
@@ -1311,12 +1316,15 @@ interface FindNearestParams {
  * Native vector / nearest-neighbour search.
  *
  * Backends declaring `search.vector` translate the call into a single
- * server-side `findNearest` query. The SQLite-shaped backends (shared
- * SQLite, Cloudflare DO) do not declare this capability — they have no
- * native vector index, and emulating ANN on top of `json_extract` is a
- * non-starter for any realistic dataset. Firestore Standard and
- * Enterprise both implement it via the classic `Query.findNearest(...)`
- * API; the pipeline `findNearest` stage is a future optimisation.
+ * server-side `findNearest` query. Firestore Standard and Enterprise
+ * both implement it via the classic `Query.findNearest(...)` API; the
+ * pipeline `findNearest` stage is a future optimisation. The local
+ * better-sqlite3 backend (`firegraph/sqlite-local`) implements it as a
+ * brute-force scan scored by a deterministic SQL UDF — exact rather
+ * than approximate, fine for local files at local-file scale. The D1
+ * and Cloudflare DO editions do not declare the capability: those
+ * runtimes expose no UDF registration surface, and emulating ANN on top
+ * of `json_extract` alone is a non-starter for any realistic dataset.
  *
  * Migrations are NOT applied to the result. The vector query selects
  * documents by similarity, not by query plan — applying migrations
@@ -1827,11 +1835,14 @@ interface StorageBackend<C extends Capability = Capability> {
     findEdgesProjected?(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<Array<Record<string, unknown>>>;
     /**
      * Run a vector / nearest-neighbour query. Present only on backends that
-     * declare `search.vector`. There is no client-side fallback — the
-     * SQLite-shaped backends (shared SQLite, Cloudflare DO) genuinely have
-     * no native ANN index, and a JS-side k-NN sweep over `findEdges()` would
-     * scale catastrophically. Backends without the cap throw
-     * `UNSUPPORTED_OPERATION` from the client wrapper.
+     * declare `search.vector`. There is no client-side fallback — backends
+     * without the cap throw `UNSUPPORTED_OPERATION` from the client wrapper.
+     * In-tree: both Firestore editions (native ANN via `Query.findNearest`)
+     * and the local better-sqlite3 backend (`firegraph/sqlite-local`, a
+     * brute-force UDF-scored scan — exact, not approximate). The D1 and
+     * Cloudflare DO editions stay without the cap: no UDF registration
+     * surface, and a JS-side k-NN sweep over `findEdges()` would scale
+     * catastrophically.
      *
      * `params` carries the user-facing shape (vector field path, query
      * vector, distance metric, optional threshold and result-field). The
@@ -1859,11 +1870,14 @@ interface StorageBackend<C extends Capability = Capability> {
     findNearest?(params: FindNearestParams): Promise<StoredGraphRecord[]>;
     /**
      * Run a full-text search query. Present only on backends that declare
-     * `search.fullText`. There is no client-side fallback — the only
-     * in-tree backend that supports it is Firestore Enterprise (via
-     * Pipeline `search({ query: documentMatches(...) })`); Standard and
-     * the SQLite-shaped backends throw `UNSUPPORTED_OPERATION` from the
-     * client wrapper.
+     * `search.fullText`. There is no client-side fallback — backends
+     * without the cap throw `UNSUPPORTED_OPERATION` from the client
+     * wrapper. In-tree: Firestore Enterprise (via Pipeline
+     * `search({ query: documentMatches(...) })`) and the local
+     * better-sqlite3 backend (`firegraph/sqlite-local`, via a
+     * trigger-synced FTS5 index ranked by `bm25()`). Firestore Standard
+     * never gets it (Enterprise-only product feature); D1 and the
+     * Cloudflare DO edition don't ship FTS5 trigger infrastructure.
      *
      * The backend is responsible for path normalisation (rewriting
      * bare `fields` entries to `data.<name>`, rejecting envelope fields
@@ -1894,4 +1908,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-DNzv8KSR.d.ts}

@@ -1095,9 +1095,14 @@ interface FullTextSearchParams {
  *     Enterprise product feature, not a free-tier feature).
  *   - **Firestore Standard** — not supported. FTS is an Enterprise-only
  *     product feature; this row will never become "✓".
- *   - **SQLite / Cloudflare DO** — not supported. No native FTS index;
- *     emulating it over `json_extract` is not viable for any realistic
- *     dataset.
+ *   - **Local SQLite (`firegraph/sqlite-local`)** ✓ — backed by one FTS5
+ *     table per graph table, kept in sync by pure-SQL triggers and ranked
+ *     by `bm25()`. The whole `data` payload is indexed as one combined
+ *     text column, so a non-empty `fields` list is rejected with
+ *     `INVALID_QUERY`.
+ *   - **Shared SQLite (D1) / Cloudflare DO** — not supported. No FTS5
+ *     trigger infrastructure on those runtimes; emulating FTS over
+ *     `json_extract` is not viable for any realistic dataset.
  *
  * Migrations are NOT applied to the result. The search index walked
  * the raw stored shape; rehydrating each row through the migration
@@ -1311,12 +1316,15 @@ interface FindNearestParams {
  * Native vector / nearest-neighbour search.
  *
  * Backends declaring `search.vector` translate the call into a single
- * server-side `findNearest` query. The SQLite-shaped backends (shared
- * SQLite, Cloudflare DO) do not declare this capability — they have no
- * native vector index, and emulating ANN on top of `json_extract` is a
- * non-starter for any realistic dataset. Firestore Standard and
- * Enterprise both implement it via the classic `Query.findNearest(...)`
- * API; the pipeline `findNearest` stage is a future optimisation.
+ * server-side `findNearest` query. Firestore Standard and Enterprise
+ * both implement it via the classic `Query.findNearest(...)` API; the
+ * pipeline `findNearest` stage is a future optimisation. The local
+ * better-sqlite3 backend (`firegraph/sqlite-local`) implements it as a
+ * brute-force scan scored by a deterministic SQL UDF — exact rather
+ * than approximate, fine for local files at local-file scale. The D1
+ * and Cloudflare DO editions do not declare the capability: those
+ * runtimes expose no UDF registration surface, and emulating ANN on top
+ * of `json_extract` alone is a non-starter for any realistic dataset.
  *
  * Migrations are NOT applied to the result. The vector query selects
  * documents by similarity, not by query plan — applying migrations
@@ -1827,11 +1835,14 @@ interface StorageBackend<C extends Capability = Capability> {
     findEdgesProjected?(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<Array<Record<string, unknown>>>;
     /**
      * Run a vector / nearest-neighbour query. Present only on backends that
-     * declare `search.vector`. There is no client-side fallback — the
-     * SQLite-shaped backends (shared SQLite, Cloudflare DO) genuinely have
-     * no native ANN index, and a JS-side k-NN sweep over `findEdges()` would
-     * scale catastrophically. Backends without the cap throw
-     * `UNSUPPORTED_OPERATION` from the client wrapper.
+     * declare `search.vector`. There is no client-side fallback — backends
+     * without the cap throw `UNSUPPORTED_OPERATION` from the client wrapper.
+     * In-tree: both Firestore editions (native ANN via `Query.findNearest`)
+     * and the local better-sqlite3 backend (`firegraph/sqlite-local`, a
+     * brute-force UDF-scored scan — exact, not approximate). The D1 and
+     * Cloudflare DO editions stay without the cap: no UDF registration
+     * surface, and a JS-side k-NN sweep over `findEdges()` would scale
+     * catastrophically.
      *
      * `params` carries the user-facing shape (vector field path, query
      * vector, distance metric, optional threshold and result-field). The
@@ -1859,11 +1870,14 @@ interface StorageBackend<C extends Capability = Capability> {
     findNearest?(params: FindNearestParams): Promise<StoredGraphRecord[]>;
     /**
      * Run a full-text search query. Present only on backends that declare
-     * `search.fullText`. There is no client-side fallback — the only
-     * in-tree backend that supports it is Firestore Enterprise (via
-     * Pipeline `search({ query: documentMatches(...) })`); Standard and
-     * the SQLite-shaped backends throw `UNSUPPORTED_OPERATION` from the
-     * client wrapper.
+     * `search.fullText`. There is no client-side fallback — backends
+     * without the cap throw `UNSUPPORTED_OPERATION` from the client
+     * wrapper. In-tree: Firestore Enterprise (via Pipeline
+     * `search({ query: documentMatches(...) })`) and the local
+     * better-sqlite3 backend (`firegraph/sqlite-local`, via a
+     * trigger-synced FTS5 index ranked by `bm25()`). Firestore Standard
+     * never gets it (Enterprise-only product feature); D1 and the
+     * Cloudflare DO edition don't ship FTS5 trigger infrastructure.
      *
      * The backend is responsible for path normalisation (rewriting
      * bare `fields` entries to `data.<name>`, rejecting envelope fields
@@ -1894,4 +1908,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 };