flowquery 1.0.70 → 1.0.71

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/README.md +456 -103
  2. package/dist/compute/provenance.d.ts +201 -0
  3. package/dist/compute/provenance.d.ts.map +1 -0
  4. package/dist/compute/provenance.js +216 -0
  5. package/dist/compute/provenance.js.map +1 -0
  6. package/dist/compute/runner.d.ts +196 -3
  7. package/dist/compute/runner.d.ts.map +1 -1
  8. package/dist/compute/runner.js +283 -2
  9. package/dist/compute/runner.js.map +1 -1
  10. package/dist/flowquery.min.js +1 -1
  11. package/dist/graph/bindings.d.ts.map +1 -1
  12. package/dist/graph/bindings.js +15 -1
  13. package/dist/graph/bindings.js.map +1 -1
  14. package/dist/graph/data_cache.d.ts +4 -0
  15. package/dist/graph/data_cache.d.ts.map +1 -1
  16. package/dist/graph/data_cache.js +15 -3
  17. package/dist/graph/data_cache.js.map +1 -1
  18. package/dist/graph/data_resolver.d.ts.map +1 -1
  19. package/dist/graph/data_resolver.js +23 -4
  20. package/dist/graph/data_resolver.js.map +1 -1
  21. package/dist/graph/physical_node.d.ts +4 -8
  22. package/dist/graph/physical_node.d.ts.map +1 -1
  23. package/dist/graph/physical_node.js +14 -85
  24. package/dist/graph/physical_node.js.map +1 -1
  25. package/dist/graph/physical_relationship.d.ts +4 -8
  26. package/dist/graph/physical_relationship.d.ts.map +1 -1
  27. package/dist/graph/physical_relationship.js +14 -85
  28. package/dist/graph/physical_relationship.js.map +1 -1
  29. package/dist/graph/relationship_match_collector.d.ts.map +1 -1
  30. package/dist/graph/relationship_match_collector.js +9 -0
  31. package/dist/graph/relationship_match_collector.js.map +1 -1
  32. package/dist/graph/virtual_sources.d.ts +8 -0
  33. package/dist/graph/virtual_sources.d.ts.map +1 -0
  34. package/dist/graph/virtual_sources.js +31 -0
  35. package/dist/graph/virtual_sources.js.map +1 -0
  36. package/dist/graph/virtual_statement.d.ts +41 -0
  37. package/dist/graph/virtual_statement.d.ts.map +1 -0
  38. package/dist/graph/virtual_statement.js +143 -0
  39. package/dist/graph/virtual_statement.js.map +1 -0
  40. package/dist/index.browser.d.ts +3 -3
  41. package/dist/index.browser.d.ts.map +1 -1
  42. package/dist/index.browser.js.map +1 -1
  43. package/dist/index.node.d.ts +3 -3
  44. package/dist/index.node.d.ts.map +1 -1
  45. package/dist/index.node.js.map +1 -1
  46. package/dist/parsing/operations/aggregated_return.d.ts +10 -0
  47. package/dist/parsing/operations/aggregated_return.d.ts.map +1 -1
  48. package/dist/parsing/operations/aggregated_return.js +56 -3
  49. package/dist/parsing/operations/aggregated_return.js.map +1 -1
  50. package/dist/parsing/operations/aggregated_with.d.ts +20 -0
  51. package/dist/parsing/operations/aggregated_with.d.ts.map +1 -1
  52. package/dist/parsing/operations/aggregated_with.js +33 -1
  53. package/dist/parsing/operations/aggregated_with.js.map +1 -1
  54. package/dist/parsing/operations/group_by.d.ts +32 -0
  55. package/dist/parsing/operations/group_by.d.ts.map +1 -1
  56. package/dist/parsing/operations/group_by.js +103 -0
  57. package/dist/parsing/operations/group_by.js.map +1 -1
  58. package/dist/parsing/operations/let.d.ts.map +1 -1
  59. package/dist/parsing/operations/let.js +53 -0
  60. package/dist/parsing/operations/let.js.map +1 -1
  61. package/dist/parsing/operations/load.d.ts +20 -0
  62. package/dist/parsing/operations/load.d.ts.map +1 -1
  63. package/dist/parsing/operations/load.js +71 -0
  64. package/dist/parsing/operations/load.js.map +1 -1
  65. package/dist/parsing/operations/order_by.d.ts +6 -0
  66. package/dist/parsing/operations/order_by.d.ts.map +1 -1
  67. package/dist/parsing/operations/order_by.js +10 -1
  68. package/dist/parsing/operations/order_by.js.map +1 -1
  69. package/dist/parsing/operations/return.d.ts +34 -0
  70. package/dist/parsing/operations/return.d.ts.map +1 -1
  71. package/dist/parsing/operations/return.js +95 -2
  72. package/dist/parsing/operations/return.js.map +1 -1
  73. package/dist/parsing/operations/union.d.ts +19 -2
  74. package/dist/parsing/operations/union.d.ts.map +1 -1
  75. package/dist/parsing/operations/union.js +47 -11
  76. package/dist/parsing/operations/union.js.map +1 -1
  77. package/dist/parsing/operations/union_all.d.ts +5 -1
  78. package/dist/parsing/operations/union_all.d.ts.map +1 -1
  79. package/dist/parsing/operations/union_all.js +8 -2
  80. package/dist/parsing/operations/union_all.js.map +1 -1
  81. package/dist/parsing/statement_info_crawler.d.ts +106 -0
  82. package/dist/parsing/statement_info_crawler.d.ts.map +1 -1
  83. package/dist/parsing/statement_info_crawler.js +231 -12
  84. package/dist/parsing/statement_info_crawler.js.map +1 -1
  85. package/package.json +1 -1
@@ -0,0 +1,201 @@
1
+ import Node from "../graph/node";
2
+ import Relationship from "../graph/relationship";
3
+ /**
4
+ * One observation that a particular alias was bound to a particular node id
5
+ * while a result row was being projected. For non-aggregate rows there is
6
+ * exactly one `NodeBinding` per registered node slot; aggregate rows may
7
+ * carry multiple observations under the same alias when distinct ids fed the
8
+ * group.
9
+ *
10
+ * `id` preserves the original scalar type from the underlying record (string,
11
+ * number, etc.). `id === null` indicates an OPTIONAL MATCH miss.
12
+ */
13
+ export interface NodeBinding {
14
+ /** The node identifier from the query (e.g. `a`), or `null` if anonymous. */
15
+ alias: string | null;
16
+ /** The matched label from the query (the first declared label), or `null`. */
17
+ label: string | null;
18
+ /** The concrete `id` value of the matched node, preserving scalar type. */
19
+ id: any;
20
+ /**
21
+ * Shallow snapshot of the matched record's property values (excluding
22
+ * `id` and internal `_label`). Present whenever the runner was
23
+ * constructed with `{ provenance: true }`.
24
+ */
25
+ properties?: Record<string, any>;
26
+ /**
27
+ * When the matched node came from a virtual
28
+ * `CREATE VIRTUAL (:X) AS { ... }` sub-query, this is the inner
29
+ * runner's `RowProvenance` row that produced the record. Omitted
30
+ * when the source is not a virtual.
31
+ */
32
+ source?: RowProvenance;
33
+ }
34
+ /**
35
+ * One traversed edge in a relationship binding. Variable-length matches
36
+ * (`[:T*m..n]`) contribute multiple hops; single-hop matches contribute one.
37
+ */
38
+ export interface RelationshipHop {
39
+ left_id: any;
40
+ right_id: any;
41
+ /** Resolved relationship type (may differ from the declared type when a
42
+ * virtual relationship spans multiple underlying types). */
43
+ type: string;
44
+ /**
45
+ * Shallow snapshot of the relationship record's property values.
46
+ * Present whenever the runner was constructed with
47
+ * `{ provenance: true }`.
48
+ */
49
+ properties?: Record<string, any>;
50
+ /**
51
+ * When the traversed edge came from a virtual
52
+ * relationship's inner sub-query, this is the inner runner's row
53
+ * provenance for the contributing record. Omitted otherwise.
54
+ */
55
+ source?: RowProvenance;
56
+ }
57
+ /**
58
+ * One observation that a particular relationship alias was bound to a
59
+ * concrete path of one or more hops while a result row was being projected.
60
+ */
61
+ export interface RelationshipBinding {
62
+ /** The relationship identifier from the query (e.g. `r`), or `null`. */
63
+ alias: string | null;
64
+ /** The declared relationship type from the query, or `null` when omitted. */
65
+ type: string | null;
66
+ /** The traversed edges in path order. */
67
+ hops: RelationshipHop[];
68
+ /**
69
+ * The ordered chain of node ids visited along the relationship match:
70
+ * `[hops[0].left_id, ...hops.map(h => h.right_id)]`. Always present.
71
+ * Empty for OPTIONAL-MATCH misses and zero-hop variable-length matches.
72
+ */
73
+ path: any[];
74
+ }
75
+ /**
76
+ * One observation that a particular `LOAD` operation contributed a row
77
+ * to the projected result. Records the resolved source name and,
78
+ * recursively, the inner provenance that backed the row when the
79
+ * source was a `LET`-bound dataset.
80
+ */
81
+ export interface DataSourceBinding {
82
+ /**
83
+ * The resolved source identifier: a URL, file URI, async-function
84
+ * name, or `let://<name>` reference for a `LET`-bound dataset.
85
+ */
86
+ source: string;
87
+ /**
88
+ * When the row came from a `LET`-backed array whose inner runner
89
+ * was executed with provenance, this is the inner runner's
90
+ * `RowProvenance` row for the loaded record. Provides recursive
91
+ * traceability back through the `LET`'s own sub-query (which may
92
+ * itself include `LOAD` operations). Omitted otherwise.
93
+ */
94
+ source_provenance?: RowProvenance;
95
+ }
96
+ /**
97
+ * One flat slice of bindings - either a single non-aggregate row's
98
+ * contribution, or one input row's contribution to an aggregate group.
99
+ * Sources (`ProvenanceSource.snapshot`) and the entries in
100
+ * `RowProvenance.rows` are all `RowSegment`s.
101
+ */
102
+ export interface RowSegment {
103
+ nodes: NodeBinding[];
104
+ relationships: RelationshipBinding[];
105
+ /**
106
+ * Data sources consumed while projecting this row. Populated when
107
+ * the pipeline includes a `LOAD` operation: one entry per emitted
108
+ * `Load` record. Each entry's `source` is the URL / file URI /
109
+ * async-function name / `let://name` reference; `source_provenance`
110
+ * is the inner `RowProvenance` row when the source was a
111
+ * `LET`-bound dataset. Omitted when the segment has no Load
112
+ * contributions.
113
+ */
114
+ data_sources?: DataSourceBinding[];
115
+ }
116
+ /**
117
+ * Row-level lineage aligned by index with `Runner.results`. Extends a
118
+ * single segment (the union of contributing bindings) with `rows`, the
119
+ * ordered per-input-row segments. For non-aggregate rows `rows.length`
120
+ * is 1; for aggregates it equals the number of input rows that fed the
121
+ * group, so `result.collectField[k]` aligns positionally with
122
+ * `provenance.rows[k]`.
123
+ */
124
+ export interface RowProvenance extends RowSegment {
125
+ rows: RowSegment[];
126
+ }
127
+ /**
128
+ * Anything that can produce a `RowSegment` for the row currently being
129
+ * emitted. Two implementations exist today:
130
+ *
131
+ * - {@link ProvenanceSites} — snapshots the live bindings of a MATCH's
132
+ * `Node` / `Relationship` slots at the moment of the emit.
133
+ * - `AggregatedWith` (in `aggregated_with.ts`) — replays the pre-computed
134
+ * segment of the group it is currently flushing downstream.
135
+ *
136
+ * The terminal `Return` (and intermediate `AggregatedWith` /
137
+ * `AggregatedReturn` operations) iterate their registered sources per row
138
+ * and concatenate the segments into a single `RowSegment`.
139
+ */
140
+ export interface ProvenanceSource {
141
+ snapshot(): RowSegment;
142
+ }
143
+ /**
144
+ * Concatenate one segment into a destination segment. Lives here so the
145
+ * merge order stays consistent across consumers (`Return`, `GroupBy`,
146
+ * `AggregatedWith`).
147
+ */
148
+ export declare function mergeProvenanceSegment(into: RowSegment, segment: RowSegment): void;
149
+ /**
150
+ * Holds the set of `Node` and `Relationship` slots discovered in a query's
151
+ * MATCH operations. These are stable references; their live state is read
152
+ * synchronously on each `snapshot()` call to capture the bindings active at
153
+ * that moment.
154
+ *
155
+ * The collector is opt-in via the `provenance` Runner option and zero-cost
156
+ * when disabled.
157
+ */
158
+ export declare class ProvenanceSites {
159
+ readonly nodes: Node[];
160
+ readonly relationships: Relationship[];
161
+ private readonly _seenNodeIdentifiers;
162
+ private readonly _seenRelationshipIdentifiers;
163
+ private _captureProperties;
164
+ /**
165
+ * Enable property-level capture for snapshots produced by this collector.
166
+ * Set by the Runner when constructed with `{ provenance: true }`.
167
+ */
168
+ set captureProperties(value: boolean);
169
+ /**
170
+ * Register a node slot. `NodeReference`s (re-bindings of a previously
171
+ * matched identifier) and duplicate named identifiers are skipped so the
172
+ * same alias does not produce multiple bindings.
173
+ */
174
+ addNode(node: Node): void;
175
+ /**
176
+ * Register a relationship slot. `RelationshipReference`s and duplicate
177
+ * named identifiers are skipped. Anonymous relationships are always
178
+ * added since each represents an independent traversal slot.
179
+ */
180
+ addRelationship(rel: Relationship): void;
181
+ get isEmpty(): boolean;
182
+ /**
183
+ * Capture the currently-bound id / hop values for every registered slot.
184
+ * Returns `null` for ids of slots that are not currently matched (e.g.
185
+ * OPTIONAL MATCH misses).
186
+ */
187
+ snapshot(): RowSegment;
188
+ }
189
+ /**
190
+ * Stable canonical key for deduplicating a `NodeBinding` within an aggregate
191
+ * group. Uses `JSON.stringify` to preserve scalar type distinctions
192
+ * (`1` vs `"1"`).
193
+ */
194
+ export declare function nodeBindingKey(b: NodeBinding): string;
195
+ /**
196
+ * Stable canonical key for deduplicating a `RelationshipBinding` within an
197
+ * aggregate group. Includes every hop so variable-length paths with the
198
+ * same alias but different traversals are treated as distinct.
199
+ */
200
+ export declare function relationshipBindingKey(b: RelationshipBinding): string;
201
+ //# sourceMappingURL=provenance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/compute/provenance.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,eAAe,CAAC;AAEjC,OAAO,YAAY,MAAM,uBAAuB,CAAC;AAIjD;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IACxB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,EAAE,EAAE,GAAG,CAAC;IACR;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,GAAG,CAAC;IACb,QAAQ,EAAE,GAAG,CAAC;IACd;iEAC6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yCAAyC;IACzC,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB;;;;OAIG;IACH,IAAI,EAAE,GAAG,EAAE,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,aAAa,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC7C,IAAI,EAAE,UAAU,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,IAAI,UAAU,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAOlF;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IACxB,SAAgB,KAAK,EAAE,IAAI,EAAE,CAAM;IACnC,SAAgB,aAAa,EAAE,YAAY,EAAE,CAAM;IACnD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA0B;IAC/D,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAA0B;IACvE,OAAO,CAAC,kBAAkB,CAAkB;IAE5C;;;OAGG;IACH,IAAW,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAE1C;IAED;;;;OAIG;IACI,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAUhC;;;;OAIG;IACI,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAU/C,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;OAIG;IACI,QAAQ,IAAI,UAAU;CAqDhC;AA8CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAOrE"}
@@ -0,0 +1,216 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.ProvenanceSites = void 0;
7
+ exports.mergeProvenanceSegment = mergeProvenanceSegment;
8
+ exports.nodeBindingKey = nodeBindingKey;
9
+ exports.relationshipBindingKey = relationshipBindingKey;
10
+ const node_reference_1 = __importDefault(require("../graph/node_reference"));
11
+ const relationship_reference_1 = __importDefault(require("../graph/relationship_reference"));
12
+ const virtual_sources_1 = require("../graph/virtual_sources");
13
+ /**
14
+ * Concatenate one segment into a destination segment. Lives here so the
15
+ * merge order stays consistent across consumers (`Return`, `GroupBy`,
16
+ * `AggregatedWith`).
17
+ */
18
+ function mergeProvenanceSegment(into, segment) {
19
+ for (const n of segment.nodes)
20
+ into.nodes.push(n);
21
+ for (const r of segment.relationships)
22
+ into.relationships.push(r);
23
+ if (segment.data_sources !== undefined && segment.data_sources.length > 0) {
24
+ if (into.data_sources === undefined)
25
+ into.data_sources = [];
26
+ for (const d of segment.data_sources)
27
+ into.data_sources.push(d);
28
+ }
29
+ }
30
+ /**
31
+ * Holds the set of `Node` and `Relationship` slots discovered in a query's
32
+ * MATCH operations. These are stable references; their live state is read
33
+ * synchronously on each `snapshot()` call to capture the bindings active at
34
+ * that moment.
35
+ *
36
+ * The collector is opt-in via the `provenance` Runner option and zero-cost
37
+ * when disabled.
38
+ */
39
+ class ProvenanceSites {
40
+ constructor() {
41
+ this.nodes = [];
42
+ this.relationships = [];
43
+ this._seenNodeIdentifiers = new Set();
44
+ this._seenRelationshipIdentifiers = new Set();
45
+ this._captureProperties = false;
46
+ }
47
+ /**
48
+ * Enable property-level capture for snapshots produced by this collector.
49
+ * Set by the Runner when constructed with `{ provenance: true }`.
50
+ */
51
+ set captureProperties(value) {
52
+ this._captureProperties = value;
53
+ }
54
+ /**
55
+ * Register a node slot. `NodeReference`s (re-bindings of a previously
56
+ * matched identifier) and duplicate named identifiers are skipped so the
57
+ * same alias does not produce multiple bindings.
58
+ */
59
+ addNode(node) {
60
+ if (node instanceof node_reference_1.default)
61
+ return;
62
+ const id = node.identifier;
63
+ if (id !== null) {
64
+ if (this._seenNodeIdentifiers.has(id))
65
+ return;
66
+ this._seenNodeIdentifiers.add(id);
67
+ }
68
+ this.nodes.push(node);
69
+ }
70
+ /**
71
+ * Register a relationship slot. `RelationshipReference`s and duplicate
72
+ * named identifiers are skipped. Anonymous relationships are always
73
+ * added since each represents an independent traversal slot.
74
+ */
75
+ addRelationship(rel) {
76
+ if (rel instanceof relationship_reference_1.default)
77
+ return;
78
+ const id = rel.identifier;
79
+ if (id !== null) {
80
+ if (this._seenRelationshipIdentifiers.has(id))
81
+ return;
82
+ this._seenRelationshipIdentifiers.add(id);
83
+ }
84
+ this.relationships.push(rel);
85
+ }
86
+ get isEmpty() {
87
+ return this.nodes.length === 0 && this.relationships.length === 0;
88
+ }
89
+ /**
90
+ * Capture the currently-bound id / hop values for every registered slot.
91
+ * Returns `null` for ids of slots that are not currently matched (e.g.
92
+ * OPTIONAL MATCH misses).
93
+ */
94
+ snapshot() {
95
+ var _a, _b, _c;
96
+ const captureProps = this._captureProperties;
97
+ const nodes = new Array(this.nodes.length);
98
+ for (let i = 0; i < this.nodes.length; i++) {
99
+ const node = this.nodes[i];
100
+ const v = node.value();
101
+ const binding = {
102
+ alias: node.identifier,
103
+ label: node.label,
104
+ id: v === null || v === undefined ? null : ((_a = v.id) !== null && _a !== void 0 ? _a : null),
105
+ };
106
+ if (captureProps && v !== null && v !== undefined) {
107
+ binding.properties = extractNodeProperties(v);
108
+ }
109
+ const src = v == null ? undefined : (0, virtual_sources_1.getVirtualSource)(v);
110
+ if (src !== undefined)
111
+ binding.source = src;
112
+ nodes[i] = binding;
113
+ }
114
+ const relationships = new Array(this.relationships.length);
115
+ for (let i = 0; i < this.relationships.length; i++) {
116
+ const rel = this.relationships[i];
117
+ const matches = rel.matches;
118
+ const hops = new Array(matches.length);
119
+ for (let j = 0; j < matches.length; j++) {
120
+ const m = matches[j];
121
+ const hop = {
122
+ left_id: m.startNode == null ? null : ((_b = m.startNode.id) !== null && _b !== void 0 ? _b : null),
123
+ right_id: m.endNode == null ? null : ((_c = m.endNode.id) !== null && _c !== void 0 ? _c : null),
124
+ type: m.type,
125
+ };
126
+ if (captureProps) {
127
+ hop.properties = extractRelationshipProperties(m);
128
+ }
129
+ const src = (0, virtual_sources_1.getVirtualSource)(m);
130
+ if (src !== undefined)
131
+ hop.source = src;
132
+ hops[j] = hop;
133
+ }
134
+ const path = hops.length === 0 ? [] : new Array(hops.length + 1);
135
+ if (hops.length > 0) {
136
+ path[0] = hops[0].left_id;
137
+ for (let k = 0; k < hops.length; k++) {
138
+ path[k + 1] = hops[k].right_id;
139
+ }
140
+ }
141
+ relationships[i] = {
142
+ alias: rel.identifier,
143
+ type: rel.type,
144
+ hops,
145
+ path,
146
+ };
147
+ }
148
+ return { nodes, relationships };
149
+ }
150
+ }
151
+ exports.ProvenanceSites = ProvenanceSites;
152
+ /**
153
+ * Shallow-copy a node record's user-visible property values, stripping
154
+ * `id` and the internal `_label` injected by `DataResolver`.
155
+ */
156
+ function extractNodeProperties(record) {
157
+ const out = {};
158
+ for (const key of Object.keys(record)) {
159
+ if (key === "id" || key === "_label")
160
+ continue;
161
+ out[key] = record[key];
162
+ }
163
+ return out;
164
+ }
165
+ /**
166
+ * Shallow-copy a relationship match record's property values, stripping
167
+ * the structural fields (`type`, `startNode`, `endNode`, `properties`,
168
+ * `left_id`, `right_id`, `_type`) so what remains are the user-declared
169
+ * edge properties.
170
+ */
171
+ function extractRelationshipProperties(match) {
172
+ // The match's nested `properties` field already holds the user-declared
173
+ // edge properties (set in `RelationshipMatchCollector.push`). Prefer
174
+ // that source when present; otherwise filter the structural fields.
175
+ if (match.properties && typeof match.properties === "object") {
176
+ return Object.assign({}, match.properties);
177
+ }
178
+ const out = {};
179
+ for (const key of Object.keys(match)) {
180
+ if (key === "type" ||
181
+ key === "startNode" ||
182
+ key === "endNode" ||
183
+ key === "properties" ||
184
+ key === "left_id" ||
185
+ key === "right_id" ||
186
+ key === "_type") {
187
+ continue;
188
+ }
189
+ out[key] = match[key];
190
+ }
191
+ return out;
192
+ }
193
+ /**
194
+ * Stable canonical key for deduplicating a `NodeBinding` within an aggregate
195
+ * group. Uses `JSON.stringify` to preserve scalar type distinctions
196
+ * (`1` vs `"1"`).
197
+ */
198
+ function nodeBindingKey(b) {
199
+ var _a;
200
+ return `${(_a = b.alias) !== null && _a !== void 0 ? _a : ""}\x00${JSON.stringify(b.id)}`;
201
+ }
202
+ /**
203
+ * Stable canonical key for deduplicating a `RelationshipBinding` within an
204
+ * aggregate group. Includes every hop so variable-length paths with the
205
+ * same alias but different traversals are treated as distinct.
206
+ */
207
+ function relationshipBindingKey(b) {
208
+ var _a;
209
+ let s = `${(_a = b.alias) !== null && _a !== void 0 ? _a : ""}\x00`;
210
+ for (let i = 0; i < b.hops.length; i++) {
211
+ const h = b.hops[i];
212
+ s += `${JSON.stringify(h.left_id)}|${JSON.stringify(h.right_id)}|${h.type};`;
213
+ }
214
+ return s;
215
+ }
216
+ //# sourceMappingURL=provenance.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../src/compute/provenance.ts"],"names":[],"mappings":"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"}
@@ -1,6 +1,110 @@
1
1
  import ASTNode from "../parsing/ast_node";
2
- import { StatementInfo } from "../parsing/statement_info_crawler";
3
- export type { StatementInfo } from "../parsing/statement_info_crawler";
2
+ import Operation from "../parsing/operations/operation";
3
+ import { ColumnLineage, ColumnReference, StatementInfo } from "../parsing/statement_info_crawler";
4
+ import { NodeBinding, RelationshipBinding, RowProvenance } from "./provenance";
5
+ export type { ColumnLineage, ColumnReference, StatementInfo, } from "../parsing/statement_info_crawler";
6
+ export type { DataSourceBinding, NodeBinding, RelationshipBinding, RelationshipHop, RowProvenance, } from "./provenance";
7
+ /**
8
+ * One slice of runtime provenance that contributed to a result cell.
9
+ * Pairs the column's `ColumnReference` (i.e. `alias.property`) with the
10
+ * matching node or relationship binding from the row provenance.
11
+ */
12
+ export interface CellBindingTrace {
13
+ /** The `alias.property` reference from `ColumnLineage.references` that this binding satisfies. */
14
+ reference: ColumnReference;
15
+ /**
16
+ * The observed value of `reference.property` on the matched
17
+ * record.
18
+ *
19
+ * - For nodes: `node.id` when `reference.property === 'id'`,
20
+ * otherwise `node.properties?.[reference.property]`.
21
+ * - For relationships: built-ins (`left_id`, `right_id`, `type`)
22
+ * come from `hops[0]` directly; everything else comes from
23
+ * `hops[0].properties`. For variable-length matches over
24
+ * heterogeneous edges, inspect `relationship.hops` to see
25
+ * per-hop values.
26
+ *
27
+ * `undefined` when the binding doesn't carry that property (e.g.
28
+ * an OPTIONAL MATCH miss).
29
+ */
30
+ value: any;
31
+ /** Present when `reference.kind === 'node'`. */
32
+ node?: NodeBinding;
33
+ /** Present when `reference.kind === 'relationship'`. */
34
+ relationship?: RelationshipBinding;
35
+ }
36
+ /**
37
+ * Combined lineage and provenance for a single result cell. Bundles
38
+ * the structural lineage from `metadata.info.returns[column]` with the
39
+ * runtime bindings from `provenance[rowIndex]` that contributed to the
40
+ * cell. Produced by {@link Runner.traceRow} and {@link Runner.lineage}.
41
+ */
42
+ export interface CellTrace {
43
+ /** The output column name. */
44
+ column: string;
45
+ /** The cell value (`results[rowIndex][column]`). */
46
+ value: any;
47
+ /**
48
+ * Structural lineage for the column, copied from
49
+ * `metadata.info.returns[column]`. `null` when the column has no
50
+ * recorded structural info (e.g. unusual statement shapes that
51
+ * don't surface a `RETURN` to the crawler).
52
+ */
53
+ lineage: ColumnLineage | null;
54
+ /**
55
+ * One entry per matching `(reference, binding)` pair for this row.
56
+ * Aggregate columns may have many entries (one per input row that
57
+ * fed the group); non-aggregate columns typically have one per
58
+ * distinct reference.
59
+ *
60
+ * Empty when the column is a literal, when the runner was not
61
+ * constructed with `{ provenance: true }`, or when no row binding
62
+ * matches the column's references.
63
+ */
64
+ bindings: CellBindingTrace[];
65
+ }
66
+ /**
67
+ * Combined structural lineage and per-row provenance for an entire
68
+ * Runner execution. Produced by {@link Runner.lineage}.
69
+ */
70
+ export interface LineageReport {
71
+ /**
72
+ * Structural per-column lineage; deep copy of
73
+ * `metadata.info?.returns ?? {}`.
74
+ */
75
+ columns: Record<string, ColumnLineage>;
76
+ /**
77
+ * One `{column → CellTrace}` map per result row, aligned by index
78
+ * with `results`. Each `CellTrace` already pairs the structural
79
+ * lineage with any matching row bindings.
80
+ */
81
+ rows: Record<string, CellTrace>[];
82
+ }
83
+ /**
84
+ * Optional configuration for a {@link Runner} or {@link FlowQuery}
85
+ * invocation.
86
+ */
87
+ export interface RunnerOptions {
88
+ /**
89
+ * When `true`, the runner records row-level data lineage alongside the
90
+ * results: for each emitted row, which concrete node ids and
91
+ * relationship `(left_id, right_id, type)` hops were bound while the
92
+ * row was being projected. Access via {@link Runner.provenance}.
93
+ *
94
+ * Each {@link NodeBinding} and {@link RelationshipHop} also carries:
95
+ *
96
+ * - `properties`: a shallow copy of the matched record's user-visible
97
+ * property values.
98
+ * - `source`: when the record came from a `CREATE VIRTUAL (:X) AS
99
+ * { ... }` sub-query, the inner runner's `RowProvenance` row that
100
+ * produced it. Recursive — a virtual that matches another virtual
101
+ * carries nested `source` chains.
102
+ *
103
+ * Defaults to `false`; when disabled the runner has zero provenance
104
+ * overhead.
105
+ */
106
+ provenance?: boolean;
107
+ }
4
108
  /**
5
109
  * Metadata about the operations performed by a Runner execution.
6
110
  *
@@ -43,15 +147,18 @@ declare class Runner {
43
147
  private _args;
44
148
  private _isTopLevel;
45
149
  private _metadata;
150
+ private _options;
151
+ private _provenance;
46
152
  /**
47
153
  * Creates a new Runner instance and parses the FlowQuery statement.
48
154
  *
49
155
  * @param statement - The FlowQuery statement to execute (may contain semicolon-separated statements)
50
156
  * @param ast - An optional pre-parsed AST to use instead of parsing the statement
51
157
  * @param args - Optional parameters to inject into $-prefixed parameter references
158
+ * @param options - Optional configuration (e.g. `{ provenance: true }`)
52
159
  * @throws {Error} If the statement is null, empty, or contains syntax errors
53
160
  */
54
- constructor(statement?: string | null, ast?: ASTNode | null, args?: Record<string, any> | null);
161
+ constructor(statement?: string | null, ast?: ASTNode | null, args?: Record<string, any> | null, options?: RunnerOptions);
55
162
  private static toStatement;
56
163
  /**
57
164
  * Walks all statement ASTs to count CREATE/DELETE operations and to
@@ -66,6 +173,34 @@ declare class Runner {
66
173
  * @throws {Error} If an error occurs during execution
67
174
  */
68
175
  run(): Promise<void>;
176
+ /**
177
+ * Walks the terminal statement's operation chain and wires every
178
+ * MATCH-bound `Node` / `Relationship` slot to the operation that
179
+ * will project it. Aggregation boundaries (`AggregatedWith`,
180
+ * `AggregatedReturn`) absorb upstream sites into their group-level
181
+ * accumulation; aggregations downstream of one another chain via
182
+ * each `AggregatedWith` re-exposing itself as a provenance source
183
+ * for the next consumer.
184
+ *
185
+ * Only the last statement may produce rows; preceding statements
186
+ * are limited to CREATE / DELETE / REFRESH / DROP and never need
187
+ * row-level provenance.
188
+ */
189
+ private enableProvenance;
190
+ /**
191
+ * Walk `first..terminal`, accumulating live MATCH sites into the
192
+ * "active" source list and handing it off at every aggregation
193
+ * boundary. Each `AggregatedWith` consumes the active list and then
194
+ * re-publishes itself as the single active source going forward.
195
+ * `Load` operations contribute per-row data-source bindings.
196
+ *
197
+ * Exposed as a public static so other components (e.g. `Let` when
198
+ * running a sub-query right-hand side) can wire provenance for an
199
+ * operation chain they drive directly, without going through the
200
+ * full `Runner.run` lifecycle.
201
+ */
202
+ static wireProvenance(first: Operation, sink: RowProvenance[]): void;
203
+ private static collectSitesFromPattern;
69
204
  /**
70
205
  * Recursively walks the AST to bind ParameterReference nodes
71
206
  * to the args provided to this Runner.
@@ -92,6 +227,64 @@ declare class Runner {
92
227
  * subsequent reads.
93
228
  */
94
229
  get metadata(): RunnerMetadata;
230
+ /**
231
+ * Row-level data lineage aligned by index with {@link results}.
232
+ *
233
+ * Each {@link RowProvenance} entry lists the concrete `id` values of the
234
+ * node slots and the `(left_id, right_id, type)` hops of the
235
+ * relationship slots that were bound while the corresponding result row
236
+ * was being projected.
237
+ *
238
+ * Returns an empty array unless the runner was constructed with
239
+ * `{ provenance: true }` or the query produced no rows.
240
+ */
241
+ get provenance(): RowProvenance[];
242
+ /**
243
+ * Convenience method that bundles structural lineage with row-level
244
+ * provenance for a single result row. Returns one {@link CellTrace}
245
+ * per output column, pairing the column's
246
+ * {@link ColumnLineage | structural lineage} (from
247
+ * {@link metadata}`.info.returns`) with the node / relationship
248
+ * bindings (from {@link provenance}) whose alias matches one of the
249
+ * column's references.
250
+ *
251
+ * Equivalent to manually correlating `metadata.info.returns[col]`
252
+ * with `provenance[rowIndex].nodes` / `.relationships`, but with
253
+ * the `(alias, property) -> binding` join and the per-property
254
+ * value extraction done for you.
255
+ *
256
+ * @param rowIndex - Zero-based index into {@link results}.
257
+ * @returns A `{column -> CellTrace}` map aligned with the row.
258
+ * @throws {RangeError} If `rowIndex` is out of bounds for `results`.
259
+ */
260
+ traceRow(rowIndex: number): Record<string, CellTrace>;
261
+ /**
262
+ * One-shot combined lineage and provenance report for the entire
263
+ * Runner execution. Returns the structural per-column lineage
264
+ * (deep copy of `metadata.info?.returns`) alongside one
265
+ * {@link traceRow} map per result row.
266
+ *
267
+ * Useful as a single object to hand to a UI, dump to a log, or
268
+ * snapshot for debugging. For per-cell lookups during normal flow,
269
+ * {@link traceRow} is cheaper.
270
+ */
271
+ lineage(): LineageReport;
272
+ private static cloneColumnLineage;
273
+ /**
274
+ * Resolve `binding.property` against a captured `NodeBinding`.
275
+ * The built-in `id` lives at the top of the binding (it's excluded
276
+ * from `properties`); everything else comes from `properties`.
277
+ */
278
+ private static readNodeProperty;
279
+ /**
280
+ * Resolve `binding.property` against a captured `RelationshipBinding`.
281
+ * Returns the value from `hops[0]`: the built-ins `left_id`,
282
+ * `right_id`, and `type` come from the hop itself, while everything
283
+ * else comes from `hops[0].properties`. For variable-length matches
284
+ * with heterogeneous hops, inspect `relationship.hops` directly to
285
+ * see per-hop values.
286
+ */
287
+ private static readRelationshipProperty;
95
288
  }
96
289
  export default Runner;
97
290
  //# sourceMappingURL=runner.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"AAGA,OAAO,OAAO,MAAM,qBAAqB,CAAC;AAS1C,OAA6B,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,YAAY,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6BAA6B,EAAE,MAAM,CAAC;IACtC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6BAA6B,EAAE,MAAM,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;CACxB;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM;IACR,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,SAAS,CAAiB;IAElC;;;;;;;OAOG;gBAEC,SAAS,GAAE,MAAM,GAAG,IAAW,EAC/B,GAAG,GAAE,OAAO,GAAG,IAAW,EAC1B,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAW;IAqB3C,OAAO,CAAC,MAAM,CAAC,WAAW;IAQ1B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;;OAKG;IACU,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAetB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;OAIG;IACH,IAAW,OAAO,IAAI,GAAG,CAExB;IAED;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,cAAc,CASpC;CACJ;AAED,eAAe,MAAM,CAAC"}
1
+ {"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"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"}