flowquery 1.0.70 → 1.0.71

package/dist/graph/virtual_sources.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachVirtualSource = attachVirtualSource;
+exports.getVirtualSource = getVirtualSource;
+/**
+ * Module-level back-reference from a virtual node / relationship record
+ * (or `RelationshipMatchRecord`) to the inner-runner `RowProvenance` that
+ * produced it.
+ *
+ * Used by deep-mode provenance to thread lineage from a `CREATE VIRTUAL
+ * (:X) AS { ... }` sub-query into the outer query's row-level bindings.
+ *
+ * Decoupled from `compute/provenance` to keep the graph layer free of
+ * compute imports — the value is typed as `unknown` here and re-cast by
+ * the snapshot code that consumes it.
+ */
+const virtualSources = new WeakMap();
+/** Register a virtual-sourced record with its inner provenance row. */
+function attachVirtualSource(record, prov) {
+    virtualSources.set(record, prov);
+}
+/**
+ * Look up the inner provenance for a record / match object.  Returns
+ * `undefined` if the value did not originate from a deep-mode virtual.
+ */
+function getVirtualSource(record) {
+    if (record == null)
+        return undefined;
+    return virtualSources.get(record);
+}
+//# sourceMappingURL=virtual_sources.js.map

package/dist/graph/virtual_sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual_sources.js","sourceRoot":"","sources":["../../src/graph/virtual_sources.ts"],"names":[],"mappings":";;AAeA,kDAEC;AAMD,4CAGC;AA1BD;;;;;;;;;;;GAWG;AACH,MAAM,cAAc,GAA6B,IAAI,OAAO,EAAE,CAAC;AAE/D,uEAAuE;AACvE,SAAgB,mBAAmB,CAAC,MAAc,EAAE,IAAa;IAC7D,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAiC;IAC9D,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,OAAO,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC"}

package/dist/graph/virtual_statement.d.ts

@@ -0,0 +1,41 @@
+import ASTNode from "../parsing/ast_node";
+/**
+ * Backing statement of a virtual node or relationship: owns the AST that
+ * synthesises the records and the optional in-memory cache around its
+ * execution.
+ *
+ * Used by {@link PhysicalNode} and {@link PhysicalRelationship} via
+ * composition so both physical kinds share a single caching + execution
+ * implementation.
+ */
+declare class VirtualStatement {
+    private _statement;
+    private _isStatic;
+    private _refreshEveryMs;
+    private _cache;
+    private _cachedAt;
+    set statement(statement: ASTNode | null);
+    get statement(): ASTNode | null;
+    set isStatic(value: boolean);
+    get isStatic(): boolean;
+    set refreshEveryMs(value: number | null);
+    get refreshEveryMs(): number | null;
+    invalidateCache(): void;
+    /** True if the cached payload (if any) is still within its refresh window. */
+    private isCacheFresh;
+    /**
+     * Execute the backing statement and return its records, using the
+     * persistent cache when it is safe to do so.
+     *
+     * @param args        Pass-down filter arguments; bypasses the cache.
+     * @param provenance  Run the inner statement with provenance enabled
+     *                    so each emitted record carries a weak-map link to
+     *                    the inner row that produced it.  Also bypasses the
+     *                    cache (the weak-map binding must be re-established
+     *                    each call).
+     */
+    data(args?: Record<string, any> | null, provenance?: boolean): Promise<Record<string, any>[]>;
+    private runInner;
+}
+export default VirtualStatement;
+//# sourceMappingURL=virtual_statement.d.ts.map

package/dist/graph/virtual_statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual_statement.d.ts","sourceRoot":"","sources":["../../src/graph/virtual_statement.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,qBAAqB,CAAC;AAG1C;;;;;;;;GAQG;AACH,cAAM,gBAAgB;IAClB,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,SAAS,CAAa;IAE9B,IAAW,SAAS,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,EAG7C;IACD,IAAW,SAAS,IAAI,OAAO,GAAG,IAAI,CAErC;IAED,IAAW,QAAQ,CAAC,KAAK,EAAE,OAAO,EAEjC;IACD,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,IAAW,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAE7C;IACD,IAAW,cAAc,IAAI,MAAM,GAAG,IAAI,CAEzC;IAEM,eAAe,IAAI,IAAI;IAK9B,8EAA8E;IAC9E,OAAO,CAAC,YAAY;IAIpB;;;;;;;;;;OAUG;IACU,IAAI,CACb,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAW,EACvC,UAAU,GAAE,OAAe,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YAoBnB,QAAQ;CAoBzB;AAED,eAAe,gBAAgB,CAAC"}

package/dist/graph/virtual_statement.js

@@ -0,0 +1,143 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const virtual_sources_1 = require("./virtual_sources");
+/**
+ * Backing statement of a virtual node or relationship: owns the AST that
+ * synthesises the records and the optional in-memory cache around its
+ * execution.
+ *
+ * Used by {@link PhysicalNode} and {@link PhysicalRelationship} via
+ * composition so both physical kinds share a single caching + execution
+ * implementation.
+ */
+class VirtualStatement {
+    constructor() {
+        this._statement = null;
+        this._isStatic = false;
+        this._refreshEveryMs = null;
+        this._cache = null;
+        this._cachedAt = 0;
+    }
+    set statement(statement) {
+        this._statement = statement;
+        this.invalidateCache();
+    }
+    get statement() {
+        return this._statement;
+    }
+    set isStatic(value) {
+        this._isStatic = value;
+    }
+    get isStatic() {
+        return this._isStatic;
+    }
+    set refreshEveryMs(value) {
+        this._refreshEveryMs = value;
+    }
+    get refreshEveryMs() {
+        return this._refreshEveryMs;
+    }
+    invalidateCache() {
+        this._cache = null;
+        this._cachedAt = 0;
+    }
+    /** True if the cached payload (if any) is still within its refresh window. */
+    isCacheFresh() {
+        return this._refreshEveryMs === null || Date.now() - this._cachedAt < this._refreshEveryMs;
+    }
+    /**
+     * Execute the backing statement and return its records, using the
+     * persistent cache when it is safe to do so.
+     *
+     * @param args        Pass-down filter arguments; bypasses the cache.
+     * @param provenance  Run the inner statement with provenance enabled
+     *                    so each emitted record carries a weak-map link to
+     *                    the inner row that produced it.  Also bypasses the
+     *                    cache (the weak-map binding must be re-established
+     *                    each call).
+     */
+    data() {
+        return __awaiter(this, arguments, void 0, function* (args = null, provenance = false) {
+            if (this._statement === null) {
+                throw new Error("Statement is null");
+            }
+            // Filter pass-down queries (with args) and provenance mode bypass
+            // the persistent cache: arg-bound results depend on runtime values,
+            // and provenance mode needs fresh records to back the lineage
+            // weak-map.
+            const cacheable = !provenance && args === null && this._isStatic;
+            if (cacheable && this._cache !== null && this.isCacheFresh()) {
+                return this._cache;
+            }
+            const result = yield this.runInner(args, provenance);
+            if (cacheable) {
+                this._cache = result;
+                this._cachedAt = Date.now();
+            }
+            return result;
+        });
+    }
+    runInner(args, provenance) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Lazy dynamic import to avoid a load-time cycle:
+            // virtual_statement -> runner -> parsing -> graph (back to here).
+            // Python uses the same idiom (function-local import).
+            const RunnerCtor = (yield Promise.resolve().then(() => __importStar(require("../compute/runner")))).default;
+            const runner = new RunnerCtor(null, this._statement, args, { provenance });
+            yield runner.run();
+            const result = runner.results;
+            if (provenance) {
+                const prov = runner.provenance;
+                const len = Math.min(prov.length, result.length);
+                for (let i = 0; i < len; i++) {
+                    (0, virtual_sources_1.attachVirtualSource)(result[i], prov[i]);
+                }
+            }
+            return result;
+        });
+    }
+}
+exports.default = VirtualStatement;
+//# sourceMappingURL=virtual_statement.js.map

package/dist/graph/virtual_statement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual_statement.js","sourceRoot":"","sources":["../../src/graph/virtual_statement.ts"],"names":[],"mappings":"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"}

package/dist/index.browser.d.ts

@@ -6,8 +6,8 @@
  * @packageDocumentation
  */
 import { default as FlowQuery } from "./compute/flowquery";
-import type { RunnerMetadata } from "./compute/runner";
-import type { NodeInfo, RelationshipInfo, StatementInfo } from "./parsing/statement_info_crawler";
+import type { CellBindingTrace, CellTrace, LineageReport, NodeBinding, RelationshipBinding, RelationshipHop, RowProvenance, RunnerMetadata, RunnerOptions } from "./compute/runner";
+import type { ColumnLineage, ColumnReference, NodeInfo, RelationshipInfo, StatementInfo } from "./parsing/statement_info_crawler";
 export default FlowQuery;
-export type { NodeInfo, RelationshipInfo, RunnerMetadata, StatementInfo };
+export type { CellBindingTrace, CellTrace, ColumnLineage, ColumnReference, LineageReport, NodeBinding, NodeInfo, RelationshipBinding, RelationshipHop, RelationshipInfo, RowProvenance, RunnerMetadata, RunnerOptions, StatementInfo, };
 //# sourceMappingURL=index.browser.d.ts.map

package/dist/index.browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQvD,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AA+BlG,eAAe,SAAS,CAAC;AACzB,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EACR,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EAChB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,KAAK,EACR,aAAa,EACb,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,aAAa,EAChB,MAAM,kCAAkC,CAAC;AA+B1C,eAAe,SAAS,CAAC;AACzB,YAAY,EACR,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,eAAe,EACf,aAAa,EACb,WAAW,EACX,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,aAAa,EACb,aAAa,GAChB,CAAC"}

package/dist/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":";;;;;AAAA;;;;;;GAMG;AACH,oEAA2D;AAE3D,4EAAoD;AACpD,4FAAmE;AAQnE;;;;;GAKG;AACH,mBAAS,CAAC,aAAa,GAAG,UAAU,OAInC;IACG,OAAO,0BAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,mBAAS,CAAC,mBAAmB,GAAG,UAAU,IAAY;IAClD,OAAO,0BAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC;AAEF;;GAEG;AACH,mBAAS,CAAC,QAAQ,GAAG,kBAAQ,CAAC;AAE9B,kBAAe,mBAAS,CAAC"}
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":";;;;;AAAA;;;;;;GAMG;AACH,oEAA2D;AAY3D,4EAAoD;AACpD,4FAAmE;AAcnE;;;;;GAKG;AACH,mBAAS,CAAC,aAAa,GAAG,UAAU,OAInC;IACG,OAAO,0BAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,mBAAS,CAAC,mBAAmB,GAAG,UAAU,IAAY;IAClD,OAAO,0BAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC;AAEF;;GAEG;AACH,mBAAS,CAAC,QAAQ,GAAG,kBAAQ,CAAC;AAE9B,kBAAe,mBAAS,CAAC"}

package/dist/index.node.d.ts

@@ -6,11 +6,11 @@
  * @packageDocumentation
  */
 import { default as FlowQuery } from "./compute/flowquery";
-import { RunnerMetadata } from "./compute/runner";
+import { CellBindingTrace, CellTrace, LineageReport, RunnerMetadata } from "./compute/runner";
 import Function from "./parsing/functions/function";
 import FunctionFactory, { AsyncDataProvider } from "./parsing/functions/function_factory";
 import { FunctionMetadata, OutputSchema, ParameterSchema } from "./parsing/functions/function_metadata";
-import { NodeInfo, RelationshipInfo, StatementInfo } from "./parsing/statement_info_crawler";
+import { ColumnLineage, ColumnReference, NodeInfo, RelationshipInfo, StatementInfo } from "./parsing/statement_info_crawler";
 export default FlowQuery;
-export { FlowQuery, Function, FunctionFactory, AsyncDataProvider, FunctionMetadata, ParameterSchema, OutputSchema, RunnerMetadata, StatementInfo, NodeInfo, RelationshipInfo, };
+export { FlowQuery, Function, FunctionFactory, AsyncDataProvider, FunctionMetadata, ParameterSchema, OutputSchema, RunnerMetadata, StatementInfo, NodeInfo, RelationshipInfo, ColumnLineage, ColumnReference, CellTrace, CellBindingTrace, LineageReport, };
 //# sourceMappingURL=index.node.d.ts.map

package/dist/index.node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.node.d.ts","sourceRoot":"","sources":["../src/index.node.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,QAAQ,MAAM,8BAA8B,CAAC;AACpD,OAAO,eAAe,EAAE,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EACH,gBAAgB,EAChB,YAAY,EACZ,eAAe,EAClB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AA+B7F,eAAe,SAAS,CAAC;AACzB,OAAO,EACH,SAAS,EACT,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,gBAAgB,GACnB,CAAC"}
+{"version":3,"file":"index.node.d.ts","sourceRoot":"","sources":["../src/index.node.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC9F,OAAO,QAAQ,MAAM,8BAA8B,CAAC;AACpD,OAAO,eAAe,EAAE,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EACH,gBAAgB,EAChB,YAAY,EACZ,eAAe,EAClB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACH,aAAa,EACb,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,aAAa,EAChB,MAAM,kCAAkC,CAAC;AA+B1C,eAAe,SAAS,CAAC;AACzB,OAAO,EACH,SAAS,EACT,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,aAAa,GAChB,CAAC"}

package/dist/index.node.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.node.js","sourceRoot":"","sources":["../src/index.node.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;GAMG;AACH,oEAA2D;AA0CvD,0FA1CgB,mBAAS,OA0ChB;AAxCb,4EAAoD;AAyChD,mBAzCG,kBAAQ,CAyCH;AAxCZ,4FAA0F;AAyCtF,0BAzCG,0BAAe,CAyCH;AAjCnB;;;;;GAKG;AACH,mBAAS,CAAC,aAAa,GAAG,UAAU,OAInC;IACG,OAAO,0BAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,mBAAS,CAAC,mBAAmB,GAAG,UAAU,IAAY;IAClD,OAAO,0BAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC;AAEF;;GAEG;AACH,mBAAS,CAAC,QAAQ,GAAG,kBAAQ,CAAC;AAE9B,kBAAe,mBAAS,CAAC"}
+{"version":3,"file":"index.node.js","sourceRoot":"","sources":["../src/index.node.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;GAMG;AACH,oEAA2D;AAgDvD,0FAhDgB,mBAAS,OAgDhB;AA9Cb,4EAAoD;AA+ChD,mBA/CG,kBAAQ,CA+CH;AA9CZ,4FAA0F;AA+CtF,0BA/CG,0BAAe,CA+CH;AAjCnB;;;;;GAKG;AACH,mBAAS,CAAC,aAAa,GAAG,UAAU,OAInC;IACG,OAAO,0BAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,mBAAS,CAAC,mBAAmB,GAAG,UAAU,IAAY;IAClD,OAAO,0BAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC,CAAC;AAEF;;GAEG;AACH,mBAAS,CAAC,QAAQ,GAAG,kBAAQ,CAAC;AAE9B,kBAAe,mBAAS,CAAC"}

package/dist/parsing/operations/aggregated_return.d.ts

@@ -1,8 +1,18 @@
+import { ProvenanceSource } from "../../compute/provenance";
 import Return from "./return";
 declare class AggregatedReturn extends Return {
     private _group_by;
     run(): Promise<void>;
+    /**
+     * Provenance sources registered on an aggregate RETURN are folded
+     * into the active group's dedup maps rather than snapshotted per
+     * row, because each output row corresponds to a *group* of upstream
+     * matches.  Override to route through the embedded `GroupBy`.
+     */
+    addProvenanceSource(source: ProvenanceSource): void;
     get results(): Record<string, any>[];
+    finish(): Promise<void>;
+    private _buildAggregateOutput;
 }
 export default AggregatedReturn;
 //# sourceMappingURL=aggregated_return.d.ts.map

package/dist/parsing/operations/aggregated_return.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregated_return.d.ts","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_return.ts"],"names":[],"mappings":"AAEA,OAAO,MAAM,MAAM,UAAU,CAAC;AAE9B,cAAM,gBAAiB,SAAQ,MAAM;IACjC,OAAO,CAAC,SAAS,CAAuD;IAC3D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAGjC,IAAW,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAS1C;CACJ;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"aggregated_return.d.ts","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_return.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAiB,MAAM,0BAA0B,CAAC;AAI3E,OAAO,MAAM,MAAM,UAAU,CAAC;AAE9B,cAAM,gBAAiB,SAAQ,MAAM;IACjC,OAAO,CAAC,SAAS,CAAuD;IAC3D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAGjC;;;;;OAKG;IACI,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAG1D,IAAW,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAG1C;IACY,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAWpC,OAAO,CAAC,qBAAqB;CAmChC;AAED,eAAe,gBAAgB,CAAC"}

package/dist/parsing/operations/aggregated_return.js

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const group_by_1 = __importDefault(require("./group_by"));
+const operation_1 = __importDefault(require("./operation"));
 const return_1 = __importDefault(require("./return"));
 class AggregatedReturn extends return_1.default {
     constructor() {
@@ -24,15 +25,67 @@ class AggregatedReturn extends return_1.default {
             yield this._group_by.run();
         });
     }
+    /**
+     * Provenance sources registered on an aggregate RETURN are folded
+     * into the active group's dedup maps rather than snapshotted per
+     * row, because each output row corresponds to a *group* of upstream
+     * matches.  Override to route through the embedded `GroupBy`.
+     */
+    addProvenanceSource(source) {
+        this._group_by.addProvenanceSource(source);
+    }
     get results() {
+        const { results } = this._buildAggregateOutput();
+        return results;
+    }
+    finish() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this._provenanceSink !== null) {
+                const { provenance } = this._buildAggregateOutput();
+                this._provenanceSink.length = 0;
+                for (const p of provenance)
+                    this._provenanceSink.push(p);
+            }
+            // Skip Return.finish() because it would re-materialise provenance
+            // from the empty per-row `_results` array; chain straight to the
+            // next operation instead.
+            yield operation_1.default.prototype.finish.call(this);
+        });
+    }
+    _buildAggregateOutput() {
         if (this._where !== null) {
             this._group_by.where = this._where;
         }
-        const results = Array.from(this._group_by.generate_results());
+        const results = [];
+        const provenance = [];
+        // Emit a provenance entry per result row whenever a sink is
+        // registered, even if no provenance sources were attached (e.g.
+        // `RETURN count(*)` over no MATCH).  This keeps
+        // `runner.provenance.length === runner.results.length`.
+        const wantProvenance = this._provenanceSink !== null;
+        if (wantProvenance) {
+            const recordIter = this._group_by.generate_results();
+            const provIter = this._group_by.generate_provenance();
+            while (true) {
+                const r = recordIter.next();
+                const p = provIter.next();
+                if (r.done || p.done)
+                    break;
+                results.push(r.value);
+                provenance.push(p.value);
+            }
+        }
+        else {
+            for (const r of this._group_by.generate_results())
+                results.push(r);
+        }
         if (this._orderBy !== null) {
-            return this._orderBy.sort(results);
+            const indices = this._orderBy.sortIndices(results);
+            const sorted = indices.map((i) => results[i]);
+            const sortedProv = wantProvenance ? indices.map((i) => provenance[i]) : provenance;
+            return { results: sorted, provenance: sortedProv };
         }
-        return results;
+        return { results, provenance };
     }
 }
 exports.default = AggregatedReturn;

package/dist/parsing/operations/aggregated_return.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregated_return.js","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_return.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AACA,0DAAiC;AACjC,sDAA8B;AAE9B,MAAM,gBAAiB,SAAQ,gBAAM;IAArC;;QACY,cAAS,GAAY,IAAI,kBAAO,CAAC,IAAI,CAAC,QAAwB,CAAC,CAAC;IAc5E,CAAC;IAbgB,GAAG;;YACZ,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QAC/B,CAAC;KAAA;IACD,IAAW,OAAO;QACd,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;QACvC,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC9D,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;CACJ;AAED,kBAAe,gBAAgB,CAAC"}
+{"version":3,"file":"aggregated_return.js","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_return.ts"],"names":[],"mappings":"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"}

package/dist/parsing/operations/aggregated_with.d.ts

@@ -1,7 +1,27 @@
+import { ProvenanceSource } from "../../compute/provenance";
 import With from "./return";
 declare class AggregatedWith extends With {
     private _group_by;
+    /**
+     * Iterator over the per-group provenance produced by `_group_by`.
+     * Advanced in lockstep with `generate_results()` inside `finish()` so
+     * that `_currentGroupProvenance` always reflects the group whose row
+     * the downstream pipeline is about to project.
+     */
+    private _currentGroupProvenance;
     run(): Promise<void>;
+    /**
+     * Forward upstream provenance sources into the embedded `GroupBy`
+     * so each group accumulates the union of contributing bindings.
+     */
+    addProvenanceSource(source: ProvenanceSource): void;
+    /**
+     * Expose this aggregation as a downstream provenance source.  When
+     * the downstream pipeline projects a row, it snapshots us and
+     * receives the pre-computed provenance for the group currently being
+     * flushed by `finish()`.
+     */
+    asProvenanceSource(): ProvenanceSource;
     finish(): Promise<void>;
 }
 export default AggregatedWith;

package/dist/parsing/operations/aggregated_with.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregated_with.d.ts","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_with.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,UAAU,CAAC;AAI5B,cAAM,cAAe,SAAQ,IAAI;IAC7B,OAAO,CAAC,SAAS,CAAuD;IAC3D,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAGpB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"aggregated_with.d.ts","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_with.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAiB,MAAM,0BAA0B,CAAC;AAG3E,OAAO,IAAI,MAAM,UAAU,CAAC;AAE5B,cAAM,cAAe,SAAQ,IAAI;IAC7B,OAAO,CAAC,SAAS,CAAuD;IACxE;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB,CAA8B;IAChD,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAGjC;;;OAGG;IACI,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAG1D;;;;;OAKG;IACI,kBAAkB,IAAI,gBAAgB;IAMhC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAavC;AAED,eAAe,cAAc,CAAC"}

package/dist/parsing/operations/aggregated_with.js

@@ -12,27 +12,59 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const return_1 = __importDefault(require("./return"));
 const group_by_1 = __importDefault(require("./group_by"));
+const return_1 = __importDefault(require("./return"));
 class AggregatedWith extends return_1.default {
     constructor() {
         super(...arguments);
         this._group_by = new group_by_1.default(this.children);
+        /**
+         * Iterator over the per-group provenance produced by `_group_by`.
+         * Advanced in lockstep with `generate_results()` inside `finish()` so
+         * that `_currentGroupProvenance` always reflects the group whose row
+         * the downstream pipeline is about to project.
+         */
+        this._currentGroupProvenance = null;
     }
     run() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this._group_by.run();
         });
     }
+    /**
+     * Forward upstream provenance sources into the embedded `GroupBy`
+     * so each group accumulates the union of contributing bindings.
+     */
+    addProvenanceSource(source) {
+        this._group_by.addProvenanceSource(source);
+    }
+    /**
+     * Expose this aggregation as a downstream provenance source.  When
+     * the downstream pipeline projects a row, it snapshots us and
+     * receives the pre-computed provenance for the group currently being
+     * flushed by `finish()`.
+     */
+    asProvenanceSource() {
+        return {
+            snapshot: () => { var _a; return (_a = this._currentGroupProvenance) !== null && _a !== void 0 ? _a : { nodes: [], relationships: [], rows: [] }; },
+        };
+    }
     finish() {
         const _super = Object.create(null, {
             finish: { get: () => super.finish }
         });
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
+            const wantProvenance = this._group_by.provenanceEnabled;
+            const provIter = wantProvenance ? this._group_by.generate_provenance() : null;
             for (const _ of this._group_by.generate_results()) {
+                if (provIter !== null) {
+                    const next = provIter.next();
+                    this._currentGroupProvenance = next.done ? null : next.value;
+                }
                 yield ((_a = this.next) === null || _a === void 0 ? void 0 : _a.run());
             }
+            this._currentGroupProvenance = null;
             yield _super.finish.call(this);
         });
     }

package/dist/parsing/operations/aggregated_with.js.map

@@ -1 +1 @@
-{"version":3,"file":"aggregated_with.js","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_with.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAAA,sDAA4B;AAC5B,0DAAiC;AAGjC,MAAM,cAAe,SAAQ,gBAAI;IAAjC;;QACY,cAAS,GAAY,IAAI,kBAAO,CAAC,IAAI,CAAC,QAAwB,CAAC,CAAC;IAU5E,CAAC;IATgB,GAAG;;YACZ,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QAC/B,CAAC;KAAA;IACY,MAAM;;;;;;YACf,KAAI,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,gBAAgB,EAAE,EAAE,CAAC;gBAC/C,MAAM,CAAA,MAAA,IAAI,CAAC,IAAI,0CAAE,GAAG,EAAE,CAAA,CAAC;YAC3B,CAAC;YACD,MAAM,OAAM,MAAM,WAAE,CAAC;QACzB,CAAC;KAAA;CACJ;AAED,kBAAe,cAAc,CAAC"}
+{"version":3,"file":"aggregated_with.js","sourceRoot":"","sources":["../../../src/parsing/operations/aggregated_with.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAEA,0DAAiC;AACjC,sDAA4B;AAE5B,MAAM,cAAe,SAAQ,gBAAI;IAAjC;;QACY,cAAS,GAAY,IAAI,kBAAO,CAAC,IAAI,CAAC,QAAwB,CAAC,CAAC;QACxE;;;;;WAKG;QACK,4BAAuB,GAAyB,IAAI,CAAC;IAoCjE,CAAC;IAnCgB,GAAG;;YACZ,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QAC/B,CAAC;KAAA;IACD;;;OAGG;IACI,mBAAmB,CAAC,MAAwB;QAC/C,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IACD;;;;;OAKG;IACI,kBAAkB;QACrB,OAAO;YACH,QAAQ,EAAE,GAAkB,EAAE,WAC1B,OAAA,MAAA,IAAI,CAAC,uBAAuB,mCAAI,EAAE,KAAK,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA,EAAA;SACjF,CAAC;IACN,CAAC;IACY,MAAM;;;;;;YACf,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC;YACxD,MAAM,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAC9E,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,gBAAgB,EAAE,EAAE,CAAC;gBAChD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;oBACpB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;oBAC7B,IAAI,CAAC,uBAAuB,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;gBACjE,CAAC;gBACD,MAAM,CAAA,MAAA,IAAI,CAAC,IAAI,0CAAE,GAAG,EAAE,CAAA,CAAC;YAC3B,CAAC;YACD,IAAI,CAAC,uBAAuB,GAAG,IAAI,CAAC;YACpC,MAAM,OAAM,MAAM,WAAE,CAAC;QACzB,CAAC;KAAA;CACJ;AAED,kBAAe,cAAc,CAAC"}

package/dist/parsing/operations/group_by.d.ts

@@ -1,3 +1,4 @@
+import { NodeBinding, ProvenanceSource, RelationshipBinding, RowProvenance, RowSegment } from "../../compute/provenance";
 import AggregationElement from "../functions/reducer_element";
 import Projection from "./projection";
 import Where from "./where";
@@ -5,11 +6,25 @@ declare class Node {
     private _value;
     private _children;
     private _elements;
+    private _provenanceNodes;
+    private _provenanceRels;
+    private _provenanceRows;
     constructor(value?: any);
     get value(): any;
     get children(): Map<string, Node>;
     get elements(): AggregationElement[] | null;
     set elements(elements: AggregationElement[]);
+    /** Per-group dedup map for contributing node bindings (lazy). */
+    get provenanceNodes(): Map<string, NodeBinding>;
+    /** Per-group dedup map for contributing relationship bindings (lazy). */
+    get provenanceRelationships(): Map<string, RelationshipBinding>;
+    /**
+     * Per-input-row contribution segments in arrival order.  One entry is
+     * appended per `GroupBy.run()` call that lands in this group, so an
+     * aggregate row's `provenance.rows` aligns positionally with
+     * `collect(...)` outputs from the same group.
+     */
+    get provenanceRows(): RowSegment[];
 }
 declare class GroupBy extends Projection {
     private _root;
@@ -17,7 +32,17 @@ declare class GroupBy extends Projection {
     private _mappers;
     private _reducers;
     protected _where: Where | null;
+    private _provenanceSources;
     run(): Promise<void>;
+    /**
+     * Register a provenance source whose snapshot is folded into the
+     * currently active group on every `run()`.  May be called multiple
+     * times to compose contributions from several upstream MATCHes or
+     * upstream aggregation boundaries.
+     */
+    addProvenanceSource(source: ProvenanceSource): void;
+    get provenanceEnabled(): boolean;
+    private recordProvenance;
     private get root();
     private get current();
     private set current(value);
@@ -28,6 +53,13 @@ declare class GroupBy extends Projection {
     private _generate_mappers;
     private get reducers();
     generate_results(mapperIndex?: number, node?: Node): Generator<Record<string, any>>;
+    /**
+     * Walks the group tree in the same traversal order as
+     * {@link generate_results}, yielding the materialised {@link
+     * RowProvenance} for each emitted group.  When provenance is
+     * disabled, yields empty entries so callers can still zip cleanly.
+     */
+    generate_provenance(mapperIndex?: number, node?: Node): Generator<RowProvenance>;
     set where(where: Where);
     get where(): boolean;
 }

package/dist/parsing/operations/group_by.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group_by.d.ts","sourceRoot":"","sources":["../../../src/parsing/operations/group_by.ts"],"names":[],"mappings":"AAEA,OAAO,kBAAkB,MAAM,8BAA8B,CAAC;AAC9D,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,SAAS,CAAC;AAE5B,cAAM,IAAI;IACN,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,SAAS,CAAqC;gBAC1C,KAAK,GAAE,GAAU;IAG7B,IAAW,KAAK,IAAI,GAAG,CAEtB;IACD,IAAW,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAEvC;IACD,IAAW,QAAQ,IAAI,kBAAkB,EAAE,GAAG,IAAI,CAEjD;IACD,IAAW,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,EAEjD;CACJ;AAED,cAAM,OAAQ,SAAQ,UAAU;IAC5B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,SAAS,CAAoC;IACrD,SAAS,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAQ;IACzB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,OAAO,KAAK,IAAI,GAEf;IACD,OAAO,KAAK,OAAO,GAElB;IACD,OAAO,KAAK,OAAO,QAElB;IACD,OAAO,CAAC,SAAS;IAGjB,OAAO,CAAC,GAAG;IAeX,OAAO,CAAC,MAAM;IASd,OAAO,KAAK,OAAO,GAKlB;IACD,OAAO,CAAE,iBAAiB;IAO1B,OAAO,KAAK,QAAQ,GASnB;IACO,gBAAgB,CACpB,WAAW,GAAE,MAAU,EACvB,IAAI,GAAE,IAAgB,GACvB,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAyBjC,IAAW,KAAK,CAAC,KAAK,EAAE,KAAK,EAE5B;IACD,IAAW,KAAK,IAAI,OAAO,CAK1B;CACJ;AAED,eAAe,OAAO,CAAC"}
+{"version":3,"file":"group_by.d.ts","sourceRoot":"","sources":["../../../src/parsing/operations/group_by.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,UAAU,EAGb,MAAM,0BAA0B,CAAC;AAGlC,OAAO,kBAAkB,MAAM,8BAA8B,CAAC;AAC9D,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,SAAS,CAAC;AAE5B,cAAM,IAAI;IACN,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,eAAe,CAAiD;IACxE,OAAO,CAAC,eAAe,CAA6B;gBACxC,KAAK,GAAE,GAAU;IAG7B,IAAW,KAAK,IAAI,GAAG,CAEtB;IACD,IAAW,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAEvC;IACD,IAAW,QAAQ,IAAI,kBAAkB,EAAE,GAAG,IAAI,CAEjD;IACD,IAAW,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,EAEjD;IACD,iEAAiE;IACjE,IAAW,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAKrD;IACD,yEAAyE;IACzE,IAAW,uBAAuB,IAAI,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAKrE;IACD;;;;;OAKG;IACH,IAAW,cAAc,IAAI,UAAU,EAAE,CAKxC;CACJ;AAED,cAAM,OAAQ,SAAQ,UAAU;IAC5B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,SAAS,CAAoC;IACrD,SAAS,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAQ;IACtC,OAAO,CAAC,kBAAkB,CAAmC;IAChD,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;;;OAKG;IACI,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAM1D,IAAW,iBAAiB,IAAI,OAAO,CAEtC;IACD,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,KAAK,IAAI,GAEf;IACD,OAAO,KAAK,OAAO,GAElB;IACD,OAAO,KAAK,OAAO,QAElB;IACD,OAAO,CAAC,SAAS;IAGjB,OAAO,CAAC,GAAG;IAeX,OAAO,CAAC,MAAM;IASd,OAAO,KAAK,OAAO,GAKlB;IACD,OAAO,CAAE,iBAAiB;IAO1B,OAAO,KAAK,QAAQ,GASnB;IACO,gBAAgB,CACpB,WAAW,GAAE,MAAU,EACvB,IAAI,GAAE,IAAgB,GACvB,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAyBjC;;;;;OAKG;IACK,mBAAmB,CACvB,WAAW,GAAE,MAAU,EACvB,IAAI,GAAE,IAAgB,GACvB,SAAS,CAAC,aAAa,CAAC;IAwB3B,IAAW,KAAK,CAAC,KAAK,EAAE,KAAK,EAE5B;IACD,IAAW,KAAK,IAAI,OAAO,CAK1B;CACJ;AAED,eAAe,OAAO,CAAC"}