@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/cloudflare/index.d.cts

@@ -1,6 +1,8 @@
-import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-np4gEVhB.cjs';
-import { c as GraphRegistry, I as IndexSpec, i as QueryFilter, z as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-BGWxcpI_.cjs';
+import { W as WritableRecord, f as WriteMode, U as UpdatePayload, G as GraphRegistry, I as IndexSpec, p as QueryFilter, ai as QueryOptions, z as AggregateSpec, O as CascadeResult, F as FindEdgesParams, H as BulkOptions, L as BulkResult, b as BulkUpdatePatch, E as ExpandParams, S as StorageBackend, B as BackendCapabilities, t as GraphClient, Z as DynamicGraphClient, m as StoredGraphRecord, T as TransactionBackend, a as BatchBackend, u as GraphReader, e as ExpandResult, a8 as GraphClientOptions, $ as DynamicRegistryConfig } from '../backend-DuvHGgK1.cjs';
+export { A as AggregateExtension, w as AggregateField, x as AggregateOp, y as AggregateResult, N as Capability, d as DmlExtension, J as JoinExtension, g as createCapabilities, h as deleteField, j as intersectCapabilities } from '../backend-DuvHGgK1.cjs';
 import { DurableObject } from 'cloudflare:workers';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, b as createMergedRegistry, d as createRegistry, f as generateId } from '../registry-Bc7h6WTM.cjs';
+export { C as CapabilityNotSupportedError } from '../errors-BRc3I_eH.cjs';
 import '@google-cloud/firestore';
 
 /**
@@ -40,6 +42,30 @@ interface DORecordWire {
     createdAtMs: number;
     updatedAtMs: number;
 }
+/**
+ * Discriminator for one projected column on the DO backend. The decoder
+ * uses this to recover the JS-shape of the requested field. Mirrors the
+ * shared-SQLite `ProjectedColumnKind` — same kinds, same decode rules. The
+ * two share no module so the symbol is duplicated; the contract is locked
+ * by the cross-backend test in `tests/unit/cloudflare-sql.test.ts`.
+ */
+type DOProjectedColumnKind = 'builtin-text' | 'builtin-int' | 'builtin-timestamp' | 'data' | 'json';
+/** Per-column metadata returned alongside the compiled projection statement. */
+interface DOProjectedColumnSpec {
+    /** Original caller-supplied field name. Used as the alias in the SQL
+     *  projection list AND as the key in the returned JS row. */
+    field: string;
+    /** Kind discriminator — see `DOProjectedColumnKind`. */
+    kind: DOProjectedColumnKind;
+    /**
+     * For `kind === 'json'` only: alias of the paired `json_type` companion
+     * column. Uses a positional sentinel (`__fg_t_<idx>`) keyed by the
+     * field's position in the unique projection list rather than the
+     * historical `<field>__t` suffix, which would collide if the caller
+     * projected both `'foo'` and `'foo__t'` (both legal user input).
+     */
+    typeAlias?: string;
+}
 
 /**
  * `FiregraphDO` — the Durable Object class that holds a single subgraph's
@@ -124,6 +150,7 @@ type BatchOp = {
     kind: 'set';
     docId: string;
     record: WritableRecord;
+    mode: WriteMode;
 } | {
     kind: 'update';
     docId: string;
@@ -185,7 +212,15 @@ declare class FiregraphDO extends DurableObject<unknown> {
     constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    /**
+     * Aggregate query (capability `query.aggregate`). Compiles a single
+     * `SELECT` projecting one column per alias; SQLite handles count, sum,
+     * avg, min, max natively. Empty-set fix-ups (NULL → 0 for sum/min/max,
+     * NaN for avg) happen on the client side in `DORPCBackend.aggregate` so
+     * the wire payload stays a plain row of (alias → number | null).
+     */
+    _fgAggregate(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number | null>>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     /**
@@ -197,6 +232,21 @@ declare class FiregraphDO extends DurableObject<unknown> {
     _fgBatch(ops: BatchOp[]): Promise<void>;
     _fgRemoveNodeCascade(uid: string): Promise<CascadeResult>;
     _fgBulkRemoveEdges(params: FindEdgesParams, _options?: BulkOptions): Promise<BulkResult>;
+    _fgBulkDelete(filters: QueryFilter[], _options?: BulkOptions): Promise<BulkResult>;
+    _fgBulkUpdate(filters: QueryFilter[], patch: BulkUpdatePatch, _options?: BulkOptions): Promise<BulkResult>;
+    _fgExpand(params: ExpandParams): Promise<ExpandResultWire>;
+    _fgFindEdgesProjected(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<{
+        rows: Array<Record<string, unknown>>;
+        columns: DOProjectedColumnSpec[];
+    }>;
+    /**
+     * Run a DML statement with `RETURNING "doc_id"` so the affected-row count
+     * comes back authoritatively. Errors are caught and surfaced via the
+     * `BulkResult.errors` array (single batch, batchIndex 0) so the wire
+     * payload stays a regular `BulkResult` and the client doesn't have to
+     * differentiate "RPC threw" from "single-statement failure."
+     */
+    private execDmlWithReturning;
     /**
      * Wipe every row. Called by the client when tearing down a subgraph DO as
      * part of cascade — the DO itself can't be destroyed (DO IDs persist
@@ -257,14 +307,80 @@ interface DurableObjectIdLike {
 interface FiregraphStub {
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    /**
+     * Optional — added in Phase 4 (`query.aggregate`). Marked optional so
+     * external worker code that hand-rolls a stub wrapper around a real DO
+     * stub (e.g. for testing or for layering structured-clone shims) keeps
+     * compiling without modification. `FiregraphDO` always implements this
+     * method, but callers of `DORPCBackend.aggregate` must either assert the
+     * stub supports it or be prepared for `UNSUPPORTED_OPERATION` at runtime.
+     */
+    _fgAggregate?(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number | null>>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     _fgBatch(ops: BatchOp[]): Promise<void>;
     _fgRemoveNodeCascade(uid: string): Promise<CascadeResult>;
     _fgBulkRemoveEdges(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Optional — added in Phase 5 (`query.dml`). Same back-compat rationale as
+     * `_fgAggregate`: external worker code that hand-rolls a stub wrapper keeps
+     * compiling without modification. `FiregraphDO` always implements this
+     * method; callers of `DORPCBackend.bulkDelete` either assert support or
+     * accept `UNSUPPORTED_OPERATION` at runtime.
+     */
+    _fgBulkDelete?(filters: QueryFilter[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Optional — added in Phase 5 (`query.dml`). See `_fgBulkDelete`.
+     */
+    _fgBulkUpdate?(filters: QueryFilter[], patch: BulkUpdatePatch, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Optional — added in Phase 6 (`query.join`). Same back-compat rationale as
+     * `_fgAggregate` / `_fgBulkDelete`: external worker code that hand-rolls a
+     * stub wrapper keeps compiling without modification. `FiregraphDO` always
+     * implements this method; callers of `DORPCBackend.expand` either assert
+     * the stub supports it or accept `UNSUPPORTED_OPERATION` at runtime.
+     *
+     * The wire shape uses `ExpandResultWire` so `StoredGraphRecord` instances
+     * (which carry `Timestamp` wrappers) survive the structured-clone hop —
+     * they're rehydrated on this side via `hydrateDORecord`, just like the
+     * `query()` and `_fgBulkRemoveEdges` paths.
+     */
+    _fgExpand?(params: ExpandParams): Promise<ExpandResultWire>;
+    /**
+     * Optional — added in Phase 7 (`query.select`). Same back-compat rationale
+     * as `_fgAggregate` / `_fgBulkDelete` / `_fgExpand`: external worker code
+     * that hand-rolls a stub wrapper keeps compiling without modification.
+     * `FiregraphDO` always implements this method; callers of
+     * `DORPCBackend.findEdgesProjected` either assert the stub supports it or
+     * accept `UNSUPPORTED_OPERATION` at runtime.
+     *
+     * The wire shape returns `{ rows, columns }` — raw row objects from the
+     * SQLite executor plus the per-column metadata produced by
+     * `compileDOFindEdgesProjected`. Decoding (BigInt → number, timestamp
+     * rehydration, paired `__t` resolution for `data.*` paths) happens on
+     * the client side via `decodeDOProjectedRow`. We deliberately do NOT
+     * decode inside the DO because `GraphTimestampImpl` instances do not
+     * survive workerd's structured-clone boundary as class instances —
+     * decoding must happen on the side that owns the prototype.
+     */
+    _fgFindEdgesProjected?(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<{
+        rows: Array<Record<string, unknown>>;
+        columns: DOProjectedColumnSpec[];
+    }>;
     _fgDestroy(): Promise<void>;
 }
+/**
+ * Wire shape for `_fgExpand`. The DO returns rows as `DORecordWire` (the
+ * SQLite row layout) and the backend re-hydrates them on this side, so
+ * `Timestamp` wrappers are reconstructed locally and never round-trip
+ * through workerd's structured-clone boundary as plain objects.
+ */
+interface ExpandResultWire {
+    edges: DORecordWire[];
+    /** Aligned with `edges`; absent when the caller didn't request hydration. */
+    targets?: Array<DORecordWire | null>;
+}
 interface FiregraphNamespace {
     idFromName(name: string): DurableObjectIdLike;
     get(id: DurableObjectIdLike): FiregraphStub;
@@ -303,9 +419,26 @@ interface DORPCBackendOptions {
      * own overload signatures.
      * @internal
      */
-    makeSiblingClient?: (siblingStorageKey: string) => GraphClient | DynamicGraphClient;
+    makeSiblingClient?: (siblingStorageKey: string) => GraphClient<CloudflareCapability> | DynamicGraphClient<CloudflareCapability>;
 }
-declare class DORPCBackend implements StorageBackend {
+/**
+ * Capability union declared by the DO RPC backend.
+ *
+ * Note the absence of `core.transactions`: `runTransaction` throws
+ * `UNSUPPORTED_OPERATION` because holding a synchronous SQLite transaction
+ * across async RPC calls would block the DO's single-threaded executor (see
+ * `transactionsUnsupported` above). `raw.sql` is also intentionally absent —
+ * the SQL surface lives inside the DO and isn't exposed across the RPC
+ * boundary.
+ *
+ * Conservative declaration matters: the type-level capability gate (Phase 3)
+ * relies on the union and the runtime cap-set agreeing. Adding a cap here
+ * without a corresponding runtime method would let callers reach a method
+ * that doesn't exist.
+ */
+type CloudflareCapability = 'core.read' | 'core.write' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.dml' | 'query.join' | 'query.select';
+declare class DORPCBackend implements StorageBackend<CloudflareCapability> {
+    readonly capabilities: BackendCapabilities<CloudflareCapability>;
     readonly collectionPath = "firegraph";
     readonly scopePath: string;
     /** @internal */
@@ -314,13 +447,21 @@ declare class DORPCBackend implements StorageBackend {
     readonly namespace: FiregraphNamespace;
     private readonly registryAccessor?;
     /** @internal — see `DORPCBackendOptions.makeSiblingClient` for the union-type rationale. */
-    readonly makeSiblingClient?: (siblingStorageKey: string) => GraphClient | DynamicGraphClient;
+    readonly makeSiblingClient?: (siblingStorageKey: string) => GraphClient<CloudflareCapability> | DynamicGraphClient<CloudflareCapability>;
     private cachedStub;
     constructor(namespace: FiregraphNamespace, options: DORPCBackendOptions);
     private get stub();
     getDoc(docId: string): Promise<StoredGraphRecord | null>;
     query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
-    setDoc(docId: string, record: WritableRecord): Promise<void>;
+    /**
+     * Run an aggregate query inside the backing DO. The DO returns a row of
+     * `{ alias: number | null }` (null = SQLite NULL for SUM/MIN/MAX over an
+     * empty set, or the count being literally 0); this method resolves NULL
+     * to 0 for SUM/MIN/MAX and to NaN for AVG, matching the SQLite backend
+     * and the Firestore Standard helper.
+     */
+    aggregate(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number>>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     updateDoc(docId: string, update: UpdatePayload): Promise<void>;
     deleteDoc(docId: string): Promise<void>;
     runTransaction<T>(_fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
@@ -328,6 +469,57 @@ declare class DORPCBackend implements StorageBackend {
     subgraph(parentNodeUid: string, name: string): StorageBackend;
     removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
     bulkRemoveEdges(params: FindEdgesParams, _reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Single-statement bulk DELETE inside the backing DO. The DO compiles
+     * the filter list to one `DELETE … WHERE …` statement and returns a
+     * `BulkResult` whose `deleted` is the affected-row count.
+     *
+     * Defensive `_fgBulkDelete` presence check mirrors `aggregate()`: the
+     * RPC method is optional on `FiregraphStub` so external worker code with
+     * a hand-rolled stub wrapper still type-checks. Surface a clear
+     * `UNSUPPORTED_OPERATION` rather than `TypeError: stub._fgBulkDelete is
+     * not a function` when the wrapper hasn't forwarded the method.
+     */
+    bulkDelete(filters: QueryFilter[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Single-statement bulk UPDATE inside the backing DO. Same contract as
+     * `bulkDelete` for the missing-method case; the DO compiles the patch to
+     * one `UPDATE … SET data = json_patch(...) WHERE …` statement.
+     */
+    bulkUpdate(filters: QueryFilter[], patch: BulkUpdatePatch, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Multi-source fan-out — `query.join` capability. Routes the call through
+     * the DO's `_fgExpand` RPC, which compiles to one `SELECT … WHERE
+     * "aUid" IN (?, …)` statement (plus, when `params.hydrate === true`, a
+     * second IN-clause statement against the node rows).
+     *
+     * Defensive `_fgExpand` presence check matches the bulk-DML pattern: the
+     * RPC method is optional on `FiregraphStub` so external worker code with
+     * a hand-rolled stub wrapper still type-checks. We surface a clear
+     * `UNSUPPORTED_OPERATION` rather than `TypeError: stub._fgExpand is not a
+     * function` if the wrapper hasn't forwarded the method.
+     */
+    expand(params: ExpandParams): Promise<ExpandResult>;
+    /**
+     * Server-side projection — `query.select` capability. Forwards the call to
+     * the DO's `_fgFindEdgesProjected` RPC, which compiles to a single
+     * `SELECT json_extract(...) AS …, json_type(...) AS …__t FROM <table>
+     * WHERE …` statement. The DO returns raw rows + per-column metadata; this
+     * method decodes each row locally via `decodeDOProjectedRow`.
+     *
+     * Decoding lives on this side (not inside the DO) because
+     * `GraphTimestampImpl` is a class — its prototype does not survive
+     * workerd's structured-clone boundary — so timestamp rehydration must
+     * happen wherever the rows are consumed by the GraphClient.
+     *
+     * Defensive `_fgFindEdgesProjected` presence check matches the `expand` /
+     * bulk-DML / aggregate pattern: the RPC method is optional on
+     * `FiregraphStub` so external worker code with a hand-rolled stub wrapper
+     * still type-checks. Surface a clear `UNSUPPORTED_OPERATION` rather than
+     * `TypeError: stub._fgFindEdgesProjected is not a function` if the
+     * wrapper hasn't forwarded the method.
+     */
+    findEdgesProjected(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<Array<Record<string, unknown>>>;
     /**
      * Wipe this DO's storage. The DO itself can't be deleted — its ID
      * persists forever — but its rows can be emptied, which is what the
@@ -440,6 +632,18 @@ declare class DORPCBackend implements StorageBackend {
  * ```
  */
 
+/**
+ * The DO declares a strict subset of `Capability` (no `search.*`,
+ * `realtime.listen`, or `raw.*`). Local variables and helper closures
+ * that round-trip the client need to use the narrower form so that a
+ * `GraphClient<CloudflareCapability>` (which doesn't promise, e.g.,
+ * `findNearest`) is assignable. Using the unparameterized
+ * `GraphClient` here would require the DO to implement every
+ * extension method, which would defeat the whole point of the
+ * capability gate.
+ */
+type DOGraphClient = GraphClient<CloudflareCapability>;
+type DODynamicGraphClient = DynamicGraphClient<CloudflareCapability>;
 /**
  * Options for `createDOClient`. Same shape as `GraphClientOptions`; the DO
  * backend does not expose a table label of its own — the DO owns its SQLite
@@ -461,8 +665,8 @@ type DOClientOptions = GraphClientOptions;
  */
 declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options: DOClientOptions & {
     registryMode: DynamicRegistryConfig;
-}): DynamicGraphClient;
-declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options?: DOClientOptions): GraphClient;
+}): DODynamicGraphClient;
+declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options?: DOClientOptions): DOGraphClient;
 /**
  * Construct a peer `GraphClient` that shares `client`'s DO namespace and
  * construction options but targets a different root DO (i.e. a different
@@ -495,8 +699,8 @@ declare function createDOClient(namespace: FiregraphNamespace, rootKey: string,
  *                         as `createDOClient`'s `rootKey`: non-empty,
  *                         no `/`.
  */
-declare function createSiblingClient(client: GraphClient, siblingRootKey: string): GraphClient;
-declare function createSiblingClient(client: DynamicGraphClient, siblingRootKey: string): DynamicGraphClient;
+declare function createSiblingClient(client: DOGraphClient, siblingRootKey: string): DOGraphClient;
+declare function createSiblingClient(client: DODynamicGraphClient, siblingRootKey: string): DODynamicGraphClient;
 
 /**
  * Flat SQLite schema for a single firegraph DO.
@@ -551,4 +755,4 @@ interface BuildDOSchemaOptions {
  */
 declare function buildDOSchemaStatements(table: string, options?: BuildDOSchemaOptions): string[];
 
-export { type BatchOp, type BuildDOSchemaOptions, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, buildDOSchemaStatements, createDOClient, createSiblingClient };
+export { AggregateSpec, BackendCapabilities, type BatchOp, type BuildDOSchemaOptions, BulkUpdatePatch, type CloudflareCapability, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, ExpandParams, ExpandResult, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, buildDOSchemaStatements, createDOClient, createSiblingClient };

package/dist/cloudflare/index.d.ts

@@ -1,6 +1,8 @@
-import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-U-MLShlg.js';
-import { c as GraphRegistry, I as IndexSpec, i as QueryFilter, z as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-BGWxcpI_.js';
+import { W as WritableRecord, f as WriteMode, U as UpdatePayload, G as GraphRegistry, I as IndexSpec, p as QueryFilter, ai as QueryOptions, z as AggregateSpec, O as CascadeResult, F as FindEdgesParams, H as BulkOptions, L as BulkResult, b as BulkUpdatePatch, E as ExpandParams, S as StorageBackend, B as BackendCapabilities, t as GraphClient, Z as DynamicGraphClient, m as StoredGraphRecord, T as TransactionBackend, a as BatchBackend, u as GraphReader, e as ExpandResult, a8 as GraphClientOptions, $ as DynamicRegistryConfig } from '../backend-DuvHGgK1.js';
+export { A as AggregateExtension, w as AggregateField, x as AggregateOp, y as AggregateResult, N as Capability, d as DmlExtension, J as JoinExtension, g as createCapabilities, h as deleteField, j as intersectCapabilities } from '../backend-DuvHGgK1.js';
 import { DurableObject } from 'cloudflare:workers';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, b as createMergedRegistry, d as createRegistry, f as generateId } from '../registry-C2KUPVZj.js';
+export { C as CapabilityNotSupportedError } from '../errors-BRc3I_eH.js';
 import '@google-cloud/firestore';
 
 /**
@@ -40,6 +42,30 @@ interface DORecordWire {
     createdAtMs: number;
     updatedAtMs: number;
 }
+/**
+ * Discriminator for one projected column on the DO backend. The decoder
+ * uses this to recover the JS-shape of the requested field. Mirrors the
+ * shared-SQLite `ProjectedColumnKind` — same kinds, same decode rules. The
+ * two share no module so the symbol is duplicated; the contract is locked
+ * by the cross-backend test in `tests/unit/cloudflare-sql.test.ts`.
+ */
+type DOProjectedColumnKind = 'builtin-text' | 'builtin-int' | 'builtin-timestamp' | 'data' | 'json';
+/** Per-column metadata returned alongside the compiled projection statement. */
+interface DOProjectedColumnSpec {
+    /** Original caller-supplied field name. Used as the alias in the SQL
+     *  projection list AND as the key in the returned JS row. */
+    field: string;
+    /** Kind discriminator — see `DOProjectedColumnKind`. */
+    kind: DOProjectedColumnKind;
+    /**
+     * For `kind === 'json'` only: alias of the paired `json_type` companion
+     * column. Uses a positional sentinel (`__fg_t_<idx>`) keyed by the
+     * field's position in the unique projection list rather than the
+     * historical `<field>__t` suffix, which would collide if the caller
+     * projected both `'foo'` and `'foo__t'` (both legal user input).
+     */
+    typeAlias?: string;
+}
 
 /**
  * `FiregraphDO` — the Durable Object class that holds a single subgraph's
@@ -124,6 +150,7 @@ type BatchOp = {
     kind: 'set';
     docId: string;
     record: WritableRecord;
+    mode: WriteMode;
 } | {
     kind: 'update';
     docId: string;
@@ -185,7 +212,15 @@ declare class FiregraphDO extends DurableObject<unknown> {
     constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    /**
+     * Aggregate query (capability `query.aggregate`). Compiles a single
+     * `SELECT` projecting one column per alias; SQLite handles count, sum,
+     * avg, min, max natively. Empty-set fix-ups (NULL → 0 for sum/min/max,
+     * NaN for avg) happen on the client side in `DORPCBackend.aggregate` so
+     * the wire payload stays a plain row of (alias → number | null).
+     */
+    _fgAggregate(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number | null>>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     /**
@@ -197,6 +232,21 @@ declare class FiregraphDO extends DurableObject<unknown> {
     _fgBatch(ops: BatchOp[]): Promise<void>;
     _fgRemoveNodeCascade(uid: string): Promise<CascadeResult>;
     _fgBulkRemoveEdges(params: FindEdgesParams, _options?: BulkOptions): Promise<BulkResult>;
+    _fgBulkDelete(filters: QueryFilter[], _options?: BulkOptions): Promise<BulkResult>;
+    _fgBulkUpdate(filters: QueryFilter[], patch: BulkUpdatePatch, _options?: BulkOptions): Promise<BulkResult>;
+    _fgExpand(params: ExpandParams): Promise<ExpandResultWire>;
+    _fgFindEdgesProjected(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<{
+        rows: Array<Record<string, unknown>>;
+        columns: DOProjectedColumnSpec[];
+    }>;
+    /**
+     * Run a DML statement with `RETURNING "doc_id"` so the affected-row count
+     * comes back authoritatively. Errors are caught and surfaced via the
+     * `BulkResult.errors` array (single batch, batchIndex 0) so the wire
+     * payload stays a regular `BulkResult` and the client doesn't have to
+     * differentiate "RPC threw" from "single-statement failure."
+     */
+    private execDmlWithReturning;
     /**
      * Wipe every row. Called by the client when tearing down a subgraph DO as
      * part of cascade — the DO itself can't be destroyed (DO IDs persist
@@ -257,14 +307,80 @@ interface DurableObjectIdLike {
 interface FiregraphStub {
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
-    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    /**
+     * Optional — added in Phase 4 (`query.aggregate`). Marked optional so
+     * external worker code that hand-rolls a stub wrapper around a real DO
+     * stub (e.g. for testing or for layering structured-clone shims) keeps
+     * compiling without modification. `FiregraphDO` always implements this
+     * method, but callers of `DORPCBackend.aggregate` must either assert the
+     * stub supports it or be prepared for `UNSUPPORTED_OPERATION` at runtime.
+     */
+    _fgAggregate?(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number | null>>;
+    _fgSetDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
     _fgDeleteDoc(docId: string): Promise<void>;
     _fgBatch(ops: BatchOp[]): Promise<void>;
     _fgRemoveNodeCascade(uid: string): Promise<CascadeResult>;
     _fgBulkRemoveEdges(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Optional — added in Phase 5 (`query.dml`). Same back-compat rationale as
+     * `_fgAggregate`: external worker code that hand-rolls a stub wrapper keeps
+     * compiling without modification. `FiregraphDO` always implements this
+     * method; callers of `DORPCBackend.bulkDelete` either assert support or
+     * accept `UNSUPPORTED_OPERATION` at runtime.
+     */
+    _fgBulkDelete?(filters: QueryFilter[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Optional — added in Phase 5 (`query.dml`). See `_fgBulkDelete`.
+     */
+    _fgBulkUpdate?(filters: QueryFilter[], patch: BulkUpdatePatch, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Optional — added in Phase 6 (`query.join`). Same back-compat rationale as
+     * `_fgAggregate` / `_fgBulkDelete`: external worker code that hand-rolls a
+     * stub wrapper keeps compiling without modification. `FiregraphDO` always
+     * implements this method; callers of `DORPCBackend.expand` either assert
+     * the stub supports it or accept `UNSUPPORTED_OPERATION` at runtime.
+     *
+     * The wire shape uses `ExpandResultWire` so `StoredGraphRecord` instances
+     * (which carry `Timestamp` wrappers) survive the structured-clone hop —
+     * they're rehydrated on this side via `hydrateDORecord`, just like the
+     * `query()` and `_fgBulkRemoveEdges` paths.
+     */
+    _fgExpand?(params: ExpandParams): Promise<ExpandResultWire>;
+    /**
+     * Optional — added in Phase 7 (`query.select`). Same back-compat rationale
+     * as `_fgAggregate` / `_fgBulkDelete` / `_fgExpand`: external worker code
+     * that hand-rolls a stub wrapper keeps compiling without modification.
+     * `FiregraphDO` always implements this method; callers of
+     * `DORPCBackend.findEdgesProjected` either assert the stub supports it or
+     * accept `UNSUPPORTED_OPERATION` at runtime.
+     *
+     * The wire shape returns `{ rows, columns }` — raw row objects from the
+     * SQLite executor plus the per-column metadata produced by
+     * `compileDOFindEdgesProjected`. Decoding (BigInt → number, timestamp
+     * rehydration, paired `__t` resolution for `data.*` paths) happens on
+     * the client side via `decodeDOProjectedRow`. We deliberately do NOT
+     * decode inside the DO because `GraphTimestampImpl` instances do not
+     * survive workerd's structured-clone boundary as class instances —
+     * decoding must happen on the side that owns the prototype.
+     */
+    _fgFindEdgesProjected?(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<{
+        rows: Array<Record<string, unknown>>;
+        columns: DOProjectedColumnSpec[];
+    }>;
     _fgDestroy(): Promise<void>;
 }
+/**
+ * Wire shape for `_fgExpand`. The DO returns rows as `DORecordWire` (the
+ * SQLite row layout) and the backend re-hydrates them on this side, so
+ * `Timestamp` wrappers are reconstructed locally and never round-trip
+ * through workerd's structured-clone boundary as plain objects.
+ */
+interface ExpandResultWire {
+    edges: DORecordWire[];
+    /** Aligned with `edges`; absent when the caller didn't request hydration. */
+    targets?: Array<DORecordWire | null>;
+}
 interface FiregraphNamespace {
     idFromName(name: string): DurableObjectIdLike;
     get(id: DurableObjectIdLike): FiregraphStub;
@@ -303,9 +419,26 @@ interface DORPCBackendOptions {
      * own overload signatures.
      * @internal
      */
-    makeSiblingClient?: (siblingStorageKey: string) => GraphClient | DynamicGraphClient;
+    makeSiblingClient?: (siblingStorageKey: string) => GraphClient<CloudflareCapability> | DynamicGraphClient<CloudflareCapability>;
 }
-declare class DORPCBackend implements StorageBackend {
+/**
+ * Capability union declared by the DO RPC backend.
+ *
+ * Note the absence of `core.transactions`: `runTransaction` throws
+ * `UNSUPPORTED_OPERATION` because holding a synchronous SQLite transaction
+ * across async RPC calls would block the DO's single-threaded executor (see
+ * `transactionsUnsupported` above). `raw.sql` is also intentionally absent —
+ * the SQL surface lives inside the DO and isn't exposed across the RPC
+ * boundary.
+ *
+ * Conservative declaration matters: the type-level capability gate (Phase 3)
+ * relies on the union and the runtime cap-set agreeing. Adding a cap here
+ * without a corresponding runtime method would let callers reach a method
+ * that doesn't exist.
+ */
+type CloudflareCapability = 'core.read' | 'core.write' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.dml' | 'query.join' | 'query.select';
+declare class DORPCBackend implements StorageBackend<CloudflareCapability> {
+    readonly capabilities: BackendCapabilities<CloudflareCapability>;
     readonly collectionPath = "firegraph";
     readonly scopePath: string;
     /** @internal */
@@ -314,13 +447,21 @@ declare class DORPCBackend implements StorageBackend {
     readonly namespace: FiregraphNamespace;
     private readonly registryAccessor?;
     /** @internal — see `DORPCBackendOptions.makeSiblingClient` for the union-type rationale. */
-    readonly makeSiblingClient?: (siblingStorageKey: string) => GraphClient | DynamicGraphClient;
+    readonly makeSiblingClient?: (siblingStorageKey: string) => GraphClient<CloudflareCapability> | DynamicGraphClient<CloudflareCapability>;
     private cachedStub;
     constructor(namespace: FiregraphNamespace, options: DORPCBackendOptions);
     private get stub();
     getDoc(docId: string): Promise<StoredGraphRecord | null>;
     query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
-    setDoc(docId: string, record: WritableRecord): Promise<void>;
+    /**
+     * Run an aggregate query inside the backing DO. The DO returns a row of
+     * `{ alias: number | null }` (null = SQLite NULL for SUM/MIN/MAX over an
+     * empty set, or the count being literally 0); this method resolves NULL
+     * to 0 for SUM/MIN/MAX and to NaN for AVG, matching the SQLite backend
+     * and the Firestore Standard helper.
+     */
+    aggregate(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number>>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
     updateDoc(docId: string, update: UpdatePayload): Promise<void>;
     deleteDoc(docId: string): Promise<void>;
     runTransaction<T>(_fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
@@ -328,6 +469,57 @@ declare class DORPCBackend implements StorageBackend {
     subgraph(parentNodeUid: string, name: string): StorageBackend;
     removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
     bulkRemoveEdges(params: FindEdgesParams, _reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Single-statement bulk DELETE inside the backing DO. The DO compiles
+     * the filter list to one `DELETE … WHERE …` statement and returns a
+     * `BulkResult` whose `deleted` is the affected-row count.
+     *
+     * Defensive `_fgBulkDelete` presence check mirrors `aggregate()`: the
+     * RPC method is optional on `FiregraphStub` so external worker code with
+     * a hand-rolled stub wrapper still type-checks. Surface a clear
+     * `UNSUPPORTED_OPERATION` rather than `TypeError: stub._fgBulkDelete is
+     * not a function` when the wrapper hasn't forwarded the method.
+     */
+    bulkDelete(filters: QueryFilter[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Single-statement bulk UPDATE inside the backing DO. Same contract as
+     * `bulkDelete` for the missing-method case; the DO compiles the patch to
+     * one `UPDATE … SET data = json_patch(...) WHERE …` statement.
+     */
+    bulkUpdate(filters: QueryFilter[], patch: BulkUpdatePatch, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Multi-source fan-out — `query.join` capability. Routes the call through
+     * the DO's `_fgExpand` RPC, which compiles to one `SELECT … WHERE
+     * "aUid" IN (?, …)` statement (plus, when `params.hydrate === true`, a
+     * second IN-clause statement against the node rows).
+     *
+     * Defensive `_fgExpand` presence check matches the bulk-DML pattern: the
+     * RPC method is optional on `FiregraphStub` so external worker code with
+     * a hand-rolled stub wrapper still type-checks. We surface a clear
+     * `UNSUPPORTED_OPERATION` rather than `TypeError: stub._fgExpand is not a
+     * function` if the wrapper hasn't forwarded the method.
+     */
+    expand(params: ExpandParams): Promise<ExpandResult>;
+    /**
+     * Server-side projection — `query.select` capability. Forwards the call to
+     * the DO's `_fgFindEdgesProjected` RPC, which compiles to a single
+     * `SELECT json_extract(...) AS …, json_type(...) AS …__t FROM <table>
+     * WHERE …` statement. The DO returns raw rows + per-column metadata; this
+     * method decodes each row locally via `decodeDOProjectedRow`.
+     *
+     * Decoding lives on this side (not inside the DO) because
+     * `GraphTimestampImpl` is a class — its prototype does not survive
+     * workerd's structured-clone boundary — so timestamp rehydration must
+     * happen wherever the rows are consumed by the GraphClient.
+     *
+     * Defensive `_fgFindEdgesProjected` presence check matches the `expand` /
+     * bulk-DML / aggregate pattern: the RPC method is optional on
+     * `FiregraphStub` so external worker code with a hand-rolled stub wrapper
+     * still type-checks. Surface a clear `UNSUPPORTED_OPERATION` rather than
+     * `TypeError: stub._fgFindEdgesProjected is not a function` if the
+     * wrapper hasn't forwarded the method.
+     */
+    findEdgesProjected(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<Array<Record<string, unknown>>>;
     /**
      * Wipe this DO's storage. The DO itself can't be deleted — its ID
      * persists forever — but its rows can be emptied, which is what the
@@ -440,6 +632,18 @@ declare class DORPCBackend implements StorageBackend {
  * ```
  */
 
+/**
+ * The DO declares a strict subset of `Capability` (no `search.*`,
+ * `realtime.listen`, or `raw.*`). Local variables and helper closures
+ * that round-trip the client need to use the narrower form so that a
+ * `GraphClient<CloudflareCapability>` (which doesn't promise, e.g.,
+ * `findNearest`) is assignable. Using the unparameterized
+ * `GraphClient` here would require the DO to implement every
+ * extension method, which would defeat the whole point of the
+ * capability gate.
+ */
+type DOGraphClient = GraphClient<CloudflareCapability>;
+type DODynamicGraphClient = DynamicGraphClient<CloudflareCapability>;
 /**
  * Options for `createDOClient`. Same shape as `GraphClientOptions`; the DO
  * backend does not expose a table label of its own — the DO owns its SQLite
@@ -461,8 +665,8 @@ type DOClientOptions = GraphClientOptions;
  */
 declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options: DOClientOptions & {
     registryMode: DynamicRegistryConfig;
-}): DynamicGraphClient;
-declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options?: DOClientOptions): GraphClient;
+}): DODynamicGraphClient;
+declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options?: DOClientOptions): DOGraphClient;
 /**
  * Construct a peer `GraphClient` that shares `client`'s DO namespace and
  * construction options but targets a different root DO (i.e. a different
@@ -495,8 +699,8 @@ declare function createDOClient(namespace: FiregraphNamespace, rootKey: string,
  *                         as `createDOClient`'s `rootKey`: non-empty,
  *                         no `/`.
  */
-declare function createSiblingClient(client: GraphClient, siblingRootKey: string): GraphClient;
-declare function createSiblingClient(client: DynamicGraphClient, siblingRootKey: string): DynamicGraphClient;
+declare function createSiblingClient(client: DOGraphClient, siblingRootKey: string): DOGraphClient;
+declare function createSiblingClient(client: DODynamicGraphClient, siblingRootKey: string): DODynamicGraphClient;
 
 /**
  * Flat SQLite schema for a single firegraph DO.
@@ -551,4 +755,4 @@ interface BuildDOSchemaOptions {
  */
 declare function buildDOSchemaStatements(table: string, options?: BuildDOSchemaOptions): string[];
 
-export { type BatchOp, type BuildDOSchemaOptions, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, buildDOSchemaStatements, createDOClient, createSiblingClient };
+export { AggregateSpec, BackendCapabilities, type BatchOp, type BuildDOSchemaOptions, BulkUpdatePatch, type CloudflareCapability, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, ExpandParams, ExpandResult, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, buildDOSchemaStatements, createDOClient, createSiblingClient };