@stackables/bridge-compiler 0.0.1 → 1.0.1

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 (75) hide show
  1. package/README.md +49 -0
  2. package/build/bridge-compiler/src/bridge-format.d.ts +8 -0
  3. package/build/bridge-compiler/src/bridge-format.d.ts.map +1 -0
  4. package/build/{bridge-format.js → bridge-compiler/src/bridge-format.js} +9 -5
  5. package/build/{bridge-lint.d.ts.map → bridge-compiler/src/bridge-lint.d.ts.map} +1 -1
  6. package/build/{index.d.ts → bridge-compiler/src/index.d.ts} +3 -3
  7. package/build/bridge-compiler/src/index.d.ts.map +1 -0
  8. package/build/{index.js → bridge-compiler/src/index.js} +3 -3
  9. package/build/bridge-compiler/src/language-service.d.ts.map +1 -0
  10. package/build/{language-service.js → bridge-compiler/src/language-service.js} +47 -6
  11. package/build/{parser → bridge-compiler/src/parser}/index.d.ts +1 -1
  12. package/build/bridge-compiler/src/parser/index.d.ts.map +1 -0
  13. package/build/{parser → bridge-compiler/src/parser}/index.js +1 -1
  14. package/build/{parser → bridge-compiler/src/parser}/lexer.d.ts +1 -0
  15. package/build/bridge-compiler/src/parser/lexer.d.ts.map +1 -0
  16. package/build/{parser → bridge-compiler/src/parser}/lexer.js +155 -31
  17. package/build/{parser → bridge-compiler/src/parser}/parser.d.ts +12 -3
  18. package/build/bridge-compiler/src/parser/parser.d.ts.map +1 -0
  19. package/build/{parser → bridge-compiler/src/parser}/parser.js +63 -13
  20. package/build/bridge-core/src/ExecutionTree.d.ts +213 -0
  21. package/build/bridge-core/src/ExecutionTree.d.ts.map +1 -0
  22. package/build/bridge-core/src/ExecutionTree.js +1323 -0
  23. package/build/bridge-core/src/execute-bridge.d.ts +69 -0
  24. package/build/bridge-core/src/execute-bridge.d.ts.map +1 -0
  25. package/build/bridge-core/src/execute-bridge.js +52 -0
  26. package/build/bridge-core/src/index.d.ts +18 -0
  27. package/build/bridge-core/src/index.d.ts.map +1 -0
  28. package/build/bridge-core/src/index.js +20 -0
  29. package/build/bridge-core/src/merge-documents.d.ts +25 -0
  30. package/build/bridge-core/src/merge-documents.d.ts.map +1 -0
  31. package/build/bridge-core/src/merge-documents.js +91 -0
  32. package/build/bridge-core/src/tools/index.d.ts +2 -0
  33. package/build/bridge-core/src/tools/index.d.ts.map +1 -0
  34. package/build/bridge-core/src/tools/index.js +1 -0
  35. package/build/bridge-core/src/tools/internal.d.ts +71 -0
  36. package/build/bridge-core/src/tools/internal.d.ts.map +1 -0
  37. package/build/bridge-core/src/tools/internal.js +59 -0
  38. package/build/bridge-core/src/types.d.ts +349 -0
  39. package/build/bridge-core/src/types.d.ts.map +1 -0
  40. package/build/bridge-core/src/types.js +3 -0
  41. package/build/bridge-core/src/utils.d.ts +9 -0
  42. package/build/bridge-core/src/utils.d.ts.map +1 -0
  43. package/build/bridge-core/src/utils.js +23 -0
  44. package/build/bridge-core/src/version-check.d.ts +64 -0
  45. package/build/bridge-core/src/version-check.d.ts.map +1 -0
  46. package/build/bridge-core/src/version-check.js +205 -0
  47. package/build/bridge-stdlib/src/index.d.ts +34 -0
  48. package/build/bridge-stdlib/src/index.d.ts.map +1 -0
  49. package/build/bridge-stdlib/src/index.js +40 -0
  50. package/build/bridge-stdlib/src/tools/arrays.d.ts +28 -0
  51. package/build/bridge-stdlib/src/tools/arrays.d.ts.map +1 -0
  52. package/build/bridge-stdlib/src/tools/arrays.js +50 -0
  53. package/build/bridge-stdlib/src/tools/audit.d.ts +36 -0
  54. package/build/bridge-stdlib/src/tools/audit.d.ts.map +1 -0
  55. package/build/bridge-stdlib/src/tools/audit.js +39 -0
  56. package/build/bridge-stdlib/src/tools/http-call.d.ts +35 -0
  57. package/build/bridge-stdlib/src/tools/http-call.d.ts.map +1 -0
  58. package/build/bridge-stdlib/src/tools/http-call.js +118 -0
  59. package/build/bridge-stdlib/src/tools/strings.d.ts +13 -0
  60. package/build/bridge-stdlib/src/tools/strings.d.ts.map +1 -0
  61. package/build/bridge-stdlib/src/tools/strings.js +12 -0
  62. package/build/bridge-types/src/index.d.ts +63 -0
  63. package/build/bridge-types/src/index.d.ts.map +1 -0
  64. package/build/bridge-types/src/index.js +8 -0
  65. package/package.json +3 -3
  66. package/build/bridge-format.d.ts +0 -8
  67. package/build/bridge-format.d.ts.map +0 -1
  68. package/build/index.d.ts.map +0 -1
  69. package/build/language-service.d.ts.map +0 -1
  70. package/build/parser/index.d.ts.map +0 -1
  71. package/build/parser/lexer.d.ts.map +0 -1
  72. package/build/parser/parser.d.ts.map +0 -1
  73. /package/build/{bridge-lint.d.ts → bridge-compiler/src/bridge-lint.d.ts} +0 -0
  74. /package/build/{bridge-lint.js → bridge-compiler/src/bridge-lint.js} +0 -0
  75. /package/build/{language-service.d.ts → bridge-compiler/src/language-service.d.ts} +0 -0
@@ -5,7 +5,7 @@
5
5
  * Produces the *exact same* AST types (`Instruction[]`).
6
6
  */
7
7
  import { CstParser } from "chevrotain";
8
- import { allTokens, Identifier, VersionKw, ToolKw, BridgeKw, DefineKw, ConstKw, WithKw, AsKw, FromKw, InputKw, OutputKw, ContextKw, OnKw, ErrorKw, Arrow, ForceKw, AliasKw, AndKw, OrKw, NotKw, ThrowKw, PanicKw, ContinueKw, BreakKw, NullCoalesce, ErrorCoalesce, SafeNav, CatchKw, LParen, RParen, LCurly, RCurly, LSquare, RSquare, Equals, Dot, Colon, Comma, StringLiteral, NumberLiteral, PathToken, TrueLiteral, FalseLiteral, NullLiteral, Star, Slash, Plus, Minus, GreaterEqual, LessEqual, DoubleEquals, NotEquals, GreaterThan, LessThan, QuestionMark, BridgeLexer, } from "./lexer.js";
8
+ import { allTokens, Identifier, VersionKw, ToolKw, BridgeKw, DefineKw, ConstKw, WithKw, AsKw, FromKw, InputKw, OutputKw, ContextKw, OnKw, ErrorKw, Arrow, ForceKw, AliasKw, AndKw, OrKw, NotKw, ThrowKw, PanicKw, ContinueKw, BreakKw, NullCoalesce, ErrorCoalesce, SafeNav, CatchKw, LParen, RParen, LCurly, RCurly, LSquare, RSquare, Equals, Dot, Colon, Comma, StringLiteral, NumberLiteral, PathToken, TrueLiteral, FalseLiteral, NullLiteral, Star, Slash, Plus, Minus, GreaterEqual, LessEqual, DoubleEquals, NotEquals, GreaterThan, LessThan, QuestionMark, VersionTag, BridgeLexer, } from "./lexer.js";
9
9
  import { SELF_MODULE } from "@stackables/bridge-core";
10
10
  // ── Reserved-word guards (mirroring the regex parser) ──────────────────────
11
11
  const RESERVED_KEYWORDS = new Set([
@@ -160,6 +160,9 @@ class BridgeParser extends CstParser {
160
160
  },
161
161
  ALT: () => {
162
162
  this.SUBRULE(this.dottedName, { LABEL: "toolName" });
163
+ this.OPTION3(() => {
164
+ this.CONSUME(VersionTag, { LABEL: "toolVersion" });
165
+ });
163
166
  this.CONSUME3(AsKw);
164
167
  this.SUBRULE3(this.nameToken, { LABEL: "toolAlias" });
165
168
  },
@@ -350,6 +353,9 @@ class BridgeParser extends CstParser {
350
353
  },
351
354
  ALT: () => {
352
355
  this.SUBRULE(this.dottedName, { LABEL: "refName" });
356
+ this.OPTION6(() => {
357
+ this.CONSUME(VersionTag, { LABEL: "refVersion" });
358
+ });
353
359
  this.OPTION5(() => {
354
360
  this.CONSUME5(AsKw);
355
361
  this.SUBRULE5(this.nameToken, { LABEL: "refAlias" });
@@ -1051,6 +1057,19 @@ const parserInstance = new BridgeParser();
1051
1057
  // Lenient instance: error recovery enabled (used by parseBridgeDiagnostics)
1052
1058
  const diagParserInstance = new BridgeParser({ recovery: true });
1053
1059
  const BRIDGE_VERSION = "1.5";
1060
+ /** Minimum major version the parser can handle (inclusive). */
1061
+ const BRIDGE_MIN_MAJOR = 1;
1062
+ /** Maximum major version the parser can handle (inclusive). */
1063
+ const BRIDGE_MAX_MAJOR = 1;
1064
+ /** Exported parser version metadata for runtime use. */
1065
+ export const PARSER_VERSION = {
1066
+ /** Current bridge language version */
1067
+ current: BRIDGE_VERSION,
1068
+ /** Minimum supported major version (inclusive) */
1069
+ minMajor: BRIDGE_MIN_MAJOR,
1070
+ /** Maximum supported major version (inclusive) */
1071
+ maxMajor: BRIDGE_MAX_MAJOR,
1072
+ };
1054
1073
  // ═══════════════════════════════════════════════════════════════════════════
1055
1074
  // Public API
1056
1075
  // ═══════════════════════════════════════════════════════════════════════════
@@ -1100,11 +1119,11 @@ export function parseBridgeDiagnostics(text) {
1100
1119
  });
1101
1120
  }
1102
1121
  // 3. Visit → AST (semantic errors thrown as "Line N: ..." messages)
1103
- let instructions = [];
1122
+ let document = { instructions: [] };
1104
1123
  let startLines = new Map();
1105
1124
  try {
1106
1125
  const result = toBridgeAst(cst, []);
1107
- instructions = result.instructions;
1126
+ document = { version: result.version, instructions: result.instructions };
1108
1127
  startLines = result.startLines;
1109
1128
  }
1110
1129
  catch (err) {
@@ -1120,7 +1139,7 @@ export function parseBridgeDiagnostics(text) {
1120
1139
  },
1121
1140
  });
1122
1141
  }
1123
- return { instructions, diagnostics, startLines };
1142
+ return { document, diagnostics, startLines };
1124
1143
  }
1125
1144
  function internalParse(text, previousInstructions) {
1126
1145
  // 1. Lex
@@ -1137,7 +1156,8 @@ function internalParse(text, previousInstructions) {
1137
1156
  throw new Error(e.message);
1138
1157
  }
1139
1158
  // 3. Visit → AST
1140
- return toBridgeAst(cst, previousInstructions).instructions;
1159
+ const result = toBridgeAst(cst, previousInstructions);
1160
+ return { version: result.version, instructions: result.instructions };
1141
1161
  }
1142
1162
  // ═══════════════════════════════════════════════════════════════════════════
1143
1163
  // CST → AST transformation (imperative visitor)
@@ -2204,9 +2224,22 @@ function toBridgeAst(cst, previousInstructions) {
2204
2224
  }
2205
2225
  const versionTok = tok(versionDecl, "ver");
2206
2226
  const versionNum = versionTok?.image;
2207
- if (versionNum !== BRIDGE_VERSION) {
2208
- throw new Error(`Unsupported bridge version "${versionNum}". This parser requires: version ${BRIDGE_VERSION}`);
2227
+ if (!versionNum) {
2228
+ throw new Error(`Missing version number. Bridge files must begin with: version ${BRIDGE_VERSION}`);
2229
+ }
2230
+ // Accept any version whose major falls within the supported range.
2231
+ // When the parser supports multiple majors (e.g. 1.x through 2.x),
2232
+ // bridge files from any of them are valid syntax.
2233
+ const vParts = versionNum.split(".");
2234
+ const vMajor = parseInt(vParts[0], 10);
2235
+ const supportedRange = BRIDGE_MIN_MAJOR === BRIDGE_MAX_MAJOR
2236
+ ? `${BRIDGE_MIN_MAJOR}.x`
2237
+ : `${BRIDGE_MIN_MAJOR}.x – ${BRIDGE_MAX_MAJOR}.x`;
2238
+ if (isNaN(vMajor) || vMajor < BRIDGE_MIN_MAJOR || vMajor > BRIDGE_MAX_MAJOR) {
2239
+ throw new Error(`Unsupported bridge major version "${versionNum}". This parser supports version ${supportedRange}`);
2209
2240
  }
2241
+ // Store the declared version (lives on BridgeDocument, not in instructions).
2242
+ const version = versionNum;
2210
2243
  const tagged = [];
2211
2244
  for (const n of subs(cst, "constDecl"))
2212
2245
  tagged.push({
@@ -2270,7 +2303,7 @@ function toBridgeAst(cst, previousInstructions) {
2270
2303
  }
2271
2304
  }
2272
2305
  }
2273
- return { instructions, startLines };
2306
+ return { version, instructions, startLines };
2274
2307
  }
2275
2308
  // ── Const ───────────────────────────────────────────────────────────────
2276
2309
  function buildConstDef(node) {
@@ -2319,7 +2352,13 @@ function buildToolDef(node, previousInstructions) {
2319
2352
  else if (wc.toolName) {
2320
2353
  const tName = extractDottedName(wc.toolName[0]);
2321
2354
  const tAlias = extractNameToken(wc.toolAlias[0]);
2322
- deps.push({ kind: "tool", handle: tAlias, tool: tName });
2355
+ const tVersion = wc.toolVersion?.[0]?.image.slice(1);
2356
+ deps.push({
2357
+ kind: "tool",
2358
+ handle: tAlias,
2359
+ tool: tName,
2360
+ ...(tVersion ? { version: tVersion } : {}),
2361
+ });
2323
2362
  }
2324
2363
  continue;
2325
2364
  }
@@ -2400,10 +2439,10 @@ function buildBridge(node, previousInstructions) {
2400
2439
  `}`,
2401
2440
  ].join("\n");
2402
2441
  const result = internalParse(expandedText, previousInstructions);
2403
- const bridgeInst = result.find((i) => i.kind === "bridge");
2442
+ const bridgeInst = result.instructions.find((i) => i.kind === "bridge");
2404
2443
  if (bridgeInst)
2405
2444
  bridgeInst.passthrough = passthroughName;
2406
- return result;
2445
+ return result.instructions;
2407
2446
  }
2408
2447
  // Full bridge block
2409
2448
  const bodyLines = subs(node, "bridgeBodyLine");
@@ -2530,6 +2569,7 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
2530
2569
  }
2531
2570
  else if (wc.refName) {
2532
2571
  const name = extractDottedName(wc.refName[0]);
2572
+ const versionTag = wc.refVersion?.[0]?.image.slice(1);
2533
2573
  const lastDot = name.lastIndexOf(".");
2534
2574
  const defaultHandle = lastDot !== -1 ? name.substring(lastDot + 1) : name;
2535
2575
  const handle = wc.refAlias
@@ -2554,7 +2594,12 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
2554
2594
  const key = `${modulePart}:${fieldPart}`;
2555
2595
  const instance = (instanceCounters.get(key) ?? 0) + 1;
2556
2596
  instanceCounters.set(key, instance);
2557
- handleBindings.push({ handle, kind: "tool", name });
2597
+ handleBindings.push({
2598
+ handle,
2599
+ kind: "tool",
2600
+ name,
2601
+ ...(versionTag ? { version: versionTag } : {}),
2602
+ });
2558
2603
  handleRes.set(handle, {
2559
2604
  module: modulePart,
2560
2605
  type: bridgeType,
@@ -2566,7 +2611,12 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
2566
2611
  const key = `Tools:${name}`;
2567
2612
  const instance = (instanceCounters.get(key) ?? 0) + 1;
2568
2613
  instanceCounters.set(key, instance);
2569
- handleBindings.push({ handle, kind: "tool", name });
2614
+ handleBindings.push({
2615
+ handle,
2616
+ kind: "tool",
2617
+ name,
2618
+ ...(versionTag ? { version: versionTag } : {}),
2619
+ });
2570
2620
  handleRes.set(handle, {
2571
2621
  module: SELF_MODULE,
2572
2622
  type: "Tools",
@@ -0,0 +1,213 @@
1
+ import type { Bridge, BridgeDocument, ToolMap } from "./types.ts";
2
+ /** Fatal panic error — bypasses all error boundaries (`?.` and `catch`). */
3
+ export declare class BridgePanicError extends Error {
4
+ constructor(message: string);
5
+ }
6
+ /** Abort error — raised when an external AbortSignal cancels execution. */
7
+ export declare class BridgeAbortError extends Error {
8
+ constructor(message?: string);
9
+ }
10
+ /** Maximum shadow-tree nesting depth before a BridgePanicError is thrown. */
11
+ export declare const MAX_EXECUTION_DEPTH = 30;
12
+ /**
13
+ * Structured logger interface for Bridge engine events.
14
+ * Accepts any compatible logger: pino, winston, bunyan, `console`, etc.
15
+ * All methods default to silent no-ops when no logger is provided.
16
+ */
17
+ export interface Logger {
18
+ debug?: (...args: any[]) => void;
19
+ info?: (...args: any[]) => void;
20
+ warn?: (...args: any[]) => void;
21
+ error?: (...args: any[]) => void;
22
+ }
23
+ /** Matches graphql's internal Path type (not part of the public exports map) */
24
+ interface Path {
25
+ readonly prev: Path | undefined;
26
+ readonly key: string | number;
27
+ readonly typename: string | undefined;
28
+ }
29
+ type Trunk = {
30
+ module: string;
31
+ type: string;
32
+ field: string;
33
+ instance?: number;
34
+ };
35
+ /** Trace verbosity level.
36
+ * - `"off"` (default) — no collection, zero overhead
37
+ * - `"basic"` — tool, fn, timing, errors; no input/output
38
+ * - `"full"` — everything including input and output */
39
+ export type TraceLevel = "basic" | "full" | "off";
40
+ /** A single recorded tool invocation. */
41
+ export type ToolTrace = {
42
+ /** Tool name as resolved (e.g. "hereGeo", "std.str.toUpperCase") */
43
+ tool: string;
44
+ /** The function that was called (e.g. "httpCall", "upperCase") */
45
+ fn: string;
46
+ /** Input object passed to the tool function (only in "full" level) */
47
+ input?: Record<string, any>;
48
+ /** Resolved output (only in "full" level, on success) */
49
+ output?: any;
50
+ /** Error message (present when the tool threw) */
51
+ error?: string;
52
+ /** Wall-clock duration in milliseconds */
53
+ durationMs: number;
54
+ /** Monotonic timestamp (ms) relative to the first trace in the request */
55
+ startedAt: number;
56
+ };
57
+ /** Shared trace collector — one per request, passed through the tree. */
58
+ export declare class TraceCollector {
59
+ readonly traces: ToolTrace[];
60
+ readonly level: "basic" | "full";
61
+ private readonly epoch;
62
+ constructor(level?: "basic" | "full");
63
+ /** Returns ms since the collector was created */
64
+ now(): number;
65
+ record(trace: ToolTrace): void;
66
+ /** Build a trace entry, omitting input/output for basic level. */
67
+ entry(base: {
68
+ tool: string;
69
+ fn: string;
70
+ startedAt: number;
71
+ durationMs: number;
72
+ input?: Record<string, any>;
73
+ output?: any;
74
+ error?: string;
75
+ }): ToolTrace;
76
+ }
77
+ export declare class ExecutionTree {
78
+ trunk: Trunk;
79
+ private document;
80
+ private context?;
81
+ private parent?;
82
+ state: Record<string, any>;
83
+ bridge: Bridge | undefined;
84
+ private toolDepCache;
85
+ private toolDefCache;
86
+ private pipeHandleMap;
87
+ /**
88
+ * Maps trunk keys to `@version` strings from handle bindings.
89
+ * Populated in the constructor so `schedule()` can prefer versioned
90
+ * tool lookups (e.g. `std.str.toLowerCase@999.1`) over the default.
91
+ */
92
+ private handleVersionMap;
93
+ /** Promise that resolves when all critical `force` handles have settled. */
94
+ private forcedExecution?;
95
+ /** Shared trace collector — present only when tracing is enabled. */
96
+ tracer?: TraceCollector;
97
+ /** Structured logger passed from BridgeOptions. Defaults to no-ops. */
98
+ logger?: Logger;
99
+ /** External abort signal — cancels execution when triggered. */
100
+ signal?: AbortSignal;
101
+ private toolFns?;
102
+ /** Shadow-tree nesting depth (0 for root). */
103
+ private depth;
104
+ constructor(trunk: Trunk, document: BridgeDocument, toolFns?: ToolMap, context?: Record<string, any> | undefined, parent?: ExecutionTree | undefined);
105
+ /** Derive tool name from a trunk */
106
+ private getToolName;
107
+ /** Deep-lookup a tool function by dotted name (e.g. "std.str.toUpperCase").
108
+ * Falls back to a flat key lookup for backward compat (e.g. "hereapi.geocode" as literal key). */
109
+ private lookupToolFn;
110
+ /** Resolve a ToolDef by name, merging the extends chain (cached) */
111
+ private resolveToolDefByName;
112
+ /** Resolve a tool definition's wires into a nested input object */
113
+ private resolveToolWires;
114
+ /** Resolve a source reference from a tool wire against its dependencies */
115
+ private resolveToolSource;
116
+ /** Call a tool dependency (cached per request) */
117
+ private resolveToolDep;
118
+ schedule(target: Trunk, pullChain?: Set<string>): any;
119
+ /**
120
+ * Invoke a tool function, recording both an OpenTelemetry span and (when
121
+ * tracing is enabled) a ToolTrace entry. All three tool-call sites in the
122
+ * engine delegate here so instrumentation lives in exactly one place.
123
+ */
124
+ private callTool;
125
+ shadow(): ExecutionTree;
126
+ /** Returns collected traces (empty array when tracing is disabled). */
127
+ getTraces(): ToolTrace[];
128
+ private pullSingle;
129
+ push(args: Record<string, any>): void;
130
+ /** Store the aggregated promise for critical forced handles so
131
+ * `response()` can await it exactly once per bridge execution. */
132
+ setForcedExecution(p: Promise<void>): void;
133
+ /** Return the critical forced-execution promise (if any). */
134
+ getForcedExecution(): Promise<void> | undefined;
135
+ /**
136
+ * Eagerly schedule tools targeted by `force <handle>` statements.
137
+ *
138
+ * Returns an array of promises for **critical** forced handles (those
139
+ * without `?? null`). Fire-and-forget handles (`catchError: true`) are
140
+ * scheduled but their errors are silently suppressed.
141
+ *
142
+ * Callers must `await Promise.all(...)` the returned promises so that a
143
+ * critical force failure propagates as a standard error.
144
+ */
145
+ executeForced(): Promise<any>[];
146
+ /**
147
+ * Resolve a set of matched wires.
148
+ *
149
+ * Architecture: two distinct resolution axes —
150
+ *
151
+ * **Falsy Gate** (`||`, within a wire): `falsyFallbackRefs` + `falsyFallback`
152
+ * → truthy check — falsy values (0, "", false) trigger fallback chain.
153
+ *
154
+ * **Overdefinition** (across wires): multiple wires target the same path
155
+ * → nullish check — only null/undefined falls through to the next wire.
156
+ *
157
+ * Per-wire layers:
158
+ * Layer 1 — Execution (pullSingle + safe modifier)
159
+ * Layer 2a — Falsy Gate (falsyFallbackRefs → falsyFallback / falsyControl)
160
+ * Layer 2b — Nullish Gate (nullishFallbackRef / nullishFallback / nullishControl)
161
+ * Layer 3 — Catch (catchFallbackRef / catchFallback / catchControl)
162
+ *
163
+ * After layers 1–2b, the overdefinition boundary (`!= null`) decides whether
164
+ * to return or continue to the next wire.
165
+ */
166
+ private resolveWires;
167
+ /**
168
+ * Resolve an output field by path for use outside of a GraphQL resolver.
169
+ *
170
+ * This is the non-GraphQL equivalent of what `response()` does per field:
171
+ * it finds all wires targeting `this.trunk` at `path` and resolves them.
172
+ *
173
+ * Used by `executeBridge()` so standalone bridge execution does not need to
174
+ * fabricate GraphQL Path objects to pull output data.
175
+ *
176
+ * @param path - Output field path, e.g. `["lat"]`. Pass `[]` for whole-output
177
+ * array bridges (`o <- items[] as x { ... }`).
178
+ * @param array - When `true` and the result is an array, wraps each element
179
+ * in a shadow tree (mirrors `response()` array handling).
180
+ */
181
+ pullOutputField(path: string[], array?: boolean): Promise<unknown>;
182
+ /**
183
+ * Execute the bridge end-to-end without GraphQL.
184
+ *
185
+ * Injects `input` as the trunk arguments, runs forced wires, then pulls
186
+ * and materialises every output field into a plain JS object (or array of
187
+ * objects for array-mapped bridges).
188
+ *
189
+ * This is the single entry-point used by `executeBridge()`.
190
+ */
191
+ run(input: Record<string, unknown>): Promise<unknown>;
192
+ /**
193
+ * Recursively convert shadow trees into plain JS objects.
194
+ *
195
+ * Wire categories at each level (prefix = P):
196
+ * Leaf — `to.path = [...P, name]`, no deeper paths → scalar
197
+ * Array — direct wire AND deeper paths → pull as array, recurse
198
+ * Nested object — only deeper paths, no direct wire → pull each
199
+ * full path and assemble via setNested
200
+ */
201
+ private materializeShadows;
202
+ response(ipath: Path, array: boolean): Promise<any>;
203
+ /**
204
+ * Find define output wires for a specific field path.
205
+ *
206
+ * Looks for whole-object define forward wires (`o <- defineHandle`)
207
+ * at path=[] for this trunk, then searches the define's output wires
208
+ * for ones matching the requested field path.
209
+ */
210
+ private findDefineFieldWires;
211
+ }
212
+ export {};
213
+ //# sourceMappingURL=ExecutionTree.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ExecutionTree.d.ts","sourceRoot":"","sources":["../../../../bridge-core/src/ExecutionTree.ts"],"names":[],"mappings":"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"}