@lostgradient/weft 0.23.1 → 0.24.0

package/dist/runtime/portable.d.ts

@@ -129,9 +129,17 @@ export declare function hashString(data: string): string;
  * try to resolve or stub. Returns `undefined` in the browser or any runtime
  * lacking `process.getBuiltinModule`, so callers on a browser-reachable path
  * must treat the result as optional rather than throwing at import time.
+ *
+ * Overloaded per known specifier so callers get the correct module type from
+ * the literal `id` argument alone, without an explicit type argument. Add a
+ * new literal overload here when a new built-in specifier is loaded through
+ * this helper.
  * @internal
  */
-export declare function tryLoadNodeBuiltin<T>(id: string): T | undefined;
+export declare function tryLoadNodeBuiltin(id: 'node:fs'): typeof import('node:fs') | undefined;
+export declare function tryLoadNodeBuiltin(id: 'node:fs/promises'): typeof import('node:fs/promises') | undefined;
+export declare function tryLoadNodeBuiltin(id: 'node:zlib'): typeof import('node:zlib') | undefined;
+export declare function tryLoadNodeBuiltin(id: 'node:module'): typeof import('node:module') | undefined;
 /**
  * Return the byte size of a file at the given path.
  *

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

@@ -34,7 +34,9 @@ function dataForConflict(data) {
     reason: data.reason,
     missingTypes: data.missingTypes === void 0 ? void 0 : [...data.missingTypes],
     missingWorkflowCount: data.missingWorkflowCount,
-    samplesTruncated: data.samplesTruncated
+    samplesTruncated: data.samplesTruncated,
+    currentGeneration: data.currentGeneration,
+    compatibilityReasons: data.compatibilityReasons === void 0 ? void 0 : [...data.compatibilityReasons]
   });
 }
 function dataForNotFound(data) {

package/dist/server/handler/auth-context-principal.js

@@ -21,5 +21,9 @@ export function authContextToPrincipal(authContext) {
       return principalFromMutualTls({ subject: "mtls-caller", scopes: [] });
     case "public":
       return anonymousPrincipal();
+    default: {
+      const exhaustiveCheck = authContext.method;
+      throw Error(`Unknown auth context method: ${JSON.stringify(exhaustiveCheck)}`);
+    }
   }
 }

package/dist/server/json-rpc-http.js

@@ -66,6 +66,8 @@ function dispatchResultToResponse(result) {
       return Response.json(result.response, { status: 200, headers: CACHE_CONTROL_HEADERS });
     case "batch":
       return Response.json(result.responses, { status: 200, headers: CACHE_CONTROL_HEADERS });
+    default:
+      throw Error(`Unknown JSON-RPC dispatch result kind: ${JSON.stringify(result)}`);
   }
 }
 const CONTENT_LENGTH_PATTERN = /^(0|[1-9]\d*)$/;

package/dist/server/json-rpc-websocket.js

@@ -12,8 +12,13 @@ import {
   validateSessionPrimitiveFrame,
   validateSubscribeParams
 } from "./json-rpc-websocket-validation.js";
-import { executeSubscription } from "./operation-catalog.js";
+import {
+  executeSubscription
+} from "./operation-catalog.js";
 const DEFAULT_MAX_SUBSCRIPTIONS = 100, DEFAULT_MAX_FRAME_BYTES = 1048576;
+function isSessionPrimitive(method) {
+  return method === SESSION_METHODS.SUBSCRIBE || method === WORKFLOW_EVENTS_OPERATION_NAME || method === SESSION_METHODS.FLEET_SUBSCRIBE || method === SESSION_METHODS.UNSUBSCRIBE;
+}
 export function createJsonRpcWebSocketSession(options) {
   const { registry, engine, principal, emitter, feed, fleetFeed } = options, maxSubscriptions = options.maxSubscriptions ?? DEFAULT_MAX_SUBSCRIPTIONS, maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, transport = options.transport ?? "jsonRpcWebSocket", subscriptions = new Map;
   let emitterBroken = !1, disposed = !1;
@@ -186,9 +191,6 @@ export function createJsonRpcWebSocketSession(options) {
       params: { subscriptionId, reason: "client-unsubscribed" }
     });
   }
-  function isSessionPrimitive(method) {
-    return method === SESSION_METHODS.SUBSCRIBE || method === WORKFLOW_EVENTS_OPERATION_NAME || method === SESSION_METHODS.FLEET_SUBSCRIBE || method === SESSION_METHODS.UNSUBSCRIBE;
-  }
   async function handleSessionPrimitive(validation) {
     const sessionPrimitiveError = validateSessionPrimitiveFrame(validation);
     if (sessionPrimitiveError !== null) {

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

@@ -17,6 +17,6 @@ export { executeOperation } from './pipeline.ts';
 export { UNIVERSAL_FAULT_DEFAULTS, raiseFault } from './raise-fault.ts';
 export { createOperationRegistry } from './registry.ts';
 export { SubscriptionElementValidationError, executeStream, executeSubscription, } from './stream-pipeline.ts';
-export { OPERATION_NAME_PATTERN, isValidOperationName, validateOperationName, type AuthorizationDecision, type DispatchContext, type DispatchResult, type ErasedOperation, type McpToolMetadata, type OperationContext, type OperationDefinition, type OperationInvocationResult, type OperationKind, type OperationRegistry, type ParameterizedAccessHint, type PipelineTrace, type PipelineTraceMarker, type RegistrableOperation, type StreamOperationInvocation, type SubscriptionOperationInvocation, type TransportAvailability, type UnknownKeyDisposition, type UnknownKeyPolicy, } from './types.ts';
+export { OPERATION_NAME_PATTERN, isValidOperationName, validateOperationName, type AuthorizationDecision, type DispatchContext, type DispatchResult, type ErasedOperation, type McpToolMetadata, type OperationContext, type OperationDefinition, type OperationInvocationResult, type OperationKind, type OperationRegistry, type ParameterizedAccessHint, type PipelineTrace, type PipelineTraceMarker, type RegistrableOperation, type StreamOperationInvocation, type SubscriptionOperationInvocation, type SubscriptionStartEnvelope, type TransportAvailability, type UnknownKeyDisposition, type UnknownKeyPolicy, } from './types.ts';
 export { catalogWorkflow } from './workflow-adapter.ts';
 export type { CatalogWorkflowOptions } from './workflow-adapter.ts';

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

@@ -28,6 +28,8 @@ export function transportToAvailabilityKey(transport) {
       return "jsonRpcWebSocket";
     case "jsonRpcStdio":
       return "jsonRpcStdio";
+    default:
+      throw Error(`Unknown transport kind: ${JSON.stringify(transport)}`);
   }
 }
 export function extractTopLevelObjectKeys(schema) {

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

@@ -45,6 +45,23 @@ export type SubscriptionOperationInvocation<Element, Envelope> = {
     readonly iterable: AsyncIterable<Element>;
     readonly close: () => Promise<void>;
 };
+/**
+ * Envelope acknowledging that a JSON-RPC subscription has started. This is
+ * the protocol-level shape the built-in JSON-RPC WebSocket subscriptions
+ * (`weft.workflows.events` and the fleet-events subscription in
+ * `json-rpc-websocket.ts`) use for their own `outputSchema`/envelope — it is
+ * NOT the general contract for every `kind: 'subscription'` operation.
+ * `executeSubscription` in `stream-pipeline.ts` stays generic over
+ * `Envelope` precisely because a catalog subscription can declare any
+ * envelope shape its own `outputSchema` validates; other subscription
+ * operations are free to use a different shape (see the
+ * `subscriptionId`-only regression case in
+ * `operation-catalog/dispatch-audit.test.ts`).
+ */
+export type SubscriptionStartEnvelope = {
+    readonly subscriptionId: string;
+    readonly cursor: string;
+};
 export type OperationInvocationResult<Output, Element = unknown> = Output | StreamOperationInvocation<Element> | SubscriptionOperationInvocation<Element, Output>;
 /**
  * Metadata that connects an operation-catalog entry to a live MCP tool.

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

@@ -34,6 +34,7 @@
  * `data` payload forms the basis of cross-transport parity: every fault is
  * serialized consistently across REST and JSON-RPC transports.
  */
+import type { WorkflowCompatibilityReason } from '../core/contract/compatibility.ts';
 import type { FaultCode } from '../core/fault-code.ts';
 import { type WeftErrorCode } from '../core/weft-error.ts';
 /** Transport identifiers as seen by `executeOperation`. */
@@ -78,6 +79,8 @@ export type OperationFault = {
         missingTypes?: readonly string[] | undefined;
         missingWorkflowCount?: number | undefined;
         samplesTruncated?: boolean | undefined;
+        currentGeneration?: number | undefined;
+        compatibilityReasons?: readonly WorkflowCompatibilityReason[] | undefined;
     };
 } | {
     code: 'Unprocessable';

package/dist/server/operation-fault.js

@@ -30,7 +30,9 @@ const NO_REST_FAULT_DATA = Object.freeze({}), REST_FAULT_DATA_EXTRACTORS = {
   Conflict: (data) => filterDefined({
     missingTypes: data.missingTypes === void 0 ? void 0 : [...data.missingTypes],
     missingWorkflowCount: data.missingWorkflowCount,
-    samplesTruncated: data.samplesTruncated
+    samplesTruncated: data.samplesTruncated,
+    currentGeneration: data.currentGeneration,
+    compatibilityReasons: data.compatibilityReasons === void 0 ? void 0 : [...data.compatibilityReasons]
   }),
   Unprocessable: () => NO_REST_FAULT_DATA,
   PayloadTooLarge: (data) => ({ maxBytes: data.maxBytes }),

package/dist/server/operations/activate-workflow-revision.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `weft.workflows.revisions.activate` operation + REST binding.
+ *
+ * Activates an already-installed `(name, revision)` as the durably
+ * advertised active revision — bookkeeping only. See
+ * `core/engine/engine-workflows-namespace.ts`'s module doc: activation
+ * moves `RegistrySnapshot.activeRevisions`, never which in-process handler
+ * `engine.start()` dispatches to.
+ *
+ * @module server/operations/activate-workflow-revision
+ */
+import { z } from 'zod';
+import type { WorkflowCatalogActivationResult } from '../../core/catalog/index.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const activateWorkflowRevisionInput: z.ZodObject<{
+    name: z.ZodUnknown;
+    revision: z.ZodUnknown;
+    expectedGeneration: z.ZodOptional<z.ZodUnknown>;
+    policy: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type ActivateWorkflowRevisionInput = z.infer<typeof activateWorkflowRevisionInput>;
+export type ActivateWorkflowRevisionOutput = WorkflowCatalogActivationResult;
+export declare const activateWorkflowRevisionOperation: import("../operation-catalog.ts").OperationDefinition<{
+    name: unknown;
+    revision: unknown;
+    expectedGeneration?: unknown;
+    policy?: unknown;
+}, WorkflowCatalogActivationResult, unknown>;
+export declare const activateWorkflowRevisionRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/activate-workflow-revision.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+import {
+  activationRefusalToFault,
+  readWorkflowCatalogRestBody,
+  throwWorkflowCatalogOperationFault,
+  validateExpectedGenerationField,
+  validatePolicyField,
+  validateWorkflowNameField,
+  validateWorkflowRevisionField,
+  workflowsAdminAccess
+} from "./workflow-catalog-operation-helpers.js";
+const activateWorkflowRevisionInput = z.object({
+  name: z.unknown().describe("Workflow name. Runtime validation requires a wire-safe identifier."),
+  revision: z.unknown().describe("Installed revision to activate. Runtime validation requires a non-empty string."),
+  expectedGeneration: z.unknown().optional().describe("The durable generation this caller last observed. Required once the workflow has an " + "active revision \u2014 omitting it there refuses with expected-generation-required."),
+  policy: z.unknown().optional().describe("Optional compatibility policy override.")
+}), activateWorkflowRevisionOutput = z.unknown();
+export const activateWorkflowRevisionOperation = defineOperation({
+  name: "weft.workflows.revisions.activate",
+  mcpExposable: !1,
+  summary: "Activate an installed workflow revision",
+  description: "Activate an already-installed `(name, revision)` as the durably advertised active revision for `name`. Returns the structured result verbatim: `{ applied: true, pointer }` on success, " + "or `{ applied: false, reason, ... }` on refusal \u2014 surfaced as a Conflict fault with `reason` " + "one of `incompatible`, `stale-generation`, `expected-generation-required`, or `conflict`. Faults with NotFound when the revision was never installed. Never changes which in-process " + "handler `engine.start()` dispatches to \u2014 see the workflow-versioning guide.",
+  destructive: !0,
+  tags: ["Workflow Catalog"],
+  inputSchema: activateWorkflowRevisionInput,
+  outputSchema: activateWorkflowRevisionOutput,
+  access: workflowsAdminAccess,
+  producibleFaults: ["NotFound", "Conflict", "InvalidParams"],
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    const e = engine, name = validateWorkflowNameField(input.name), revision = validateWorkflowRevisionField(input.revision), expectedGeneration = validateExpectedGenerationField(input.expectedGeneration), policy = validatePolicyField(input.policy);
+    let result;
+    try {
+      result = await e.workflows.activate(name, revision, {
+        ...expectedGeneration === void 0 ? {} : { expectedGeneration },
+        ...policy === void 0 ? {} : { policy }
+      });
+    } catch (error) {
+      throwWorkflowCatalogOperationFault(error);
+    }
+    if (!result.applied)
+      throw activationRefusalToFault(result);
+    return result;
+  }
+}), activateWorkflowRevisionRestBinding = {
+  method: "POST",
+  path: "/v1/registry/workflows/:name/activate",
+  pathParamNames: ["name"],
+  operationName: "weft.workflows.revisions.activate",
+  inputSources: {
+    name: { kind: "path", pathParam: "name" },
+    revision: { kind: "body-field", bodyField: "revision" },
+    expectedGeneration: { kind: "body-field", bodyField: "expectedGeneration" },
+    policy: { kind: "body-field", bodyField: "policy" }
+  },
+  extractInput: async (request, pathParams, context) => {
+    const body = await readWorkflowCatalogRestBody(request, context);
+    return {
+      name: pathParams.name ?? "",
+      revision: body.revision,
+      expectedGeneration: body.expectedGeneration,
+      policy: body.policy
+    };
+  },
+  success: { kind: "json", status: 200 }
+};

package/dist/server/operations/fleet-events-subscription.js

@@ -85,7 +85,7 @@ function getFleetEventFeed(engine, transport) {
     if (isFleetEventSubscriber(fleetFeed))
       return fleetFeed;
   }
-  raiseFault(fleetEventsSubscriptionOperation, {
+  return raiseFault(fleetEventsSubscriptionOperation, {
     code: "UnsupportedTransport",
     message: "Fleet event subscription requires a WebSocket fleet event feed",
     data: { transport, supported: ["jsonRpcWebSocket"] }

package/dist/server/operations/fork-workflow.js

@@ -54,7 +54,7 @@ export const forkWorkflowOperation = defineOperation({
     try {
       return { id: (await typedEngine.fork(input.workflowId, options)).id };
     } catch (error) {
-      resolveForkAccess(error);
+      return resolveForkAccess(error);
     }
   }
 }), forkWorkflowRestBinding = {

package/dist/server/operations/get-active-workflow-revision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `weft.workflows.active.get` operation + REST binding.
+ *
+ * Returns the currently active revision pointer for one workflow name.
+ * Named `active.get` rather than `revisions.getActive` — `OPERATION_NAME_PATTERN`
+ * forbids camelCase wire segments, and `getActive` is only this namespace
+ * method's TypeScript name (`engine.workflows.getActive`).
+ *
+ * In-memory only: matches `RegistrySnapshot.activeRevisions`' existing
+ * staleness contract exactly (see `engine-workflows-namespace.ts`'s
+ * `getActive` JSDoc), which is what makes "operations and the registry
+ * snapshot agree" true by construction.
+ *
+ * @module server/operations/get-active-workflow-revision
+ */
+import { z } from 'zod';
+import type { WorkflowCatalogActivePointer } from '../../core/catalog/index.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const getActiveWorkflowRevisionInput: z.ZodObject<{
+    name: z.ZodUnknown;
+}, z.core.$strip>;
+export type GetActiveWorkflowRevisionInput = z.infer<typeof getActiveWorkflowRevisionInput>;
+export type GetActiveWorkflowRevisionOutput = WorkflowCatalogActivePointer;
+export declare const getActiveWorkflowRevisionOperation: import("../operation-catalog.ts").OperationDefinition<{
+    name: unknown;
+}, Readonly<{
+    revision: string;
+    generation: number;
+    activatedAt: number;
+}>, unknown>;
+export declare const getActiveWorkflowRevisionRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/get-active-workflow-revision.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+import {
+  validateWorkflowNameField,
+  workflowsReadAccess
+} from "./workflow-catalog-operation-helpers.js";
+const getActiveWorkflowRevisionInput = z.object({
+  name: z.unknown().describe("Workflow name. Runtime validation requires a wire-safe identifier.")
+}), getActiveWorkflowRevisionOutput = z.unknown();
+export const getActiveWorkflowRevisionOperation = defineOperation({
+  name: "weft.workflows.active.get",
+  mcpExposable: !1,
+  summary: "Get the currently active revision pointer for a workflow",
+  description: "Read the current `{ revision, generation, activatedAt }` active pointer for `name`. Read-only, in-memory (matches `RegistrySnapshot.activeRevisions`' staleness contract exactly). Faults with NotFound when `name` has never been activated.",
+  destructive: !1,
+  tags: ["Workflow Catalog"],
+  inputSchema: getActiveWorkflowRevisionInput,
+  outputSchema: getActiveWorkflowRevisionOutput,
+  access: workflowsReadAccess,
+  producibleFaults: ["NotFound", "InvalidParams"],
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    const e = engine, name = validateWorkflowNameField(input.name), pointer = await e.workflows.getActive(name);
+    if (pointer === null)
+      throw {
+        code: "NotFound",
+        message: `Workflow "${name}" has never been activated`,
+        data: { resource: "workflow-active-revision", identifier: name }
+      };
+    return pointer;
+  }
+}), getActiveWorkflowRevisionRestBinding = {
+  method: "GET",
+  path: "/v1/registry/workflows/:name/active",
+  pathParamNames: ["name"],
+  operationName: "weft.workflows.active.get",
+  inputSources: {
+    name: { kind: "path", pathParam: "name" }
+  },
+  extractInput: async (_request, pathParams) => ({
+    name: pathParams.name ?? ""
+  }),
+  success: { kind: "json", status: 200 }
+};

package/dist/server/operations/get-catalog-diagnostics.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `weft.catalog.diagnostics` operation + REST binding (WFT-12).
+ *
+ * Read-only, bounded diagnostics for one `(name, revision)` workflow
+ * catalog entry: whether it is installed, whether it is currently active,
+ * its full reference-count breakdown, and whether it would currently be
+ * removable. No REST/JSON-RPC removal surface exists this batch — removal
+ * (`removeWorkflowRevision`) is a plain in-process function, not a wire
+ * operation, per the coordinator's "single bounded diagnostics operation"
+ * steer.
+ *
+ * Static, not factory-built — unlike `get-worker-diagnostics.ts`'s injected
+ * `WorkerRegistry`, this operation needs no per-server state beyond the
+ * live `engine` every `invoke` already receives, matching
+ * `get-retention-overview.ts`'s shape.
+ *
+ * @module server/operations/get-catalog-diagnostics
+ */
+import { z } from 'zod';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const getCatalogDiagnosticsInput: z.ZodObject<{
+    name: z.ZodString;
+    revision: z.ZodString;
+}, z.core.$strict>;
+declare const getCatalogDiagnosticsOutput: z.ZodObject<{
+    name: z.ZodString;
+    revision: z.ZodString;
+    installed: z.ZodBoolean;
+    active: z.ZodBoolean;
+    activeRevision: z.ZodOptional<z.ZodString>;
+    references: z.ZodObject<{
+        registeredDefinitions: z.ZodNumber;
+        inFlightStarts: z.ZodNumber;
+        nonTerminalRuns: z.ZodNumber;
+        pinnedSchedules: z.ZodNumber;
+        pendingDispatches: z.ZodNumber;
+        activeExecutionRealms: z.ZodNumber;
+        retainedRecoveryRecords: z.ZodNumber;
+    }, z.core.$strict>;
+    removable: z.ZodBoolean;
+}, z.core.$strict>;
+export type GetCatalogDiagnosticsInput = z.infer<typeof getCatalogDiagnosticsInput>;
+export type GetCatalogDiagnosticsOutput = z.infer<typeof getCatalogDiagnosticsOutput>;
+/**
+ * `weft.catalog.diagnostics`: bounded, per-`(name, revision)` diagnostics
+ * for the durable workflow catalog. Requires `system:read`. Never returns
+ * manifest or contract content — only identity, active-pointer state, and
+ * low-cardinality reference counts, matching the repository's "metrics
+ * remain low-cardinality" observability convention.
+ *
+ * @example
+ * ```ts
+ * import { HttpClient } from '@lostgradient/weft/client';
+ *
+ * const client = new HttpClient({ baseUrl: 'https://weft.example.com' });
+ * const diagnostics = await client.operations['weft.catalog.diagnostics']({
+ *   name: 'checkout',
+ *   revision: 'some-revision',
+ * });
+ * console.log(diagnostics.installed, diagnostics.removable);
+ * ```
+ */
+export declare const getCatalogDiagnosticsOperation: import("../operation-catalog.ts").OperationDefinition<{
+    name: string;
+    revision: string;
+}, {
+    name: string;
+    revision: string;
+    installed: boolean;
+    active: boolean;
+    references: {
+        registeredDefinitions: number;
+        inFlightStarts: number;
+        nonTerminalRuns: number;
+        pinnedSchedules: number;
+        pendingDispatches: number;
+        activeExecutionRealms: number;
+        retainedRecoveryRecords: number;
+    };
+    removable: boolean;
+    activeRevision?: string | undefined;
+}, unknown>;
+/** REST binding for `weft.catalog.diagnostics`: `GET /v1/catalog/:name/revisions/:revision/diagnostics`. */
+export declare const getCatalogDiagnosticsRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/get-catalog-diagnostics.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { getWorkflowRevisionDiagnostics } from "../../core/engine.js";
+import { shapeOperationFaultAsJson } from "../operation-fault.js";
+import { defineOperation } from "../operation-registry.js";
+const workflowRevisionReferenceCountsSchema = z.object({
+  registeredDefinitions: z.number().int().nonnegative(),
+  inFlightStarts: z.number().int().nonnegative(),
+  nonTerminalRuns: z.number().int().nonnegative(),
+  pinnedSchedules: z.number().int().nonnegative(),
+  pendingDispatches: z.number().int().nonnegative(),
+  activeExecutionRealms: z.number().int().nonnegative(),
+  retainedRecoveryRecords: z.number().int().nonnegative()
+}).strict(), getCatalogDiagnosticsInput = z.object({
+  name: z.string().min(1),
+  revision: z.string().min(1)
+}).strict(), getCatalogDiagnosticsOutput = z.object({
+  name: z.string(),
+  revision: z.string(),
+  installed: z.boolean(),
+  active: z.boolean(),
+  activeRevision: z.string().optional(),
+  references: workflowRevisionReferenceCountsSchema,
+  removable: z.boolean()
+}).strict();
+export const getCatalogDiagnosticsOperation = defineOperation({
+  name: "weft.catalog.diagnostics",
+  mcpExposable: !1,
+  summary: "Get bounded reference-count and removability diagnostics for one workflow revision",
+  description: "Report whether a `(name, revision)` workflow catalog entry is installed, whether it is currently the active revision, its full reference-count breakdown, and whether it's currently removable. Never returns manifest or contract content.",
+  destructive: !1,
+  tags: ["Observability"],
+  inputSchema: getCatalogDiagnosticsInput,
+  outputSchema: getCatalogDiagnosticsOutput,
+  access: { kind: "scoped", scopes: { kind: "anyOf", scopes: ["system:read"] } },
+  producibleFaults: [],
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ engine, input }) => {
+    return getWorkflowRevisionDiagnostics(engine, input.name, input.revision);
+  }
+}), getCatalogDiagnosticsRestBinding = {
+  method: "GET",
+  path: "/v1/catalog/:name/revisions/:revision/diagnostics",
+  pathParamNames: ["name", "revision"],
+  operationName: "weft.catalog.diagnostics",
+  inputSources: {
+    name: { kind: "path", pathParam: "name" },
+    revision: { kind: "path", pathParam: "revision" }
+  },
+  extractInput: async (_request, pathParams) => ({
+    name: pathParams.name ?? "",
+    revision: pathParams.revision ?? ""
+  }),
+  success: { kind: "json", status: 200 },
+  shapeFault: shapeOperationFaultAsJson
+};

package/dist/server/operations/get-registry.js

@@ -1,14 +1,19 @@
 import { z } from "zod";
 import {
   buildRegistrySnapshot,
-  RegistrySchemaConversionError
+  REGISTRY_VERSION,
+  RegistryManifestLimitError,
+  RegistrySchemaConversionError,
+  RegistryWorkflowCountLimitError
 } from "../../core/registry-snapshot.js";
 import { defineOperation } from "../operation-registry.js";
 const getRegistryInput = z.object({}), objectValue = z.unknown().refine((value) => typeof value === "object" && value !== null && !Array.isArray(value), {
   message: "expected an object"
 }), getRegistryOutput = z.object({
-  registryVersion: z.literal(1),
-  workflows: objectValue,
+  registryVersion: z.literal(REGISTRY_VERSION),
+  generatedAt: z.string(),
+  workflows: z.array(objectValue),
+  activeRevisions: objectValue,
   activities: objectValue
 }).strict();
 export const getRegistryOperation = defineOperation({
@@ -28,7 +33,7 @@ export const getRegistryOperation = defineOperation({
   unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
   invoke: async ({ engine }) => {
     try {
-      return buildRegistrySnapshot(engine);
+      return await buildRegistrySnapshot(engine);
     } catch (error) {
       if (error instanceof RegistrySchemaConversionError)
         console.error(`[weft.system.registry] ${error.message}`, {
@@ -36,6 +41,14 @@ export const getRegistryOperation = defineOperation({
           entityName: error.entityName,
           direction: error.direction
         });
+      else if (error instanceof RegistryManifestLimitError)
+        console.error(`[weft.system.registry] ${error.message}`, {
+          workflowType: error.workflowType
+        });
+      else if (error instanceof RegistryWorkflowCountLimitError)
+        console.error(`[weft.system.registry] ${error.message}`, {
+          count: error.count
+        });
       throw error;
     }
   }

package/dist/server/operations/get-workflow-revision.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `weft.workflows.revisions.get` operation + REST binding.
+ *
+ * Returns one installed `(name, revision)` workflow catalog record.
+ *
+ * @module server/operations/get-workflow-revision
+ */
+import { z } from 'zod';
+import type { WorkflowRevisionRecord } from '../../core/catalog/index.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const getWorkflowRevisionInput: z.ZodObject<{
+    name: z.ZodUnknown;
+    revision: z.ZodUnknown;
+}, z.core.$strip>;
+export type GetWorkflowRevisionInput = z.infer<typeof getWorkflowRevisionInput>;
+export type GetWorkflowRevisionOutput = WorkflowRevisionRecord;
+export declare const getWorkflowRevisionOperation: import("../operation-catalog.ts").OperationDefinition<{
+    name: unknown;
+    revision: unknown;
+}, Readonly<{
+    manifest: import("../../index.ts").WorkflowRevisionManifest;
+    installedAt: number;
+}>, unknown>;
+export declare const getWorkflowRevisionRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/get-workflow-revision.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+import {
+  validateWorkflowNameField,
+  validateWorkflowRevisionField,
+  workflowsReadAccess
+} from "./workflow-catalog-operation-helpers.js";
+const getWorkflowRevisionInput = z.object({
+  name: z.unknown().describe("Workflow name. Runtime validation requires a wire-safe identifier."),
+  revision: z.unknown().describe("Installed revision. Runtime validation requires a non-empty string.")
+}), getWorkflowRevisionOutput = z.unknown();
+export const getWorkflowRevisionOperation = defineOperation({
+  name: "weft.workflows.revisions.get",
+  mcpExposable: !1,
+  summary: "Get one installed workflow revision",
+  description: "Read one durably installed `(name, revision)` workflow catalog record. Read-only. Faults with NotFound when no such revision was installed.",
+  destructive: !1,
+  tags: ["Workflow Catalog"],
+  inputSchema: getWorkflowRevisionInput,
+  outputSchema: getWorkflowRevisionOutput,
+  access: workflowsReadAccess,
+  producibleFaults: ["NotFound", "InvalidParams"],
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    const e = engine, name = validateWorkflowNameField(input.name), revision = validateWorkflowRevisionField(input.revision), record = await e.workflows.getRevision(name, revision);
+    if (record === null)
+      throw {
+        code: "NotFound",
+        message: `Workflow "${name}" has no installed revision "${revision}"`,
+        data: { resource: "workflow-revision", identifier: `${name}:${revision}` }
+      };
+    return record;
+  }
+}), getWorkflowRevisionRestBinding = {
+  method: "GET",
+  path: "/v1/registry/workflows/:name/revisions/:revision",
+  pathParamNames: ["name", "revision"],
+  operationName: "weft.workflows.revisions.get",
+  inputSources: {
+    name: { kind: "path", pathParam: "name" },
+    revision: { kind: "path", pathParam: "revision" }
+  },
+  extractInput: async (_request, pathParams) => ({
+    name: pathParams.name ?? "",
+    revision: pathParams.revision ?? ""
+  }),
+  success: { kind: "json", status: 200 }
+};

package/dist/server/operations/install-workflow-revision.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `weft.workflows.revisions.install` operation + REST binding.
+ *
+ * Durably installs a validated {@link WorkflowRevisionManifest} for a
+ * workflow the engine already has an in-process definition for. Catalog
+ * bookkeeping only — see `core/engine/engine-workflows-namespace.ts`'s
+ * module doc: installing (and later activating) a revision never changes
+ * which in-process handler `engine.start()` dispatches to.
+ *
+ * @module server/operations/install-workflow-revision
+ */
+import { z } from 'zod';
+import type { WorkflowRevisionRecord } from '../../core/catalog/index.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const installWorkflowRevisionInput: z.ZodObject<{
+    manifest: z.ZodUnknown;
+}, z.core.$strip>;
+export type InstallWorkflowRevisionInput = z.infer<typeof installWorkflowRevisionInput>;
+export type InstallWorkflowRevisionOutput = WorkflowRevisionRecord;
+export declare const installWorkflowRevisionOperation: import("../operation-catalog.ts").OperationDefinition<{
+    manifest: unknown;
+}, Readonly<{
+    manifest: import("../../index.ts").WorkflowRevisionManifest;
+    installedAt: number;
+}>, unknown>;
+export declare const installWorkflowRevisionRestBinding: UnknownRestBinding;
+export {};