@typicalday/firegraph 0.15.0 → 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',
@@ -1172,6 +1172,28 @@ 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-CvImIwTY.d.cts → backend-CE3pM9-T.d.ts}

@@ -1,4 +1,4 @@
-import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-BpYLdwCW.cjs';
+import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-DNzv8KSR.js';
 
 /**
  * Driver-level SQLite abstraction.
@@ -101,6 +101,36 @@ interface SqliteBackendOptions {
      * 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`.
@@ -132,6 +162,6 @@ type SqliteCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core
  * 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>;
+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-BpYLdwCW.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

package/dist/{backend-BpYLdwCW.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

package/dist/{backend-YH5HtawN.d.ts → backend-EjFfw9yO.d.cts}

@@ -1,4 +1,4 @@
-import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-BpYLdwCW.js';
+import { p as GraphRegistry, I as IndexSpec, S as StorageBackend } from './backend-DNzv8KSR.cjs';
 
 /**
  * Driver-level SQLite abstraction.
@@ -101,6 +101,36 @@ interface SqliteBackendOptions {
      * 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`.
@@ -132,6 +162,6 @@ type SqliteCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core
  * 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>;
+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 };