@boundaryml/baml-bridge-web 0.0.0

package/dist/workerd/shared/define_function.js

@@ -0,0 +1,274 @@
+// define_function.ts — runtime factories for BAML callables, the Node analog
+// of `define_function` in sdks/python/src/baml_bridge/__init__.py.
+//
+// Generated SDK code emits, per BAML function:
+//   export const f = defineFunction("user.ns.f", "sync", ["a"]) as (a: A) => R;
+//   export const f_async = defineFunction("user.ns.f", "async", ["a"]) as (a: A) => Promise<R>;
+// and per instance method (inside the class body):
+//   m = defineInstanceFunction("user.ns.C.m", "sync", ["self"]).bind(this) as () => R;
+//
+// The factory captures (fqn, mode, requiredNames, optionalNames) by closure;
+// the returned callable zips positional args against requiredNames into kwargs,
+// encodes it, calls the runtime, and decodes the result.
+import { getRuntime, newFunctionCall as nativeNewFunctionCall, } from '../native.js';
+import { encodeCallArgs, decodeCallResult } from './proto.js';
+import { lowerTypeToWireTy } from './wire_ty.js';
+/** Sentinel for "argument not supplied" so optional kwargs can be skipped. */
+export const UNSET = Symbol('baml.UNSET');
+/**
+ * Resolve the caller's `$types` option onto the callee's own generic params, in
+ * declaration order. Mirrors Python's `_resolve_types_kwarg`: `$types` is an
+ * object keyed by param name and is required iff the callee declares its own
+ * generic params; it must bind exactly those params (no missing, no extras).
+ */
+function resolveTypesOption(typesOpt, typeParams) {
+    if (typeParams.length === 0) {
+        if (typesOpt !== undefined && typesOpt !== null) {
+            throw new TypeError('$types is not accepted here: this function/method declares no generic type ' +
+                'parameters of its own');
+        }
+        return [];
+    }
+    const example = `{ ${JSON.stringify(typeParams[0])}: 'int' }`;
+    if (typesOpt === undefined || typesOpt === null) {
+        throw new TypeError(`$types is required for this generic call: bind every type parameter in ` +
+            `${JSON.stringify(typeParams)} with an object, e.g. $types: ${example}`);
+    }
+    if (typeof typesOpt !== 'object' || Array.isArray(typesOpt)) {
+        throw new TypeError(`$types must be an object mapping type-parameter names to types (e.g. ` +
+            `$types: ${example}); got ${typeof typesOpt}`);
+    }
+    const obj = typesOpt;
+    const missing = typeParams.filter((n) => !(n in obj));
+    if (missing.length) {
+        throw new TypeError(`$types is missing binding(s) for ${JSON.stringify(missing)}: every type parameter ` +
+            `in ${JSON.stringify(typeParams)} must be bound.`);
+    }
+    const extra = Object.keys(obj).filter((k) => !typeParams.includes(k));
+    if (extra.length) {
+        throw new TypeError(`$types has unknown type parameter(s) ${JSON.stringify(extra)}; expected exactly ` +
+            `${JSON.stringify(typeParams)}.`);
+    }
+    return typeParams.map((n) => obj[n]);
+}
+/** The `$types` field of a generic receiver instance (its class TypeVar
+ * bindings), or `undefined` when the receiver carries none. The TS analog of
+ * Python's `pydantic_instance_type_args(self)`. */
+function receiverTypes(self) {
+    if (self != null && typeof self === 'object') {
+        const t = self.$types;
+        if (t != null && typeof t === 'object') {
+            return t;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the named, order-preserving wire `type_args` for a generic call. Mirrors
+ * Python's `_build_type_args`: enclosing class params (recovered from the `self`
+ * receiver's `$types`) come first, then the callee's own params (`$types`
+ * option) — De Bruijn order. Class params are seeded only when the receiver
+ * actually carries them, so a non-generic receiver keeps the engine's
+ * recover-from-receiver behavior. Returns `[]` when the call binds nothing.
+ */
+function buildTypeArgs(self, typesOpt, typeParams, classTypeParams) {
+    const wire = [];
+    const classTypes = classTypeParams.length ? receiverTypes(self) : undefined;
+    if (classTypes) {
+        for (const name of classTypeParams) {
+            wire.push([name, lowerTypeToWireTy(classTypes[name])]);
+        }
+    }
+    const resolved = resolveTypesOption(typesOpt, typeParams);
+    if (typeParams.length > 0) {
+        if (classTypeParams.length && !classTypes) {
+            // The method's own params sit after the class prefix in De Bruijn
+            // order; without recovered class args we can't position them.
+            throw new TypeError('$types on a generic method requires a generic receiver carrying its class type ' +
+                'args (a `$types` field on the instance)');
+        }
+        typeParams.forEach((name, i) => {
+            wire.push([name, lowerTypeToWireTy(resolved[i])]);
+        });
+    }
+    return wire;
+}
+function newFunctionCall() {
+    return BigInt(nativeNewFunctionCall());
+}
+function attachCallContext(ctx, callId) {
+    ctx?._attachCallId(callId.toString());
+    return {
+        detach() {
+            ctx?._detachCallId(callId.toString());
+        },
+    };
+}
+function buildArgs(args, requiredParamNames, optionalParamNames) {
+    const positionalLimit = requiredParamNames.length;
+    if (args.length > positionalLimit + 1) {
+        throw new TypeError(`got ${args.length} positional arguments but only ${positionalLimit} positional ` +
+            `parameter names (${JSON.stringify(requiredParamNames)})`);
+    }
+    const built = {};
+    for (let i = 0; i < args.length && i < positionalLimit; i++) {
+        if (args[i] === UNSET)
+            continue;
+        built[requiredParamNames[i]] = args[i];
+    }
+    let ctx;
+    let types;
+    if (args.length > positionalLimit) {
+        const opts = args[positionalLimit];
+        if (opts === undefined || opts === UNSET) {
+            return { kwargs: built };
+        }
+        if (opts === null || Array.isArray(opts) || typeof opts !== 'object') {
+            throw new TypeError('optional arguments must be passed as an object');
+        }
+        const optionNames = new Set(optionalParamNames);
+        for (const [key, value] of Object.entries(opts)) {
+            if (key === '$ctx') {
+                if (value !== undefined && value !== UNSET) {
+                    ctx = value;
+                }
+                continue;
+            }
+            if (key === '$types') {
+                // Generic-call TypeVar bindings — captured here and lowered to
+                // wire `type_args` by the factory, never sent as a kwarg value.
+                if (value !== undefined && value !== UNSET) {
+                    types = value;
+                }
+                continue;
+            }
+            if (!optionNames.has(key)) {
+                throw new TypeError(`unknown optional argument ${JSON.stringify(key)}`);
+            }
+            if (value === undefined || value === UNSET)
+                continue;
+            built[key] = value;
+        }
+    }
+    return { kwargs: built, ctx, types };
+}
+/**
+ * Factory for a free function or static method binding. Returns a callable
+ * that maps positional args to kwargs, encodes, calls the runtime, and decodes.
+ * `sync` returns the decoded value; `async` returns a `Promise` of it.
+ */
+export function defineFunction(bamlFqn, mode, requiredParamNames, optionalParamNames, generics) {
+    const requiredNames = [...requiredParamNames];
+    const optionNames = [...(optionalParamNames ?? [])];
+    // A free function / static method binds only its OWN generic params (a
+    // generic receiver is never in play here), so `classTypeParams` is unused.
+    const typeParams = generics?.typeParams ?? [];
+    const isGeneric = typeParams.length > 0;
+    // Eagerly reject `$types` on a non-generic call, matching the generic path's
+    // strict binding contract (mirrors Python's `is_generic` gate).
+    const typeArgsFor = (built) => isGeneric ? buildTypeArgs(undefined, built.types, typeParams, []) : [];
+    if (mode === 'sync') {
+        return (...args) => {
+            const built = buildArgs(args, requiredNames, optionNames);
+            const typeArgs = typeArgsFor(built);
+            const rt = getRuntime();
+            const callId = newFunctionCall();
+            const argsProto = encodeCallArgs(built.kwargs, { syncMode: true, callId, typeArgs });
+            const callCtxBinding = attachCallContext(built.ctx, callId);
+            let resultBytes;
+            try {
+                resultBytes = rt.callFunctionSync(bamlFqn, argsProto, null, null);
+            }
+            finally {
+                callCtxBinding.detach();
+            }
+            return decodeCallResult(resultBytes);
+        };
+    }
+    if (mode === 'async') {
+        return async (...args) => {
+            const built = buildArgs(args, requiredNames, optionNames);
+            const typeArgs = typeArgsFor(built);
+            const rt = getRuntime();
+            const callId = newFunctionCall();
+            const argsProto = encodeCallArgs(built.kwargs, { callId, typeArgs });
+            const callCtxBinding = attachCallContext(built.ctx, callId);
+            let resultBytes;
+            try {
+                resultBytes = await rt.callFunction(bamlFqn, argsProto, null, null);
+            }
+            finally {
+                callCtxBinding.detach();
+            }
+            return decodeCallResult(resultBytes);
+        };
+    }
+    throw new Error(`mode must be 'sync' or 'async', got ${JSON.stringify(mode)}`);
+}
+/**
+ * Receiver-binding factory for instance methods. `paramNames[0]` is always
+ * `"self"`. Codegen emits the binding as a class-field initializer
+ * `m = defineInstanceFunction(...).bind(this) as () => R;`, so `.bind(self)`
+ * captures the instance at construction time; the synthetic `self` param never
+ * appears in the surface type.
+ */
+export function defineInstanceFunction(bamlFqn, mode, requiredParamNames, optionalParamNames, generics) {
+    const requiredNames = [...requiredParamNames];
+    const optionNames = [...(optionalParamNames ?? [])];
+    const selfName = requiredNames[0] ?? 'self';
+    const rest = requiredNames.slice(1);
+    // An instance method binds its own `<...>` params (caller's `$types`) AND
+    // the enclosing class's params, recovered from the `self` receiver's
+    // `$types` field. Mirrors Python's `class_type_params` for instance methods.
+    const typeParams = generics?.typeParams ?? [];
+    const classTypeParams = generics?.classTypeParams ?? [];
+    const isGeneric = typeParams.length > 0 || classTypeParams.length > 0;
+    const makeArgs = (self, args) => {
+        const built = buildArgs(args, rest, optionNames);
+        built.kwargs[selfName] = self;
+        return built;
+    };
+    return {
+        bind(self) {
+            const typeArgsFor = (built) => isGeneric ? buildTypeArgs(self, built.types, typeParams, classTypeParams) : [];
+            if (mode === 'sync') {
+                return (...args) => {
+                    const built = makeArgs(self, args);
+                    const typeArgs = typeArgsFor(built);
+                    const rt = getRuntime();
+                    const callId = newFunctionCall();
+                    const argsProto = encodeCallArgs(built.kwargs, { syncMode: true, callId, typeArgs });
+                    const callCtxBinding = attachCallContext(built.ctx, callId);
+                    let resultBytes;
+                    try {
+                        resultBytes = rt.callFunctionSync(bamlFqn, argsProto, null, null);
+                    }
+                    finally {
+                        callCtxBinding.detach();
+                    }
+                    return decodeCallResult(resultBytes);
+                };
+            }
+            if (mode === 'async') {
+                return async (...args) => {
+                    const built = makeArgs(self, args);
+                    const typeArgs = typeArgsFor(built);
+                    const rt = getRuntime();
+                    const callId = newFunctionCall();
+                    const argsProto = encodeCallArgs(built.kwargs, { callId, typeArgs });
+                    const callCtxBinding = attachCallContext(built.ctx, callId);
+                    let resultBytes;
+                    try {
+                        resultBytes = await rt.callFunction(bamlFqn, argsProto, null, null);
+                    }
+                    finally {
+                        callCtxBinding.detach();
+                    }
+                    return decodeCallResult(resultBytes);
+                };
+            }
+            throw new Error(`mode must be 'sync' or 'async', got ${JSON.stringify(mode)}`);
+        },
+    };
+}
+//# sourceMappingURL=define_function.js.map

package/dist/workerd/shared/define_function.js.map

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

package/dist/workerd/shared/errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Structured detail carried by a thrown `BamlError` / `BamlPanic`, mirroring
+ * `bridge_python`'s `BamlError(value, baml_trace=..., class_name=...)`.
+ *
+ * - `value`: the fully decoded thrown BAML value (a generated class instance
+ *   when the FQN is mapped, else a plain object / primitive).
+ * - `bamlTrace`: the pre-rendered `File "...", line N, in fn` frame strings
+ *   from the BAML stack.
+ * - `className`: the thrown value's BAML FQN when known (e.g.
+ *   `baml.json.JsonParseError`).
+ */
+export interface BamlErrorDetail {
+    value?: unknown;
+    bamlTrace?: string[];
+    className?: string;
+}
+export declare class BamlError extends Error {
+    /** The decoded thrown BAML value, or `undefined` for SDK-internal errors. */
+    readonly value: unknown;
+    /** Pre-rendered BAML stack frames; empty for SDK-internal errors. */
+    readonly bamlTrace: string[];
+    /** The thrown value's BAML FQN, when known. */
+    readonly className: string | undefined;
+    constructor(message: string, detail?: BamlErrorDetail);
+}
+export declare class BamlInvalidArgumentError extends BamlError {
+    constructor(message: string);
+}
+export declare class BamlClientError extends BamlError {
+    constructor(message: string);
+}
+export declare class BamlCancelledError extends BamlError {
+    constructor(message: string);
+}
+export declare class BamlAbortError extends Error {
+    readonly reason: unknown;
+    constructor(message: string, options?: {
+        reason?: unknown;
+    });
+}
+/**
+ * Raised for SDK-setup failures and BAML-runtime panics — the Node analog of
+ * `bridge_python`'s `BamlPanic`. The in-call panic path (`decodeCallResult`'s
+ * `panic` arm) and the `getRuntime` not-initialized path both surface this,
+ * except clean process-exit panics, which exit after flushing telemetry.
+ */
+export declare class BamlPanic extends BamlError {
+    constructor(message: string, detail?: BamlErrorDetail);
+}
+export declare function wrapNativeError(err: unknown): BamlError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/workerd/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../typescript_src/shared/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,SAAU,SAAQ,KAAK;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe;CAOxD;AAED,qBAAa,wBAAyB,SAAQ,SAAS;gBACvC,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAC9B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,kBAAmB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,cAAe,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE;CAK9D;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,SAAS;gBACxB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe;CAIxD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAGvD"}

package/dist/workerd/shared/errors.js

@@ -0,0 +1,60 @@
+// errors.ts — mirrors bridge_python/python_src/baml_py/errors.py
+export class BamlError extends Error {
+    /** The decoded thrown BAML value, or `undefined` for SDK-internal errors. */
+    value;
+    /** Pre-rendered BAML stack frames; empty for SDK-internal errors. */
+    bamlTrace;
+    /** The thrown value's BAML FQN, when known. */
+    className;
+    constructor(message, detail) {
+        super(message);
+        this.name = 'BamlError';
+        this.value = detail?.value;
+        this.bamlTrace = detail?.bamlTrace ? [...detail.bamlTrace] : [];
+        this.className = detail?.className;
+    }
+}
+export class BamlInvalidArgumentError extends BamlError {
+    constructor(message) {
+        super(message);
+        this.name = 'BamlInvalidArgumentError';
+    }
+}
+export class BamlClientError extends BamlError {
+    constructor(message) {
+        super(message);
+        this.name = 'BamlClientError';
+    }
+}
+export class BamlCancelledError extends BamlError {
+    constructor(message) {
+        super(message);
+        this.name = 'BamlCancelledError';
+    }
+}
+export class BamlAbortError extends Error {
+    reason;
+    constructor(message, options) {
+        super(message);
+        this.name = 'AbortError';
+        this.reason = options?.reason;
+    }
+}
+/**
+ * Raised for SDK-setup failures and BAML-runtime panics — the Node analog of
+ * `bridge_python`'s `BamlPanic`. The in-call panic path (`decodeCallResult`'s
+ * `panic` arm) and the `getRuntime` not-initialized path both surface this,
+ * except clean process-exit panics, which exit after flushing telemetry.
+ */
+export class BamlPanic extends BamlError {
+    constructor(message, detail) {
+        super(message, detail);
+        this.name = 'BamlPanic';
+    }
+}
+export function wrapNativeError(err) {
+    if (!(err instanceof Error))
+        return new BamlError(String(err));
+    return new BamlError(err.message);
+}
+//# sourceMappingURL=errors.js.map

package/dist/workerd/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../typescript_src/shared/errors.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAmBjE,MAAM,OAAO,SAAU,SAAQ,KAAK;IAChC,6EAA6E;IACpE,KAAK,CAAU;IACxB,qEAAqE;IAC5D,SAAS,CAAW;IAC7B,+CAA+C;IACtC,SAAS,CAAqB;IAEvC,YAAY,OAAe,EAAE,MAAwB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,MAAM,EAAE,KAAK,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,SAAS,CAAC;IACvC,CAAC;CACJ;AAED,MAAM,OAAO,wBAAyB,SAAQ,SAAS;IACnD,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IAC3C,CAAC;CACJ;AAED,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC1C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAClC,CAAC;CACJ;AAED,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAC7C,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACrC,CAAC;CACJ;AAED,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC5B,MAAM,CAAU;IAEzB,YAAY,OAAe,EAAE,OAA8B;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAClC,CAAC;CACJ;AAED;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,SAAS;IACpC,YAAY,OAAe,EAAE,MAAwB;QACjD,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC5B,CAAC;CACJ;AAED,MAAM,UAAU,eAAe,CAAC,GAAY;IACxC,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/D,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/workerd/shared/host_value_registry.d.ts

@@ -0,0 +1,50 @@
+import { type HandleKey } from '../native.js';
+/**
+ * Register an arbitrary host JS value and return its native `HandleKey` for
+ * the `_handle: Handle(HOST_VALUE_OPAQUE, key)` slot of a
+ * `baml.errors.HostCallable` Instance (or any future opaque-value carrier).
+ * Mints a fresh key via the Rust side's shared counter (guaranteed non-zero —
+ * Rust `next_key` skips `0`); stores the value keyed by the same key
+ * (recomposed as a `bigint` for `Map`-key equality).
+ *
+ * Returns the native `HandleKey` directly so it can flow into the
+ * protobufjs encoder without an intermediate `bigint→Long` conversion
+ * (protobufjs reads `uint64` fields from a `{low, high}` shape, which
+ * the native `HandleKey` already provides; a bare `bigint` does not
+ * encode correctly through the `IInboundValue.handle.key` field).
+ */
+export declare function registerHostOpaque(value: unknown): HandleKey;
+/**
+ * Look up a host-registered JS value by key. Returns `undefined` when:
+ * - the key is the reserved sentinel `0n` (no real value was registered);
+ * - the engine has already released the entry (last `HostValueArc` clone
+ *   dropped → Rust `host_release_callback` fired → `_releaseHostValue`
+ *   removed the entry);
+ * - the key was minted by a different Node process (cross-runtime handle).
+ *
+ * Callers should fall back to a metadata-built exception in those cases.
+ *
+ * GC/decode race: a release notification and a rehydrating decode can be
+ * scheduled on the libuv loop concurrently in principle, but in practice
+ * the same `HostValueArc` cannot drop *while* the engine is actively
+ * emitting an outbound proto referencing its key — the outbound encode
+ * holds a strong handle through proto serialization, and the release tsfn
+ * isn't fired until that strong handle drops. By the time the TS decoder
+ * runs `tryRehydrateHostValueByKey`, the only way the map entry is gone is if
+ * a *prior* outbound completed and the engine has since dropped its last
+ * Arc; in that case the user has already observed the original throw at
+ * least once, so a second lookup-miss → metadata-fallback is acceptable.
+ */
+export declare function lookupHostValue(key: bigint): unknown;
+/**
+ * Convenience for the outbound decoder: if `handle` is a `BamlHandle`
+ * tagged `HOST_VALUE_OPAQUE`, look up the originating JS value in
+ * the registry and return it. Returns `undefined` for any other handle
+ * type, a non-`BamlHandle` argument, or a key that doesn't resolve.
+ *
+ * Used by `decodeCallResult`'s `error` arm to rehydrate the original JS
+ * exception when a BAML-thrown `baml.errors.HostCallable` propagates back
+ * to the same Node process that originated it.
+ */
+export declare function tryRehydrateHostValueByKey(handle: unknown): unknown;
+//# sourceMappingURL=host_value_registry.d.ts.map

package/dist/workerd/shared/host_value_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host_value_registry.d.ts","sourceRoot":"","sources":["../../typescript_src/shared/host_value_registry.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAkE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AA4B9G;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAI5D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAInE"}

package/dist/workerd/shared/host_value_registry.js

@@ -0,0 +1,134 @@
+// host_value_registry.ts — mirrors bridge_python's `register_host_opaque`
+// + `lookup_host_value` pair.
+//
+// An arbitrary host JS value round-trips back to the *same* Node process as
+// the *same* object (identity preserved), not flattened into a metadata-only
+// wrapper. A native JS exception raised inside a user callable is the primary
+// consumer: it round-trips as the *same* `Error` object (`raised === caught`
+// identity), not a metadata-only `BamlError(HostCallable(...))` wrapper. The
+// plumbing:
+//
+//   1. The TS bridge catches the JS error inside `sendHostCallableError`
+//      (proto.ts) and calls `registerHostOpaque(err)` here.
+//   2. `registerHostOpaque` mints a globally-unique key via
+//      `native.mintHostValueKey` (drawing from the shared callable+opaque
+//      counter on the Rust side so the engine sees one keyspace), stores
+//      the JS value in the local `Map<bigint, unknown>`, returns the key.
+//   3. The bridge emits an `InboundValue.Class(name="baml.errors.HostCallable",
+//      fields=[..., _handle: Handle(HOST_VALUE_OPAQUE, key)])`. The engine
+//      interns an `Arc<HostValueArc>` per the same key.
+//   4. When BAML propagates the throw back out to the host, the outbound
+//      encoder re-emits the `_handle: Handle(HOST_VALUE_OPAQUE, key)`. The
+//      TS decoder (proto.ts) inspects a decoded `HostCallable` instance,
+//      reads `_handle.key`, calls `lookupHostValue(key)` here, and re-throws
+//      the original JS error.
+//   5. When the engine drops its last `Arc<HostValueArc>(key)`, the Rust
+//      `host_release_callback` fires the TS-installed release callback
+//      (`native.registerHostValueReleaseCallback`), which calls `_releaseHostValue`
+//      here to remove the map entry.
+//
+// Foreign runtimes (a different Node process, the Python bridge, etc.) see
+// a `_handle` whose key doesn't resolve in their local registry; the
+// decoder falls back to the metadata-bearing `BamlError(HostCallable(...))`
+// wrapper. The reserved `0` is used as a sentinel by code paths that
+// cannot register a real JS value (engine-internal synthetic faults like
+// "no JS callable for this key"); `_releaseHostValue(0n)` is a benign
+// no-op since `mintHostValueKey` never returns `0`.
+import { mintHostValueKey, registerHostValueReleaseCallback, BamlHandle } from '../native.js';
+import { baml_bridge } from './proto/baml_cffi.js';
+const BamlHandleType = baml_bridge.cffi.v1.BamlHandleType;
+const hostValueMap = new Map();
+/**
+ * Convert a `HandleKey` (`{ low, high }`) to a `bigint` for use as a `Map` key.
+ * Native `HandleKey` instances split a `u64` across two `i32` low/high halves
+ * (signed, two's-complement). Recompose by treating each half as a 32-bit
+ * unsigned value via `>>> 0`, then shift+or as `bigint`.
+ *
+ * The `>>> 0` coercion matters whenever either half's MSB is set: without it,
+ * a negative `i32` would widen to a negative `bigint` and corrupt the
+ * recomposed `u64`. Examples:
+ *
+ *   - `{ low: 1, high: 0 }` →  `0x1n`               (small key, no MSB set)
+ *   - `{ low: -1, high: -1 }` → `0xFFFFFFFFFFFFFFFFn` (u64::MAX; both halves'
+ *      MSB set — `>>> 0` reinterprets `-1` as `0xFFFFFFFF` before widening)
+ *   - `{ low: 0, high: 1 }` →  `0x1_00000000n`     (2^32)
+ */
+function handleKeyToBigint(key) {
+    const low = BigInt(key.low >>> 0);
+    const high = BigInt(key.high >>> 0);
+    return (high << 32n) | low;
+}
+/**
+ * Register an arbitrary host JS value and return its native `HandleKey` for
+ * the `_handle: Handle(HOST_VALUE_OPAQUE, key)` slot of a
+ * `baml.errors.HostCallable` Instance (or any future opaque-value carrier).
+ * Mints a fresh key via the Rust side's shared counter (guaranteed non-zero —
+ * Rust `next_key` skips `0`); stores the value keyed by the same key
+ * (recomposed as a `bigint` for `Map`-key equality).
+ *
+ * Returns the native `HandleKey` directly so it can flow into the
+ * protobufjs encoder without an intermediate `bigint→Long` conversion
+ * (protobufjs reads `uint64` fields from a `{low, high}` shape, which
+ * the native `HandleKey` already provides; a bare `bigint` does not
+ * encode correctly through the `IInboundValue.handle.key` field).
+ */
+export function registerHostOpaque(value) {
+    const key = mintHostValueKey();
+    hostValueMap.set(handleKeyToBigint(key), value);
+    return key;
+}
+/**
+ * Look up a host-registered JS value by key. Returns `undefined` when:
+ * - the key is the reserved sentinel `0n` (no real value was registered);
+ * - the engine has already released the entry (last `HostValueArc` clone
+ *   dropped → Rust `host_release_callback` fired → `_releaseHostValue`
+ *   removed the entry);
+ * - the key was minted by a different Node process (cross-runtime handle).
+ *
+ * Callers should fall back to a metadata-built exception in those cases.
+ *
+ * GC/decode race: a release notification and a rehydrating decode can be
+ * scheduled on the libuv loop concurrently in principle, but in practice
+ * the same `HostValueArc` cannot drop *while* the engine is actively
+ * emitting an outbound proto referencing its key — the outbound encode
+ * holds a strong handle through proto serialization, and the release tsfn
+ * isn't fired until that strong handle drops. By the time the TS decoder
+ * runs `tryRehydrateHostValueByKey`, the only way the map entry is gone is if
+ * a *prior* outbound completed and the engine has since dropped its last
+ * Arc; in that case the user has already observed the original throw at
+ * least once, so a second lookup-miss → metadata-fallback is acceptable.
+ */
+export function lookupHostValue(key) {
+    return hostValueMap.get(key);
+}
+/**
+ * Convenience for the outbound decoder: if `handle` is a `BamlHandle`
+ * tagged `HOST_VALUE_OPAQUE`, look up the originating JS value in
+ * the registry and return it. Returns `undefined` for any other handle
+ * type, a non-`BamlHandle` argument, or a key that doesn't resolve.
+ *
+ * Used by `decodeCallResult`'s `error` arm to rehydrate the original JS
+ * exception when a BAML-thrown `baml.errors.HostCallable` propagates back
+ * to the same Node process that originated it.
+ */
+export function tryRehydrateHostValueByKey(handle) {
+    if (!(handle instanceof BamlHandle))
+        return undefined;
+    if (handle.handleType !== BamlHandleType.HOST_VALUE_OPAQUE)
+        return undefined;
+    return lookupHostValue(handleKeyToBigint(handle.key));
+}
+/**
+ * Internal: remove the map entry for `key`. Wired at module init as the
+ * Rust-side release callback. Idempotent and absent-key-safe so the same
+ * callback can be invoked for *every* `HostValueArc` release (including
+ * callable keys, which never have a TS-side host-value entry).
+ */
+function _releaseHostValue(key) {
+    hostValueMap.delete(handleKeyToBigint(key));
+}
+// Install the Rust-side release callback exactly once at module load. The
+// napi function is itself first-call-wins on the Rust side, so reloads
+// (e.g. test harnesses) are harmless.
+registerHostValueReleaseCallback(_releaseHostValue);
+//# sourceMappingURL=host_value_registry.js.map

package/dist/workerd/shared/host_value_registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host_value_registry.js","sourceRoot":"","sources":["../../typescript_src/shared/host_value_registry.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8BAA8B;AAC9B,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,YAAY;AACZ,EAAE;AACF,yEAAyE;AACzE,4DAA4D;AAC5D,4DAA4D;AAC5D,0EAA0E;AAC1E,yEAAyE;AACzE,0EAA0E;AAC1E,gFAAgF;AAChF,2EAA2E;AAC3E,wDAAwD;AACxD,yEAAyE;AACzE,2EAA2E;AAC3E,yEAAyE;AACzE,6EAA6E;AAC7E,8BAA8B;AAC9B,yEAAyE;AACzE,uEAAuE;AACvE,oFAAoF;AACpF,qCAAqC;AACrC,EAAE;AACF,2EAA2E;AAC3E,qEAAqE;AACrE,4EAA4E;AAC5E,qEAAqE;AACrE,yEAAyE;AACzE,sEAAsE;AACtE,oDAAoD;AAEpD,OAAO,EAAE,gBAAgB,EAAE,gCAAgC,EAAE,UAAU,EAAkB,MAAM,cAAc,CAAC;AAC9G,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,cAAc,CAAC;AAE1D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAmB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,SAAS,iBAAiB,CAAC,GAAc;IACrC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC7C,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,YAAY,CAAC,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACvC,OAAO,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAe;IACtD,IAAI,CAAC,CAAC,MAAM,YAAY,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACtD,IAAI,MAAM,CAAC,UAAU,KAAK,cAAc,CAAC,iBAAiB;QAAE,OAAO,SAAS,CAAC;IAC7E,OAAO,eAAe,CAAC,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAc;IACrC,YAAY,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,0EAA0E;AAC1E,uEAAuE;AACvE,sCAAsC;AACtC,gCAAgC,CAAC,iBAAiB,CAAC,CAAC"}