@typicalday/firegraph 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,8 +1,9 @@
-import { S as StorageBackend, F as FiregraphError } from './scope-path-D2mNENJ-.cjs';
-export { C as CrossBackendTransactionError, D as DynamicRegistryError, E as EdgeNotFoundError, I as InvalidQueryError, M as MigrationError, N as NodeNotFoundError, Q as QuerySafetyError, R as RegistryScopeError, c as RegistryViolationError, a as StorageScopeSegment, d as TraversalError, V as ValidationError, b as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-D2mNENJ-.cjs';
-import { G as GraphClientOptions, b as GraphClient, a as DynamicGraphClient, c as DiscoveryResult, R as RegistryEntry, d as GraphRegistry, e as GraphReader, M as MigrationExecutor, D as DynamicRegistryConfig, S as StoredGraphRecord, f as MigrationWriteBack, g as MigrationStep, F as FindEdgesParams, Q as QueryPlan, h as FindNodesParams, i as QueryFilter, j as GraphRecord, k as MigrationFn, l as StoredMigrationStep, T as TraversalBuilder } from './types-DfWVTsMn.cjs';
-export { B as BulkBatchError, m as BulkOptions, n as BulkProgress, o as BulkResult, C as CascadeResult, p as DefineTypeOptions, q as DiscoveredEntity, E as EdgeTopology, r as EdgeTypeData, s as FiregraphConfig, t as GraphBatch, u as GraphTransaction, v as GraphWriter, H as HopDefinition, w as HopResult, N as NodeTypeData, x as QueryMode, y as QueryOptions, z as ScanProtection, A as TraversalOptions, I as TraversalResult, V as ViewContext, J as ViewDefaultsConfig, K as ViewResolverConfig, W as WhereClause, L as defineConfig, O as resolveView } from './types-DfWVTsMn.cjs';
+import { S as StorageBackend } from './backend-np4gEVhB.cjs';
+import { G as GraphClientOptions, a as GraphClient, D as DynamicGraphClient, I as IndexSpec, b as DiscoveryResult, R as RegistryEntry, c as GraphRegistry, d as GraphReader, M as MigrationExecutor, e as DynamicRegistryConfig, S as StoredGraphRecord, f as MigrationWriteBack, g as MigrationStep, F as FindEdgesParams, Q as QueryPlan, h as FindNodesParams, i as QueryFilter, j as GraphRecord, k as MigrationFn, l as StoredMigrationStep, T as TraversalBuilder } from './types-BGWxcpI_.cjs';
+export { B as BulkBatchError, m as BulkOptions, n as BulkProgress, o as BulkResult, C as CascadeResult, p as DefineTypeOptions, q as DiscoveredEntity, E as EdgeTopology, r as EdgeTypeData, s as FiregraphConfig, t as GraphBatch, u as GraphTransaction, v as GraphWriter, H as HopDefinition, w as HopResult, x as IndexFieldSpec, N as NodeTypeData, y as QueryMode, z as QueryOptions, A as ScanProtection, J as TraversalOptions, K as TraversalResult, V as ViewContext, L as ViewDefaultsConfig, O as ViewResolverConfig, W as WhereClause, P as defineConfig, U as resolveView } from './types-BGWxcpI_.cjs';
 export { CodegenOptions, generateTypes } from './codegen/index.cjs';
+import { F as FiregraphError } from './scope-path-B1G3YiA7.cjs';
+export { C as CrossBackendTransactionError, D as DynamicRegistryError, E as EdgeNotFoundError, I as InvalidQueryError, M as MigrationError, N as NodeNotFoundError, Q as QuerySafetyError, R as RegistryScopeError, b as RegistryViolationError, S as StorageScopeSegment, T as TraversalError, V as ValidationError, a as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-B1G3YiA7.cjs';
 import { Firestore } from '@google-cloud/firestore';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.cjs';
 export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.cjs';
@@ -10,9 +11,10 @@ export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b
 /**
  * Create a `GraphClient` backed by an arbitrary `StorageBackend`.
  *
- * Used by backend-specific factories (D1, DO-SQLite, etc.) — most callers
- * should use the higher-level `createGraphClient(firestore, ...)` overload
- * below or import the equivalent from `firegraph/d1` / `firegraph/do-sqlite`.
+ * Used by backend-specific factories (e.g. `createDOClient` in
+ * `firegraph/cloudflare`) — most callers should use the higher-level
+ * `createGraphClient(firestore, ...)` overload below for Firestore, or the
+ * Cloudflare factory for DO-backed graphs.
  */
 declare function createGraphClientFromBackend(backend: StorageBackend, options?: GraphClientOptions, metaBackend?: StorageBackend): GraphClient | DynamicGraphClient;
 
@@ -62,6 +64,54 @@ declare function resolveAncestorCollection(collectionPath: string, uid: string):
  */
 declare function isAncestorUid(collectionPath: string, uid: string): boolean;
 
+/**
+ * Default core index preset.
+ *
+ * This set covers the query patterns firegraph's query planner emits for
+ * built-in operations — `findNodes`, `findEdges`, cascade delete, traversal,
+ * and the DO/SQLite path compilers. Apps that need additional indexes
+ * (descending timestamps, `data.*` filters, composite fields unique to
+ * their query shapes) declare them on `RegistryEntry.indexes` or override
+ * this preset wholesale via the backend-specific `coreIndexes` option —
+ * `FiregraphDOOptions.coreIndexes` for the DO backend,
+ * `BuildSchemaOptions.coreIndexes` for the legacy SQLite backend, and
+ * `GenerateIndexOptions.coreIndexes` for the Firestore CLI generator.
+ *
+ * ## Ownership model
+ *
+ * This list is firegraph's *recommendation* — not non-negotiable policy.
+ * Consumers can:
+ *
+ *   1. Accept the preset as-is (default).
+ *   2. Extend it: `coreIndexes: [...DEFAULT_CORE_INDEXES, ...more]`.
+ *   3. Replace it entirely with a tailored set.
+ *   4. Disable it (`coreIndexes: []`) and take full responsibility for
+ *      index coverage — only do this if you're provisioning a complete
+ *      custom set.
+ *
+ * ## Per-backend emission
+ *
+ * The Firestore generator skips single-field entries (Firestore implicitly
+ * indexes every field) and emits one composite index per multi-field spec.
+ * The SQLite-flavored generators (DO, legacy) emit every spec as-is.
+ *
+ * ## Why these specific indexes
+ *
+ * - `aUid` / `bUid` — required for `_fgRemoveNodeCascade`, which scans by
+ *   each UID side independently. A composite `(aUid, axbType)` also
+ *   satisfies `aUid`-alone via leading-column prefix, but the single-field
+ *   form is cheaper for the common case.
+ * - `aType` / `bType` — `findNodes({ aType })` and cross-type enumeration.
+ * - `(aUid, axbType)` — forward edge lookup (`findEdges({ aUid, axbType })`)
+ *   and the `get` strategy fallback when only two of three triple fields
+ *   are present.
+ * - `(axbType, bUid)` — reverse edge traversal.
+ * - `(aType, axbType)` — type-scoped edge scans (e.g., `findEdges({ aType, axbType })`).
+ * - `(axbType, bType)` — scope edges of one relation to a target type.
+ */
+
+declare const DEFAULT_CORE_INDEXES: ReadonlyArray<IndexSpec>;
+
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
  * a per-entity folder structure.
@@ -153,8 +203,10 @@ declare function createRegistryFromGraph(reader: GraphReader, executor?: Migrati
  * Firestore-specific client factory.
  *
  * Kept in its own module so that bundlers don't pull
- * `@google-cloud/firestore` into SQLite-only entry points
- * (`firegraph/d1`, `firegraph/do-sqlite`).
+ * `@google-cloud/firestore` into non-Firestore entry points — most
+ * importantly the Cloudflare DO backend (`firegraph/cloudflare`) and the
+ * routing primitive (`firegraph/backend`), both of which must load cleanly
+ * in a Workers environment where the Node Firestore SDK is unavailable.
  */
 
 declare function createGraphClient(db: Firestore, collectionPath: string, options: GraphClientOptions & {
@@ -164,6 +216,33 @@ declare function createGraphClient(db: Firestore, collectionPath: string, option
 
 declare function generateId(): string;
 
+/**
+ * Firestore composite index generator.
+ *
+ * Translates firegraph's declarative `IndexSpec[]` (core preset plus per-entry
+ * registry indexes) into the `firestore.indexes.json` shape consumed by
+ * `firebase deploy --only firestore:indexes`.
+ *
+ * ## What Firestore needs
+ *
+ * Firestore auto-indexes every top-level field (including `data.*`) for
+ * single-field equality queries — we only need to emit *composite* indexes
+ * here. That means:
+ *
+ *   1. Single-field specs are dropped (Firestore already covers them).
+ *   2. Composite specs (two or more fields) get one `FirestoreIndex`.
+ *   3. Specs with `where` are dropped with a warning — Firestore composite
+ *      indexes do not support partial predicates.
+ *   4. When a registry entry has `targetGraph` set, every composite is also
+ *      emitted with `queryScope: 'COLLECTION_GROUP'` under the targetGraph
+ *      name, so `findEdgesGlobal()` queries across subgraphs can hit an
+ *      index.
+ *
+ * The SQLite-flavored backends (DO, legacy) consume the same `IndexSpec[]`
+ * via `src/internal/sqlite-index-ddl.ts` but emit every spec (single fields
+ * included) as `CREATE INDEX` DDL.
+ */
+
 interface FirestoreIndexField {
     fieldPath: string;
     order: 'ASCENDING' | 'DESCENDING';
@@ -177,25 +256,35 @@ interface FirestoreIndexConfig {
     indexes: FirestoreIndex[];
     fieldOverrides: unknown[];
 }
+interface GenerateIndexOptions {
+    /**
+     * Replaces firegraph's built-in core preset. Defaults to
+     * `DEFAULT_CORE_INDEXES`. Pass `[]` to disable core indexes entirely.
+     */
+    coreIndexes?: IndexSpec[];
+    /**
+     * Registry entries supplying per-triple `indexes`. Entries without
+     * `indexes` contribute no composites; entries with `targetGraph` also
+     * trigger `COLLECTION_GROUP` mirrors under each distinct targetGraph
+     * segment name.
+     */
+    registryEntries?: ReadonlyArray<RegistryEntry>;
+    /**
+     * Entity discovery result. Convenience for callers that have a
+     * `DiscoveryResult` but not a built registry — treated as if every
+     * discovered entity were expanded to its registry entries carrying just
+     * `indexes` + `targetGraph`. Mutually usable with `registryEntries`
+     * (both are concatenated and deduplicated at the spec level).
+     */
+    entities?: DiscoveryResult;
+}
 /**
- * Generates a Firestore index configuration for a firegraph collection.
- *
- * Always includes the 4 base composite indexes. If an entity discovery result
- * is provided, generates additional data-field indexes for common query
- * patterns on node data fields:
- *   (aType, axbType, data.{field})
- *
- * When registry entries with `targetGraph` are provided, also generates
- * collection group indexes for `findEdgesGlobal()` queries. The collection
- * group name defaults to `'graph'` (the standard subgraph name) but can be
- * overridden per `targetGraph` value.
- *
- * @param collection - Firestore collection name (e.g. 'graph')
- * @param entities - Optional discovery result for per-entity data field indexes
- * @param registryEntries - Optional registry entries; when any have `targetGraph`,
- *   collection group indexes are generated for the distinct subgraph names
+ * Build a Firestore index configuration from firegraph's declarative index
+ * specs. Deduplicates by field list + scope before emitting. Single-field
+ * specs are dropped; partial-index specs (`where` set) are dropped with a
+ * one-time warning.
  */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
+declare function generateIndexConfig(collection: string, options?: GenerateIndexOptions): FirestoreIndexConfig;
 
 /**
  * Default result limit applied to findEdges/findNodes queries
@@ -491,4 +580,4 @@ declare function deserializeFirestoreTypes(data: Record<string, unknown>, db?: F
  */
 declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, EDGE_TYPE_SCHEMA, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, META_EDGE_TYPE, META_NODE_TYPE, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, QueryFilter, QueryPlan, type QuerySafetyResult, RegistryEntry, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, analyzeQuerySafety, applyMigrationChain, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileMigrationFn, compileMigrations, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createGraphClientFromBackend, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, defaultExecutor, deserializeFirestoreTypes, destroySandboxWorker, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, isTaggedValue, jsonSchemaToFieldMeta, matchScope, matchScopeAny, migrateRecord, migrateRecords, precompileSource, resolveAncestorCollection, serializeFirestoreTypes, validateMigrationChain };
+export { BOOTSTRAP_ENTRIES, DEFAULT_CORE_INDEXES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, EDGE_TYPE_SCHEMA, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, type GenerateIndexOptions, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, IndexSpec, META_EDGE_TYPE, META_NODE_TYPE, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, QueryFilter, QueryPlan, type QuerySafetyResult, RegistryEntry, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, analyzeQuerySafety, applyMigrationChain, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileMigrationFn, compileMigrations, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createGraphClientFromBackend, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, defaultExecutor, deserializeFirestoreTypes, destroySandboxWorker, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, isTaggedValue, jsonSchemaToFieldMeta, matchScope, matchScopeAny, migrateRecord, migrateRecords, precompileSource, resolveAncestorCollection, serializeFirestoreTypes, validateMigrationChain };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { S as StorageBackend, F as FiregraphError } from './scope-path-BtajqNK5.js';
-export { C as CrossBackendTransactionError, D as DynamicRegistryError, E as EdgeNotFoundError, I as InvalidQueryError, M as MigrationError, N as NodeNotFoundError, Q as QuerySafetyError, R as RegistryScopeError, c as RegistryViolationError, a as StorageScopeSegment, d as TraversalError, V as ValidationError, b as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-BtajqNK5.js';
-import { G as GraphClientOptions, b as GraphClient, a as DynamicGraphClient, c as DiscoveryResult, R as RegistryEntry, d as GraphRegistry, e as GraphReader, M as MigrationExecutor, D as DynamicRegistryConfig, S as StoredGraphRecord, f as MigrationWriteBack, g as MigrationStep, F as FindEdgesParams, Q as QueryPlan, h as FindNodesParams, i as QueryFilter, j as GraphRecord, k as MigrationFn, l as StoredMigrationStep, T as TraversalBuilder } from './types-DfWVTsMn.js';
-export { B as BulkBatchError, m as BulkOptions, n as BulkProgress, o as BulkResult, C as CascadeResult, p as DefineTypeOptions, q as DiscoveredEntity, E as EdgeTopology, r as EdgeTypeData, s as FiregraphConfig, t as GraphBatch, u as GraphTransaction, v as GraphWriter, H as HopDefinition, w as HopResult, N as NodeTypeData, x as QueryMode, y as QueryOptions, z as ScanProtection, A as TraversalOptions, I as TraversalResult, V as ViewContext, J as ViewDefaultsConfig, K as ViewResolverConfig, W as WhereClause, L as defineConfig, O as resolveView } from './types-DfWVTsMn.js';
+import { S as StorageBackend } from './backend-U-MLShlg.js';
+import { G as GraphClientOptions, a as GraphClient, D as DynamicGraphClient, I as IndexSpec, b as DiscoveryResult, R as RegistryEntry, c as GraphRegistry, d as GraphReader, M as MigrationExecutor, e as DynamicRegistryConfig, S as StoredGraphRecord, f as MigrationWriteBack, g as MigrationStep, F as FindEdgesParams, Q as QueryPlan, h as FindNodesParams, i as QueryFilter, j as GraphRecord, k as MigrationFn, l as StoredMigrationStep, T as TraversalBuilder } from './types-BGWxcpI_.js';
+export { B as BulkBatchError, m as BulkOptions, n as BulkProgress, o as BulkResult, C as CascadeResult, p as DefineTypeOptions, q as DiscoveredEntity, E as EdgeTopology, r as EdgeTypeData, s as FiregraphConfig, t as GraphBatch, u as GraphTransaction, v as GraphWriter, H as HopDefinition, w as HopResult, x as IndexFieldSpec, N as NodeTypeData, y as QueryMode, z as QueryOptions, A as ScanProtection, J as TraversalOptions, K as TraversalResult, V as ViewContext, L as ViewDefaultsConfig, O as ViewResolverConfig, W as WhereClause, P as defineConfig, U as resolveView } from './types-BGWxcpI_.js';
 export { CodegenOptions, generateTypes } from './codegen/index.js';
+import { F as FiregraphError } from './scope-path-B1G3YiA7.js';
+export { C as CrossBackendTransactionError, D as DynamicRegistryError, E as EdgeNotFoundError, I as InvalidQueryError, M as MigrationError, N as NodeNotFoundError, Q as QuerySafetyError, R as RegistryScopeError, b as RegistryViolationError, S as StorageScopeSegment, T as TraversalError, V as ValidationError, a as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-B1G3YiA7.js';
 import { Firestore } from '@google-cloud/firestore';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.js';
 export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.js';
@@ -10,9 +11,10 @@ export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b
 /**
  * Create a `GraphClient` backed by an arbitrary `StorageBackend`.
  *
- * Used by backend-specific factories (D1, DO-SQLite, etc.) — most callers
- * should use the higher-level `createGraphClient(firestore, ...)` overload
- * below or import the equivalent from `firegraph/d1` / `firegraph/do-sqlite`.
+ * Used by backend-specific factories (e.g. `createDOClient` in
+ * `firegraph/cloudflare`) — most callers should use the higher-level
+ * `createGraphClient(firestore, ...)` overload below for Firestore, or the
+ * Cloudflare factory for DO-backed graphs.
  */
 declare function createGraphClientFromBackend(backend: StorageBackend, options?: GraphClientOptions, metaBackend?: StorageBackend): GraphClient | DynamicGraphClient;
 
@@ -62,6 +64,54 @@ declare function resolveAncestorCollection(collectionPath: string, uid: string):
  */
 declare function isAncestorUid(collectionPath: string, uid: string): boolean;
 
+/**
+ * Default core index preset.
+ *
+ * This set covers the query patterns firegraph's query planner emits for
+ * built-in operations — `findNodes`, `findEdges`, cascade delete, traversal,
+ * and the DO/SQLite path compilers. Apps that need additional indexes
+ * (descending timestamps, `data.*` filters, composite fields unique to
+ * their query shapes) declare them on `RegistryEntry.indexes` or override
+ * this preset wholesale via the backend-specific `coreIndexes` option —
+ * `FiregraphDOOptions.coreIndexes` for the DO backend,
+ * `BuildSchemaOptions.coreIndexes` for the legacy SQLite backend, and
+ * `GenerateIndexOptions.coreIndexes` for the Firestore CLI generator.
+ *
+ * ## Ownership model
+ *
+ * This list is firegraph's *recommendation* — not non-negotiable policy.
+ * Consumers can:
+ *
+ *   1. Accept the preset as-is (default).
+ *   2. Extend it: `coreIndexes: [...DEFAULT_CORE_INDEXES, ...more]`.
+ *   3. Replace it entirely with a tailored set.
+ *   4. Disable it (`coreIndexes: []`) and take full responsibility for
+ *      index coverage — only do this if you're provisioning a complete
+ *      custom set.
+ *
+ * ## Per-backend emission
+ *
+ * The Firestore generator skips single-field entries (Firestore implicitly
+ * indexes every field) and emits one composite index per multi-field spec.
+ * The SQLite-flavored generators (DO, legacy) emit every spec as-is.
+ *
+ * ## Why these specific indexes
+ *
+ * - `aUid` / `bUid` — required for `_fgRemoveNodeCascade`, which scans by
+ *   each UID side independently. A composite `(aUid, axbType)` also
+ *   satisfies `aUid`-alone via leading-column prefix, but the single-field
+ *   form is cheaper for the common case.
+ * - `aType` / `bType` — `findNodes({ aType })` and cross-type enumeration.
+ * - `(aUid, axbType)` — forward edge lookup (`findEdges({ aUid, axbType })`)
+ *   and the `get` strategy fallback when only two of three triple fields
+ *   are present.
+ * - `(axbType, bUid)` — reverse edge traversal.
+ * - `(aType, axbType)` — type-scoped edge scans (e.g., `findEdges({ aType, axbType })`).
+ * - `(axbType, bType)` — scope edges of one relation to a target type.
+ */
+
+declare const DEFAULT_CORE_INDEXES: ReadonlyArray<IndexSpec>;
+
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
  * a per-entity folder structure.
@@ -153,8 +203,10 @@ declare function createRegistryFromGraph(reader: GraphReader, executor?: Migrati
  * Firestore-specific client factory.
  *
  * Kept in its own module so that bundlers don't pull
- * `@google-cloud/firestore` into SQLite-only entry points
- * (`firegraph/d1`, `firegraph/do-sqlite`).
+ * `@google-cloud/firestore` into non-Firestore entry points — most
+ * importantly the Cloudflare DO backend (`firegraph/cloudflare`) and the
+ * routing primitive (`firegraph/backend`), both of which must load cleanly
+ * in a Workers environment where the Node Firestore SDK is unavailable.
  */
 
 declare function createGraphClient(db: Firestore, collectionPath: string, options: GraphClientOptions & {
@@ -164,6 +216,33 @@ declare function createGraphClient(db: Firestore, collectionPath: string, option
 
 declare function generateId(): string;
 
+/**
+ * Firestore composite index generator.
+ *
+ * Translates firegraph's declarative `IndexSpec[]` (core preset plus per-entry
+ * registry indexes) into the `firestore.indexes.json` shape consumed by
+ * `firebase deploy --only firestore:indexes`.
+ *
+ * ## What Firestore needs
+ *
+ * Firestore auto-indexes every top-level field (including `data.*`) for
+ * single-field equality queries — we only need to emit *composite* indexes
+ * here. That means:
+ *
+ *   1. Single-field specs are dropped (Firestore already covers them).
+ *   2. Composite specs (two or more fields) get one `FirestoreIndex`.
+ *   3. Specs with `where` are dropped with a warning — Firestore composite
+ *      indexes do not support partial predicates.
+ *   4. When a registry entry has `targetGraph` set, every composite is also
+ *      emitted with `queryScope: 'COLLECTION_GROUP'` under the targetGraph
+ *      name, so `findEdgesGlobal()` queries across subgraphs can hit an
+ *      index.
+ *
+ * The SQLite-flavored backends (DO, legacy) consume the same `IndexSpec[]`
+ * via `src/internal/sqlite-index-ddl.ts` but emit every spec (single fields
+ * included) as `CREATE INDEX` DDL.
+ */
+
 interface FirestoreIndexField {
     fieldPath: string;
     order: 'ASCENDING' | 'DESCENDING';
@@ -177,25 +256,35 @@ interface FirestoreIndexConfig {
     indexes: FirestoreIndex[];
     fieldOverrides: unknown[];
 }
+interface GenerateIndexOptions {
+    /**
+     * Replaces firegraph's built-in core preset. Defaults to
+     * `DEFAULT_CORE_INDEXES`. Pass `[]` to disable core indexes entirely.
+     */
+    coreIndexes?: IndexSpec[];
+    /**
+     * Registry entries supplying per-triple `indexes`. Entries without
+     * `indexes` contribute no composites; entries with `targetGraph` also
+     * trigger `COLLECTION_GROUP` mirrors under each distinct targetGraph
+     * segment name.
+     */
+    registryEntries?: ReadonlyArray<RegistryEntry>;
+    /**
+     * Entity discovery result. Convenience for callers that have a
+     * `DiscoveryResult` but not a built registry — treated as if every
+     * discovered entity were expanded to its registry entries carrying just
+     * `indexes` + `targetGraph`. Mutually usable with `registryEntries`
+     * (both are concatenated and deduplicated at the spec level).
+     */
+    entities?: DiscoveryResult;
+}
 /**
- * Generates a Firestore index configuration for a firegraph collection.
- *
- * Always includes the 4 base composite indexes. If an entity discovery result
- * is provided, generates additional data-field indexes for common query
- * patterns on node data fields:
- *   (aType, axbType, data.{field})
- *
- * When registry entries with `targetGraph` are provided, also generates
- * collection group indexes for `findEdgesGlobal()` queries. The collection
- * group name defaults to `'graph'` (the standard subgraph name) but can be
- * overridden per `targetGraph` value.
- *
- * @param collection - Firestore collection name (e.g. 'graph')
- * @param entities - Optional discovery result for per-entity data field indexes
- * @param registryEntries - Optional registry entries; when any have `targetGraph`,
- *   collection group indexes are generated for the distinct subgraph names
+ * Build a Firestore index configuration from firegraph's declarative index
+ * specs. Deduplicates by field list + scope before emitting. Single-field
+ * specs are dropped; partial-index specs (`where` set) are dropped with a
+ * one-time warning.
  */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
+declare function generateIndexConfig(collection: string, options?: GenerateIndexOptions): FirestoreIndexConfig;
 
 /**
  * Default result limit applied to findEdges/findNodes queries
@@ -491,4 +580,4 @@ declare function deserializeFirestoreTypes(data: Record<string, unknown>, db?: F
  */
 declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, EDGE_TYPE_SCHEMA, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, META_EDGE_TYPE, META_NODE_TYPE, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, QueryFilter, QueryPlan, type QuerySafetyResult, RegistryEntry, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, analyzeQuerySafety, applyMigrationChain, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileMigrationFn, compileMigrations, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createGraphClientFromBackend, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, defaultExecutor, deserializeFirestoreTypes, destroySandboxWorker, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, isTaggedValue, jsonSchemaToFieldMeta, matchScope, matchScopeAny, migrateRecord, migrateRecords, precompileSource, resolveAncestorCollection, serializeFirestoreTypes, validateMigrationChain };
+export { BOOTSTRAP_ENTRIES, DEFAULT_CORE_INDEXES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, EDGE_TYPE_SCHEMA, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, type GenerateIndexOptions, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, IndexSpec, META_EDGE_TYPE, META_NODE_TYPE, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, QueryFilter, QueryPlan, type QuerySafetyResult, RegistryEntry, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, analyzeQuerySafety, applyMigrationChain, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileMigrationFn, compileMigrations, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createGraphClientFromBackend, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, defaultExecutor, deserializeFirestoreTypes, destroySandboxWorker, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, isTaggedValue, jsonSchemaToFieldMeta, matchScope, matchScopeAny, migrateRecord, migrateRecords, precompileSource, resolveAncestorCollection, serializeFirestoreTypes, validateMigrationChain };

package/dist/index.js

@@ -1,9 +1,3 @@
-import {
-  SERIALIZATION_TAG,
-  deserializeFirestoreTypes,
-  isTaggedValue,
-  serializeFirestoreTypes
-} from "./chunk-5753Y42M.js";
 import {
   appendStorageScope,
   isAncestorScopeUid,
@@ -12,6 +6,7 @@ import {
 } from "./chunk-TYYPRVIE.js";
 import {
   BOOTSTRAP_ENTRIES,
+  DEFAULT_CORE_INDEXES,
   DEFAULT_QUERY_LIMIT,
   EDGE_TYPE_SCHEMA,
   GraphClientImpl,
@@ -43,7 +38,7 @@ import {
   migrateRecords,
   precompileSource,
   validateMigrationChain
-} from "./chunk-EVUM6ORB.js";
+} from "./chunk-6SB34IPQ.js";
 import {
   CrossBackendTransactionError,
   DynamicRegistryError,
@@ -57,14 +52,20 @@ import {
   RegistryViolationError,
   TraversalError,
   ValidationError
-} from "./chunk-GLOVWKQH.js";
+} from "./chunk-R7CRGYY4.js";
 import {
   generateTypes
-} from "./chunk-YLGXLEUE.js";
+} from "./chunk-GJVVRTQT.js";
 import {
   QueryClient,
   QueryClientError
-} from "./chunk-SU4FNLC3.js";
+} from "./chunk-EEKWRX5E.js";
+import {
+  SERIALIZATION_TAG,
+  deserializeFirestoreTypes,
+  isTaggedValue,
+  serializeFirestoreTypes
+} from "./chunk-5753Y42M.js";
 
 // src/config.ts
 function defineConfig(config) {
@@ -219,7 +220,8 @@ function loadNodeEntity(dir, name) {
     sampleData,
     allowedIn: meta?.allowedIn,
     migrations,
-    migrationWriteBack: meta?.migrationWriteBack
+    migrationWriteBack: meta?.migrationWriteBack,
+    indexes: meta?.indexes
   };
 }
 function loadEdgeEntity(dir, name) {
@@ -256,7 +258,8 @@ function loadEdgeEntity(dir, name) {
     allowedIn: meta?.allowedIn,
     targetGraph: topology.targetGraph ?? meta?.targetGraph,
     migrations,
-    migrationWriteBack: meta?.migrationWriteBack
+    migrationWriteBack: meta?.migrationWriteBack,
+    indexes: meta?.indexes
   };
 }
 function getSubdirectories(dir) {
@@ -783,124 +786,74 @@ function generateId() {
 }
 
 // src/indexes.ts
-function baseIndexes(collection) {
-  return [
-    {
-      collectionGroup: collection,
-      queryScope: "COLLECTION",
-      fields: [
-        { fieldPath: "aUid", order: "ASCENDING" },
-        { fieldPath: "axbType", order: "ASCENDING" }
-      ]
-    },
-    {
-      collectionGroup: collection,
-      queryScope: "COLLECTION",
-      fields: [
-        { fieldPath: "axbType", order: "ASCENDING" },
-        { fieldPath: "bUid", order: "ASCENDING" }
-      ]
-    },
-    {
-      collectionGroup: collection,
-      queryScope: "COLLECTION",
-      fields: [
-        { fieldPath: "aType", order: "ASCENDING" },
-        { fieldPath: "axbType", order: "ASCENDING" }
-      ]
-    },
-    {
-      collectionGroup: collection,
-      queryScope: "COLLECTION",
-      fields: [
-        { fieldPath: "axbType", order: "ASCENDING" },
-        { fieldPath: "bType", order: "ASCENDING" }
-      ]
-    }
-  ];
+function normalizeField(f) {
+  return typeof f === "string" ? { path: f, desc: false } : { path: f.path, desc: !!f.desc };
 }
-function extractSchemaFields(schema) {
-  const s = schema;
-  if (s.type !== "object" || !s.properties) return [];
-  return Object.keys(s.properties);
+function specFingerprint(spec, scope) {
+  const normalized = spec.fields.map(normalizeField);
+  return `${scope}::${JSON.stringify(normalized)}`;
 }
-function collectionGroupIndexes(collectionName) {
-  return [
-    {
-      collectionGroup: collectionName,
-      queryScope: "COLLECTION_GROUP",
-      fields: [
-        { fieldPath: "aUid", order: "ASCENDING" },
-        { fieldPath: "axbType", order: "ASCENDING" }
-      ]
-    },
-    {
-      collectionGroup: collectionName,
-      queryScope: "COLLECTION_GROUP",
-      fields: [
-        { fieldPath: "axbType", order: "ASCENDING" },
-        { fieldPath: "bUid", order: "ASCENDING" }
-      ]
-    },
-    {
-      collectionGroup: collectionName,
-      queryScope: "COLLECTION_GROUP",
-      fields: [
-        { fieldPath: "aType", order: "ASCENDING" },
-        { fieldPath: "axbType", order: "ASCENDING" }
-      ]
-    },
-    {
-      collectionGroup: collectionName,
-      queryScope: "COLLECTION_GROUP",
-      fields: [
-        { fieldPath: "axbType", order: "ASCENDING" },
-        { fieldPath: "bType", order: "ASCENDING" }
-      ]
-    }
-  ];
+function toFirestoreFields(spec) {
+  return spec.fields.map((f) => {
+    const n = normalizeField(f);
+    return {
+      fieldPath: n.path,
+      order: n.desc ? "DESCENDING" : "ASCENDING"
+    };
+  });
 }
-function generateIndexConfig(collection, entities, registryEntries) {
-  const indexes = baseIndexes(collection);
-  if (entities) {
-    for (const [, entity] of entities.nodes) {
-      const fields = extractSchemaFields(entity.schema);
-      for (const field of fields) {
-        indexes.push({
-          collectionGroup: collection,
-          queryScope: "COLLECTION",
-          fields: [
-            { fieldPath: "aType", order: "ASCENDING" },
-            { fieldPath: "axbType", order: "ASCENDING" },
-            { fieldPath: `data.${field}`, order: "ASCENDING" }
-          ]
-        });
-      }
-    }
-    for (const [, entity] of entities.edges) {
-      const fields = extractSchemaFields(entity.schema);
-      for (const field of fields) {
-        indexes.push({
-          collectionGroup: collection,
-          queryScope: "COLLECTION",
-          fields: [
-            { fieldPath: "aUid", order: "ASCENDING" },
-            { fieldPath: "axbType", order: "ASCENDING" },
-            { fieldPath: `data.${field}`, order: "ASCENDING" }
-          ]
-        });
-      }
+var warnedOnPartialIndex = false;
+function generateIndexConfig(collection, options = {}) {
+  const core = options.coreIndexes ?? [...DEFAULT_CORE_INDEXES];
+  const fromEntries = (options.registryEntries ?? []).flatMap((e) => {
+    if (!e.indexes) return [];
+    return e.indexes;
+  });
+  const targetGraphNames = /* @__PURE__ */ new Set();
+  for (const entry of options.registryEntries ?? []) {
+    if (entry.targetGraph) targetGraphNames.add(entry.targetGraph);
+  }
+  if (options.entities) {
+    for (const [, entity] of options.entities.edges) {
+      const tg = entity.targetGraph ?? entity.topology?.targetGraph;
+      if (tg) targetGraphNames.add(tg);
     }
   }
-  if (registryEntries) {
-    const targetGraphNames = /* @__PURE__ */ new Set();
-    for (const entry of registryEntries) {
-      if (entry.targetGraph) {
-        targetGraphNames.add(entry.targetGraph);
+  const allSpecs = [...core, ...fromEntries];
+  const seen = /* @__PURE__ */ new Set();
+  const indexes = [];
+  for (const spec of allSpecs) {
+    if (!spec.fields || spec.fields.length < 2) {
+      continue;
+    }
+    if (spec.where) {
+      if (!warnedOnPartialIndex) {
+        warnedOnPartialIndex = true;
+        console.warn(
+          "firegraph: IndexSpec.where is ignored by the Firestore generator \u2014 Firestore composite indexes do not support predicates. The SQLite backends will still honor `where`."
+        );
       }
+      continue;
+    }
+    const fields = toFirestoreFields(spec);
+    const colKey = specFingerprint(spec, `col:${collection}`);
+    if (!seen.has(colKey)) {
+      seen.add(colKey);
+      indexes.push({
+        collectionGroup: collection,
+        queryScope: "COLLECTION",
+        fields
+      });
     }
-    for (const name of targetGraphNames) {
-      indexes.push(...collectionGroupIndexes(name));
+    for (const tg of targetGraphNames) {
+      const cgKey = specFingerprint(spec, `cg:${tg}`);
+      if (seen.has(cgKey)) continue;
+      seen.add(cgKey);
+      indexes.push({
+        collectionGroup: tg,
+        queryScope: "COLLECTION_GROUP",
+        fields
+      });
     }
   }
   return { indexes, fieldOverrides: [] };
@@ -1226,6 +1179,7 @@ function defineViews(input) {
 export {
   BOOTSTRAP_ENTRIES,
   CrossBackendTransactionError,
+  DEFAULT_CORE_INDEXES,
   DEFAULT_QUERY_LIMIT,
   DiscoveryError,
   DynamicRegistryError,