camino-package-runtime/src/bindings.ts

import { create } from "@bufbuild/protobuf";
import { ValueSchema, ObjectValueSchema, type Value } from "./camino/api_pb.js";
import {
  derived,
  jsToProtoValue,
  liveValue,
  protoValueToJs,
  type RuntimeContext,
  type RuntimeHandler,
  type DerivedHandler,
} from "./index.js";

export type { QxObjectRef } from "./references.js";
import { assertReferenceFree, referenceToWire } from "./references.js";
declare const watchBrand: unique symbol;
export type QxWatchHandle = string & { readonly [watchBrand]: true };
export type MessageBinding<T> = { encode(value: T): Value; decode(value: Value): T };
export type QxLiveValue = ReturnType<typeof liveValue>;
const reactPropsDescriptor = "org.quixos.web-studio.ReactProps";
// Explicit temporary props exception, matching orch's RPC contract. Field shapes
// remain unchecked pending generics; ordinary messages and state do not gain it.
export const opaqueReactPropsBinding: MessageBinding<Record<string, unknown>> = {
  encode(value) {
    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("React props must be an object");
    return jsToProtoValue(value);
  },
  decode(value) {
    if (value.kind.case !== "objectValue") throw new Error("React props must be an object");
    return protoValueToJs(value) as Record<string, unknown>;
  },
};
export type BindingValue<B> = B extends MessageBinding<infer T> ? T : never;
export type QxHandler<C, O> = (context: C) => O | Promise<O>;
export type QxDerived<C, O> = { kind: "derived"; get: QxHandler<C, O> };
export type QxSession<C> = { id: string; run<T>(work: (context: C) => Promise<T>): Promise<T>; close(): Promise<void> };
export type QxContextLifecycle<C> = { signal?: AbortSignal; openSession?: () => Promise<QxSession<C>> };
export const qxDerived = <C, O>(get: QxHandler<C, O>): QxDerived<C, O> => ({ kind: "derived", get });

/** Versioned binding ABI. This mirrors the language-neutral value IR. */
export type QxValueType =
  | { kind: "builtin"; name: "unit" | "watch-handle" }
  | { kind: "scalar"; name: string }
  | { kind: "message"; descriptorId: string }
  | { kind: "record"; fields: Record<string, QxValueType> }
  | { kind: "object-ref"; expectation: unknown }
  | { kind: "optional" | "list"; value: QxValueType };
export type QxOperationSpec = { id: string; inputType: QxValueType; outputType: QxValueType };
export type QxPortSpec =
  | { kind: "state"; id: string; valueType: QxValueType; primitives: string[] }
  | { kind: "edge"; id: string; primitives: string[] }
  | { kind: "interface"; id: string; operations: Record<string, QxOperationSpec> }
  | { kind: "constructor"; id: string; inputType: QxValueType };
export type QxHandlerSpec = {
  inputType: QxValueType;
  outputType: QxValueType;
  eventType?: QxValueType;
  ports: Record<string, QxPortSpec>;
};
export type QxMessages = Record<string, MessageBinding<any>>;

// Conversion belongs at the binding boundary. It does not add orchestrator validation.
export const decodeQxValue = (type: QxValueType, value: Value | undefined, messages: QxMessages): any => {
  if (type.kind === "builtin" && type.name === "unit") return null;
  if (type.kind === "optional" && !value) return null;
  if (!value) throw new Error("Missing QX wire value");
  if (type.kind === "record") {
    if (value.kind.case !== "objectValue") throw new Error("Expected QX record");
    const fields = value.kind.value.fields;
    if (Object.keys(fields).some((name) => !Object.hasOwn(type.fields, name)))
      throw new Error("Unexpected QX record field");
    return Object.fromEntries(
      Object.entries(type.fields).map(([name, field]) => [name, decodeQxValue(field, fields[name], messages)]),
    );
  }
  if (type.kind === "optional")
    return value.kind.case === "nullValue" ? null : decodeQxValue(type.value, value, messages);
  if (type.kind === "list") {
    if (value.kind.case !== "listValue") throw new Error("Expected QX list");
    return value.kind.value.values.map((entry) => decodeQxValue(type.value, entry, messages));
  }
  if (type.kind === "message") {
    if (type.descriptorId !== reactPropsDescriptor) assertReferenceFree(protoValueToJs(value));
    const decoded = requireMessage(messages, type.descriptorId).decode(value);
    if (type.descriptorId !== reactPropsDescriptor) assertReferenceFree(decoded);
    return decoded;
  }
  if (type.kind === "object-ref") {
    if (value.kind.case !== "refValue") throw new Error("Expected a declared RPC object reference");
    return protoValueToJs(value);
  }
  if (value.kind.case === "refValue") throw new Error("Reference supplied to a non-reference value");
  if (type.kind === "scalar") {
    if (type.name === "int64" || type.name === "uint64") {
      if (value.kind.case !== "integerValue") throw new Error("Expected QX integer");
      return BigInt(value.kind.value);
    }
    if (type.name === "bytes") {
      if (value.kind.case !== "bytesValue") throw new Error("Expected QX bytes");
      return value.kind.value;
    }
  }
  return protoValueToJs(value);
};

const requireMessage = (messages: QxMessages, id: string) => {
  const binding = messages[id];
  if (!binding) throw new Error(`Missing message binding ${id}`);
  return binding;
};
export const encodeQxValue = (type: QxValueType, value: any, messages: QxMessages): Value => {
  if (type.kind === "builtin" && type.name === "unit") return jsToProtoValue(null);
  if (type.kind === "record") {
    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected QX record");
    if (Object.keys(value).some((name) => !Object.hasOwn(type.fields, name)))
      throw new Error("Unexpected QX record field");
    const fields = Object.fromEntries(
      Object.entries(type.fields).map(([name, field]) => {
        if (!Object.hasOwn(value, name) && field.kind !== "optional")
          throw new Error(`Missing QX record field ${name}`);
        return [name, encodeQxValue(field, value[name] ?? (field.kind === "optional" ? null : value[name]), messages)];
      }),
    );
    return create(ValueSchema, { kind: { case: "objectValue", value: create(ObjectValueSchema, { fields }) } });
  }
  if (type.kind === "optional")
    return value === null ? jsToProtoValue(null) : encodeQxValue(type.value, value, messages);
  if (type.kind === "list")
    return jsToProtoValue(value.map((entry: unknown) => liveValue(encodeQxValue(type.value, entry, messages))));
  if (type.kind === "object-ref") {
    referenceToWire(value);
    return jsToProtoValue(value);
  }
  if (type.kind !== "message" || type.descriptorId !== reactPropsDescriptor) assertReferenceFree(value);
  if (type.kind === "message") {
    const encoded = requireMessage(messages, type.descriptorId).encode(value);
    if (type.descriptorId !== reactPropsDescriptor) assertReferenceFree(protoValueToJs(encoded));
    return encoded;
  }
  return jsToProtoValue(value);
};

const inputValue = (context: RuntimeContext, type: QxValueType) => {
  if (type.kind === "message" || type.kind === "record")
    return create(ValueSchema, {
      kind: { case: "objectValue", value: create(ObjectValueSchema, { fields: context.inputProto }) },
    });
  return context.inputProto.value;
};
const inputFields = (type: QxValueType, value: unknown, messages: QxMessages): Record<string, unknown> => {
  if (type.kind === "builtin" && type.name === "unit") return {};
  const encoded = encodeQxValue(type, value, messages);
  if (type.kind === "message" || type.kind === "record") {
    if (encoded.kind.case !== "objectValue") throw new Error("Message inputs must encode an object value");
    return Object.fromEntries(Object.entries(encoded.kind.value.fields).map(([key, entry]) => [key, liveValue(entry)]));
  }
  return { value: liveValue(encoded) };
};

/** The sole unchecked cast connects generated contracts to the dynamic RPC runtime. */
export const bindQxHandler = <C, O>(
  spec: QxHandlerSpec,
  handler: QxHandler<C, O> | QxDerived<C, O>,
  messages: QxMessages,
): RuntimeHandler | DerivedHandler => {
  const bindContext = (raw: RuntimeContext): C => {
    const ports = Object.fromEntries(
      Object.entries(spec.ports).map(([name, port]) => {
        switch (port.kind) {
          case "state": {
            const state = raw.state(port.id);
            return [
              name,
              {
                ...(port.primitives.includes("read")
                  ? {
                      get: async () => decodeQxValue(port.valueType, (await state.live()).$quixosValue, messages),
                      live: () => state.live(),
                    }
                  : {}),
                ...(port.primitives.includes("write")
                  ? {
                      set: async (value: unknown) =>
                        state.set(liveValue(encodeQxValue(port.valueType, value, messages))),
                    }
                  : {}),
              },
            ];
          }
          case "edge": {
            const edge = raw.edge(port.id);
            return [
              name,
              {
                ...Object.fromEntries(
                  port.primitives.map((primitive) => [
                    primitive,
                    edge[primitive as "resolve" | "connect" | "disconnect"],
                  ]),
                ),
                ...(port.primitives.includes("resolve") ? { collection: edge.collection } : {}),
                ...(port.primitives.includes("resolve") &&
                port.primitives.includes("connect") &&
                port.primitives.includes("disconnect")
                  ? { replace: edge.replace }
                  : {}),
              },
            ];
          }
          case "interface": {
            const target = raw.interface(port.id);
            return [
              name,
              {
                objectId: target.objectId,
                live: Object.fromEntries(
                  Object.entries(port.operations).map(([name, operation]) => [
                    name,
                    (input: unknown) => target.live(operation.id, inputFields(operation.inputType, input, messages)),
                  ]),
                ),
                ...Object.fromEntries(
                  Object.entries(port.operations).map(([name, operation]) => [
                    name,
                    async (input: unknown) =>
                      decodeQxValue(
                        operation.outputType,
                        (await target.live(operation.id, inputFields(operation.inputType, input, messages)))
                          .$quixosValue,
                        messages,
                      ),
                  ]),
                ),
              },
            ];
          }
          case "constructor":
            return [
              name,
              {
                construct: (input: unknown) =>
                  raw.constructor(port.id).construct(inputFields(port.inputType, input, messages)),
              },
            ];
        }
      }),
    );
    return {
      objectId: raw.objectId,
      signal: raw.signal,
      ...(raw.openSession
        ? {
            openSession: async () => {
              const session = await raw.openSession!();
              return {
                id: session.id,
                close: () => session.close(),
                run: <T>(work: (context: C) => Promise<T>) => session.run((next) => work(bindContext(next))),
              };
            },
          }
        : {}),
      input: decodeQxValue(spec.inputType, inputValue(raw, spec.inputType), messages),
      ports,
    } as C;
  };
  const execute = async (raw: RuntimeContext) => {
    const context = bindContext(raw);
    const value = await (typeof handler === "function" ? handler(context) : handler.get(context));
    return liveValue(encodeQxValue(spec.eventType ?? spec.outputType, value, messages));
  };
  return typeof handler === "function" ? execute : derived(execute);
};