@typicalday/firegraph 0.1.0 → 0.3.0

package/dist/index.js

@@ -14,6 +14,16 @@ import { createHash } from "crypto";
 
 // src/internal/constants.ts
 var NODE_RELATION = "is";
+var DEFAULT_QUERY_LIMIT = 500;
+var BUILTIN_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt"
+]);
 var SHARD_SEPARATOR = ":";
 
 // src/docid.ts
@@ -110,6 +120,21 @@ var DynamicRegistryError = class extends FiregraphError {
     this.name = "DynamicRegistryError";
   }
 };
+var QuerySafetyError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "QUERY_SAFETY");
+    this.name = "QuerySafetyError";
+  }
+};
+var RegistryScopeError = class extends FiregraphError {
+  constructor(aType, axbType, bType, scopePath, allowedIn) {
+    super(
+      `Type (${aType}) -[${axbType}]-> (${bType}) is not allowed at scope "${scopePath || "root"}". Allowed in: [${allowedIn.join(", ")}]`,
+      "REGISTRY_SCOPE"
+    );
+    this.name = "RegistryScopeError";
+  }
+};
 
 // src/query.ts
 function buildEdgeQueryPlan(params) {
@@ -123,27 +148,32 @@ function buildEdgeQueryPlan(params) {
   if (axbType) filters.push({ field: "axbType", op: "==", value: axbType });
   if (bType) filters.push({ field: "bType", op: "==", value: bType });
   if (bUid) filters.push({ field: "bUid", op: "==", value: bUid });
-  const builtinFields = ["aType", "aUid", "axbType", "bType", "bUid", "createdAt", "updatedAt"];
   if (params.where) {
     for (const clause of params.where) {
-      const field = builtinFields.includes(clause.field) ? clause.field : clause.field.startsWith("data.") ? clause.field : `data.${clause.field}`;
+      const field = BUILTIN_FIELDS.has(clause.field) ? clause.field : clause.field.startsWith("data.") ? clause.field : `data.${clause.field}`;
       filters.push({ field, op: clause.op, value: clause.value });
     }
   }
   if (filters.length === 0) {
     throw new InvalidQueryError("findEdges requires at least one filter parameter");
   }
-  const options = limit !== void 0 || orderBy ? { limit, orderBy } : void 0;
-  return { strategy: "query", filters, options };
+  const effectiveLimit = limit === void 0 ? DEFAULT_QUERY_LIMIT : limit || void 0;
+  return { strategy: "query", filters, options: { limit: effectiveLimit, orderBy } };
 }
 function buildNodeQueryPlan(params) {
-  return {
-    strategy: "query",
-    filters: [
-      { field: "aType", op: "==", value: params.aType },
-      { field: "axbType", op: "==", value: NODE_RELATION }
-    ]
-  };
+  const { aType, limit, orderBy } = params;
+  const filters = [
+    { field: "aType", op: "==", value: aType },
+    { field: "axbType", op: "==", value: NODE_RELATION }
+  ];
+  if (params.where) {
+    for (const clause of params.where) {
+      const field = BUILTIN_FIELDS.has(clause.field) ? clause.field : clause.field.startsWith("data.") ? clause.field : `data.${clause.field}`;
+      filters.push({ field, op: clause.op, value: clause.value });
+    }
+  }
+  const effectiveLimit = limit === void 0 ? DEFAULT_QUERY_LIMIT : limit || void 0;
+  return { strategy: "query", filters, options: { limit: effectiveLimit, orderBy } };
 }
 
 // src/internal/firestore-adapter.ts
@@ -296,10 +326,62 @@ function createPipelineQueryAdapter(db, collectionPath) {
 
 // src/transaction.ts
 import { FieldValue as FieldValue2 } from "@google-cloud/firestore";
+
+// src/query-safety.ts
+var SAFE_INDEX_PATTERNS = [
+  /* @__PURE__ */ new Set(["aUid", "axbType"]),
+  /* @__PURE__ */ new Set(["axbType", "bUid"]),
+  /* @__PURE__ */ new Set(["aType", "axbType"]),
+  /* @__PURE__ */ new Set(["axbType", "bType"])
+];
+function analyzeQuerySafety(filters) {
+  const builtinFieldsPresent = /* @__PURE__ */ new Set();
+  let hasDataFilters = false;
+  for (const f of filters) {
+    if (BUILTIN_FIELDS.has(f.field)) {
+      builtinFieldsPresent.add(f.field);
+    } else {
+      hasDataFilters = true;
+    }
+  }
+  for (const pattern of SAFE_INDEX_PATTERNS) {
+    let matched = true;
+    for (const field of pattern) {
+      if (!builtinFieldsPresent.has(field)) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) {
+      return { safe: true };
+    }
+  }
+  const presentFields = [...builtinFieldsPresent];
+  if (presentFields.length === 0 && hasDataFilters) {
+    return {
+      safe: false,
+      reason: "Query filters only use data.* fields with no builtin field constraints. This requires a full collection scan. Add aType, aUid, axbType, bType, or bUid filters, or set allowCollectionScan: true."
+    };
+  }
+  if (hasDataFilters) {
+    return {
+      safe: false,
+      reason: `Query filters on [${presentFields.join(", ")}] do not match any indexed pattern. data.* filters without an indexed base require a full collection scan. Safe patterns: (aUid + axbType), (axbType + bUid), (aType + axbType), (axbType + bType). Set allowCollectionScan: true to override.`
+    };
+  }
+  return {
+    safe: false,
+    reason: `Query filters on [${presentFields.join(", ")}] do not match any indexed pattern. This may cause a full collection scan on Firestore Enterprise. Safe patterns: (aUid + axbType), (axbType + bUid), (aType + axbType), (axbType + bType). Set allowCollectionScan: true to override.`
+  };
+}
+
+// src/transaction.ts
 var GraphTransactionImpl = class {
-  constructor(adapter, registry) {
+  constructor(adapter, registry, scanProtection = "error", scopePath = "") {
     this.adapter = adapter;
     this.registry = registry;
+    this.scanProtection = scanProtection;
+    this.scopePath = scopePath;
   }
   async getNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -313,12 +395,22 @@ var GraphTransactionImpl = class {
     const record = await this.getEdge(aUid, axbType, bUid);
     return record !== null;
   }
+  checkQuerySafety(filters, allowCollectionScan) {
+    if (allowCollectionScan || this.scanProtection === "off") return;
+    const result = analyzeQuerySafety(filters);
+    if (result.safe) return;
+    if (this.scanProtection === "error") {
+      throw new QuerySafetyError(result.reason);
+    }
+    console.warn(`[firegraph] Query safety warning: ${result.reason}`);
+  }
   async findEdges(params) {
     const plan = buildEdgeQueryPlan(params);
     if (plan.strategy === "get") {
       const record = await this.adapter.getDoc(plan.docId);
       return record ? [record] : [];
     }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
     return this.adapter.query(plan.filters, plan.options);
   }
   async findNodes(params) {
@@ -327,11 +419,12 @@ var GraphTransactionImpl = class {
       const record = await this.adapter.getDoc(plan.docId);
       return record ? [record] : [];
     }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
     return this.adapter.query(plan.filters, plan.options);
   }
   async putNode(aType, uid, data) {
     if (this.registry) {
-      this.registry.validate(aType, NODE_RELATION, aType, data);
+      this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
     const docId = computeNodeDocId(uid);
     const record = buildNodeRecord(aType, uid, data);
@@ -339,7 +432,7 @@ var GraphTransactionImpl = class {
   }
   async putEdge(aType, aUid, axbType, bType, bUid, data) {
     if (this.registry) {
-      this.registry.validate(aType, axbType, bType, data);
+      this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
     const docId = computeEdgeDocId(aUid, axbType, bUid);
     const record = buildEdgeRecord(aType, aUid, axbType, bType, bUid, data);
@@ -365,13 +458,14 @@ var GraphTransactionImpl = class {
 // src/batch.ts
 import { FieldValue as FieldValue3 } from "@google-cloud/firestore";
 var GraphBatchImpl = class {
-  constructor(adapter, registry) {
+  constructor(adapter, registry, scopePath = "") {
     this.adapter = adapter;
     this.registry = registry;
+    this.scopePath = scopePath;
   }
   async putNode(aType, uid, data) {
     if (this.registry) {
-      this.registry.validate(aType, NODE_RELATION, aType, data);
+      this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
     const docId = computeNodeDocId(uid);
     const record = buildNodeRecord(aType, uid, data);
@@ -379,7 +473,7 @@ var GraphBatchImpl = class {
   }
   async putEdge(aType, aUid, axbType, bType, bUid, data) {
     if (this.registry) {
-      this.registry.validate(aType, axbType, bType, data);
+      this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
     const docId = computeEdgeDocId(aUid, axbType, bUid);
     const record = buildEdgeRecord(aType, aUid, axbType, bType, bUid, data);
@@ -471,14 +565,39 @@ async function bulkDeleteDocIds(db, collectionPath, docIds, options) {
   return { deleted, batches: completedBatches, errors };
 }
 async function bulkRemoveEdges(db, collectionPath, reader, params, options) {
-  const edges = await reader.findEdges(params);
+  const effectiveParams = params.limit !== void 0 ? { ...params, allowCollectionScan: params.allowCollectionScan ?? true } : { ...params, limit: 0, allowCollectionScan: params.allowCollectionScan ?? true };
+  const edges = await reader.findEdges(effectiveParams);
   const docIds = edges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
   return bulkDeleteDocIds(db, collectionPath, docIds, options);
 }
+async function deleteSubcollectionsRecursive(db, collectionPath, docId, options) {
+  const docRef = db.collection(collectionPath).doc(docId);
+  const subcollections = await docRef.listCollections();
+  if (subcollections.length === 0) return { deleted: 0, errors: [] };
+  let totalDeleted = 0;
+  const allErrors = [];
+  const subOptions = options ? { batchSize: options.batchSize, maxRetries: options.maxRetries } : void 0;
+  for (const subCollRef of subcollections) {
+    const subCollPath = subCollRef.path;
+    const snapshot = await subCollRef.select().get();
+    const subDocIds = snapshot.docs.map((d) => d.id);
+    for (const subDocId of subDocIds) {
+      const subResult = await deleteSubcollectionsRecursive(db, subCollPath, subDocId, subOptions);
+      totalDeleted += subResult.deleted;
+      allErrors.push(...subResult.errors);
+    }
+    if (subDocIds.length > 0) {
+      const result = await bulkDeleteDocIds(db, subCollPath, subDocIds, subOptions);
+      totalDeleted += result.deleted;
+      allErrors.push(...result.errors);
+    }
+  }
+  return { deleted: totalDeleted, errors: allErrors };
+}
 async function removeNodeCascade(db, collectionPath, reader, uid, options) {
   const [outgoingRaw, incomingRaw] = await Promise.all([
-    reader.findEdges({ aUid: uid }),
-    reader.findEdges({ bUid: uid })
+    reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
+    reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
   ]);
   const outgoing = outgoingRaw.filter((e) => e.axbType !== NODE_RELATION);
   const incoming = incomingRaw.filter((e) => e.axbType !== NODE_RELATION);
@@ -491,8 +610,18 @@ async function removeNodeCascade(db, collectionPath, reader, uid, options) {
       allEdges.push(edge);
     }
   }
-  const edgeDocIds = allEdges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  const shouldDeleteSubcollections = options?.deleteSubcollections !== false;
   const nodeDocId = computeNodeDocId(uid);
+  let subcollectionResult = { deleted: 0, errors: [] };
+  if (shouldDeleteSubcollections) {
+    subcollectionResult = await deleteSubcollectionsRecursive(
+      db,
+      collectionPath,
+      nodeDocId,
+      options
+    );
+  }
+  const edgeDocIds = allEdges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
   const allDocIds = [...edgeDocIds, nodeDocId];
   const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
   const result = await bulkDeleteDocIds(db, collectionPath, allDocIds, {
@@ -502,9 +631,12 @@ async function removeNodeCascade(db, collectionPath, reader, uid, options) {
   const totalChunks = Math.ceil(allDocIds.length / batchSize);
   const nodeChunkIndex = totalChunks - 1;
   const nodeDeleted = !result.errors.some((e) => e.batchIndex === nodeChunkIndex);
+  const topLevelEdgesDeleted = nodeDeleted ? result.deleted - 1 : result.deleted;
   return {
-    ...result,
-    edgesDeleted: nodeDeleted ? result.deleted - 1 : result.deleted,
+    deleted: result.deleted + subcollectionResult.deleted,
+    batches: result.batches,
+    errors: [...result.errors, ...subcollectionResult.errors],
+    edgesDeleted: topLevelEdgesDeleted,
     nodeDeleted
   };
 }
@@ -604,6 +736,39 @@ function propertyToFieldMeta(name, prop, required) {
   return { name, type: "unknown", required, description: prop.description };
 }
 
+// src/scope.ts
+function matchScope(scopePath, pattern) {
+  if (pattern === "root") return scopePath === "";
+  if (pattern === "**") return true;
+  const pathSegments = scopePath === "" ? [] : scopePath.split("/");
+  const patternSegments = pattern.split("/");
+  return matchSegments(pathSegments, 0, patternSegments, 0);
+}
+function matchScopeAny(scopePath, patterns) {
+  if (!patterns || patterns.length === 0) return true;
+  return patterns.some((p) => matchScope(scopePath, p));
+}
+function matchSegments(path, pi, pattern, qi) {
+  if (pi === path.length && qi === pattern.length) return true;
+  if (qi === pattern.length) return false;
+  const seg = pattern[qi];
+  if (seg === "**") {
+    if (qi === pattern.length - 1) return true;
+    for (let skip = 0; skip <= path.length - pi; skip++) {
+      if (matchSegments(path, pi + skip, pattern, qi + 1)) return true;
+    }
+    return false;
+  }
+  if (pi === path.length) return false;
+  if (seg === "*") {
+    return matchSegments(path, pi + 1, pattern, qi + 1);
+  }
+  if (path[pi] === seg) {
+    return matchSegments(path, pi + 1, pattern, qi + 1);
+  }
+  return false;
+}
+
 // src/registry.ts
 function tripleKey(aType, axbType, bType) {
   return `${aType}:${axbType}:${bType}`;
@@ -618,19 +783,45 @@ function createRegistry(input) {
   }
   const entryList = Object.freeze([...entries]);
   for (const entry of entries) {
+    if (entry.targetGraph && entry.targetGraph.includes("/")) {
+      throw new ValidationError(
+        `Entry (${entry.aType}) -[${entry.axbType}]-> (${entry.bType}) has invalid targetGraph "${entry.targetGraph}" \u2014 must be a single segment (no "/")`
+      );
+    }
     const key = tripleKey(entry.aType, entry.axbType, entry.bType);
     const validator = entry.jsonSchema ? compileSchema(entry.jsonSchema, `(${entry.aType}) -[${entry.axbType}]-> (${entry.bType})`) : void 0;
     map.set(key, { entry, validate: validator });
   }
+  const axbIndex = /* @__PURE__ */ new Map();
+  const axbBuild = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = axbBuild.get(entry.axbType);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      axbBuild.set(entry.axbType, [entry]);
+    }
+  }
+  for (const [key, arr] of axbBuild) {
+    axbIndex.set(key, Object.freeze(arr));
+  }
   return {
     lookup(aType, axbType, bType) {
       return map.get(tripleKey(aType, axbType, bType))?.entry;
     },
-    validate(aType, axbType, bType, data) {
+    lookupByAxbType(axbType) {
+      return axbIndex.get(axbType) ?? [];
+    },
+    validate(aType, axbType, bType, data, scopePath) {
       const rec = map.get(tripleKey(aType, axbType, bType));
       if (!rec) {
         throw new RegistryViolationError(aType, axbType, bType);
       }
+      if (scopePath !== void 0 && rec.entry.allowedIn && rec.entry.allowedIn.length > 0) {
+        if (!matchScopeAny(scopePath, rec.entry.allowedIn)) {
+          throw new RegistryScopeError(aType, axbType, bType, scopePath, rec.entry.allowedIn);
+        }
+      }
       if (rec.validate) {
         try {
           rec.validate(data);
@@ -658,7 +849,8 @@ function discoveryToEntries(discovery) {
       jsonSchema: entity.schema,
       description: entity.description,
       titleField: entity.titleField,
-      subtitleField: entity.subtitleField
+      subtitleField: entity.subtitleField,
+      allowedIn: entity.allowedIn
     });
   }
   for (const [axbType, entity] of discovery.edges) {
@@ -666,6 +858,12 @@ function discoveryToEntries(discovery) {
     if (!topology) continue;
     const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
     const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+    const resolvedTargetGraph = entity.targetGraph ?? topology.targetGraph;
+    if (resolvedTargetGraph && resolvedTargetGraph.includes("/")) {
+      throw new ValidationError(
+        `Edge "${axbType}" has invalid targetGraph "${resolvedTargetGraph}" \u2014 must be a single segment (no "/")`
+      );
+    }
     for (const aType of fromTypes) {
       for (const bType of toTypes) {
         entries.push({
@@ -676,7 +874,9 @@ function discoveryToEntries(discovery) {
           description: entity.description,
           inverseLabel: topology.inverseLabel,
           titleField: entity.titleField,
-          subtitleField: entity.subtitleField
+          subtitleField: entity.subtitleField,
+          allowedIn: entity.allowedIn,
+          targetGraph: resolvedTargetGraph
         });
       }
     }
@@ -697,7 +897,8 @@ var NODE_TYPE_SCHEMA = {
     titleField: { type: "string" },
     subtitleField: { type: "string" },
     viewTemplate: { type: "string" },
-    viewCss: { type: "string" }
+    viewCss: { type: "string" },
+    allowedIn: { type: "array", items: { type: "string", minLength: 1 } }
   },
   additionalProperties: false
 };
@@ -724,7 +925,9 @@ var EDGE_TYPE_SCHEMA = {
     titleField: { type: "string" },
     subtitleField: { type: "string" },
     viewTemplate: { type: "string" },
-    viewCss: { type: "string" }
+    viewCss: { type: "string" },
+    allowedIn: { type: "array", items: { type: "string", minLength: 1 } },
+    targetGraph: { type: "string", minLength: 1, pattern: "^[^/]+$" }
   },
   additionalProperties: false
 };
@@ -766,7 +969,8 @@ async function createRegistryFromGraph(reader) {
       jsonSchema: data.jsonSchema,
       description: data.description,
       titleField: data.titleField,
-      subtitleField: data.subtitleField
+      subtitleField: data.subtitleField,
+      allowedIn: data.allowedIn
     });
   }
   for (const record of edgeTypes) {
@@ -783,7 +987,9 @@ async function createRegistryFromGraph(reader) {
           description: data.description,
           inverseLabel: data.inverseLabel,
           titleField: data.titleField,
-          subtitleField: data.subtitleField
+          subtitleField: data.subtitleField,
+          allowedIn: data.allowedIn,
+          targetGraph: data.targetGraph
         });
       }
     }
@@ -794,9 +1000,10 @@ async function createRegistryFromGraph(reader) {
 // src/client.ts
 var _standardModeWarned = false;
 var RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set([META_NODE_TYPE, META_EDGE_TYPE]);
-var GraphClientImpl = class {
-  constructor(db, collectionPath, options) {
+var GraphClientImpl = class _GraphClientImpl {
+  constructor(db, collectionPath, options, scopePath = "") {
     this.db = db;
+    this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db, collectionPath);
     if (options?.registry && options?.registryMode) {
       throw new DynamicRegistryError(
@@ -826,6 +1033,7 @@ var GraphClientImpl = class {
         "[firegraph] Standard query mode enabled. This is NOT recommended for production:\n  - Enterprise Firestore: data.* filters cause full collection scans (high billing)\n  - Standard Firestore: data.* filters without composite indexes will fail\n  See: https://github.com/typicalday/firegraph#query-modes"
       );
     }
+    this.scanProtection = options?.scanProtection ?? "error";
     if (this.queryMode === "pipeline") {
       this.pipelineAdapter = createPipelineQueryAdapter(db, collectionPath);
       if (this.metaAdapter) {
@@ -839,6 +1047,7 @@ var GraphClientImpl = class {
   adapter;
   pipelineAdapter;
   queryMode;
+  scanProtection;
   // Static mode
   staticRegistry;
   // Dynamic mode
@@ -847,6 +1056,8 @@ var GraphClientImpl = class {
   dynamicRegistry;
   metaAdapter;
   metaPipelineAdapter;
+  // Subgraph scope tracking
+  scopePath;
   // ---------------------------------------------------------------------------
   // Registry routing
   // ---------------------------------------------------------------------------
@@ -900,6 +1111,19 @@ var GraphClientImpl = class {
     }
     return this.adapter.query(filters, options);
   }
+  /**
+   * Check whether a query's filter set is safe (matches a known index pattern).
+   * Throws QuerySafetyError or logs a warning depending on scanProtection config.
+   */
+  checkQuerySafety(filters, allowCollectionScan) {
+    if (allowCollectionScan || this.scanProtection === "off") return;
+    const result = analyzeQuerySafety(filters);
+    if (result.safe) return;
+    if (this.scanProtection === "error") {
+      throw new QuerySafetyError(result.reason);
+    }
+    console.warn(`[firegraph] Query safety warning: ${result.reason}`);
+  }
   // ---------------------------------------------------------------------------
   // GraphReader
   // ---------------------------------------------------------------------------
@@ -921,6 +1145,7 @@ var GraphClientImpl = class {
       const record = await this.adapter.getDoc(plan.docId);
       return record ? [record] : [];
     }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
     return this.executeQuery(plan.filters, plan.options);
   }
   async findNodes(params) {
@@ -929,6 +1154,7 @@ var GraphClientImpl = class {
       const record = await this.adapter.getDoc(plan.docId);
       return record ? [record] : [];
     }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
     return this.executeQuery(plan.filters, plan.options);
   }
   // ---------------------------------------------------------------------------
@@ -937,7 +1163,7 @@ var GraphClientImpl = class {
   async putNode(aType, uid, data) {
     const registry = this.getRegistryForType(aType);
     if (registry) {
-      registry.validate(aType, NODE_RELATION, aType, data);
+      registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
     const adapter = this.getAdapterForType(aType);
     const docId = computeNodeDocId(uid);
@@ -947,7 +1173,7 @@ var GraphClientImpl = class {
   async putEdge(aType, aUid, axbType, bType, bUid, data) {
     const registry = this.getRegistryForType(aType);
     if (registry) {
-      registry.validate(aType, axbType, bType, data);
+      registry.validate(aType, axbType, bType, data, this.scopePath);
     }
     const adapter = this.getAdapterForType(aType);
     const docId = computeEdgeDocId(aUid, axbType, bUid);
@@ -979,13 +1205,69 @@ var GraphClientImpl = class {
         this.adapter.collectionPath,
         firestoreTx
       );
-      const graphTx = new GraphTransactionImpl(adapter, this.getCombinedRegistry());
+      const graphTx = new GraphTransactionImpl(adapter, this.getCombinedRegistry(), this.scanProtection, this.scopePath);
       return fn(graphTx);
     });
   }
   batch() {
     const adapter = createBatchAdapter(this.db, this.adapter.collectionPath);
-    return new GraphBatchImpl(adapter, this.getCombinedRegistry());
+    return new GraphBatchImpl(adapter, this.getCombinedRegistry(), this.scopePath);
+  }
+  // ---------------------------------------------------------------------------
+  // Subgraph
+  // ---------------------------------------------------------------------------
+  subgraph(parentNodeUid, name = "graph") {
+    if (!parentNodeUid || parentNodeUid.includes("/")) {
+      throw new FiregraphError(
+        `Invalid parentNodeUid for subgraph: "${parentNodeUid}". Must be a non-empty string without "/".`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    if (name.includes("/")) {
+      throw new FiregraphError(
+        `Subgraph name must not contain "/": got "${name}". Use chained .subgraph() calls for nested subgraphs.`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    const subCollectionPath = `${this.adapter.collectionPath}/${parentNodeUid}/${name}`;
+    const newScopePath = this.scopePath ? `${this.scopePath}/${name}` : name;
+    return new _GraphClientImpl(
+      this.db,
+      subCollectionPath,
+      {
+        registry: this.getCombinedRegistry(),
+        queryMode: this.queryMode === "pipeline" ? "pipeline" : "standard",
+        scanProtection: this.scanProtection
+      },
+      newScopePath
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Collection group query
+  // ---------------------------------------------------------------------------
+  async findEdgesGlobal(params, collectionName) {
+    const name = collectionName ?? this.adapter.collectionPath.split("/").pop();
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "findEdgesGlobal() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+    const collectionGroupRef = this.db.collectionGroup(name);
+    let q = collectionGroupRef;
+    for (const f of plan.filters) {
+      q = q.where(f.field, f.op, f.value);
+    }
+    if (plan.options?.orderBy) {
+      q = q.orderBy(plan.options.orderBy.field, plan.options.orderBy.direction ?? "asc");
+    }
+    if (plan.options?.limit !== void 0) {
+      q = q.limit(plan.options.limit);
+    }
+    const snap = await q.get();
+    return snap.docs.map((doc) => doc.data());
   }
   // ---------------------------------------------------------------------------
   // Bulk operations
@@ -1017,6 +1299,7 @@ var GraphClientImpl = class {
     if (options?.subtitleField !== void 0) data.subtitleField = options.subtitleField;
     if (options?.viewTemplate !== void 0) data.viewTemplate = options.viewTemplate;
     if (options?.viewCss !== void 0) data.viewCss = options.viewCss;
+    if (options?.allowedIn !== void 0) data.allowedIn = options.allowedIn;
     await this.putNode(META_NODE_TYPE, uid, data);
   }
   async defineEdgeType(name, topology, jsonSchema, description, options) {
@@ -1038,11 +1321,13 @@ var GraphClientImpl = class {
     };
     if (jsonSchema !== void 0) data.jsonSchema = jsonSchema;
     if (topology.inverseLabel !== void 0) data.inverseLabel = topology.inverseLabel;
+    if (topology.targetGraph !== void 0) data.targetGraph = topology.targetGraph;
     if (description !== void 0) data.description = description;
     if (options?.titleField !== void 0) data.titleField = options.titleField;
     if (options?.subtitleField !== void 0) data.subtitleField = options.subtitleField;
     if (options?.viewTemplate !== void 0) data.viewTemplate = options.viewTemplate;
     if (options?.viewCss !== void 0) data.viewCss = options.viewCss;
+    if (options?.allowedIn !== void 0) data.allowedIn = options.allowedIn;
     await this.putNode(META_EDGE_TYPE, uid, data);
   }
   async reloadRegistry() {
@@ -1111,6 +1396,10 @@ function generateId() {
 var DEFAULT_LIMIT = 10;
 var DEFAULT_MAX_READS = 100;
 var DEFAULT_CONCURRENCY = 5;
+var _crossGraphWarned = false;
+function isGraphClient(reader) {
+  return "subgraph" in reader && typeof reader.subgraph === "function";
+}
 var Semaphore = class {
   constructor(slots) {
     this.slots = slots;
@@ -1136,9 +1425,10 @@ var Semaphore = class {
   }
 };
 var TraversalBuilderImpl = class {
-  constructor(reader, startUid) {
+  constructor(reader, startUid, registry) {
     this.reader = reader;
     this.startUid = startUid;
+    this.registry = registry;
   }
   hops = [];
   follow(axbType, options) {
@@ -1155,11 +1445,13 @@ var TraversalBuilderImpl = class {
     const semaphore = new Semaphore(concurrency);
     let totalReads = 0;
     let truncated = false;
-    let sourceUids = [this.startUid];
+    let sources = [
+      { uid: this.startUid, reader: this.reader }
+    ];
     const hopResults = [];
     for (let depth = 0; depth < this.hops.length; depth++) {
       const hop = this.hops[depth];
-      if (sourceUids.length === 0) {
+      if (sources.length === 0) {
         hopResults.push({
           axbType: hop.axbType,
           depth,
@@ -1170,9 +1462,12 @@ var TraversalBuilderImpl = class {
         continue;
       }
       const hopEdges = [];
-      const sourceCount = sourceUids.length;
+      const sourceCount = sources.length;
       let hopTruncated = false;
-      const tasks = sourceUids.map((uid) => async () => {
+      const resolvedTargetGraph = this.resolveTargetGraph(hop);
+      const direction = hop.direction ?? "forward";
+      const isCrossGraph = direction === "forward" && !!resolvedTargetGraph;
+      const tasks = sources.map(({ uid, reader: sourceReader }) => async () => {
         if (totalReads >= maxReads) {
           hopTruncated = true;
           return;
@@ -1184,51 +1479,79 @@ var TraversalBuilderImpl = class {
             return;
           }
           totalReads++;
-          const direction2 = hop.direction ?? "forward";
           const params = { axbType: hop.axbType };
-          if (direction2 === "forward") {
+          if (direction === "forward") {
             params.aUid = uid;
             if (hop.bType) params.bType = hop.bType;
           } else {
             params.bUid = uid;
             if (hop.aType) params.aType = hop.aType;
           }
-          if (direction2 === "forward" && hop.aType) {
+          if (direction === "forward" && hop.aType) {
             params.aType = hop.aType;
           }
-          if (direction2 === "reverse" && hop.bType) {
+          if (direction === "reverse" && hop.bType) {
             params.bType = hop.bType;
           }
           if (hop.orderBy) params.orderBy = hop.orderBy;
           const limit = hop.limit ?? DEFAULT_LIMIT;
-          if (!hop.filter) {
+          if (hop.filter) {
+            params.limit = 0;
+          } else {
             params.limit = limit;
           }
-          let edges = await this.reader.findEdges(params);
+          let hopReader;
+          let nextReader;
+          if (isCrossGraph) {
+            if (isGraphClient(this.reader)) {
+              hopReader = this.reader.subgraph(uid, resolvedTargetGraph);
+              nextReader = hopReader;
+            } else {
+              hopReader = sourceReader;
+              nextReader = sourceReader;
+              if (!_crossGraphWarned) {
+                _crossGraphWarned = true;
+                console.warn(
+                  `[firegraph] Traversal hop "${hop.axbType}" has targetGraph "${resolvedTargetGraph}" but the reader does not support subgraph(). Cross-graph hop will query the current collection instead. Pass a GraphClient to createTraversal() to enable cross-graph traversal.`
+                );
+              }
+            }
+          } else {
+            hopReader = sourceReader;
+            nextReader = sourceReader;
+          }
+          let edges2 = await hopReader.findEdges(params);
           if (hop.filter) {
-            edges = edges.filter(hop.filter);
-            edges = edges.slice(0, limit);
+            edges2 = edges2.filter(hop.filter);
+            edges2 = edges2.slice(0, limit);
+          }
+          for (const edge of edges2) {
+            hopEdges.push({ edge, reader: nextReader });
           }
-          hopEdges.push(...edges);
         } finally {
           semaphore.release();
         }
       });
       await Promise.all(tasks.map((task) => task()));
+      const edges = hopEdges.map((h) => h.edge);
       hopResults.push({
         axbType: hop.axbType,
         depth,
-        edges: returnIntermediates ? [...hopEdges] : hopEdges,
+        edges: returnIntermediates ? [...edges] : edges,
         sourceCount,
         truncated: hopTruncated
       });
       if (hopTruncated) {
         truncated = true;
       }
-      const direction = hop.direction ?? "forward";
-      sourceUids = [...new Set(
-        hopEdges.map((e) => direction === "forward" ? e.bUid : e.aUid)
-      )];
+      const seen = /* @__PURE__ */ new Map();
+      for (const { edge, reader: edgeReader } of hopEdges) {
+        const nextUid = direction === "forward" ? edge.bUid : edge.aUid;
+        if (!seen.has(nextUid)) {
+          seen.set(nextUid, edgeReader);
+        }
+      }
+      sources = [...seen.entries()].map(([uid, reader]) => ({ uid, reader }));
     }
     const lastHop = hopResults[hopResults.length - 1];
     return {
@@ -1238,9 +1561,25 @@ var TraversalBuilderImpl = class {
       truncated
     };
   }
+  /**
+   * Resolve the targetGraph for a hop. Priority:
+   * 1. Explicit `hop.targetGraph` (user override)
+   * 2. Registry `targetGraph` for the axbType (if registry available)
+   * 3. undefined (no cross-graph)
+   */
+  resolveTargetGraph(hop) {
+    if (hop.targetGraph) return hop.targetGraph;
+    if (this.registry) {
+      const entries = this.registry.lookupByAxbType(hop.axbType);
+      for (const entry of entries) {
+        if (entry.targetGraph) return entry.targetGraph;
+      }
+    }
+    return void 0;
+  }
 };
-function createTraversal(reader, startUid) {
-  return new TraversalBuilderImpl(reader, startUid);
+function createTraversal(reader, startUid, registry) {
+  return new TraversalBuilderImpl(reader, startUid, registry);
 }
 
 // src/views.ts
@@ -1451,7 +1790,8 @@ function loadNodeEntity(dir, name) {
     subtitleField: meta?.subtitleField,
     viewDefaults: meta?.viewDefaults,
     viewsPath,
-    sampleData
+    sampleData,
+    allowedIn: meta?.allowedIn
   };
 }
 function loadEdgeEntity(dir, name) {
@@ -1486,7 +1826,9 @@ function loadEdgeEntity(dir, name) {
     subtitleField: meta?.subtitleField,
     viewDefaults: meta?.viewDefaults,
     viewsPath,
-    sampleData
+    sampleData,
+    allowedIn: meta?.allowedIn,
+    targetGraph: topology.targetGraph ?? meta?.targetGraph
   };
 }
 function getSubdirectories(dir) {
@@ -1528,8 +1870,147 @@ function discoverEntities(entitiesDir) {
     warnings
   };
 }
+
+// src/cross-graph.ts
+function resolveAncestorCollection(collectionPath, uid) {
+  const segments = collectionPath.split("/");
+  for (let i = 1; i < segments.length; i += 2) {
+    if (segments[i] === uid) {
+      return segments.slice(0, i).join("/");
+    }
+  }
+  return null;
+}
+function isAncestorUid(collectionPath, uid) {
+  return resolveAncestorCollection(collectionPath, uid) !== null;
+}
+
+// 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 extractSchemaFields(schema) {
+  const s = schema;
+  if (s.type !== "object" || !s.properties) return [];
+  return Object.keys(s.properties);
+}
+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 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" }
+          ]
+        });
+      }
+    }
+  }
+  if (registryEntries) {
+    const targetGraphNames = /* @__PURE__ */ new Set();
+    for (const entry of registryEntries) {
+      if (entry.targetGraph) {
+        targetGraphNames.add(entry.targetGraph);
+      }
+    }
+    for (const name of targetGraphNames) {
+      indexes.push(...collectionGroupIndexes(name));
+    }
+  }
+  return { indexes, fieldOverrides: [] };
+}
 export {
   BOOTSTRAP_ENTRIES,
+  DEFAULT_QUERY_LIMIT,
   DiscoveryError,
   DynamicRegistryError,
   EDGE_TYPE_SCHEMA,
@@ -1542,9 +2023,12 @@ export {
   NodeNotFoundError,
   QueryClient,
   QueryClientError,
+  QuerySafetyError,
+  RegistryScopeError,
   RegistryViolationError,
   TraversalError,
   ValidationError,
+  analyzeQuerySafety,
   buildEdgeQueryPlan,
   buildEdgeRecord,
   buildNodeQueryPlan,
@@ -1562,8 +2046,13 @@ export {
   discoverEntities,
   generateDeterministicUid,
   generateId,
+  generateIndexConfig,
   generateTypes,
+  isAncestorUid,
   jsonSchemaToFieldMeta,
+  matchScope,
+  matchScopeAny,
+  resolveAncestorCollection,
   resolveView
 };
 //# sourceMappingURL=index.js.map