@lostgradient/weft 0.2.0

package/dist/server/operation-catalog/registry.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { UNSAFE_PROTOTYPE_KEYS } from "./pipeline-helpers.js";
+import {
+  validateOperationName
+} from "./types.js";
+function freezeAccessPolicy(policy) {
+  if (policy.kind === "scoped")
+    return Object.freeze({
+      kind: "scoped",
+      scopes: freezeScopeRequirement(policy.scopes)
+    });
+  if (policy.kind === "scopedAlternatives")
+    return Object.freeze({
+      kind: "scopedAlternatives",
+      alternatives: Object.freeze(policy.alternatives.map(freezeScopeRequirement))
+    });
+  if (policy.kind === "optionalAuth")
+    return Object.freeze({
+      kind: "optionalAuth",
+      authenticatedScopes: freezeScopeRequirement(policy.authenticatedScopes)
+    });
+  return Object.freeze({ ...policy });
+}
+function freezeScopeRequirement(requirement) {
+  const scopes = Object.freeze([...requirement.scopes]);
+  return Object.freeze({
+    kind: requirement.kind,
+    scopes
+  });
+}
+function objectInputSchema(operation) {
+  if (!(operation.inputSchema instanceof z.ZodObject))
+    throw Error(`operation "${operation.name}" inputSchema must be a z.ZodObject (got ${operation.inputSchema.constructor.name}); wrappers like .optional() / transforms hide the top-level shape from the unknown-key policy check`);
+  return operation.inputSchema;
+}
+function assertSafeDeclaredKeys(operation) {
+  const inputSchema = objectInputSchema(operation), unsafeDeclared = Object.keys(inputSchema.shape).filter((key) => UNSAFE_PROTOTYPE_KEYS.has(key));
+  if (unsafeDeclared.length > 0)
+    throw Error(`operation "${operation.name}" inputSchema declares unsafe top-level keys: ${unsafeDeclared.join(", ")}. Names that match a prototype-pollution vector (__proto__, constructor, prototype) are forbidden as schema keys.`);
+}
+function assertKindAndEventSchemaAgree(operation) {
+  const kind = operation.kind ?? "unary";
+  if (kind === "unary") {
+    if (operation.eventSchema !== void 0)
+      throw Error(`operation "${operation.name}" has kind: 'unary' (or unset) but declares an eventSchema. eventSchema is reserved for kind: 'stream' or kind: 'subscription'.`);
+    return;
+  }
+  if (operation.eventSchema === void 0)
+    throw Error(`operation "${operation.name}" has kind: '${kind}' but no eventSchema. Stream and subscription operations must declare an eventSchema so the dispatcher can validate each yielded element.`);
+}
+function assertDestructiveDeclared(operation) {
+  if (typeof operation.destructive !== "boolean")
+    throw Error(`operation "${operation.name}" must declare an explicit boolean "destructive" flag (got ${typeof operation.destructive}). Every operation has to state whether it irreversibly mutates state \u2014 there is no implicit default. Mark cancel/purge/bulk-delete/raw-storage-write style operations true and read-only operations false.`);
+}
+function assertMcpMetadataAgrees(operation) {
+  if (!operation.mcpExposable)
+    return;
+  if (operation.mcpTool === void 0)
+    throw Error(`operation "${operation.name}" is mcpExposable but does not declare mcpTool.workflowType metadata`);
+}
+function freezeOperation(operation) {
+  return Object.freeze({
+    ...operation,
+    tags: Object.freeze([...operation.tags]),
+    ...operation.producibleFaults === void 0 ? {} : { producibleFaults: Object.freeze([...operation.producibleFaults]) },
+    access: freezeAccessPolicy(operation.access),
+    ...operation.mcpTool === void 0 ? {} : { mcpTool: Object.freeze({ workflowType: operation.mcpTool.workflowType }) },
+    transports: Object.freeze({ ...operation.transports }),
+    unknownKeyPolicy: Object.freeze({ ...operation.unknownKeyPolicy })
+  });
+}
+export function createOperationRegistry(operations) {
+  const byName = new Map;
+  for (const operation of operations) {
+    if (byName.has(operation.name))
+      throw Error(`duplicate operation name in registry: ${operation.name}`);
+    validateOperationName(operation.name);
+    assertSafeDeclaredKeys(operation);
+    assertKindAndEventSchemaAgree(operation);
+    assertDestructiveDeclared(operation);
+    assertMcpMetadataAgrees(operation);
+    byName.set(operation.name, freezeOperation(operation));
+  }
+  const ordered = Object.freeze([...byName.values()]);
+  return {
+    get(name) {
+      return byName.get(name);
+    },
+    list() {
+      return ordered;
+    }
+  };
+}

package/dist/server/operation-catalog/stream-pipeline.d.ts

@@ -0,0 +1,25 @@
+import { WeftError } from '../../core/weft-error.ts';
+import type { OperationFault } from '../operation-fault.ts';
+import { type DispatchContext, type DispatchResult } from './types.ts';
+/**
+ * Error thrown when an element emitted by a subscription or stream fails
+ * per-element schema validation.
+ */
+export declare class SubscriptionElementValidationError extends WeftError<'SubscriptionElementValidationError'> {
+    readonly fault: OperationFault;
+    constructor(fault: OperationFault);
+}
+/**
+ * Execute a `kind: 'stream'` operation and return a schema-validating
+ * async iterable for its emitted elements.
+ */
+export declare function executeStream<Element>(operationName: string, rawInput: unknown, context: DispatchContext): Promise<DispatchResult<AsyncIterable<Element>>>;
+/**
+ * Execute a `kind: 'subscription'` operation and return its validated
+ * subscribe envelope, schema-validating element iterable, and close hook.
+ */
+export declare function executeSubscription<Element, Envelope>(operationName: string, rawInput: unknown, context: DispatchContext): Promise<DispatchResult<{
+    envelope: Envelope;
+    iterable: AsyncIterable<Element>;
+    close: () => Promise<void>;
+}>>;

package/dist/server/operation-catalog/stream-pipeline.js

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import { WeftError } from "../../core/weft-error.js";
+import {
+  dispatchFailure,
+  lookupOperation,
+  prepareAuthorizedInput,
+  validateOutputAgainstSchema
+} from "./dispatch-preparation.js";
+import { classifyEngineError } from "./pipeline-helpers.js";
+import { tracePipeline } from "./pipeline-stages.js";
+
+export class SubscriptionElementValidationError extends WeftError {
+  fault;
+  constructor(fault) {
+    super("SubscriptionElementValidationError", "subscription element failed schema validation");
+    this.fault = fault;
+  }
+}
+export async function executeStream(operationName, rawInput, context) {
+  const prepared = await prepareLongLivedOperation(operationName, rawInput, context, "stream");
+  if (!prepared.ok)
+    return prepared;
+  const { operation, input, eventSchema } = prepared.value;
+  let invocation;
+  try {
+    invocation = await operation.invoke({
+      input,
+      principal: context.principal,
+      engine: context.engine,
+      transport: context.transport
+    });
+  } catch (error) {
+    return dispatchFailure(classifyEngineError(error, operation));
+  }
+  tracePipeline(context.pipelineTrace, "invoked");
+  if (!isAsyncIterable(invocation))
+    return dispatchFailure({ code: "EngineFailure", message: "internal error", data: {} });
+  tracePipeline(context.pipelineTrace, "output-validated");
+  return {
+    ok: !0,
+    value: validateElements(invocation, eventSchema)
+  };
+}
+export async function executeSubscription(operationName, rawInput, context) {
+  const prepared = await prepareLongLivedOperation(operationName, rawInput, context, "subscription");
+  if (!prepared.ok)
+    return prepared;
+  const { operation, input, eventSchema } = prepared.value;
+  let invocation;
+  try {
+    invocation = await operation.invoke({
+      input,
+      principal: context.principal,
+      engine: context.engine,
+      transport: context.transport
+    });
+  } catch (error) {
+    return dispatchFailure(classifyEngineError(error, operation));
+  }
+  tracePipeline(context.pipelineTrace, "invoked");
+  if (!isSubscriptionInvocation(invocation))
+    return dispatchFailure({ code: "EngineFailure", message: "internal error", data: {} });
+  const envelope = validateOutputAgainstSchema(operation.outputSchema, invocation.envelope);
+  if (!envelope.ok)
+    return envelope;
+  tracePipeline(context.pipelineTrace, "output-validated");
+  return {
+    ok: !0,
+    value: {
+      envelope: envelope.value,
+      iterable: validateElements(invocation.iterable, eventSchema),
+      close: invocation.close
+    }
+  };
+}
+async function prepareLongLivedOperation(operationName, rawInput, context, expectedKind) {
+  const lookup = lookupOperation(operationName, context);
+  if (!lookup.ok)
+    return lookup;
+  const operation = lookup.value;
+  if ((operation.kind ?? "unary") !== expectedKind)
+    return dispatchFailure({
+      code: "Unprocessable",
+      message: `operation "${operation.name}" is not ${expectedKind}`,
+      data: { reason: `operation kind is "${operation.kind ?? "unary"}"` }
+    });
+  if (operation.eventSchema === void 0)
+    return dispatchFailure({
+      code: "EngineFailure",
+      message: "internal error",
+      data: {}
+    });
+  const eventSchema = operation.eventSchema, prepared = await prepareAuthorizedInput(operation, rawInput, context);
+  if (!prepared.ok)
+    return prepared;
+  return { ok: !0, value: { operation, input: prepared.value.input, eventSchema } };
+}
+async function* validateElements(iterable, eventSchema) {
+  for await (const element of iterable) {
+    let parsed;
+    try {
+      parsed = eventSchema.safeParse(element);
+    } catch {
+      throw new SubscriptionElementValidationError(elementValidationFault());
+    }
+    if (!parsed.success)
+      throw new SubscriptionElementValidationError(elementValidationFault());
+    yield parsed.data;
+  }
+}
+function isAsyncIterable(value) {
+  return value !== null && typeof value === "object" && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
+}
+function isSubscriptionInvocation(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const record = value;
+  return Object.hasOwn(record, "envelope") && isAsyncIterable(record.iterable) && typeof record.close === "function";
+}
+function elementValidationFault() {
+  return { code: "EngineFailure", message: "internal error", data: {} };
+}

package/dist/server/operation-catalog/types.d.ts

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+import type { AccessPolicy } from '../authorization.ts';
+import type { FaultCode, OperationFault, TransportKind } from '../operation-fault.ts';
+import type { Principal } from '../principal.ts';
+/**
+ * Regex for the canonical `weft.<segment>(.<segment>)+` operation-name form.
+ * Mandatory `weft.` prefix and at least one additional dot-separated segment.
+ */
+export declare const OPERATION_NAME_PATTERN: RegExp;
+/** Throws if `name` does not match the canonical operation-name pattern. */
+export declare function validateOperationName(name: string): void;
+/** Non-throwing variant of `validateOperationName`. */
+export declare function isValidOperationName(name: string): boolean;
+/**
+ * Per-operation transport availability flags. A `false` entry means callers
+ * on that transport receive `UnsupportedTransport`, not `MethodNotFound`.
+ */
+export type TransportAvailability = {
+    http: boolean;
+    jsonRpcHttp: boolean;
+    jsonRpcWebSocket: boolean;
+    jsonRpcStdio: boolean;
+};
+/**
+ * Per-transport unknown-key disposition. Top-level only; nested object
+ * behavior is controlled by the zod schema's own object mode.
+ */
+export type UnknownKeyDisposition = 'reject' | 'strip' | 'passthrough';
+export type UnknownKeyPolicy = {
+    http: UnknownKeyDisposition;
+    jsonRpc: UnknownKeyDisposition;
+};
+/**
+ * Runtime shape of an operation. Unary operations return one validated
+ * `outputSchema` value. Stream and subscription operations return long-lived
+ * iterables whose elements are validated against `eventSchema`.
+ */
+export type OperationKind = 'unary' | 'stream' | 'subscription';
+/** Invocation result for `kind: 'stream'` operations. */
+export type StreamOperationInvocation<Element> = AsyncIterable<Element>;
+/** Invocation result for `kind: 'subscription'` operations. */
+export type SubscriptionOperationInvocation<Element, Envelope> = {
+    readonly envelope: Envelope;
+    readonly iterable: AsyncIterable<Element>;
+    readonly close: () => Promise<void>;
+};
+export type OperationInvocationResult<Output> = Output | StreamOperationInvocation<unknown> | SubscriptionOperationInvocation<unknown, Output>;
+/**
+ * Metadata that connects an operation-catalog entry to a live MCP tool.
+ *
+ * v1 only supports workflow-backed MCP tools. The exact MCP tool name is
+ * resolved from the live engine registry during discovery because `tools/list`
+ * owns collision handling.
+ */
+export type McpToolMetadata = {
+    readonly workflowType: string;
+};
+/**
+ * Result of the parameter-aware `authorize` hook.
+ *
+ * **`reason` is wire-visible.** Hook authors must not embed secrets or
+ * sensitive context in a denial reason.
+ */
+export type AuthorizationDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * Stable audit markers emitted after each successful operation pipeline stage.
+ */
+export type PipelineTraceMarker = 'looked-up' | 'transport-checked' | 'access-checked' | 'parsed' | 'unknown-key-policy-applied' | 'authorized' | 'invoked' | 'output-validated';
+/**
+ * Optional observer hook used by audit tests to prove a transport used the
+ * full `executeOperation` pipeline.
+ */
+export type PipelineTrace = (marker: PipelineTraceMarker) => void;
+/**
+ * Context passed to both the `authorize` hook and `invoke`.
+ */
+export type OperationContext<Input> = {
+    readonly input: Input;
+    readonly principal: Principal;
+    readonly engine: unknown;
+    readonly transport: TransportKind;
+};
+/**
+ * Common operation fields shared by unary, stream, and subscription kinds.
+ * The discriminated union below adds `kind` and `eventSchema` per kind.
+ */
+type OperationDefinitionBase<Input, Output> = {
+    readonly name: string;
+    readonly mcpExposable: boolean;
+    readonly mcpTool?: McpToolMetadata;
+    readonly summary: string;
+    /**
+     * Optional longer-form prose describing what the operation does, its key
+     * inputs, and notable faults or preconditions. `summary` stays the short
+     * one-liner; `description` is the paragraph that surfaces in OpenAPI /
+     * OpenRPC operation descriptions, the CLI `weft api --describe` view, and
+     * MCP-facing discovery metadata. Optional: only the interactively-used
+     * subset of operations populate it. `summary` remains mandatory for all.
+     */
+    readonly description?: string;
+    readonly tags: ReadonlyArray<string>;
+    /**
+     * Whether invoking this operation irreversibly mutates state or is
+     * otherwise hard to undo (cancel, purge, bulk-delete, raw storage writes,
+     * recover-all, worker drain). Consumers read this single source of truth
+     * instead of maintaining their own allowlists: the CLI `weft api` escape
+     * hatch refuses destructive operations without explicit confirmation,
+     * dashboard bulk actions gate their confirmations on it, and MCP exposure
+     * uses it to decide what to surface. Read-only operations (`get-*`,
+     * `list-*`, `aggregate`, `registry`, `metrics`) are `false`.
+     *
+     * Required with no implicit default so every new operation is forced to
+     * make the call explicitly — the same quality-floor pattern as the
+     * lint-disable rationale rule.
+     */
+    readonly destructive: boolean;
+    readonly inputSchema: z.ZodType<Input>;
+    /**
+     * For unary operations, validates the returned value. For subscriptions,
+     * validates the subscribe envelope. For streams, describes the start/SSE
+     * metadata while each yielded element is validated by `eventSchema`.
+     */
+    readonly outputSchema: z.ZodType<Output>;
+    readonly access: AccessPolicy;
+    /** Fault codes this operation can raise in addition to universal pipeline defaults. */
+    readonly producibleFaults?: ReadonlyArray<FaultCode>;
+    /** Whether non-public operations should appear in generated discovery documents. */
+    readonly discoverable?: boolean;
+    readonly transports: TransportAvailability;
+    readonly unknownKeyPolicy: UnknownKeyPolicy;
+    readonly authorize?: (context: OperationContext<Input>) => Promise<AuthorizationDecision>;
+    readonly invoke: (context: OperationContext<Input>) => Promise<OperationInvocationResult<Output>>;
+};
+/**
+ * Unary (request/response) operation. `kind` may be omitted (defaults to
+ * `'unary'`). `eventSchema` MUST be absent — a unary operation has no
+ * per-element shape to validate. The `eventSchema?: never` constraint
+ * enforces this at the type level: passing `eventSchema` to a unary
+ * operation is a TypeScript error, not a silent runtime mismatch.
+ */
+type UnaryOperationDefinition<Input, Output> = OperationDefinitionBase<Input, Output> & {
+    readonly kind?: 'unary';
+    readonly eventSchema?: never;
+};
+/**
+ * Streaming operation (e.g. SSE). `kind: 'stream'` is required and
+ * `eventSchema` MUST be present — the dispatcher validates each yielded
+ * element against this schema. Without it the streaming pipeline would
+ * have no contract to validate per-element output against, which would
+ * silently leak un-validated data to consumers.
+ */
+type StreamOperationDefinition<Input, Output> = OperationDefinitionBase<Input, Output> & {
+    readonly kind: 'stream';
+    readonly eventSchema: z.ZodType;
+};
+/**
+ * WebSocket subscription operation. `kind: 'subscription'` is required and
+ * `eventSchema` MUST be present (validates each delivered envelope). Same
+ * rationale as `StreamOperationDefinition` — the type forbids declaring a
+ * subscription without its element schema.
+ */
+type SubscriptionOperationDefinition<Input, Output> = OperationDefinitionBase<Input, Output> & {
+    readonly kind: 'subscription';
+    readonly eventSchema: z.ZodType;
+};
+/**
+ * Discriminated union over the three operation kinds. The discriminator
+ * (`kind`) determines whether `eventSchema` is required (`'stream'` /
+ * `'subscription'`) or forbidden (`'unary'` or absent). Streaming
+ * operations declared without `eventSchema` are now a TypeScript error
+ * rather than a runtime EngineFailure; unary operations cannot
+ * accidentally carry an `eventSchema` that the pipeline would never read.
+ */
+export type OperationDefinition<Input, Output> = UnaryOperationDefinition<Input, Output> | StreamOperationDefinition<Input, Output> | SubscriptionOperationDefinition<Input, Output>;
+/**
+ * An operation with its Input/Output type parameters erased. The dispatcher
+ * only feeds values that have been validated by the operation's own schema.
+ */
+export type ErasedOperation = OperationDefinition<unknown, unknown>;
+/** Read-only registry of operations keyed by name. */
+export type OperationRegistry = {
+    get(name: string): ErasedOperation | undefined;
+    list(): ReadonlyArray<ErasedOperation>;
+};
+/**
+ * Erased operation shape accepted by `createOperationRegistry`. Mirrors
+ * the discriminated union on `OperationDefinition` so registry callers
+ * declaring a stream/subscription without `eventSchema` get a compile-time
+ * error rather than a runtime `EngineFailure` when the pipeline first
+ * attempts per-element validation.
+ */
+type RegistrableOperationBase = {
+    readonly name: string;
+    readonly mcpExposable: boolean;
+    readonly mcpTool?: McpToolMetadata;
+    readonly summary: string;
+    /** See {@link OperationDefinitionBase.description}. Optional longer-form prose. */
+    readonly description?: string;
+    readonly tags: ReadonlyArray<string>;
+    /** See {@link OperationDefinitionBase.destructive}. Required, no default. */
+    readonly destructive: boolean;
+    readonly inputSchema: z.ZodType;
+    readonly outputSchema: z.ZodType;
+    readonly access: AccessPolicy;
+    /** Fault codes this operation can raise in addition to universal pipeline defaults. */
+    readonly producibleFaults?: ReadonlyArray<FaultCode>;
+    /** Whether non-public operations should appear in generated discovery documents. */
+    readonly discoverable?: boolean;
+    readonly transports: TransportAvailability;
+    readonly unknownKeyPolicy: UnknownKeyPolicy;
+    readonly authorize?: (context: OperationContext<never>) => Promise<AuthorizationDecision>;
+    readonly invoke: (context: OperationContext<never>) => Promise<OperationInvocationResult<unknown>>;
+};
+type UnaryRegistrableOperation = RegistrableOperationBase & {
+    readonly kind?: 'unary';
+    readonly eventSchema?: never;
+};
+type StreamRegistrableOperation = RegistrableOperationBase & {
+    readonly kind: 'stream';
+    readonly eventSchema: z.ZodType;
+};
+type SubscriptionRegistrableOperation = RegistrableOperationBase & {
+    readonly kind: 'subscription';
+    readonly eventSchema: z.ZodType;
+};
+export type RegistrableOperation = UnaryRegistrableOperation | StreamRegistrableOperation | SubscriptionRegistrableOperation;
+export type DispatchContext = {
+    readonly principal: Principal;
+    readonly engine: unknown;
+    readonly transport: TransportKind;
+    readonly registry: OperationRegistry;
+    readonly pipelineTrace?: PipelineTrace;
+};
+export type DispatchResult<Output> = {
+    readonly ok: true;
+    readonly value: Output;
+} | {
+    readonly ok: false;
+    readonly fault: OperationFault;
+};
+export {};

package/dist/server/operation-catalog/types.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const OPERATION_NAME_PATTERN = /^weft\.[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/;
+export function validateOperationName(name) {
+  if (!OPERATION_NAME_PATTERN.test(name))
+    throw Error(`invalid operation name "${name}" \u2014 must match weft.<segment>(.<segment>)+ where each segment starts with a lowercase ASCII letter and may contain lowercase ASCII letters or digits (e.g., "weft.workflows.start", "weft.workflows.list2")`);
+}
+export function isValidOperationName(name) {
+  return OPERATION_NAME_PATTERN.test(name);
+}

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

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import type { WorkflowDefinition } from '../../core/types.ts';
+import type { AccessPolicy } from '../authorization.ts';
+import type { AuthorizationDecision, OperationContext, OperationDefinition, TransportAvailability, UnknownKeyPolicy } from './types.ts';
+declare const StartHandleSchema: z.ZodObject<{
+    workflowId: z.ZodString;
+    status: z.ZodString;
+}, z.core.$strip>;
+type StartHandle = z.infer<typeof StartHandleSchema>;
+type CatalogWorkflowRegistrationMetadata<Input> = Pick<WorkflowDefinition<Input>, 'description' | 'inputSchema' | 'tags'>;
+/**
+ * Options accepted by {@link catalogWorkflow}.
+ *
+ * `mcpExposable` is REQUIRED. There is no default. The plan's MCP-readiness
+ * ratchet enforces explicit per-operation declaration of MCP exposability
+ * (see `mcp-readiness.test.ts`); the adapter forwards the caller's choice
+ * verbatim so cataloged workflows participate in the same ratchet.
+ *
+ * No `engine` field. The engine instance comes from the runtime dispatch
+ * context (the same `Engine` that runs `executeOperation`). Binding the
+ * adapter to a specific engine instance was a footgun: an adapter created
+ * for engine A could be dispatched by engine B and silently start the
+ * workflow on the wrong engine. The dispatch context is the single source
+ * of truth.
+ *
+ * No `outputSchema` field. The response shape is fixed at
+ * `{ workflowId, status }` — the workflow's own result schema belongs on a
+ * future `getResult`-shaped operation.
+ *
+ * No `mode` field. v1 ships start-only semantics.
+ */
+export type CatalogWorkflowOptions<Input> = {
+    readonly name: string;
+    readonly mcpExposable: boolean;
+    readonly workflowType: string;
+    readonly summary?: string;
+    readonly tags?: ReadonlyArray<string>;
+    readonly inputSchema?: z.ZodObject<z.ZodRawShape>;
+    readonly registration?: CatalogWorkflowRegistrationMetadata<Input>;
+    readonly access: AccessPolicy;
+    readonly transports: TransportAvailability;
+    readonly unknownKeyPolicy: UnknownKeyPolicy;
+    readonly authorize?: (context: OperationContext<Input>) => Promise<AuthorizationDecision>;
+};
+/**
+ * `catalogWorkflow()` — wrap a registered workflow as a typed
+ * `OperationDefinition`. Produces one cataloged `start` operation per
+ * workflow. Always returns the start handle ({ workflowId, status });
+ * never blocks awaiting the workflow result.
+ *
+ * Schemas are opt-in for v1; required when the operation is later flagged
+ * as MCP-exposable (see `mcpExposable` ratchet in PR 6).
+ */
+export declare function catalogWorkflow<Input>(options: CatalogWorkflowOptions<Input>): OperationDefinition<Input, StartHandle>;
+export {};

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

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import {
+  WorkflowAlreadyExistsError,
+  WorkflowNotRegisteredError
+} from "../../core/engine/errors.js";
+import { runtimeWorkflowEngine } from "../../core/runtime-workflow-engine.js";
+import { StartWorkflowValidationError } from "../../core/start-workflow-validation.js";
+import { invalidParamsFault } from "../operations/operation-helpers.js";
+import { validateOperationName } from "./types.js";
+const StartHandleSchema = z.object({
+  workflowId: z.string(),
+  status: z.string()
+});
+export function catalogWorkflow(options) {
+  const presentation = resolveCatalogWorkflowPresentation(options);
+  validateOperationName(options.name);
+  return {
+    name: options.name,
+    mcpExposable: options.mcpExposable,
+    ...options.mcpExposable ? { mcpTool: { workflowType: options.workflowType } } : {},
+    summary: presentation.summary,
+    tags: presentation.tags,
+    destructive: !1,
+    inputSchema: presentation.inputSchema,
+    outputSchema: StartHandleSchema,
+    access: copyAccessPolicy(options.access),
+    producibleFaults: ["Conflict"],
+    transports: { ...options.transports },
+    unknownKeyPolicy: { ...options.unknownKeyPolicy },
+    ...options.authorize === void 0 ? {} : { authorize: options.authorize },
+    invoke: async ({ input, engine }) => {
+      const typedEngine = runtimeWorkflowEngine(engine);
+      try {
+        return { workflowId: (await typedEngine.start(options.workflowType, input)).id, status: "started" };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof WorkflowNotRegisteredError)
+          throw invalidParamsFault(message);
+        if (error instanceof WorkflowAlreadyExistsError)
+          throw {
+            code: "Conflict",
+            message,
+            data: { reason: message }
+          };
+        if (error instanceof StartWorkflowValidationError)
+          throw invalidParamsFault(message);
+        throw {
+          code: "EngineFailure",
+          message,
+          data: {}
+        };
+      }
+    }
+  };
+}
+function resolveCatalogWorkflowPresentation(options) {
+  const inputSchema = options.inputSchema ?? zodObjectFromRegistrationSchema(options.registration?.inputSchema) ?? z.object({}).passthrough(), summary = options.summary ?? options.registration?.description ?? `Start ${options.workflowType} workflow`, tags = options.tags ?? options.registration?.tags ?? [];
+  return { inputSchema, summary, tags: [...tags] };
+}
+function zodObjectFromRegistrationSchema(schema) {
+  if (schema === void 0)
+    return;
+  if (schema instanceof z.ZodObject)
+    return schema;
+  throw TypeError("catalogWorkflow() can reuse registration.inputSchema only when it is a Zod object. Pass inputSchema explicitly for other DefinitionSchema implementations.");
+}
+function copyAccessPolicy(policy) {
+  if (policy.kind === "scoped")
+    return {
+      kind: "scoped",
+      scopes: {
+        kind: policy.scopes.kind,
+        scopes: [...policy.scopes.scopes]
+      }
+    };
+  if (policy.kind === "optionalAuth")
+    return {
+      kind: "optionalAuth",
+      authenticatedScopes: {
+        kind: policy.authenticatedScopes.kind,
+        scopes: [...policy.authenticatedScopes.scopes]
+      }
+    };
+  return { ...policy };
+}

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

@@ -0,0 +1 @@
+export * from './operation-catalog/index.ts';

package/dist/server/operation-catalog.js

@@ -0,0 +1 @@
+export * from "./operation-catalog/index.js";