@bevorai/sdk 0.0.0-stage → 0.1.0-rc.0

package/dist/errors.js

@@ -0,0 +1,132 @@
+/**
+ * A non-2xx response that carries no recognised Bevor error code
+ * (proxies, gateways, validation errors, unknown codes).
+ */
+export class APIError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}: ${body || "no details"}`);
+        this.name = "APIError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Base class for errors the API reports with a known `code`. */
+export class BaseError extends Error {
+    constructor(message) {
+        super(message ?? "");
+        this.name = new.target.name;
+    }
+    get details() {
+        return { message: this.message, code: this.code };
+    }
+}
+// base classes
+/** Base class for all authentication/authorization errors. */
+export class AuthException extends BaseError {
+}
+/** Base class for all code-related errors. */
+export class CodeException extends BaseError {
+}
+/** Base class for all payment-related errors. */
+export class PaymentException extends BaseError {
+    code = "payment.error";
+    statusCode = 402;
+}
+/** Too many requests. Retrying later succeeds. */
+export class RateLimitException extends BaseError {
+    code = "app.rate_limit";
+    statusCode = 429;
+}
+// auth
+export class SessionExpiredError extends AuthException {
+    code = "auth.session_expired";
+    statusCode = 401;
+}
+export class UnauthenticatedError extends AuthException {
+    code = "auth.unauthenticated";
+    statusCode = 401;
+}
+export class PaymentRequiredError extends AuthException {
+    code = "auth.payment_required";
+    statusCode = 402;
+}
+export class UnauthorizedError extends AuthException {
+    code = "auth.unauthorized";
+    statusCode = 403;
+}
+/** Authenticated, but not allowed. Re-authenticating won't fix it. */
+export class InvalidPermissionsError extends AuthException {
+    code = "auth.invalid_permissions";
+    statusCode = 403;
+}
+export class InvalidScopeError extends AuthException {
+    code = "auth.invalid_scope";
+    statusCode = 403;
+}
+// general
+/**
+ * The request is wrong for this endpoint, regardless of any resource's state.
+ * e.g. a required header is missing, or the project kind doesn't support the route.
+ */
+export class BadRequestException extends BaseError {
+    code = "error.bad_request";
+    statusCode = 400;
+}
+/** Doesn't exist, was deleted, or isn't visible to the caller. */
+export class NotFoundError extends BaseError {
+    code = "error.not_found";
+    statusCode = 404;
+}
+/**
+ * The resource's current state forbids the action. e.g. a pipeline is running,
+ * changes are staged, or it already exists.
+ */
+export class InvalidStateException extends BaseError {
+    code = "error.invalid_state";
+    statusCode = 409;
+}
+/** Our failure, or an upstream service's. Retrying may succeed. */
+export class ServerException extends BaseError {
+    code = "error.server";
+    statusCode = 500;
+}
+/** A plan or usage limit was reached. Retrying won't help, upgrading will. */
+export class PlanLimitException extends BaseError {
+    code = "error.plan_limit";
+    statusCode = 402;
+}
+// domain
+export class CodeUnsupportedException extends CodeException {
+    code = "code.unsupported";
+    statusCode = 400;
+}
+export class CodeConflictException extends CodeException {
+    code = "code.conflict";
+    statusCode = 409;
+}
+export class PaymentFailedException extends PaymentException {
+    code = "payment.failed";
+    statusCode = 402;
+}
+/** Used to reconstruct typed errors from HTTP error response bodies. */
+export const ERROR_REGISTRY = {
+    "auth.session_expired": SessionExpiredError,
+    "auth.unauthorized": UnauthorizedError,
+    "auth.unauthenticated": UnauthenticatedError,
+    "auth.payment_required": PaymentRequiredError,
+    "auth.invalid_permissions": InvalidPermissionsError,
+    "auth.invalid_scope": InvalidScopeError,
+    "error.bad_request": BadRequestException,
+    "error.not_found": NotFoundError,
+    "error.plan_limit": PlanLimitException,
+    "error.invalid_state": InvalidStateException,
+    "error.server": ServerException,
+    "app.rate_limit": RateLimitException,
+    "payment.error": PaymentException,
+    "payment.failed": PaymentFailedException,
+    "code.unsupported": CodeUnsupportedException,
+    "code.conflict": CodeConflictException,
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACzB,MAAM,CAAS;IACf,IAAI,CAAS;IAEtB,YAAY,MAAc,EAAE,IAAY;QACvC,KAAK,CAAC,QAAQ,MAAM,KAAK,IAAI,IAAI,YAAY,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAED,iEAAiE;AACjE,MAAM,OAAgB,SAAU,SAAQ,KAAK;IAI5C,YAAY,OAAuB;QAClC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,IAAI,OAAO;QACV,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACnD,CAAC;CACD;AAED,eAAe;AAEf,8DAA8D;AAC9D,MAAM,OAAgB,aAAc,SAAQ,SAAS;CAAG;AAExD,8CAA8C;AAC9C,MAAM,OAAgB,aAAc,SAAQ,SAAS;CAAG;AAExD,iDAAiD;AACjD,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IACrC,IAAI,GAAkB,eAAe,CAAC;IACtC,UAAU,GAAW,GAAG,CAAC;CAClC;AAED,kDAAkD;AAClD,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IACvC,IAAI,GAAG,gBAAgB,CAAC;IACxB,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,OAAO;AAEP,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAC5C,IAAI,GAAG,sBAAsB,CAAC;IAC9B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IAC7C,IAAI,GAAG,sBAAsB,CAAC;IAC9B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IAC7C,IAAI,GAAG,uBAAuB,CAAC;IAC/B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAC1C,IAAI,GAAG,mBAAmB,CAAC;IAC3B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,OAAO,uBAAwB,SAAQ,aAAa;IAChD,IAAI,GAAG,0BAA0B,CAAC;IAClC,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAC1C,IAAI,GAAG,oBAAoB,CAAC;IAC5B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,UAAU;AAEV;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACxC,IAAI,GAAG,mBAAmB,CAAC;IAC3B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,kEAAkE;AAClE,MAAM,OAAO,aAAc,SAAQ,SAAS;IAClC,IAAI,GAAG,iBAAiB,CAAC;IACzB,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IAC1C,IAAI,GAAG,qBAAqB,CAAC;IAC7B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,OAAO,eAAgB,SAAQ,SAAS;IACpC,IAAI,GAAG,cAAc,CAAC;IACtB,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,8EAA8E;AAC9E,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IACvC,IAAI,GAAG,kBAAkB,CAAC;IAC1B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,SAAS;AAET,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IACjD,IAAI,GAAG,kBAAkB,CAAC;IAC1B,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC9C,IAAI,GAAG,eAAe,CAAC;IACvB,UAAU,GAAG,GAAG,CAAC;CAC1B;AAED,MAAM,OAAO,sBAAuB,SAAQ,gBAAgB;IACzC,IAAI,GAAkB,gBAAgB,CAAC;IACvC,UAAU,GAAW,GAAG,CAAC;CAC3C;AAID,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAA+C;IACzE,sBAAsB,EAAE,mBAAmB;IAC3C,mBAAmB,EAAE,iBAAiB;IACtC,sBAAsB,EAAE,oBAAoB;IAC5C,uBAAuB,EAAE,oBAAoB;IAC7C,0BAA0B,EAAE,uBAAuB;IACnD,oBAAoB,EAAE,iBAAiB;IACvC,mBAAmB,EAAE,mBAAmB;IACxC,iBAAiB,EAAE,aAAa;IAChC,kBAAkB,EAAE,kBAAkB;IACtC,qBAAqB,EAAE,qBAAqB;IAC5C,cAAc,EAAE,eAAe;IAC/B,gBAAgB,EAAE,kBAAkB;IACpC,eAAe,EAAE,gBAAgB;IACjC,gBAAgB,EAAE,sBAAsB;IACxC,kBAAkB,EAAE,wBAAwB;IAC5C,eAAe,EAAE,qBAAqB;CACtC,CAAC"}

package/dist/graph/call-node.d.ts

@@ -0,0 +1,47 @@
+import type { ResolvedStorageAccess } from "../types/graph-data.js";
+import type { EdgeType, ID } from "../types/literals.js";
+import type { Graph } from "./graph.js";
+/** JSON form of a `CallNode`, as returned by `toDict()` and the call-chain endpoint. */
+export interface CallNodeDict {
+    node_id: ID | null;
+    short_id: string | null;
+    name: string | null;
+    node_type: string | null;
+    edge_id: ID | null;
+    edge_type: EdgeType | null;
+    low_level_name: string | null;
+    target_effect_id: ID | null;
+    is_conditional: boolean;
+    is_arg: boolean;
+    is_cyclic: boolean;
+    src_field_names: string[];
+    dst_field_names: string[];
+    resolved_bindings: ResolvedStorageAccess[];
+    children: CallNodeDict[];
+}
+export declare class CallNode {
+    #private;
+    nodeId: ID | null;
+    shortId: string | null;
+    name: string | null;
+    nodeType: string | null;
+    edgeId: ID | null;
+    edgeType: EdgeType | null;
+    lowLevelName: string | null;
+    targetEffectId: ID | null;
+    isConditional: boolean;
+    isArg: boolean;
+    isCyclic: boolean;
+    srcFieldNames: string[];
+    dstFieldNames: string[];
+    resolvedBindings: ResolvedStorageAccess[];
+    children: CallNode[];
+    constructor(init?: Partial<CallNode>);
+    /** A shallow copy, like `dataclasses.replace`. */
+    clone(overrides?: Partial<CallNode>): CallNode;
+    toDict(): CallNodeDict;
+    static fromDict(data: Partial<CallNodeDict>): CallNode;
+    toText(): string;
+    static build(graph: Graph, nodeId: ID): CallNode;
+}
+//# sourceMappingURL=call-node.d.ts.map

package/dist/graph/call-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-node.d.ts","sourceRoot":"","sources":["../../src/graph/call-node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGX,qBAAqB,EAErB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AAKzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAiKxC,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,EAAE,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,EAAE,qBAAqB,EAAE,CAAC;IAC3C,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,qBAAa,QAAQ;;IACpB,MAAM,EAAE,EAAE,GAAG,IAAI,CAAQ;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC/B,MAAM,EAAE,EAAE,GAAG,IAAI,CAAQ;IACzB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAQ;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAQ;IACnC,cAAc,EAAE,EAAE,GAAG,IAAI,CAAQ;IACjC,aAAa,UAAS;IACtB,KAAK,UAAS;IACd,QAAQ,UAAS;IACjB,aAAa,EAAE,MAAM,EAAE,CAAM;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAM;IAC7B,gBAAgB,EAAE,qBAAqB,EAAE,CAAM;IAC/C,QAAQ,EAAE,QAAQ,EAAE,CAAM;IAE1B,YAAY,IAAI,GAAE,OAAO,CAAC,QAAQ,CAAM,EAEvC;IAED,kDAAkD;IAClD,KAAK,CAAC,SAAS,GAAE,OAAO,CAAC,QAAQ,CAAM,GAAG,QAAQ,CAEjD;IAED,MAAM,IAAI,YAAY,CAoBrB;IAED,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,QAAQ,CAqBrD;IAkCD,MAAM,IAAI,MAAM,CAwBf;IAkBD,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,QAAQ,CAiI/C;CACD"}

package/dist/graph/call-node.js

@@ -0,0 +1,338 @@
+const SKIP_EDGES = new Set([
+    "overrides",
+    "inherits",
+    "has_ref_comment",
+    "initializes",
+]);
+const CALL_EDGES = new Set(["calls", "calls_external"]);
+const join = (...parts) => parts.filter((part) => Boolean(part)).join(".") || null;
+const isParameterFact = (fact) => "start_byte" in fact;
+/**
+ * One function invocation: its stored storage facts, plus what its storage parameters are bound to
+ * by the call that invoked it.
+ */
+class Frame {
+    graph;
+    node;
+    paramSlots;
+    path;
+    /** the function's edges by position, including those owned by condition nodes nested in it */
+    refs = new Map();
+    accesses = [];
+    #byPos = new Map();
+    constructor(graph, node, paramSlots, path) {
+        this.graph = graph;
+        this.node = node;
+        this.paramSlots = paramSlots;
+        this.path = path;
+        const stack = [node.id];
+        while (stack.length) {
+            for (const edge of graph.getEdgesForNode(stack.pop(), {
+                direction: "out",
+            })) {
+                this.refs.set(edge.src_start_pos, edge);
+                if (edge.edge_type === "has_condition" && edge.dst_id)
+                    stack.push(edge.dst_id);
+            }
+        }
+        for (const fact of node.parameters ?? []) {
+            for (const slot of this.resolve(fact, fact.field)) {
+                const access = {
+                    edge_type: fact.is_written ? "writes" : "reads",
+                    start_byte: fact.start_byte,
+                    bound_to_node_id: slot.nodeId,
+                    bound_to_short_id: graph.getNode(slot.nodeId).short_id,
+                    bound_to_name: slot.name,
+                    field: slot.field,
+                };
+                this.accesses.push(access);
+                const pos = fact.field_start_byte ?? fact.start_byte;
+                const atPos = this.#byPos.get(pos);
+                if (atPos)
+                    atPos.push(access);
+                else
+                    this.#byPos.set(pos, [access]);
+            }
+        }
+    }
+    /** The frame `call`'s callee runs in, bound by this frame's resolution of its arguments. */
+    callee(call) {
+        if (!call.dst_id || this.path.includes(call.dst_id))
+            return null;
+        return new Frame(this.graph, this.graph.getNode(call.dst_id), this.bind(call), [...this.path, this.node.id]);
+    }
+    /** Concrete slots for a stored root, with `field` appended to the path. */
+    resolve(fact, field) {
+        // an access fact is rooted in its own `param_index`; on a binding, `param_index` is the
+        // *callee's* parameter and the root is `bound_to_param_index`
+        const paramIndex = isParameterFact(fact)
+            ? fact.param_index
+            : fact.bound_to_param_index;
+        if (paramIndex !== null && paramIndex !== undefined) {
+            return (this.paramSlots.get(paramIndex) ?? []).map((slot) => ({
+                ...slot,
+                field: join(slot.field, field),
+            }));
+        }
+        if (fact.bound_to_ref_pos === null || fact.bound_to_ref_pos === undefined)
+            return [];
+        const ref = this.refs.get(fact.bound_to_ref_pos);
+        if (!ref?.dst_id)
+            return [];
+        if (fact.bound_to_return_index === null ||
+            fact.bound_to_return_index === undefined) {
+            // a reference to a state variable: the edge's destination is the root
+            const target = this.graph.getNode(ref.dst_id);
+            return [{ nodeId: target.id, name: target.name, field: field ?? null }];
+        }
+        // the return slot of a call: what the callee returns, bound by this call's arguments
+        const callee = this.callee(ref);
+        if (callee === null)
+            return [];
+        const out = [];
+        for (const ret of callee.node.returns ?? []) {
+            if (ret.param_ind !== fact.bound_to_return_index)
+                continue;
+            for (const slot of callee.resolve(ret, ret.bound_to_field)) {
+                out.push({ ...slot, field: join(slot.field, field) });
+            }
+        }
+        return out;
+    }
+    /** What each storage parameter of `call`'s callee is bound to, resolved in this frame. */
+    bind(call) {
+        const out = new Map();
+        for (const binding of call.call_bindings ?? []) {
+            const slots = this.resolve(binding, binding.bound_to_field);
+            const existing = out.get(binding.param_index);
+            if (existing)
+                existing.push(...slots);
+            else
+                out.set(binding.param_index, slots);
+        }
+        return out;
+    }
+    at(pos) {
+        return this.#byPos.get(pos) ?? [];
+    }
+}
+export class CallNode {
+    nodeId = null;
+    shortId = null;
+    name = null;
+    nodeType = null;
+    edgeId = null;
+    edgeType = null;
+    lowLevelName = null;
+    targetEffectId = null;
+    isConditional = false;
+    isArg = false;
+    isCyclic = false;
+    srcFieldNames = [];
+    dstFieldNames = [];
+    resolvedBindings = [];
+    children = [];
+    constructor(init = {}) {
+        Object.assign(this, init);
+    }
+    /** A shallow copy, like `dataclasses.replace`. */
+    clone(overrides = {}) {
+        return new CallNode({ ...this, ...overrides });
+    }
+    toDict() {
+        return {
+            node_id: this.nodeId,
+            short_id: this.shortId,
+            name: this.name,
+            node_type: this.nodeType,
+            edge_id: this.edgeId,
+            edge_type: this.edgeType,
+            low_level_name: this.lowLevelName,
+            target_effect_id: this.targetEffectId,
+            is_conditional: this.isConditional,
+            is_arg: this.isArg,
+            is_cyclic: this.isCyclic,
+            src_field_names: [...this.srcFieldNames],
+            dst_field_names: [...this.dstFieldNames],
+            resolved_bindings: this.resolvedBindings.map((binding) => ({
+                ...binding,
+            })),
+            children: this.children.map((child) => child.toDict()),
+        };
+    }
+    static fromDict(data) {
+        return new CallNode({
+            nodeId: data.node_id ?? null,
+            shortId: data.short_id ?? null,
+            name: data.name ?? null,
+            nodeType: data.node_type ?? null,
+            edgeId: data.edge_id ?? null,
+            edgeType: data.edge_type ?? null,
+            lowLevelName: data.low_level_name ?? null,
+            targetEffectId: data.target_effect_id ?? null,
+            isConditional: Boolean(data.is_conditional),
+            isArg: Boolean(data.is_arg),
+            isCyclic: Boolean(data.is_cyclic),
+            srcFieldNames: [...(data.src_field_names ?? [])],
+            dstFieldNames: [...(data.dst_field_names ?? [])],
+            children: (data.children ?? []).map((child) => CallNode.fromDict(child)),
+            resolvedBindings: (data.resolved_bindings ?? []).map((binding) => ({
+                ...binding,
+                field: binding.field ?? null,
+            })),
+        });
+    }
+    // text
+    #label() {
+        if (this.shortId)
+            return `${this.name || this.lowLevelName || "?"} [${this.shortId}]`;
+        return `low-level method ${this.lowLevelName || this.name || "?"}`;
+    }
+    #line(parent) {
+        const label = this.#label();
+        let head = label;
+        if (this.edgeType) {
+            const verb = this.edgeType.replaceAll("_", " ");
+            // an input runs exactly when its effect does: only show its own condition if it differs
+            const inheritsCondition = this.isArg && parent?.isConditional === true;
+            if (parent?.edgeType === "has_condition" && !this.isConditional) {
+                head = `in condition ${verb} ${label}`;
+            }
+            else if (this.isConditional && !inheritsCondition) {
+                head = `conditionally ${verb} ${label}`;
+            }
+            else {
+                head = `${verb} ${label}`;
+            }
+        }
+        const tail = [];
+        if (this.srcFieldNames.length)
+            tail.push(`src: [${this.srcFieldNames.join(",")}]`);
+        if (this.dstFieldNames.length)
+            tail.push(`dst: [${this.dstFieldNames.join(",")}]`);
+        return tail.length ? `${head} ${tail.join(" ")}` : head;
+    }
+    toText() {
+        const lines = [];
+        const visit = (cn, depth, parent) => {
+            const line = cn.#line(parent);
+            lines.push("  ".repeat(depth) + (cn.isCyclic ? `[CYCLIC] ${line}` : line));
+            const args = cn.children.filter((child) => child.isArg);
+            if (args.length) {
+                lines.push("  ".repeat(depth + 1) +
+                    (cn.edgeType && CALL_EDGES.has(cn.edgeType) ? "args" : "using"));
+                for (const child of args)
+                    visit(child, depth + 2, cn);
+            }
+            for (const child of cn.children)
+                if (!child.isArg)
+                    visit(child, depth + 1, cn);
+        };
+        visit(this, 0, null);
+        return lines.join("\n");
+    }
+    // build
+    /** Points a struct-typed access at the concrete storage it hits. */
+    #resolveTo(access) {
+        this.edgeType = access.edge_type;
+        this.nodeId = access.bound_to_node_id;
+        this.shortId = access.bound_to_short_id;
+        this.name = access.bound_to_name;
+        this.dstFieldNames = access.field ? [access.field] : [];
+    }
+    static #prune(cn) {
+        cn.children = cn.children.filter((child) => CallNode.#prune(child));
+        return !(cn.edgeType === "has_condition" && cn.children.length === 0);
+    }
+    static build(graph, nodeId) {
+        const childFrame = (edge, frame) => {
+            // a condition node belongs to the same function instance
+            if (edge.edge_type === "has_condition")
+                return frame;
+            if (CALL_EDGES.has(edge.edge_type))
+                return frame.callee(edge);
+            return null;
+        };
+        /**
+         * One node per concrete slot this struct-typed access may hit; itself if unresolved. A resolved
+         * node keeps its inputs and is expanded as its new target.
+         */
+        const resolved = (child, accesses, path) => {
+            if (accesses.length === 0)
+                return [child];
+            return accesses.map((access) => {
+                const cn = child.clone({
+                    children: child.children.filter((c) => c.isArg),
+                });
+                cn.#resolveTo(access);
+                cn.children.push(...walk(access.bound_to_node_id, null, null, path, new Map())
+                    .children);
+                return cn;
+            });
+        };
+        const attachArgs = (cn, edge, path, callerArgs) => {
+            // inputs run in the caller's frame, with the caller's stack
+            if (edge === null)
+                return;
+            for (const [argEdge, argFrame] of callerArgs.get(edge.id) ?? []) {
+                const child = walk(argEdge.dst_id ?? null, argEdge, childFrame(argEdge, argFrame), path, callerArgs, true);
+                cn.children.push(...resolved(child, argFrame.at(argEdge.src_start_pos), path));
+            }
+        };
+        /** `frame` is the frame this node's body runs in: a fresh one for a callee, the enclosing one for a condition node. */
+        const walk = (nid, edge, frame, path, callerArgs, isArg = false) => {
+            const node = nid ? graph.getNode(nid) : null;
+            const lowLevelName = edge?.low_level_name ?? null;
+            const cn = new CallNode({
+                nodeId: nid,
+                shortId: node?.short_id ?? null,
+                name: node !== null ? node.name : lowLevelName,
+                nodeType: node?.node_type ?? null,
+                edgeId: edge?.id ?? null,
+                edgeType: edge?.edge_type ?? null,
+                lowLevelName,
+                targetEffectId: edge?.target_effect_id ?? null,
+                isConditional: edge ? Boolean(edge.is_conditional) : false,
+                isArg,
+                isCyclic: nid ? path.includes(nid) : false,
+                srcFieldNames: [...(edge?.src_field_names ?? [])],
+                dstFieldNames: [...(edge?.dst_field_names ?? [])],
+            });
+            if (cn.isCyclic || node === null) {
+                attachArgs(cn, edge, path, callerArgs);
+                return cn;
+            }
+            if (cn.edgeType && SKIP_EDGES.has(cn.edgeType))
+                return cn;
+            // no caller context: an entrypoint, or a node started from directly
+            const bodyFrame = frame ?? new Frame(graph, node, new Map(), path);
+            const childEdges = graph.getEdgesForNode(node.id, { direction: "out" });
+            // inputs belong to this frame: they're walked under the effect they feed, with this frame
+            const myArgs = new Map();
+            for (const childEdge of childEdges) {
+                if (!childEdge.target_effect_id)
+                    continue;
+                const entries = myArgs.get(childEdge.target_effect_id);
+                if (entries)
+                    entries.push([childEdge, bodyFrame]);
+                else
+                    myArgs.set(childEdge.target_effect_id, [[childEdge, bodyFrame]]);
+            }
+            const stack = [...path, node.id];
+            for (const childEdge of childEdges) {
+                if (childEdge.target_effect_id)
+                    continue;
+                const child = walk(childEdge.dst_id ?? null, childEdge, childFrame(childEdge, bodyFrame), stack, myArgs);
+                cn.children.push(...resolved(child, bodyFrame.at(childEdge.src_start_pos), stack));
+            }
+            if (edge === null || edge.edge_type !== "has_condition")
+                cn.resolvedBindings = bodyFrame.accesses;
+            attachArgs(cn, edge, path, callerArgs);
+            return cn;
+        };
+        const root = walk(nodeId, null, null, [], new Map());
+        CallNode.#prune(root);
+        return root;
+    }
+}
+//# sourceMappingURL=call-node.js.map

package/dist/graph/call-node.js.map

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

package/dist/graph/cursor.d.ts

@@ -0,0 +1,46 @@
+import type { EdgeType, ID } from "../types/literals.js";
+import type { GraphSnapshotEdge, GraphSnapshotNode } from "../types/responses.js";
+import type { Graph } from "./graph.js";
+type Frame = readonly [nodeId: ID, used: ReadonlySet<ID>];
+/**
+ * A movable position in the graph that remembers its path.
+ *
+ * Full execution-path DFS:
+ * ```ts
+ * const cursor = graph.cursor(nodeId);
+ * while (true) {
+ *   if (cursor.gotoFirstChild()) continue;
+ *   if (cursor.gotoNextSibling()) continue;
+ *   if (!cursor.back()) break;
+ * }
+ * ```
+ *
+ * Adding `if (cursor.gotoFirstParent()) continue;` before `back()` also walks out of the execution
+ * path into cross pathways ("what else writes this", "where else is this called"). Use `peekUp()`,
+ * or pass an `edgeType` to only allow that for certain edges.
+ */
+export declare class GraphCursor {
+    readonly graph: Graph;
+    nodeId: ID;
+    /** Edges taken from the current position, on this path. */
+    used: ReadonlySet<ID>;
+    stack: readonly Frame[];
+    constructor(graph: Graph, nodeId: ID);
+    get node(): GraphSnapshotNode;
+    get depth(): number;
+    get path(): ID[];
+    get isCycle(): boolean;
+    /**
+     * Takes the first unused outgoing edge. Moves onto its destination when it has one; an edge
+     * without a destination isn't a real node, so the cursor stays put but the edge is consumed.
+     */
+    gotoFirstChild(): GraphSnapshotEdge | null;
+    gotoFirstParent(edgeType?: EdgeType | null): GraphSnapshotEdge | null;
+    gotoNextSibling(): GraphSnapshotEdge | null;
+    back(): boolean;
+    peekUp(): [GraphSnapshotEdge, GraphSnapshotNode][];
+    peekDown(): [GraphSnapshotEdge, GraphSnapshotNode][];
+    render(source?: string | null): string;
+}
+export {};
+//# sourceMappingURL=cursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/graph/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EACX,iBAAiB,EACjB,iBAAiB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,KAAK,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,MAAM,EAAE,EAAE,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC,CAAa;IAClC,KAAK,EAAE,SAAS,KAAK,EAAE,CAAM;IAE7B,YAAY,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAGnC;IAED,IAAI,IAAI,IAAI,iBAAiB,CAE5B;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,IAAI,IAAI,EAAE,EAAE,CAEf;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,cAAc,IAAI,iBAAiB,GAAG,IAAI,CAezC;IAED,eAAe,CAAC,QAAQ,GAAE,QAAQ,GAAG,IAAW,GAAG,iBAAiB,GAAG,IAAI,CAc1E;IAED,eAAe,IAAI,iBAAiB,GAAG,IAAI,CAe1C;IAED,IAAI,IAAI,OAAO,CAMd;IAED,MAAM,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,CAMjD;IAED,QAAQ,IAAI,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,CAUnD;IAED,MAAM,CAAC,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,CAuC3C;CACD"}