@stackables/bridge-core 0.0.1

package/build/execute-bridge.d.ts

@@ -0,0 +1,57 @@
+import type { Logger, ToolTrace, TraceLevel } from "./ExecutionTree.ts";
+import type { Instruction, ToolMap } from "./types.ts";
+export type ExecuteBridgeOptions = {
+    /** Parsed bridge instructions (from `parseBridgeDiagnostics`). */
+    instructions: Instruction[];
+    /**
+     * Which bridge to execute, as `"Type.field"`.
+     * Mirrors the `bridge Type.field { ... }` declaration.
+     * Example: `"Query.searchTrains"` or `"Mutation.sendEmail"`.
+     */
+    operation: string;
+    /** Input arguments — equivalent to GraphQL field arguments. */
+    input?: Record<string, unknown>;
+    /** Additional tools to merge with the built-in `std` namespace. */
+    tools?: ToolMap;
+    /** Context available via `with context as ctx` inside the bridge. */
+    context?: Record<string, unknown>;
+    /**
+     * Enable tool-call tracing.
+     * - `"off"` (default) — no collection, zero overhead
+     * - `"basic"` — tool, fn, timing, errors; no input/output
+     * - `"full"` — everything including input and output
+     */
+    trace?: TraceLevel;
+    /** Structured logger for engine events. */
+    logger?: Logger;
+    /** External abort signal — cancels execution when triggered. */
+    signal?: AbortSignal;
+};
+export type ExecuteBridgeResult<T = unknown> = {
+    data: T;
+    traces: ToolTrace[];
+};
+/**
+ * Execute a bridge operation without GraphQL.
+ *
+ * Runs a bridge file's data-wiring logic standalone — no schema, no server,
+ * no HTTP layer required. Useful for CLI tools, background jobs, tests, and
+ * any context where you want Bridge's declarative data-fetching outside of
+ * a GraphQL server.
+ *
+ * @example
+ * ```ts
+ * import { parseBridgeDiagnostics, executeBridge } from "@stackables/bridge";
+ * import { readFileSync } from "node:fs";
+ *
+ * const { instructions } = parseBridgeDiagnostics(readFileSync("my.bridge", "utf8"));
+ * const { data } = await executeBridge({
+ *   instructions,
+ *   operation: "Query.myField",
+ *   input: { city: "Berlin" },
+ * });
+ * console.log(data);
+ * ```
+ */
+export declare function executeBridge<T = unknown>(options: ExecuteBridgeOptions): Promise<ExecuteBridgeResult<T>>;
+//# sourceMappingURL=execute-bridge.d.ts.map

package/build/execute-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-bridge.d.ts","sourceRoot":"","sources":["../src/execute-bridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAIvD,MAAM,MAAM,oBAAoB,GAAG;IACjC,kEAAkE;IAClE,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC7C,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CA+BjC"}

package/build/execute-bridge.js

@@ -0,0 +1,45 @@
+import { ExecutionTree, TraceCollector } from "./ExecutionTree.js";
+import { SELF_MODULE } from "./types.js";
+import { std } from "@stackables/bridge-stdlib";
+/**
+ * Execute a bridge operation without GraphQL.
+ *
+ * Runs a bridge file's data-wiring logic standalone — no schema, no server,
+ * no HTTP layer required. Useful for CLI tools, background jobs, tests, and
+ * any context where you want Bridge's declarative data-fetching outside of
+ * a GraphQL server.
+ *
+ * @example
+ * ```ts
+ * import { parseBridgeDiagnostics, executeBridge } from "@stackables/bridge";
+ * import { readFileSync } from "node:fs";
+ *
+ * const { instructions } = parseBridgeDiagnostics(readFileSync("my.bridge", "utf8"));
+ * const { data } = await executeBridge({
+ *   instructions,
+ *   operation: "Query.myField",
+ *   input: { city: "Berlin" },
+ * });
+ * console.log(data);
+ * ```
+ */
+export async function executeBridge(options) {
+    const { instructions, operation, input = {}, context = {} } = options;
+    const parts = operation.split(".");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`Invalid operation "${operation}" — expected "Type.field" (e.g. "Query.myField")`);
+    }
+    const [type, field] = parts;
+    const trunk = { module: SELF_MODULE, type, field };
+    const tree = new ExecutionTree(trunk, instructions, { std, ...(options.tools ?? {}) }, context);
+    if (options.logger)
+        tree.logger = options.logger;
+    if (options.signal)
+        tree.signal = options.signal;
+    const traceLevel = options.trace ?? "off";
+    if (traceLevel !== "off") {
+        tree.tracer = new TraceCollector(traceLevel);
+    }
+    const data = await tree.run(input);
+    return { data: data, traces: tree.getTraces() };
+}

package/build/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @stackables/bridge-core — The Bridge runtime engine.
+ *
+ * Contains the execution engine, type system, internal tools (math, logic,
+ * string concat), and utilities.  Given pre-parsed `Instruction[]` (JSON AST),
+ * you can execute a bridge without pulling in the parser (Chevrotain) or
+ * GraphQL dependencies.
+ */
+export { executeBridge } from "./execute-bridge.ts";
+export type { ExecuteBridgeOptions, ExecuteBridgeResult, } from "./execute-bridge.ts";
+export { ExecutionTree, TraceCollector, BridgeAbortError, BridgePanicError, } from "./ExecutionTree.ts";
+export type { Logger, ToolTrace, TraceLevel } from "./ExecutionTree.ts";
+export { SELF_MODULE } from "./types.ts";
+export type { Bridge, CacheStore, ConstDef, ControlFlowInstruction, DefineDef, HandleBinding, Instruction, NodeRef, ToolCallFn, ToolContext, ToolDef, ToolDep, ToolMap, ToolWire, Wire, } from "./types.ts";
+export { parsePath } from "./utils.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIxE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EACV,MAAM,EACN,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,SAAS,EACT,aAAa,EACb,WAAW,EACX,OAAO,EACP,UAAU,EACV,WAAW,EACX,OAAO,EACP,OAAO,EACP,OAAO,EACP,QAAQ,EACR,IAAI,GACL,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/build/index.js

@@ -0,0 +1,16 @@
+/**
+ * @stackables/bridge-core — The Bridge runtime engine.
+ *
+ * Contains the execution engine, type system, internal tools (math, logic,
+ * string concat), and utilities.  Given pre-parsed `Instruction[]` (JSON AST),
+ * you can execute a bridge without pulling in the parser (Chevrotain) or
+ * GraphQL dependencies.
+ */
+// ── Runtime engine ──────────────────────────────────────────────────────────
+export { executeBridge } from "./execute-bridge.js";
+// ── Execution tree (advanced) ───────────────────────────────────────────────
+export { ExecutionTree, TraceCollector, BridgeAbortError, BridgePanicError, } from "./ExecutionTree.js";
+// ── Types ───────────────────────────────────────────────────────────────────
+export { SELF_MODULE } from "./types.js";
+// ── Utilities ───────────────────────────────────────────────────────────────
+export { parsePath } from "./utils.js";

package/build/tools/index.d.ts

@@ -0,0 +1,2 @@
+export * as internal from "./internal.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC"}

package/build/tools/index.js

@@ -0,0 +1 @@
+export * as internal from "./internal.js";

package/build/tools/internal.d.ts

@@ -0,0 +1,71 @@
+/** Add two numbers. Returns `a + b`. */
+export declare function add(opts: {
+    a: number;
+    b: number;
+}): number;
+/** Subtract two numbers. Returns `a - b`. */
+export declare function subtract(opts: {
+    a: number;
+    b: number;
+}): number;
+/** Multiply two numbers. Returns `a * b`. */
+export declare function multiply(opts: {
+    a: number;
+    b: number;
+}): number;
+/** Divide two numbers. Returns `a / b`. */
+export declare function divide(opts: {
+    a: number;
+    b: number;
+}): number;
+/** Strict equality. Returns `true` if `a === b`, `false` otherwise. */
+export declare function eq(opts: {
+    a: any;
+    b: any;
+}): boolean;
+/** Strict inequality. Returns `true` if `a !== b`, `false` otherwise. */
+export declare function neq(opts: {
+    a: any;
+    b: any;
+}): boolean;
+/** Greater than. Returns `true` if `a > b`, `false` otherwise. */
+export declare function gt(opts: {
+    a: number;
+    b: number;
+}): boolean;
+/** Greater than or equal. Returns `true` if `a >= b`, `false` otherwise. */
+export declare function gte(opts: {
+    a: number;
+    b: number;
+}): boolean;
+/** Less than. Returns `true` if `a < b`, `false` otherwise. */
+export declare function lt(opts: {
+    a: number;
+    b: number;
+}): boolean;
+/** Less than or equal. Returns `true` if `a <= b`, `false` otherwise. */
+export declare function lte(opts: {
+    a: number;
+    b: number;
+}): boolean;
+/** Logical NOT. Returns `true` if `a` is falsy. */
+export declare function not(opts: {
+    a: any;
+}): boolean;
+/** Logical AND. Returns `true` if both `a` and `b` are truthy. */
+export declare function and(opts: {
+    a: any;
+    b: any;
+}): boolean;
+/** Logical OR. Returns `true` if either `a` or `b` is truthy. */
+export declare function or(opts: {
+    a: any;
+    b: any;
+}): boolean;
+/** String concatenation. Joins all parts into a single string. */
+export declare function concat(opts: {
+    parts: unknown[];
+}): {
+    value: string;
+};
+//# sourceMappingURL=internal.d.ts.map

package/build/tools/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/tools/internal.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,wBAAgB,GAAG,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE1D;AACD,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE/D;AACD,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE/D;AACD,2CAA2C;AAC3C,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE7D;AACD,uEAAuE;AACvE,wBAAgB,EAAE,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAEpD;AACD,yEAAyE;AACzE,wBAAgB,GAAG,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAErD;AACD,kEAAkE;AAClE,wBAAgB,EAAE,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE1D;AACD,4EAA4E;AAC5E,wBAAgB,GAAG,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE3D;AACD,+DAA+D;AAC/D,wBAAgB,EAAE,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE1D;AACD,yEAAyE;AACzE,wBAAgB,GAAG,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE3D;AACD,mDAAmD;AACnD,wBAAgB,GAAG,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAE7C;AACD,kEAAkE;AAClE,wBAAgB,GAAG,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAErD;AACD,iEAAiE;AACjE,wBAAgB,EAAE,CAAC,IAAI,EAAE;IAAE,CAAC,EAAE,GAAG,CAAC;IAAC,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAEpD;AACD,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAKpE"}

package/build/tools/internal.js

@@ -0,0 +1,59 @@
+/** Add two numbers. Returns `a + b`. */
+export function add(opts) {
+    return Number(opts.a) + Number(opts.b);
+}
+/** Subtract two numbers. Returns `a - b`. */
+export function subtract(opts) {
+    return Number(opts.a) - Number(opts.b);
+}
+/** Multiply two numbers. Returns `a * b`. */
+export function multiply(opts) {
+    return Number(opts.a) * Number(opts.b);
+}
+/** Divide two numbers. Returns `a / b`. */
+export function divide(opts) {
+    return Number(opts.a) / Number(opts.b);
+}
+/** Strict equality. Returns `true` if `a === b`, `false` otherwise. */
+export function eq(opts) {
+    return opts.a === opts.b;
+}
+/** Strict inequality. Returns `true` if `a !== b`, `false` otherwise. */
+export function neq(opts) {
+    return opts.a !== opts.b;
+}
+/** Greater than. Returns `true` if `a > b`, `false` otherwise. */
+export function gt(opts) {
+    return Number(opts.a) > Number(opts.b);
+}
+/** Greater than or equal. Returns `true` if `a >= b`, `false` otherwise. */
+export function gte(opts) {
+    return Number(opts.a) >= Number(opts.b);
+}
+/** Less than. Returns `true` if `a < b`, `false` otherwise. */
+export function lt(opts) {
+    return Number(opts.a) < Number(opts.b);
+}
+/** Less than or equal. Returns `true` if `a <= b`, `false` otherwise. */
+export function lte(opts) {
+    return Number(opts.a) <= Number(opts.b);
+}
+/** Logical NOT. Returns `true` if `a` is falsy. */
+export function not(opts) {
+    return !opts.a;
+}
+/** Logical AND. Returns `true` if both `a` and `b` are truthy. */
+export function and(opts) {
+    return Boolean(opts.a) && Boolean(opts.b);
+}
+/** Logical OR. Returns `true` if either `a` or `b` is truthy. */
+export function or(opts) {
+    return Boolean(opts.a) || Boolean(opts.b);
+}
+/** String concatenation. Joins all parts into a single string. */
+export function concat(opts) {
+    const result = (opts.parts ?? [])
+        .map((v) => (v == null ? "" : String(v)))
+        .join("");
+    return { value: result };
+}

package/build/types.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Structured node reference — identifies a specific data point in the execution graph.
+ *
+ * Every wire has a "from" and "to", each described by a NodeRef.
+ * The trunk (module + type + field + instance) identifies the node,
+ * while path drills into its data.
+ */
+export type NodeRef = {
+    /** Module identifier: "hereapi", "sendgrid", "zillow", or SELF_MODULE */
+    module: string;
+    /** GraphQL type ("Query" | "Mutation") or "Tools" for tool functions */
+    type: string;
+    /** Field or function name: "geocode", "search", "centsToUsd" */
+    field: string;
+    /** Instance number for tool calls (1, 2, ...) */
+    instance?: number;
+    /** References the current array element in a shadow tree (for per-element mapping) */
+    element?: boolean;
+    /** Path into the data: ["items", "0", "position", "lat"] */
+    path: string[];
+    /** True when the first `?.` is right after the root (e.g., `api?.data`) */
+    rootSafe?: boolean;
+    /** Per-segment safety flags (same length as `path`); true = `?.` before that segment */
+    pathSafe?: boolean[];
+};
+/**
+ * A wire connects a data source (from) to a data sink (to).
+ * Execution is pull-based: when "to" is demanded, "from" is resolved.
+ *
+ * Constant wires (`=`) set a fixed value on the target.
+ * Pull wires (`<-`) resolve the source at runtime.
+ * Pipe wires (`pipe: true`) are generated by the `<- h1:h2:source` shorthand
+ * and route data through declared tool handles; the serializer collapses them
+ * back to pipe notation.
+ */
+export type Wire = {
+    from: NodeRef;
+    to: NodeRef;
+    pipe?: true;
+    safe?: true;
+    falsyFallbackRefs?: NodeRef[];
+    falsyFallback?: string;
+    falsyControl?: ControlFlowInstruction;
+    nullishFallback?: string;
+    nullishFallbackRef?: NodeRef;
+    nullishControl?: ControlFlowInstruction;
+    catchFallback?: string;
+    catchFallbackRef?: NodeRef;
+    catchControl?: ControlFlowInstruction;
+} | {
+    value: string;
+    to: NodeRef;
+} | {
+    cond: NodeRef;
+    thenRef?: NodeRef;
+    thenValue?: string;
+    elseRef?: NodeRef;
+    elseValue?: string;
+    to: NodeRef;
+    falsyFallbackRefs?: NodeRef[];
+    falsyFallback?: string;
+    falsyControl?: ControlFlowInstruction;
+    nullishFallback?: string;
+    nullishFallbackRef?: NodeRef;
+    nullishControl?: ControlFlowInstruction;
+    catchFallback?: string;
+    catchFallbackRef?: NodeRef;
+    catchControl?: ControlFlowInstruction;
+} | {
+    /** Short-circuit logical AND: evaluate left first, only evaluate right if left is truthy */
+    condAnd: {
+        leftRef: NodeRef;
+        rightRef?: NodeRef;
+        rightValue?: string;
+        safe?: true;
+        rightSafe?: true;
+    };
+    to: NodeRef;
+    falsyFallbackRefs?: NodeRef[];
+    falsyFallback?: string;
+    falsyControl?: ControlFlowInstruction;
+    nullishFallback?: string;
+    nullishFallbackRef?: NodeRef;
+    nullishControl?: ControlFlowInstruction;
+    catchFallback?: string;
+    catchFallbackRef?: NodeRef;
+    catchControl?: ControlFlowInstruction;
+} | {
+    /** Short-circuit logical OR: evaluate left first, only evaluate right if left is falsy */
+    condOr: {
+        leftRef: NodeRef;
+        rightRef?: NodeRef;
+        rightValue?: string;
+        safe?: true;
+        rightSafe?: true;
+    };
+    to: NodeRef;
+    falsyFallbackRefs?: NodeRef[];
+    falsyFallback?: string;
+    falsyControl?: ControlFlowInstruction;
+    nullishFallback?: string;
+    nullishFallbackRef?: NodeRef;
+    nullishControl?: ControlFlowInstruction;
+    catchFallback?: string;
+    catchFallbackRef?: NodeRef;
+    catchControl?: ControlFlowInstruction;
+};
+/**
+ * Bridge definition — wires one GraphQL field to its data sources.
+ */
+export type Bridge = {
+    kind: "bridge";
+    /** GraphQL type: "Query" | "Mutation" */
+    type: string;
+    /** GraphQL field name */
+    field: string;
+    /** Declared data sources and their wire handles */
+    handles: HandleBinding[];
+    /** Connection wires */
+    wires: Wire[];
+    /**
+     * When set, this bridge was declared with the passthrough shorthand:
+     * `bridge Type.field with <name>`. The value is the define/tool name.
+     */
+    passthrough?: string;
+    /** Handles to eagerly evaluate (e.g. side-effect tools).
+     *  Critical by default — a forced handle that throws aborts the bridge.
+     *  Add `catchError: true` (written as `force <handle> ?? null`) to
+     *  swallow the error for fire-and-forget side-effects. */
+    forces?: Array<{
+        handle: string;
+        module: string;
+        type: string;
+        field: string;
+        instance?: number;
+        /** When true, errors from this forced handle are silently caught (`?? null`). */
+        catchError?: true;
+    }>;
+    arrayIterators?: Record<string, string>;
+    pipeHandles?: Array<{
+        key: string;
+        handle: string;
+        baseTrunk: {
+            module: string;
+            type: string;
+            field: string;
+            instance?: number;
+        };
+    }>;
+};
+/**
+ * A handle binding — declares a named data source available in a bridge.
+ *
+ * Every wire reference in the bridge body must trace back to one of these.
+ */
+export type HandleBinding = {
+    handle: string;
+    kind: "tool";
+    name: string;
+} | {
+    handle: string;
+    kind: "input";
+} | {
+    handle: string;
+    kind: "output";
+} | {
+    handle: string;
+    kind: "context";
+} | {
+    handle: string;
+    kind: "const";
+} | {
+    handle: string;
+    kind: "define";
+    name: string;
+};
+/** Internal module identifier for the bridge's own trunk (input args + output fields) */
+export declare const SELF_MODULE = "_";
+/**
+ * Tool definition — a declared tool with wires, dependencies, and optional inheritance.
+ *
+ * Tool blocks define reusable, composable API call configurations:
+ *   tool hereapi httpCall        — root tool with function name
+ *   tool hereapi.geocode extends hereapi  — child inherits parent wires
+ *
+ * The engine resolves extends chains, merges wires, and calls the
+ * registered tool function with the fully-built input object.
+ */
+export type ToolDef = {
+    kind: "tool";
+    /** Tool name: "hereapi", "sendgrid.send", "authService" */
+    name: string;
+    /** Function name — looked up in the tools map. Omitted when extends is used. */
+    fn?: string;
+    /** Parent tool name — inherits fn, deps, and wires */
+    extends?: string;
+    /** Dependencies declared via `with` inside the tool block */
+    deps: ToolDep[];
+    /** Wires: constants (`=`) and pulls (`<-`) defining the tool's input */
+    wires: ToolWire[];
+};
+/**
+ * A dependency declared inside a tool block.
+ *
+ *   with context                 — brings the full GraphQL context into scope
+ *   with authService as auth     — brings another tool's output into scope
+ */
+export type ToolDep = {
+    kind: "context";
+    handle: string;
+} | {
+    kind: "tool";
+    handle: string;
+    tool: string;
+} | {
+    kind: "const";
+    handle: string;
+};
+/**
+ * A wire in a tool block — either a constant value, a pull from a dependency,
+ * or an error fallback.
+ *
+ * Examples:
+ *   baseUrl = "https://api.sendgrid.com/v3"         → constant
+ *   method = POST                                     → constant (unquoted)
+ *   headers.Authorization <- ctx.sendgrid.token      → pull from context
+ *   headers.Authorization <- auth.access_token       → pull from tool dep
+ *   on error = { "lat": 0, "lon": 0 }               → constant fallback
+ *   on error <- ctx.fallbacks.geo                     → pull fallback from context
+ */
+export type ToolWire = {
+    target: string;
+    kind: "constant";
+    value: string;
+} | {
+    target: string;
+    kind: "pull";
+    source: string;
+} | {
+    kind: "onError";
+    value: string;
+} | {
+    kind: "onError";
+    source: string;
+};
+/**
+ * Context passed to every tool function as the second argument.
+ *
+ * Provides access to engine services (logger, etc.) without polluting the
+ * input object.  Tools that don't need it simply ignore the second arg.
+ */
+export type { ToolContext, ToolCallFn, ToolMap, CacheStore, } from "@stackables/bridge-types";
+/**
+ * Explicit control flow instruction — used on the right side of fallback
+ * gates (`||`, `??`, `catch`) to influence execution.
+ *
+ *   - `throw`    — raises a standard Error with the given message
+ *   - `panic`    — raises a BridgePanicError that bypasses all error boundaries
+ *   - `continue` — skips the current array element (sentinel value)
+ *   - `break`    — halts array iteration (sentinel value)
+ */
+export type ControlFlowInstruction = {
+    kind: "throw";
+    message: string;
+} | {
+    kind: "panic";
+    message: string;
+} | {
+    kind: "continue";
+} | {
+    kind: "break";
+};
+/**
+ * Named constant definition — a reusable value defined in the bridge file.
+ *
+ * Constants are available in bridge blocks via `with const as c` and in tool
+ * blocks via `with const`. The engine collects all ConstDef instructions into
+ * a single namespace object keyed by name.
+ *
+ * Examples:
+ *   const fallbackGeo = { "lat": 0, "lon": 0 }
+ *   const defaultCurrency = "EUR"
+ */
+export type ConstDef = {
+    kind: "const";
+    /** Constant name — used as the key in the const namespace */
+    name: string;
+    /** Raw JSON string — parsed at runtime when accessed */
+    value: string;
+};
+/** Union of all instruction types */
+export type Instruction = Bridge | ToolDef | ConstDef | DefineDef;
+/**
+ * Define block — a reusable named subgraph (pipeline / macro).
+ *
+ * At parse time a define is stored as a template.  When a bridge declares
+ * `with <define> as <handle>`, the define's handles and wires are inlined
+ * into the bridge with namespaced identifiers for isolation.
+ *
+ * Example:
+ *   define secureProfile {
+ *     with userApi as api
+ *     with input as i
+ *     with output as o
+ *     api.id <- i.userId
+ *     o.name <- api.login
+ *   }
+ */
+export type DefineDef = {
+    kind: "define";
+    /** Define name — referenced in bridge `with` declarations */
+    name: string;
+    /** Declared handles (tools, input, output, etc.) */
+    handles: HandleBinding[];
+    /** Connection wires (same format as Bridge wires) */
+    wires: Wire[];
+    /** Array iterators (same as Bridge) */
+    arrayIterators?: Record<string, string>;
+    /** Pipe fork registry (same as Bridge) */
+    pipeHandles?: Bridge["pipeHandles"];
+};
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

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

package/build/types.js

@@ -0,0 +1,2 @@
+/** Internal module identifier for the bridge's own trunk (input args + output fields) */
+export const SELF_MODULE = "_";

package/build/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared utilities for the Bridge runtime.
+ */
+/**
+ * Split a dotted path string into path segments, expanding array indices.
+ * e.g. "items[0].name" → ["items", "0", "name"]
+ */
+export declare function parsePath(text: string): string[];
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAchD"}

package/build/utils.js

@@ -0,0 +1,23 @@
+/**
+ * Shared utilities for the Bridge runtime.
+ */
+/**
+ * Split a dotted path string into path segments, expanding array indices.
+ * e.g. "items[0].name" → ["items", "0", "name"]
+ */
+export function parsePath(text) {
+    const parts = [];
+    for (const segment of text.split(".")) {
+        const match = segment.match(/^([^[]+)(?:\[(\d*)\])?$/);
+        if (match) {
+            parts.push(match[1]);
+            if (match[2] !== undefined && match[2] !== "") {
+                parts.push(match[2]);
+            }
+        }
+        else {
+            parts.push(segment);
+        }
+    }
+    return parts;
+}