@lostgradient/weft 0.2.0

package/dist/server/deadline-tracker.js

@@ -0,0 +1,106 @@
+export class DeadlineTracker {
+  #heap;
+  #liveGeneration;
+  #nextGeneration;
+  #liveCount;
+  constructor() {
+    this.#heap = [];
+    this.#liveGeneration = new Map;
+    this.#nextGeneration = 1;
+    this.#liveCount = 0;
+  }
+  get size() {
+    return this.#liveCount;
+  }
+  peekDeadline() {
+    this.#purgeTop();
+    return this.#heap[0]?.deadline;
+  }
+  add(entry) {
+    const wasLive = this.#isLive(entry.operationId), generation = this.#nextGeneration++;
+    this.#liveGeneration.set(entry.operationId, generation);
+    this.#heap.push({ ...entry, generation });
+    this.#siftUp(this.#heap.length - 1);
+    if (!wasLive)
+      this.#liveCount++;
+  }
+  popMin() {
+    this.#purgeTop();
+    if (this.#heap.length === 0)
+      return;
+    const min = this.#extractMin();
+    this.#liveGeneration.delete(min.operationId);
+    this.#liveCount--;
+    return min;
+  }
+  remove(operationId) {
+    if (!this.#isLive(operationId))
+      return;
+    this.#liveGeneration.delete(operationId);
+    this.#liveCount--;
+  }
+  drainExpired(now) {
+    const expired = [];
+    while (!0) {
+      this.#purgeTop();
+      if (this.#heap.length === 0 || this.#heap[0].deadline > now)
+        break;
+      const min = this.#extractMin();
+      this.#liveGeneration.delete(min.operationId);
+      this.#liveCount--;
+      expired.push(min);
+    }
+    return expired;
+  }
+  clear() {
+    this.#heap.length = 0;
+    this.#liveGeneration.clear();
+    this.#liveCount = 0;
+  }
+  #isLive(operationId) {
+    const gen = this.#liveGeneration.get(operationId);
+    return gen !== void 0 && gen > 0;
+  }
+  #isStale(entry) {
+    const live = this.#liveGeneration.get(entry.operationId) ?? 0;
+    return entry.generation !== live;
+  }
+  #extractMin() {
+    if (this.#heap.length === 0)
+      return;
+    const min = this.#heap[0], last = this.#heap.pop();
+    if (this.#heap.length > 0) {
+      this.#heap[0] = last;
+      this.#siftDown(0);
+    }
+    return min;
+  }
+  #purgeTop() {
+    while (this.#heap.length > 0 && this.#isStale(this.#heap[0]))
+      this.#extractMin();
+  }
+  #siftUp(index) {
+    while (index > 0) {
+      const parent = index - 1 >>> 1;
+      if (this.#heap[parent].deadline <= this.#heap[index].deadline)
+        break;
+      [this.#heap[parent], this.#heap[index]] = [this.#heap[index], this.#heap[parent]];
+      index = parent;
+    }
+  }
+  #siftDown(index) {
+    const length = this.#heap.length;
+    while (!0) {
+      let smallest = index;
+      const left = 2 * index + 1, right = 2 * index + 2;
+      if (left < length && this.#heap[left].deadline < this.#heap[smallest].deadline)
+        smallest = left;
+      if (right < length && this.#heap[right].deadline < this.#heap[smallest].deadline)
+        smallest = right;
+      if (smallest === index)
+        break;
+      [this.#heap[smallest], this.#heap[index]] = [this.#heap[index], this.#heap[smallest]];
+      index = smallest;
+    }
+  }
+}

package/dist/server/discovery-filter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared operation filter for public discovery documents.
+ *
+ * @module server/discovery-filter
+ */
+import type { ErasedOperation } from './operation-catalog.ts';
+/**
+ * Return whether an operation should appear in generated discovery documents.
+ *
+ * Public operations are always discoverable. Non-public operations opt in with
+ * `discoverable: true`; `discoverable: false` cannot hide a public operation.
+ */
+export declare function isDiscoverable(operation: ErasedOperation): boolean;

package/dist/server/discovery-filter.js

@@ -0,0 +1,5 @@
+export function isDiscoverable(operation) {
+  if (operation.access.kind === "public")
+    return !0;
+  return operation.discoverable === !0;
+}

package/dist/server/discovery-info.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared `DiscoveryInfo` type and helper for applying it to API discovery documents.
+ *
+ * @module server/discovery-info
+ */
+/**
+ * Operator-supplied metadata applied uniformly to all three discovery documents
+ * (`/openapi.json`, `/openrpc.json`, `/asyncapi.json`). Set it once on
+ * `serve({ discoveryInfo })` and the description, contact, license, and
+ * external-docs fields appear in every discovery surface from a single source,
+ * so the three documents never drift.
+ *
+ * @example
+ * ```ts
+ * import { serve, type DiscoveryInfo } from '@lostgradient/weft/server';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * const discoveryInfo: DiscoveryInfo = {
+ *   description: 'Order processing API',
+ *   contact: { name: 'Platform', email: 'platform@example.com' },
+ *   license: { name: 'MIT' },
+ * };
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * await using server = serve({ engine, discoveryInfo });
+ * void server;
+ * ```
+ */
+export type DiscoveryInfo = {
+    /** Long-form description rendered in each document's `info.description`. */
+    description?: string;
+    /** Contact details rendered in each document's `info.contact`. */
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    /** License rendered in each document's `info.license`. */
+    license?: {
+        name: string;
+        url?: string;
+    };
+    /**
+     * External documentation reference. **Placement is asymmetric across the
+     * three discovery documents:**
+     *
+     * - OpenAPI 3.1: rendered inside `info.externalDocs` (or at the document
+     *   root depending on the OpenAPI generator's chosen location, but
+     *   semantically attached to the document's metadata block).
+     * - OpenRPC 1.3.2: rendered inside `info.externalDocs`.
+     * - AsyncAPI 3.0.0: rendered at the **document top-level**, NOT inside
+     *   `info`. The AsyncAPI 3.0 spec moved `externalDocs` out of `info`.
+     *
+     * `applyDiscoveryInfo` does NOT place this field; each generator's call
+     * site is responsible for picking the spec-correct location.
+     */
+    externalDocs?: {
+        description?: string;
+        url: string;
+    };
+};
+/**
+ * Merge `DiscoveryInfo` fields into a document's `info` object (or top-level
+ * for AsyncAPI 3.0 `externalDocs`).
+ *
+ * Returns a shallow copy of `target` with the discovery info fields applied.
+ * Fields absent from `info` are omitted from the output.
+ */
+export declare function applyDiscoveryInfo(target: Record<string, unknown>, info: DiscoveryInfo | undefined): Record<string, unknown>;

package/dist/server/discovery-info.js

@@ -0,0 +1,12 @@
+export function applyDiscoveryInfo(target, info) {
+  if (info === void 0)
+    return target;
+  const result = { ...target };
+  if (info.description !== void 0)
+    result.description = info.description;
+  if (info.contact !== void 0)
+    result.contact = { ...info.contact };
+  if (info.license !== void 0)
+    result.license = { ...info.license };
+  return result;
+}

package/dist/server/engine-event-feed-backend.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Engine-backed `WorkflowEventFeedBackend` — the production backing
+ * for `createWorkflowEventFeed` (see `workflow-event-feed.ts`). REST
+ * SSE, the JSON-RPC WebSocket session, and the JSON-RPC stdio session
+ * all consume the feed; this module is where the feed meets the
+ * `Engine`'s durable state.
+ *
+ * **Single committed sequence authority.** Replay and live delivery
+ * share the same source of truth — the unified
+ * `replayWorkflowFeed` / `snapshotWorkflowFeedTail` /
+ * `subscribeWorkflowFeedCommits` triple on `Engine`. The subscription
+ * fires only AFTER `storage.batch()` (events) or `storage.put()`
+ * (tokens) resolves, so an event in the live buffer is already
+ * durable and scannable by `replayWorkflowFeed`. This is the
+ * invariant the feed's atomic-handoff (buffer-then-snapshot-then-
+ * replay-then-drain) relies on.
+ *
+ * The backend is intentionally stateless — it holds only the `Engine`
+ * reference. Listener state lives on the engine and is cleaned up by
+ * the caller's unsubscribe function.
+ *
+ * @module server/engine-event-feed-backend
+ */
+import type { Engine } from '../core/engine.ts';
+import { type WorkflowEventFeedBackend } from './workflow-event-feed.ts';
+/**
+ * Build the production `WorkflowEventFeedBackend`. Call once per
+ * engine instance and share the returned backend across every
+ * transport that needs a feed.
+ */
+export declare function createEngineEventFeedBackend(engine: Engine): WorkflowEventFeedBackend;

package/dist/server/engine-event-feed-backend.js

@@ -0,0 +1,36 @@
+import {
+  encodeCursor
+} from "./workflow-event-feed.js";
+export function createEngineEventFeedBackend(engine) {
+  return {
+    async* replay({ workflowId, selector, afterSequence }) {
+      const coreSelector = toCoreSelector(selector);
+      for await (const record of engine.replayWorkflowFeed(workflowId, coreSelector, afterSequence))
+        yield recordToEnvelope(record);
+    },
+    snapshotTailSequence(workflowId, selector) {
+      return engine.snapshotWorkflowFeedTail(workflowId, toCoreSelector(selector));
+    },
+    subscribeLive(workflowId, selector, listener) {
+      return engine.subscribeWorkflowFeedCommits(workflowId, toCoreSelector(selector), (record) => listener(recordToEnvelope(record)));
+    }
+  };
+}
+function toCoreSelector(selector) {
+  if (selector === "events")
+    return "events";
+  if (selector === "tokens")
+    return "tokens";
+  throw Error(`Unhandled EventSelector: ${String(selector)}`);
+}
+function recordToEnvelope(record) {
+  return {
+    kind: record.kind,
+    workflowId: record.workflowId,
+    selector: record.selector,
+    sequence: record.sequence,
+    cursor: encodeCursor(record.sequence),
+    emittedAtMs: record.timestamp,
+    payload: record.payload
+  };
+}

package/dist/server/fault-to-http.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `faultToHttpResponse` — pure mapper from a transport-neutral
+ * `OperationFault` into a `Response` shaped for the REST surface.
+ *
+ * Body shape: `{ error: { code, message, data? } }`. The `code` matches the
+ * fault discriminant verbatim so REST clients can switch on the same names
+ * that JSON-RPC clients see in their `data.weftCode`.
+ *
+ * Pure: no engine, no I/O, no logging. Errors visible to clients are
+ * exactly what the fault carries; internal `EngineFailure` detail belongs
+ * in server logs, not the response body.
+ */
+import { type OperationFault } from './operation-fault.ts';
+export declare function faultToHttpResponse(fault: OperationFault): Response;

package/dist/server/fault-to-http.js

@@ -0,0 +1,29 @@
+import { FAULT_CODE_TO_HTTP_STATUS } from "./operation-fault.js";
+export function faultToHttpResponse(fault) {
+  const status = FAULT_CODE_TO_HTTP_STATUS[fault.code], body = JSON.stringify({ error: shapeErrorBody(fault) }), headers = new Headers({ "content-type": "application/json; charset=utf-8" });
+  return new Response(body, { status, headers });
+}
+function shapeErrorBody(fault) {
+  const base = { code: fault.code, message: fault.message };
+  if (fault.code === "EngineFailure" || fault.code === "NotImplemented")
+    return base;
+  if (fault.code === "Timeout")
+    return shapeTimeoutBody(base, fault.data);
+  if (fault.code === "NotFound")
+    return shapeNotFoundBody(base, fault.data);
+  return { ...base, data: fault.data };
+}
+function shapeTimeoutBody(base, data) {
+  const defined = filterDefined(data);
+  return Object.keys(defined).length === 0 ? base : { ...base, data: defined };
+}
+function shapeNotFoundBody(base, data) {
+  return data.identifier === void 0 ? { ...base, data: { resource: data.resource } } : { ...base, data };
+}
+function filterDefined(input) {
+  const output = {};
+  for (const [key, value] of Object.entries(input))
+    if (value !== void 0)
+      output[key] = value;
+  return output;
+}

package/dist/server/fault-to-json-rpc.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `faultToJsonRpcError` — pure mapper from a transport-neutral
+ * `OperationFault` into the JSON-RPC 2.0 error object the dispatchers send.
+ *
+ * Wire shape: `{ code, message, data }`. The numeric `code` follows the
+ * JSON-RPC spec for reserved errors (`InvalidParams: -32602`,
+ * `MethodNotFound: -32601`) and the Weft domain band -32010..-32099 for
+ * everything else (per Track 8 design decision 4).
+ *
+ * Every `data` object carries `{ weftCode, httpStatus }` plus the typed
+ * fault-specific payload. The pair is a uniform machine-readable handle:
+ * clients can route on `weftCode` (string) when they want symbolic names,
+ * or on `httpStatus` (number) when they want HTTP-equivalent semantics.
+ *
+ * Pure: no engine, no I/O. The fault decides the wire shape.
+ */
+import { type OperationFault } from './operation-fault.ts';
+export type JsonRpcError = {
+    code: number;
+    message: string;
+    data: Record<string, unknown>;
+};
+export declare function faultToJsonRpcError(fault: OperationFault): JsonRpcError;

package/dist/server/fault-to-json-rpc.js

@@ -0,0 +1,60 @@
+import {
+  FAULT_CODE_TO_HTTP_STATUS,
+  FAULT_CODE_TO_JSON_RPC_CODE
+} from "./operation-fault.js";
+export function faultToJsonRpcError(fault) {
+  const code = FAULT_CODE_TO_JSON_RPC_CODE[fault.code], httpStatus = FAULT_CODE_TO_HTTP_STATUS[fault.code], data = {
+    ...extractFaultDataPayload(fault),
+    weftCode: fault.code,
+    httpStatus
+  };
+  return { code, message: fault.message, data };
+}
+const EMPTY = {}, FAULT_DATA_EXTRACTORS = {
+  NotImplemented: () => EMPTY,
+  EngineFailure: () => EMPTY,
+  Unauthorized: (data) => ({ reason: data.reason }),
+  Forbidden: (data) => ({ reason: data.reason }),
+  Unprocessable: (data) => ({ reason: data.reason }),
+  Conflict: dataForConflict,
+  NotFound: dataForNotFound,
+  Timeout: dataForTimeout,
+  UnsupportedTransport: dataForUnsupportedTransport,
+  SubscriptionOverflow: dataForSubscriptionOverflow,
+  InvalidParams: dataForInvalidParams,
+  MethodNotFound: (data) => ({ method: data.method })
+};
+function extractFaultDataPayload(fault) {
+  const extractor = FAULT_DATA_EXTRACTORS[fault.code];
+  return extractor(fault.data);
+}
+function dataForConflict(data) {
+  return filterDefined({
+    reason: data.reason,
+    missingTypes: data.missingTypes === void 0 ? void 0 : [...data.missingTypes],
+    missingWorkflowCount: data.missingWorkflowCount,
+    samplesTruncated: data.samplesTruncated
+  });
+}
+function dataForNotFound(data) {
+  return data.identifier === void 0 ? { resource: data.resource } : { resource: data.resource, identifier: data.identifier };
+}
+function dataForTimeout(data) {
+  return data.operationName === void 0 ? {} : { operationName: data.operationName };
+}
+function dataForUnsupportedTransport(data) {
+  return { transport: data.transport, supported: [...data.supported] };
+}
+function dataForSubscriptionOverflow(data) {
+  return { subscriptionId: data.subscriptionId, droppedCount: data.droppedCount };
+}
+function dataForInvalidParams(data) {
+  return { issues: data.issues.map((issue) => ({ ...issue, path: [...issue.path] })) };
+}
+function filterDefined(input) {
+  const output = {};
+  for (const [key, value] of Object.entries(input))
+    if (value !== void 0)
+      output[key] = value;
+  return output;
+}

package/dist/server/handler/binding-dispatch.d.ts

@@ -0,0 +1,11 @@
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+/**
+ * Find a REST binding that matches the request's method and path.
+ * Returns null if no binding matches. Delegates path resolution to the
+ * canonical `bindingPathMatches` helper, keeping segment and parameter
+ * matching consistent across dispatch and documentation.
+ */
+export declare function matchRestBinding(method: string, pathname: string, bindings: ReadonlyArray<UnknownRestBinding> | undefined): {
+    readonly binding: UnknownRestBinding;
+    readonly pathParams: Record<string, string>;
+} | null;

package/dist/server/handler/binding-dispatch.js

@@ -0,0 +1,13 @@
+import { bindingPathMatches } from "../rest-binding.js";
+export function matchRestBinding(method, pathname, bindings) {
+  if (bindings === void 0)
+    return null;
+  for (const binding of bindings) {
+    if (binding.method !== method)
+      continue;
+    const params = bindingPathMatches(binding.path, pathname);
+    if (params !== null)
+      return { binding, pathParams: params };
+  }
+  return null;
+}

package/dist/server/handler/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Platform-agnostic HTTP request handler for the workflow REST API.
+ * Maps Request to Response with no Bun-specific dependencies.
+ *
+ * Dispatch model: REST-only meta and discovery endpoints are reserved direct
+ * routes, using the table shared with the OpenAPI generator. Every other
+ * operation-backed REST route is resolved through `RestBinding` entries and
+ * the `dispatchViaExecuteOperation` pipeline.
+ *
+ * @module server/handler
+ */
+import type { Engine } from '../../core/engine.ts';
+import { type HandlerOptions } from './route-dispatch.ts';
+export { authContextToPrincipal, isOperationFaultLike, type HandlerOptions, } from './route-dispatch.ts';
+export { extractRouteParameters, getRequiredRouteParameter } from './route-matching.ts';
+/**
+ * Pure HTTP request handler. Maps Request to Response.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, MemoryStorage, handleRequest } from '@lostgradient/weft';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ *
+ * const request = new Request('http://localhost/v1/health');
+ * const response = await handleRequest(request, engine);
+ * console.log(response.status); // 200
+ * ```
+ */
+export declare function handleRequest(request: Request, engine: Engine, options?: HandlerOptions): Promise<Response>;

package/dist/server/handler/index.js

@@ -0,0 +1,78 @@
+import { MalformedRouteParameterError } from "../rest-binding.js";
+import { matchRestBinding } from "./binding-dispatch.js";
+import { errorResponse } from "./response-helpers.js";
+import {
+  authContextToPrincipal,
+  defaultOperationRegistry,
+  defaultRestBindings,
+  DIRECT_ROUTE_EXECUTORS,
+  dispatchViaExecuteOperation
+} from "./route-dispatch.js";
+import { matchDirectRoute } from "./route-matching.js";
+export {
+  authContextToPrincipal,
+  isOperationFaultLike
+} from "./route-dispatch.js";
+export { extractRouteParameters, getRequiredRouteParameter } from "./route-matching.js";
+function routeParameterErrorResponse(error) {
+  if (error instanceof MalformedRouteParameterError)
+    return errorResponse(error.message, 400);
+  return null;
+}
+function matchRouteBoundary(matcher) {
+  try {
+    return { kind: "matched", value: matcher() };
+  } catch (error) {
+    const response = routeParameterErrorResponse(error);
+    if (response !== null)
+      return { kind: "malformed", response };
+    throw error;
+  }
+}
+function validateHandlerOptions(options) {
+  if (options?.restBindings === void 0 === (options?.operationRegistry === void 0))
+    return null;
+  return errorResponse("`restBindings` and `operationRegistry` must be supplied together (or both omitted).", 500);
+}
+async function dispatchRestBinding(request, engine, bindingMatch, operationRegistry, options, url) {
+  try {
+    const principal = authContextToPrincipal(options?.authContext);
+    return await dispatchViaExecuteOperation(request, engine, bindingMatch.binding, bindingMatch.pathParams, operationRegistry, principal, options?.pipelineTrace);
+  } catch (error) {
+    console.error("Unhandled error in dispatchViaExecuteOperation", {
+      method: request.method,
+      path: url.pathname,
+      error
+    });
+    return errorResponse("Internal server error", 500);
+  }
+}
+async function dispatchDirectRoute(request, engine, route, options, url) {
+  try {
+    const executor = DIRECT_ROUTE_EXECUTORS[route.handler];
+    return await executor({ request, engine, options });
+  } catch (error) {
+    console.error("Unhandled error in handleRequest", {
+      method: request.method,
+      path: url.pathname,
+      error
+    });
+    return errorResponse("Internal server error", 500);
+  }
+}
+export async function handleRequest(request, engine, options) {
+  const url = new URL(request.url), optionError = validateHandlerOptions(options);
+  if (optionError !== null)
+    return optionError;
+  const directRouteLookup = matchRouteBoundary(() => matchDirectRoute(request.method, url.pathname));
+  if (directRouteLookup.kind === "malformed")
+    return directRouteLookup.response;
+  if (directRouteLookup.value !== null)
+    return dispatchDirectRoute(request, engine, directRouteLookup.value, options, url);
+  const restBindings = options?.restBindings ?? defaultRestBindings(), operationRegistry = options?.operationRegistry ?? defaultOperationRegistry(), bindingLookup = matchRouteBoundary(() => matchRestBinding(request.method, url.pathname, restBindings));
+  if (bindingLookup.kind === "malformed")
+    return bindingLookup.response;
+  if (bindingLookup.value !== null)
+    return dispatchRestBinding(request, engine, bindingLookup.value, operationRegistry, options, url);
+  return errorResponse(`Not found: ${request.method} ${url.pathname}`, 404);
+}

package/dist/server/handler/response-helpers.d.ts

@@ -0,0 +1,5 @@
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+export declare function jsonResponse(body: unknown, status?: number): Response;
+export declare function negotiatedResponse(request: Request, body: unknown, status?: number): Response;
+export declare function errorResponse(message: string, status: number): Response;
+export declare function defaultShapeSuccess(value: unknown, shape: UnknownRestBinding['success']): Response;

package/dist/server/handler/response-helpers.js

@@ -0,0 +1,28 @@
+import { encode } from "../../core/codec.js";
+export function jsonResponse(body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function msgpackResponse(body, status = 200) {
+  return new Response(encode(body), {
+    status,
+    headers: { "Content-Type": "application/msgpack" }
+  });
+}
+export function negotiatedResponse(request, body, status = 200) {
+  if ((request.headers.get("Accept") ?? "").includes("application/msgpack"))
+    return msgpackResponse(body, status);
+  return jsonResponse(body, status);
+}
+export function errorResponse(message, status) {
+  return jsonResponse({ error: message }, status);
+}
+export function defaultShapeSuccess(value, shape) {
+  if (shape.kind === "empty")
+    return new Response(null, { status: shape.status });
+  if (shape.kind === "streaming")
+    throw Error("streaming RestBinding must provide shapeSuccess");
+  return jsonResponse(value, shape.status);
+}