@lostgradient/weft 0.2.0

package/dist/server/openrpc-document-schema.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimal committed Zod schema for the OpenRPC document shape that Weft emits.
+ *
+ * @module server/openrpc-document-schema
+ */
+import { z } from 'zod';
+export declare const ContentDescriptorSchema: z.ZodObject<{
+    name: z.ZodString;
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    required: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const OpenRpcMethodSchema: z.ZodObject<{
+    name: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>>>;
+    paramStructure: z.ZodLiteral<"by-name">;
+    params: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        required: z.ZodBoolean;
+    }, z.core.$strict>>;
+    result: z.ZodObject<{
+        name: z.ZodString;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        required: z.ZodBoolean;
+    }, z.core.$strict>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        $ref: z.ZodString;
+    }, z.core.$strict>>>;
+    'x-weft-paramsSchema': z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    'x-weft-mcp': z.ZodOptional<z.ZodObject<{
+        workflowType: z.ZodString;
+        toolName: z.ZodString;
+        toolDiscovery: z.ZodObject<{
+            method: z.ZodLiteral<"tools/list">;
+            source: z.ZodLiteral<"live">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const OpenRpcDocumentSchema: z.ZodObject<{
+    openrpc: z.ZodLiteral<"1.3.2">;
+    info: z.ZodObject<{
+        title: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        license: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        externalDocs: z.ZodOptional<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    methods: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>>>;
+        paramStructure: z.ZodLiteral<"by-name">;
+        params: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            required: z.ZodBoolean;
+        }, z.core.$strict>>;
+        result: z.ZodObject<{
+            name: z.ZodString;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            required: z.ZodBoolean;
+        }, z.core.$strict>;
+        errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            $ref: z.ZodString;
+        }, z.core.$strict>>>;
+        'x-weft-paramsSchema': z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        'x-weft-mcp': z.ZodOptional<z.ZodObject<{
+            workflowType: z.ZodString;
+            toolName: z.ZodString;
+            toolDiscovery: z.ZodObject<{
+                method: z.ZodLiteral<"tools/list">;
+                source: z.ZodLiteral<"live">;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    components: z.ZodOptional<z.ZodObject<{
+        errors: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            code: z.ZodNumber;
+            message: z.ZodString;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            'x-http-status': z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        schemas: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strict>>>;
+    'x-weft-mcp': z.ZodOptional<z.ZodObject<{
+        discoveryPath: z.ZodLiteral<"/.well-known/mcp.json">;
+        toolDiscoveryMethod: z.ZodLiteral<"tools/list">;
+        toolNames: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type OpenRpcDocument = z.infer<typeof OpenRpcDocumentSchema>;

package/dist/server/openrpc-document-schema.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { MCP_DISCOVERY_PATH, MCP_TOOLS_LIST_METHOD } from "./mcp-discovery.js";
+export const ContentDescriptorSchema = z.strictObject({
+  name: z.string(),
+  schema: z.record(z.string(), z.unknown()),
+  required: z.boolean()
+});
+const OpenRpcMcpMethodMetadataSchema = z.strictObject({
+  workflowType: z.string(),
+  toolName: z.string(),
+  toolDiscovery: z.strictObject({
+    method: z.literal(MCP_TOOLS_LIST_METHOD),
+    source: z.literal("live")
+  })
+});
+export const OpenRpcMethodSchema = z.strictObject({
+  name: z.string(),
+  summary: z.string().optional(),
+  description: z.string().optional(),
+  tags: z.array(z.strictObject({ name: z.string() })).optional(),
+  paramStructure: z.literal("by-name"),
+  params: z.array(ContentDescriptorSchema),
+  result: ContentDescriptorSchema,
+  errors: z.array(z.strictObject({ $ref: z.string() })).optional(),
+  "x-weft-paramsSchema": z.record(z.string(), z.unknown()),
+  "x-weft-mcp": OpenRpcMcpMethodMetadataSchema.optional()
+});
+const OpenRpcMcpMetadataSchema = z.strictObject({
+  discoveryPath: z.literal(MCP_DISCOVERY_PATH),
+  toolDiscoveryMethod: z.literal(MCP_TOOLS_LIST_METHOD),
+  toolNames: z.array(z.string())
+});
+export const OpenRpcDocumentSchema = z.strictObject({
+  openrpc: z.literal("1.3.2"),
+  info: z.strictObject({
+    title: z.string(),
+    version: z.string(),
+    description: z.string().optional(),
+    contact: z.strictObject({
+      name: z.string().optional(),
+      url: z.string().optional(),
+      email: z.string().optional()
+    }).optional(),
+    license: z.strictObject({
+      name: z.string(),
+      url: z.string().optional()
+    }).optional(),
+    externalDocs: z.strictObject({
+      description: z.string().optional(),
+      url: z.string()
+    }).optional()
+  }),
+  methods: z.array(OpenRpcMethodSchema),
+  components: z.strictObject({
+    errors: z.record(z.string(), z.strictObject({
+      code: z.number(),
+      message: z.string(),
+      data: z.record(z.string(), z.unknown()).optional(),
+      "x-http-status": z.number().optional()
+    })).optional(),
+    schemas: z.record(z.string(), z.unknown()).optional()
+  }).optional(),
+  servers: z.array(z.strictObject({ url: z.string() })).optional(),
+  "x-weft-mcp": OpenRpcMcpMetadataSchema.optional()
+});

package/dist/server/openrpc-errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * OpenRPC `components.errors` derived from the closed `FaultCode` union.
+ *
+ * @module server/openrpc-errors
+ */
+import { z } from 'zod';
+export declare const UnauthorizedDataSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const ForbiddenDataSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const NotFoundDataSchema: z.ZodObject<{
+    resource: z.ZodString;
+    identifier: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ConflictDataSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const UnprocessableDataSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+export declare const TimeoutDataSchema: z.ZodObject<{
+    operationName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const NotImplementedDataSchema: z.ZodObject<{}, z.core.$strip>;
+export declare const UnsupportedTransportDataSchema: z.ZodObject<{
+    transport: z.ZodEnum<{
+        "http-rest": "http-rest";
+        jsonRpcHttp: "jsonRpcHttp";
+        jsonRpcWebSocket: "jsonRpcWebSocket";
+        jsonRpcStdio: "jsonRpcStdio";
+    }>;
+    supported: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        "http-rest": "http-rest";
+        jsonRpcHttp: "jsonRpcHttp";
+        jsonRpcWebSocket: "jsonRpcWebSocket";
+        jsonRpcStdio: "jsonRpcStdio";
+    }>>>;
+}, z.core.$strip>;
+export declare const SubscriptionOverflowDataSchema: z.ZodObject<{
+    subscriptionId: z.ZodString;
+    droppedCount: z.ZodNumber;
+}, z.core.$strip>;
+export declare const InvalidParamsDataSchema: z.ZodObject<{
+    issues: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        path: z.ZodReadonly<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        message: z.ZodString;
+        code: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MethodNotFoundDataSchema: z.ZodObject<{
+    method: z.ZodString;
+}, z.core.$strip>;
+export declare const EngineFailureDataSchema: z.ZodObject<{}, z.core.$strip>;
+type OpenRpcError = {
+    code: number;
+    message: string;
+    data?: Record<string, unknown>;
+    'x-http-status': number;
+};
+/**
+ * Build the `components.errors` array for an OpenRPC document.
+ *
+ * Derived from `FAULT_CODE_TO_JSON_RPC_CODE` (the single source of truth).
+ * Every `FaultCode` in the closed union gets one entry with:
+ * - `code`: JSON-RPC error code
+ * - `message`: human-readable fault name
+ * - `data`: JSON Schema from the Zod schema for that fault's data payload
+ * - `x-http-status`: HTTP status code for REST callers
+ */
+export declare function buildOpenRpcComponentsErrors(): Record<string, OpenRpcError>;
+export {};

package/dist/server/openrpc-errors.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import {
+  FAULT_CODE_TO_HTTP_STATUS,
+  FAULT_CODE_TO_JSON_RPC_CODE
+} from "./operation-fault.js";
+export const UnauthorizedDataSchema = z.object({ reason: z.string() }), ForbiddenDataSchema = z.object({ reason: z.string() }), NotFoundDataSchema = z.object({
+  resource: z.string(),
+  identifier: z.string().optional()
+}), ConflictDataSchema = z.object({ reason: z.string() }), UnprocessableDataSchema = z.object({ reason: z.string() }), TimeoutDataSchema = z.object({ operationName: z.string().optional() }), NotImplementedDataSchema = z.object({});
+const TransportKindSchema = z.enum([
+  "http-rest",
+  "jsonRpcHttp",
+  "jsonRpcWebSocket",
+  "jsonRpcStdio"
+]);
+export const UnsupportedTransportDataSchema = z.object({
+  transport: TransportKindSchema,
+  supported: z.array(TransportKindSchema).readonly()
+}), SubscriptionOverflowDataSchema = z.object({
+  subscriptionId: z.string(),
+  droppedCount: z.number()
+}), InvalidParamsDataSchema = z.object({
+  issues: z.array(z.object({
+    path: z.array(z.union([z.string(), z.number()])).readonly(),
+    message: z.string(),
+    code: z.string()
+  })).readonly()
+}), MethodNotFoundDataSchema = z.object({ method: z.string() }), EngineFailureDataSchema = z.object({});
+const FAULT_DATA_SCHEMAS = {
+  Unauthorized: UnauthorizedDataSchema,
+  Forbidden: ForbiddenDataSchema,
+  NotFound: NotFoundDataSchema,
+  Conflict: ConflictDataSchema,
+  Unprocessable: UnprocessableDataSchema,
+  Timeout: TimeoutDataSchema,
+  NotImplemented: NotImplementedDataSchema,
+  UnsupportedTransport: UnsupportedTransportDataSchema,
+  SubscriptionOverflow: SubscriptionOverflowDataSchema,
+  InvalidParams: InvalidParamsDataSchema,
+  MethodNotFound: MethodNotFoundDataSchema,
+  EngineFailure: EngineFailureDataSchema
+};
+export function buildOpenRpcComponentsErrors() {
+  const result = {};
+  for (const [faultCode, jsonRpcCode] of Object.entries(FAULT_CODE_TO_JSON_RPC_CODE)) {
+    const httpStatus = FAULT_CODE_TO_HTTP_STATUS[faultCode], dataSchema = FAULT_DATA_SCHEMAS[faultCode], jsonSchema = z.toJSONSchema(dataSchema, {
+      unrepresentable: "any"
+    }), { $schema: _unused, ...dataJsonSchema } = jsonSchema;
+    result[faultCode] = {
+      code: jsonRpcCode,
+      message: faultCode,
+      data: dataJsonSchema,
+      "x-http-status": httpStatus
+    };
+  }
+  return result;
+}

package/dist/server/openrpc.d.ts

@@ -0,0 +1,53 @@
+/**
+ * OpenRPC 1.3.2 document generator driven from the transport-neutral
+ * `OperationRegistry`. Produces a JSON-serializable OpenRPC document
+ * listing every operation whose transport availability intersects
+ * `OpenRpcOptions.transports`.
+ *
+ *   - `transports: ['http']` → WebSocket-only methods are omitted
+ *     (calling `weft.workflows.subscribe` over HTTP would return
+ *     `UnsupportedTransport`, so the method should not appear in the
+ *     HTTP-only document).
+ *   - Every listed method carries `paramStructure: 'by-name'`, per-field
+ *     `ContentDescriptor`s for human-readable surface, AND an
+ *     `x-weft-paramsSchema` extension whose `additionalProperties` is
+ *     computed from `unknownKeyPolicy.jsonRpc` (`'reject'` → false;
+ *     `'strip'` / `'passthrough'` → true). The extension is the
+ *     authoritative top-level object schema used by runtime enforcement
+ *     and generator tooling; the per-field descriptors cannot drift
+ *     from it by the "names match" invariant enforced in tests.
+ *   - `rpc.discover` is itself emitted as a method so clients can
+ *     locate the document via JSON-RPC.
+ *
+ * @module server/openrpc
+ */
+import type { McpToolDefinition } from '../mcp/tools.ts';
+import { type DiscoveryInfo } from './discovery-info.ts';
+import { type OperationRegistry } from './operation-catalog.ts';
+/** Transports that MAY be listed in `OpenRpcOptions.transports`. */
+export type OpenRpcTransport = 'http' | 'websocket' | 'stdio';
+export type OpenRpcOptions = {
+    /** Live operation registry. Only operations from this registry can be listed. */
+    readonly registry: OperationRegistry;
+    /** JSON-RPC transports whose methods should be included in the document. */
+    readonly transports: ReadonlyArray<OpenRpcTransport>;
+    /** Document title. Defaults to `'Weft Workflow Engine'`. */
+    readonly title?: string;
+    /** Document version. Defaults to the current Weft package version. */
+    readonly version?: string;
+    /** Operator-supplied discovery metadata applied to the `info` object. */
+    readonly discoveryInfo?: DiscoveryInfo;
+    /** Optional server URL; emitted as a single-entry `servers` array. */
+    readonly serverUrl?: string;
+    /**
+     * Live MCP `tools/list` output. Required when any listed operation is
+     * `mcpExposable`, because live MCP tool naming owns workflow-name collision
+     * handling.
+     */
+    readonly mcpTools?: ReadonlyArray<Pick<McpToolDefinition, 'name' | 'title'>>;
+};
+/**
+ * Generate an OpenRPC 1.3.2 document. See module doc-comment for the
+ * runtime-filtering contract.
+ */
+export declare function generateOpenRpcDocument(options: OpenRpcOptions): Record<string, unknown>;

package/dist/server/openrpc.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import { definitionSchemaToJsonSchema } from "../core/types/definition-schema-to-json.js";
+import { VERSION } from "../version.js";
+import { isDiscoverable } from "./discovery-filter.js";
+import { applyDiscoveryInfo } from "./discovery-info.js";
+import { asPlainObject, compareStrings } from "./json-schema-utilities.js";
+import { MCP_DISCOVERY_PATH, MCP_TOOLS_LIST_METHOD } from "./mcp-discovery.js";
+import { OpenRpcDocumentSchema } from "./openrpc-document-schema.js";
+import { buildOpenRpcComponentsErrors } from "./openrpc-errors.js";
+import {
+  UNIVERSAL_FAULT_DEFAULTS
+} from "./operation-catalog.js";
+export function generateOpenRpcDocument(options) {
+  const methods = [], mcpTools = [];
+  let registryProvidesDiscover = !1;
+  for (const operation of options.registry.list()) {
+    if (!isOperationLiveOnJsonRpc(operation, options.transports))
+      continue;
+    if (!isDiscoverable(operation))
+      continue;
+    if (operation.name === DISCOVER_METHOD_NAME)
+      registryProvidesDiscover = !0;
+    const method = buildMethod(operation);
+    if (operation.mcpExposable) {
+      const metadata = buildMethodMcpMetadata(operation, options.mcpTools);
+      method["x-weft-mcp"] = metadata;
+      mcpTools.push({ toolName: metadata.toolName });
+    }
+    methods.push(method);
+  }
+  if (!registryProvidesDiscover && options.transports.length > 0)
+    methods.push(buildDiscoverMethod());
+  const document = {
+    openrpc: "1.3.2",
+    info: buildOpenRpcInfo(options),
+    methods,
+    components: {
+      errors: buildOpenRpcComponentsErrors()
+    },
+    "x-weft-mcp": buildDocumentMcpMetadata(mcpTools)
+  };
+  applyOpenRpcServer(document, options.serverUrl);
+  return document;
+}
+const DISCOVER_METHOD_NAME = "rpc.discover";
+function buildOpenRpcInfo(options) {
+  const title = options.title ?? "Weft Workflow Engine", version = options.version ?? VERSION, infoBlock = applyDiscoveryInfo({ title, version }, options.discoveryInfo);
+  if (options.discoveryInfo?.externalDocs !== void 0)
+    infoBlock.externalDocs = { ...options.discoveryInfo.externalDocs };
+  return infoBlock;
+}
+function applyOpenRpcServer(document, serverUrl) {
+  if (serverUrl)
+    document.servers = [{ url: serverUrl }];
+}
+function buildDocumentMcpMetadata(tools) {
+  return {
+    discoveryPath: MCP_DISCOVERY_PATH,
+    toolDiscoveryMethod: MCP_TOOLS_LIST_METHOD,
+    toolNames: [...tools].map((tool) => tool.toolName).toSorted(compareStrings)
+  };
+}
+function buildMethodMcpMetadata(operation, mcpTools) {
+  const workflowType = operation.mcpTool?.workflowType;
+  if (workflowType === void 0)
+    throw Error(`openrpc: operation ${operation.name} is mcpExposable but lacks mcpTool.workflowType metadata`);
+  const toolName = resolveLiveMcpToolName(operation.name, workflowType, mcpTools);
+  return {
+    workflowType,
+    toolName,
+    toolDiscovery: {
+      method: MCP_TOOLS_LIST_METHOD,
+      source: "live"
+    }
+  };
+}
+function resolveLiveMcpToolName(operationName, workflowType, mcpTools) {
+  if (mcpTools === void 0)
+    throw Error(`openrpc: operation ${operationName} is mcpExposable but no live MCP tools/list metadata was provided`);
+  const matches = mcpTools.filter((tool) => tool.title === workflowType);
+  if (matches.length !== 1)
+    throw Error(`openrpc: operation ${operationName} maps to workflow "${workflowType}", but live MCP tools/list returned ${matches.length} matching tools`);
+  return matches[0].name;
+}
+function isOperationLiveOnJsonRpc(operation, transports) {
+  const available = operation.transports;
+  for (const transport of transports)
+    if (transportIsAvailable(transport, available))
+      return !0;
+  return !1;
+}
+function transportIsAvailable(transport, available) {
+  switch (transport) {
+    case "http":
+      return available.jsonRpcHttp;
+    case "websocket":
+      return available.jsonRpcWebSocket;
+    case "stdio":
+      return available.jsonRpcStdio;
+    default:
+      return !1;
+  }
+}
+function buildMethod(operation) {
+  if (!(operation.inputSchema instanceof z.ZodObject))
+    throw Error(`openrpc: operation ${operation.name} has non-object inputSchema; generator requires z.ZodObject`);
+  const inputSchema = operation.inputSchema, paramsSchema = zodObjectToJsonSchema(inputSchema, operation.unknownKeyPolicy.jsonRpc), descriptors = buildContentDescriptors(paramsSchema), resultSchema = definitionSchemaToJsonSchema(operation.outputSchema, "output"), method = {
+    name: operation.name,
+    paramStructure: "by-name",
+    params: descriptors,
+    result: { name: "result", schema: resultSchema, required: !0 },
+    "x-weft-paramsSchema": paramsSchema
+  };
+  if (operation.summary)
+    method.summary = operation.summary;
+  if (operation.description !== void 0)
+    method.description = operation.description;
+  if (operation.tags.length > 0)
+    method.tags = [...operation.tags].toSorted(compareStrings).map((name) => ({ name }));
+  method.errors = buildMethodErrorReferences(operation);
+  return method;
+}
+function buildDiscoverMethod() {
+  return {
+    name: "rpc.discover",
+    summary: "Return the OpenRPC document for this server",
+    paramStructure: "by-name",
+    params: [],
+    result: {
+      name: "openRpcDocument",
+      schema: definitionSchemaToJsonSchema(OpenRpcDocumentSchema),
+      required: !0
+    },
+    errors: buildUniversalErrorReferences(),
+    "x-weft-paramsSchema": {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: !1
+    }
+  };
+}
+const UNIVERSAL_FAULT_CODES = [...UNIVERSAL_FAULT_DEFAULTS];
+function buildMethodErrorReferences(operation) {
+  const faultCodes = new Set(UNIVERSAL_FAULT_CODES);
+  for (const faultCode of operation.producibleFaults ?? [])
+    faultCodes.add(faultCode);
+  return [...faultCodes].map((faultCode) => ({
+    $ref: `#/components/errors/${faultCode}`
+  }));
+}
+function buildUniversalErrorReferences() {
+  return UNIVERSAL_FAULT_CODES.map((faultCode) => ({
+    $ref: `#/components/errors/${faultCode}`
+  }));
+}
+function zodObjectToJsonSchema(schema, jsonRpcPolicy) {
+  return {
+    ...definitionSchemaToJsonSchema(schema),
+    additionalProperties: jsonRpcPolicy !== "reject"
+  };
+}
+function buildContentDescriptors(paramsSchema) {
+  const properties = asPlainObject(paramsSchema.properties), requiredList = asStringArray(paramsSchema.required), defs = asPlainObjectOrUndefined(paramsSchema.$defs), names = Object.keys(properties).toSorted(compareStrings), requiredSet = new Set(requiredList);
+  return names.map((name) => {
+    const baseSchema = asPlainObject(properties[name]), schema = defs ? { ...baseSchema, $defs: defs } : baseSchema;
+    return { name, schema, required: requiredSet.has(name) };
+  });
+}
+function asPlainObjectOrUndefined(value) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value))
+    return value;
+  return;
+}
+function asStringArray(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.filter((entry) => typeof entry === "string");
+}

package/dist/server/operation-catalog/activity-adapter.d.ts

@@ -0,0 +1,11 @@
+import { type ActivityMetadata, type ActivityRegistry } from '../../core/activity-registry.ts';
+/**
+ * Catalog-shaped activity metadata for discovery and code generation.
+ *
+ * Activities are dispatchable units, not standalone user-facing operations.
+ * This adapter intentionally returns metadata only; it does not produce
+ * executable `OperationDefinition` values.
+ */
+export type CatalogActivityDefinition = ActivityMetadata;
+export declare function catalogActivity(metadata: ActivityMetadata): CatalogActivityDefinition;
+export declare function catalogActivities(registry: ActivityRegistry): CatalogActivityDefinition[];

package/dist/server/operation-catalog/activity-adapter.js

@@ -0,0 +1,9 @@
+import {
+  copyActivityMetadata
+} from "../../core/activity-registry.js";
+export function catalogActivity(metadata) {
+  return copyActivityMetadata(metadata);
+}
+export function catalogActivities(registry) {
+  return registry.listDefinitions();
+}

package/dist/server/operation-catalog/dispatch-allowlist.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Catalog dispatch exemptions for transport-level session lifecycle primitives.
+ */
+export declare const DISPATCH_ALLOWLIST: ReadonlySet<string>;

package/dist/server/operation-catalog/dispatch-allowlist.js

@@ -0,0 +1,4 @@
+export const DISPATCH_ALLOWLIST = new Set([
+  "weft.workflows.subscribe",
+  "weft.workflows.unsubscribe"
+]);

package/dist/server/operation-catalog/dispatch-preparation.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { OperationFault } from '../operation-fault.ts';
+import { type DispatchContext, type DispatchResult, type ErasedOperation } from './types.ts';
+/**
+ * Look up an operation by name. Emits the `looked-up` trace marker on
+ * success. On failure (unknown operation) emits no marker, matching the
+ * existing dispatch behavior where `MethodNotFound` ends the pipeline
+ * before any marker is recorded.
+ */
+export declare function lookupOperation(operationName: string, context: DispatchContext): DispatchResult<ErasedOperation>;
+/**
+ * Take an already-looked-up operation and run transport, access, input
+ * parsing with unknown-key policy, and authorization. Emits markers
+ * `transport-checked`, `access-checked`, the parse markers emitted from
+ * inside `parseAndApplyUnknownKeyPolicy`, then `authorized`.
+ *
+ * Authorization is part of this helper's contract; callers must not
+ * re-authorize the same input.
+ */
+export declare function prepareAuthorizedInput(operation: ErasedOperation, rawInput: unknown, context: DispatchContext): Promise<DispatchResult<{
+    input: unknown;
+}>>;
+/**
+ * Safely run `schema.safeParse(value)`. Maps any thrown exception or
+ * failed parse to `{ code: 'EngineFailure', message: 'internal error', data: {} }`.
+ * On success returns the parsed data so Zod transforms, defaults, and
+ * refinements are honored.
+ *
+ * The `Output` generic is the caller's declared output type for the
+ * operation. The schema is erased to `z.ZodType` on `ErasedOperation`,
+ * so we cast `parseResult.data` to `Output` at the validated boundary —
+ * the same single-level cast the previous private helpers performed
+ * (`validateAndReturnOutput` and `validateOutput`). The cast is safe
+ * because the success branch is only reachable after `schema.safeParse`
+ * succeeded.
+ */
+export declare function validateOutputAgainstSchema<Output>(schema: z.ZodType, value: unknown): DispatchResult<Output>;
+/** Wrap an `OperationFault` in the standard `DispatchResult` failure shape. */
+export declare function dispatchFailure(fault: OperationFault): DispatchResult<never>;

package/dist/server/operation-catalog/dispatch-preparation.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { transportToPolicyKey } from "./pipeline-helpers.js";
+import {
+  checkAccess,
+  checkAuthorization,
+  checkTransport,
+  parseAndApplyUnknownKeyPolicy,
+  tracePipeline
+} from "./pipeline-stages.js";
+export function lookupOperation(operationName, context) {
+  const operation = context.registry.get(operationName);
+  if (operation === void 0)
+    return dispatchFailure({
+      code: "MethodNotFound",
+      message: `unknown operation: ${operationName}`,
+      data: { method: operationName }
+    });
+  tracePipeline(context.pipelineTrace, "looked-up");
+  return { ok: !0, value: operation };
+}
+export async function prepareAuthorizedInput(operation, rawInput, context) {
+  const pipelineTrace = context.pipelineTrace, transportFailure = checkTransport(operation, context);
+  if (transportFailure !== null)
+    return transportFailure;
+  tracePipeline(pipelineTrace, "transport-checked");
+  const accessFailure = checkAccess(operation, context);
+  if (accessFailure !== null)
+    return accessFailure;
+  tracePipeline(pipelineTrace, "access-checked");
+  const parseOutcome = parseAndApplyUnknownKeyPolicy(operation, rawInput, transportToPolicyKey(context.transport), pipelineTrace);
+  if (parseOutcome.kind === "failure")
+    return dispatchFailure(parseOutcome.fault);
+  const authorizationFailure = await checkAuthorization(operation, parseOutcome.input, context);
+  if (authorizationFailure !== null)
+    return authorizationFailure;
+  tracePipeline(pipelineTrace, "authorized");
+  return { ok: !0, value: { input: parseOutcome.input } };
+}
+export function validateOutputAgainstSchema(schema, value) {
+  let parseResult;
+  try {
+    parseResult = schema.safeParse(value);
+  } catch {
+    return dispatchFailure({ code: "EngineFailure", message: "internal error", data: {} });
+  }
+  if (!parseResult.success)
+    return dispatchFailure({ code: "EngineFailure", message: "internal error", data: {} });
+  return { ok: !0, value: parseResult.data };
+}
+export function dispatchFailure(fault) {
+  return { ok: !1, fault };
+}