@lostgradient/weft 0.2.0

package/dist/worker/protocol-schemas.js

@@ -0,0 +1,180 @@
+import { REMOTE_WORKER_PROTOCOL_VERSION } from "./protocol-version.js";
+const jsonValueSchema = {
+  $ref: "#/$defs/jsonValue"
+}, jsonObjectSchema = {
+  type: "object",
+  additionalProperties: jsonValueSchema
+}, stringMapSchema = {
+  type: "object",
+  additionalProperties: { type: "string" }
+}, protocolVersionSchema = {
+  const: REMOTE_WORKER_PROTOCOL_VERSION
+};
+export const REMOTE_WORKER_MESSAGE_SCHEMAS = {
+  register: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "protocolVersion", "workerId", "activities"],
+    properties: {
+      type: { const: "register" },
+      protocolVersion: protocolVersionSchema,
+      workerId: { type: "string", minLength: 1 },
+      activities: {
+        type: "array",
+        items: { type: "string", minLength: 1 }
+      },
+      concurrency: { type: "number", minimum: 1, maximum: 1000 },
+      queue: { type: "string", minLength: 1 },
+      deploymentName: { type: "string", minLength: 1 },
+      buildId: { type: "string", minLength: 1 },
+      runtimeVersion: { type: "string", minLength: 1 },
+      gitSha: { type: "string", minLength: 1 },
+      startedAt: { type: "number" },
+      capabilities: jsonObjectSchema
+    }
+  },
+  heartbeat: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "workerId"],
+    properties: {
+      type: { const: "heartbeat" },
+      workerId: { type: "string", minLength: 1 }
+    }
+  },
+  taskResult: {
+    oneOf: [
+      {
+        type: "object",
+        additionalProperties: !1,
+        required: ["type", "operationId", "status", "value"],
+        properties: {
+          type: { const: "taskResult" },
+          operationId: { type: "string", minLength: 1 },
+          status: { const: "completed" },
+          value: jsonValueSchema
+        }
+      },
+      {
+        type: "object",
+        additionalProperties: !1,
+        required: ["type", "operationId", "status", "error"],
+        properties: {
+          type: { const: "taskResult" },
+          operationId: { type: "string", minLength: 1 },
+          status: { const: "failed" },
+          error: { type: "string" }
+        }
+      },
+      {
+        type: "object",
+        additionalProperties: !1,
+        required: ["type", "operationId", "status", "error"],
+        properties: {
+          type: { const: "taskResult" },
+          operationId: { type: "string", minLength: 1 },
+          status: { const: "cancelled" },
+          error: { type: "string" },
+          cancelled: { const: !0 }
+        }
+      }
+    ]
+  },
+  task: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "operationId", "activityName", "input"],
+    properties: {
+      type: { const: "task" },
+      operationId: { type: "string", minLength: 1 },
+      activityName: { type: "string", minLength: 1 },
+      input: jsonValueSchema,
+      attempt: { type: "number", minimum: 1 },
+      headers: stringMapSchema
+    }
+  },
+  cancel: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "operationId"],
+    properties: {
+      type: { const: "cancel" },
+      operationId: { type: "string", minLength: 1 }
+    }
+  },
+  shutdown: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type"],
+    properties: {
+      type: { const: "shutdown" }
+    }
+  },
+  registerAck: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "protocolVersion", "workerId", "queue", "activities", "concurrency"],
+    properties: {
+      type: { const: "registerAck" },
+      protocolVersion: protocolVersionSchema,
+      workerId: { type: "string", minLength: 1 },
+      queue: { type: "string", minLength: 1 },
+      activities: {
+        type: "array",
+        items: { type: "string", minLength: 1 }
+      },
+      concurrency: { type: "number", minimum: 1, maximum: 1000 }
+    }
+  },
+  registerError: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "code", "message", "supportedProtocolVersions"],
+    properties: {
+      type: { const: "registerError" },
+      code: { enum: ["invalid_registration", "unsupported_protocol_version"] },
+      message: { type: "string" },
+      supportedProtocolVersions: {
+        type: "array",
+        items: protocolVersionSchema
+      },
+      requestedProtocolVersion: { type: "number" }
+    }
+  },
+  protocolError: {
+    type: "object",
+    additionalProperties: !1,
+    required: ["type", "code", "message"],
+    properties: {
+      type: { const: "protocolError" },
+      code: {
+        enum: ["invalid_json", "invalid_message", "unknown_message_type", "registration_required"]
+      },
+      message: { type: "string" }
+    }
+  }
+}, REMOTE_WORKER_PROTOCOL_JSON_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://weft.dev/schemas/remote-worker-protocol.v1.json",
+  title: "Weft RemoteWorker Protocol v1",
+  oneOf: Object.keys(REMOTE_WORKER_MESSAGE_SCHEMAS).map((messageType) => ({
+    $ref: `#/$defs/messages/${messageType}`
+  })),
+  $defs: {
+    jsonValue: {
+      oneOf: [
+        { type: "null" },
+        { type: "boolean" },
+        { type: "number" },
+        { type: "string" },
+        { type: "array", items: { $ref: "#/$defs/jsonValue" } },
+        {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    jsonObject: jsonObjectSchema,
+    messages: REMOTE_WORKER_MESSAGE_SCHEMAS
+  }
+};

package/dist/worker/protocol-version.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Canonical RemoteWorker wire protocol version constants.
+ *
+ * Lives in a leaf module so both the parser implementation (`protocol.ts`) and
+ * the JSON Schema declarations (`protocol-schemas.ts`) can depend on the
+ * version without forming an import cycle.
+ *
+ * @module worker/protocol-version
+ */
+/**
+ * Current RemoteWorker wire protocol version.
+ *
+ * **Version 2** (Phase 4 of the workflow-builder refactor) bumps the semantics
+ * of the `activities: string[]` field in the register message. Each entry is
+ * now a qualified `${workflowType}.${activityName}` name rather than a bare
+ * activity name, so the server can dispatch the correct workflow's activity
+ * implementation when the same activity key is used by multiple workflows. The
+ * wire shape did not change; only the meaning of the strings.
+ *
+ * @example
+ * ```ts
+ * import { REMOTE_WORKER_PROTOCOL_VERSION } from '@lostgradient/weft/worker-protocol';
+ *
+ * const registration = { type: 'register', protocolVersion: REMOTE_WORKER_PROTOCOL_VERSION };
+ * ```
+ */
+export declare const REMOTE_WORKER_PROTOCOL_VERSION = 2;
+/**
+ * Lowest RemoteWorker protocol version accepted by this package.
+ *
+ * @example
+ * ```ts
+ * import { REMOTE_WORKER_MIN_PROTOCOL_VERSION } from '@lostgradient/weft/worker-protocol';
+ *
+ * const supportsCurrentVersion = REMOTE_WORKER_MIN_PROTOCOL_VERSION === 2;
+ * ```
+ */
+export declare const REMOTE_WORKER_MIN_PROTOCOL_VERSION = 2;
+/**
+ * Highest RemoteWorker protocol version accepted by this package.
+ *
+ * @example
+ * ```ts
+ * import { REMOTE_WORKER_MAX_PROTOCOL_VERSION } from '@lostgradient/weft/worker-protocol';
+ *
+ * const canUseRequestedVersion = 2 <= REMOTE_WORKER_MAX_PROTOCOL_VERSION;
+ * ```
+ */
+export declare const REMOTE_WORKER_MAX_PROTOCOL_VERSION = 2;
+/**
+ * Explicit supported RemoteWorker protocol versions.
+ *
+ * @example
+ * ```ts
+ * import { REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS } from '@lostgradient/weft/worker-protocol';
+ *
+ * const supported = REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS.includes(2);
+ * ```
+ */
+export declare const REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS: readonly [2];
+/**
+ * RemoteWorker protocol version accepted by this package.
+ *
+ * @example
+ * ```ts
+ * import type { RemoteWorkerProtocolVersion } from '@lostgradient/weft/worker-protocol';
+ *
+ * const version: RemoteWorkerProtocolVersion = 2;
+ * ```
+ */
+export type RemoteWorkerProtocolVersion = (typeof REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS)[number];

package/dist/worker/protocol-version.js

@@ -0,0 +1 @@
+export const REMOTE_WORKER_PROTOCOL_VERSION = 2, REMOTE_WORKER_MIN_PROTOCOL_VERSION = 2, REMOTE_WORKER_MAX_PROTOCOL_VERSION = 2, REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS = [REMOTE_WORKER_PROTOCOL_VERSION];

package/dist/worker/protocol.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Canonical RemoteWorker WebSocket protocol contract.
+ *
+ * This module owns the parser trust boundary: every guard below maps to one
+ * documented schema field. Wire-shape types live in `./protocol-messages.ts`,
+ * JSON Schema documents in `./protocol-schemas.ts`, and internal helpers in
+ * `./protocol-internals.ts`. All are re-exported so the public surface
+ * `@lostgradient/weft/worker-protocol` stays a single import path.
+ *
+ * @module worker/protocol
+ */
+import type { RemoteWorkerProtocolFailure, RemoteWorkerProtocolParseResult } from './protocol-internals.ts';
+import { isRemoteWorkerJsonValue } from './protocol-internals.ts';
+import type { CancelMessage, CancelledTaskResultMessage, CompletedTaskResultMessage, FailedTaskResultMessage, HeartbeatMessage, ProtocolErrorMessage, RegisterAckMessage, RegisterErrorMessage, RegisterMessage, RemoteWorkerCapabilities, RemoteWorkerJsonValue, ShutdownMessage, TaskMessage } from './protocol-messages.ts';
+import { REMOTE_WORKER_MESSAGE_SCHEMAS, REMOTE_WORKER_PROTOCOL_JSON_SCHEMA } from './protocol-schemas.ts';
+import type { RemoteWorkerProtocolVersion } from './protocol-version.ts';
+import { REMOTE_WORKER_MAX_PROTOCOL_VERSION, REMOTE_WORKER_MIN_PROTOCOL_VERSION, REMOTE_WORKER_PROTOCOL_VERSION, REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS } from './protocol-version.ts';
+export { REMOTE_WORKER_MAX_PROTOCOL_VERSION, REMOTE_WORKER_MESSAGE_SCHEMAS, REMOTE_WORKER_MIN_PROTOCOL_VERSION, REMOTE_WORKER_PROTOCOL_JSON_SCHEMA, REMOTE_WORKER_PROTOCOL_VERSION, REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS, isRemoteWorkerJsonValue, };
+export type { CancelMessage, CancelledTaskResultMessage, CompletedTaskResultMessage, FailedTaskResultMessage, HeartbeatMessage, ProtocolErrorMessage, RegisterAckMessage, RegisterErrorMessage, RegisterMessage, RemoteWorkerCapabilities, RemoteWorkerJsonValue, RemoteWorkerProtocolFailure, RemoteWorkerProtocolParseResult, RemoteWorkerProtocolVersion, ShutdownMessage, TaskMessage, };
+/**
+ * Worker-to-server task result message. Discriminated union over `status`.
+ *
+ * @example
+ * ```ts
+ * import type { TaskResultMessage } from '@lostgradient/weft/worker-protocol';
+ *
+ * const message: TaskResultMessage = {
+ *   type: 'taskResult', operationId: 'op-1', status: 'completed', value: { ok: true },
+ * };
+ * ```
+ */
+export type TaskResultMessage = CompletedTaskResultMessage | FailedTaskResultMessage | CancelledTaskResultMessage;
+/**
+ * Messages accepted from a worker stream client.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerToServerMessage } from '@lostgradient/weft/worker-protocol';
+ *
+ * const message: WorkerToServerMessage = { type: 'heartbeat', workerId: 'worker-1' };
+ * ```
+ */
+export type WorkerToServerMessage = RegisterMessage | HeartbeatMessage | TaskResultMessage;
+/**
+ * Messages the server may send to a worker stream client.
+ *
+ * @example
+ * ```ts
+ * import type { ServerToWorkerMessage } from '@lostgradient/weft/worker-protocol';
+ *
+ * const message: ServerToWorkerMessage = { type: 'shutdown' };
+ * ```
+ */
+export type ServerToWorkerMessage = RegisterAckMessage | RegisterErrorMessage | ProtocolErrorMessage | TaskMessage | CancelMessage | ShutdownMessage;
+/**
+ * Parse and validate a worker-to-server protocol message.
+ * @example
+ * ```ts
+ * import { parseWorkerToServerMessage } from '@lostgradient/weft/worker-protocol';
+ * const result = parseWorkerToServerMessage({ type: 'heartbeat', workerId: 'worker-1' });
+ * ```
+ */
+export declare function parseWorkerToServerMessage(value: unknown): RemoteWorkerProtocolParseResult<WorkerToServerMessage>;
+/**
+ * Parse and validate a server-to-worker protocol message.
+ * @example
+ * ```ts
+ * import { parseServerToWorkerMessage } from '@lostgradient/weft/worker-protocol';
+ * const result = parseServerToWorkerMessage({ type: 'shutdown' });
+ * ```
+ */
+export declare function parseServerToWorkerMessage(value: unknown): RemoteWorkerProtocolParseResult<ServerToWorkerMessage>;

package/dist/worker/protocol.js

@@ -0,0 +1,2 @@
+// @bun
+var h=Object.defineProperty;var q=(z)=>z;function T(z,B){this[z]=q.bind(null,B)}var a=(z,B)=>{for(var D in B)h(z,D,{get:B[D],enumerable:!0,configurable:!0,set:T.bind(B,D)})};var o=(z,B)=>()=>(z&&(B=z(z=0)),B);function F(z){return z!==null&&typeof z==="object"&&!Array.isArray(z)}function x(z){if(z===null||typeof z==="string"||typeof z==="boolean"||typeof z==="number"&&Number.isFinite(z))return!0;if(Array.isArray(z))return z.every(x);if(!F(z))return!1;return Object.values(z).every(x)}function U(z){return typeof z==="string"&&z.length>0}function L(z){return Array.isArray(z)&&z.every(U)}function K(z){if(!F(z))return!1;return Object.values(z).every((B)=>typeof B==="string")}function f(z){if(!F(z))return!1;return Object.values(z).every(x)}function G(z){return typeof z==="number"&&Number.isFinite(z)}function Q(z,B,D){return{ok:!1,error:{code:z,message:B,...D!==void 0?{requestedProtocolVersion:D}:{}}}}function A(z,B,D){let X={};for(let[Y,$,b,C]of D){let H=B[Y];if(H===void 0){if($)return{ok:!1,error:Q(z,C)};continue}if(!b(H))return{ok:!1,error:Q(z,C)};X[Y]=H}return{ok:!0,values:X}}var Z=2,W=2,k=2,I=[2];var j={$ref:"#/$defs/jsonValue"},w={type:"object",additionalProperties:j},M={type:"object",additionalProperties:{type:"string"}},J={const:Z},N={register:{type:"object",additionalProperties:!1,required:["type","protocolVersion","workerId","activities"],properties:{type:{const:"register"},protocolVersion:J,workerId:{type:"string",minLength:1},activities:{type:"array",items:{type:"string",minLength:1}},concurrency:{type:"number",minimum:1,maximum:1000},queue:{type:"string",minLength:1},deploymentName:{type:"string",minLength:1},buildId:{type:"string",minLength:1},runtimeVersion:{type:"string",minLength:1},gitSha:{type:"string",minLength:1},startedAt:{type:"number"},capabilities:w}},heartbeat:{type:"object",additionalProperties:!1,required:["type","workerId"],properties:{type:{const:"heartbeat"},workerId:{type:"string",minLength:1}}},taskResult:{oneOf:[{type:"object",additionalProperties:!1,required:["type","operationId","status","value"],properties:{type:{const:"taskResult"},operationId:{type:"string",minLength:1},status:{const:"completed"},value:j}},{type:"object",additionalProperties:!1,required:["type","operationId","status","error"],properties:{type:{const:"taskResult"},operationId:{type:"string",minLength:1},status:{const:"failed"},error:{type:"string"}}},{type:"object",additionalProperties:!1,required:["type","operationId","status","error"],properties:{type:{const:"taskResult"},operationId:{type:"string",minLength:1},status:{const:"cancelled"},error:{type:"string"},cancelled:{const:!0}}}]},task:{type:"object",additionalProperties:!1,required:["type","operationId","activityName","input"],properties:{type:{const:"task"},operationId:{type:"string",minLength:1},activityName:{type:"string",minLength:1},input:j,attempt:{type:"number",minimum:1},headers:M}},cancel:{type:"object",additionalProperties:!1,required:["type","operationId"],properties:{type:{const:"cancel"},operationId:{type:"string",minLength:1}}},shutdown:{type:"object",additionalProperties:!1,required:["type"],properties:{type:{const:"shutdown"}}},registerAck:{type:"object",additionalProperties:!1,required:["type","protocolVersion","workerId","queue","activities","concurrency"],properties:{type:{const:"registerAck"},protocolVersion:J,workerId:{type:"string",minLength:1},queue:{type:"string",minLength:1},activities:{type:"array",items:{type:"string",minLength:1}},concurrency:{type:"number",minimum:1,maximum:1000}}},registerError:{type:"object",additionalProperties:!1,required:["type","code","message","supportedProtocolVersions"],properties:{type:{const:"registerError"},code:{enum:["invalid_registration","unsupported_protocol_version"]},message:{type:"string"},supportedProtocolVersions:{type:"array",items:J},requestedProtocolVersion:{type:"number"}}},protocolError:{type:"object",additionalProperties:!1,required:["type","code","message"],properties:{type:{const:"protocolError"},code:{enum:["invalid_json","invalid_message","unknown_message_type","registration_required"]},message:{type:"string"}}}},P={$schema:"https://json-schema.org/draft/2020-12/schema",$id:"https://weft.dev/schemas/remote-worker-protocol.v1.json",title:"Weft RemoteWorker Protocol v1",oneOf:Object.keys(N).map((z)=>({$ref:`#/$defs/messages/${z}`})),$defs:{jsonValue:{oneOf:[{type:"null"},{type:"boolean"},{type:"number"},{type:"string"},{type:"array",items:{$ref:"#/$defs/jsonValue"}},{type:"object",additionalProperties:{$ref:"#/$defs/jsonValue"}}]},jsonObject:w,messages:N}};var g=new Set(["register","heartbeat","taskResult"]),_=new Set(["registerAck","registerError","protocolError","task","cancel","shutdown"]);function y(z){if(z===Z)return{ok:!0,message:z};let B=G(z)?z:void 0;return Q("unsupported_protocol_version",`Unsupported RemoteWorker protocol version: ${String(z)}`,B)}var S=[["workerId",!0,U,"register.workerId must be a non-empty string"],["activities",!0,L,"register.activities must be an array of non-empty strings"],["concurrency",!1,G,"register.concurrency must be a finite number"],["queue",!1,U,"register.queue must be a non-empty string"],["deploymentName",!1,U,"register.deploymentName must be a non-empty string when present"],["buildId",!1,U,"register.buildId must be a non-empty string when present"],["runtimeVersion",!1,U,"register.runtimeVersion must be a non-empty string when present"],["gitSha",!1,U,"register.gitSha must be a non-empty string when present"],["startedAt",!1,G,"register.startedAt must be a finite number when present"],["capabilities",!1,f,"register.capabilities must be a JSON object when present"]];function E(z){let B=y(z.protocolVersion);if(!B.ok)return B;let D=A("invalid_registration",z,S);if(!D.ok)return D.error;return{ok:!0,message:{type:"register",protocolVersion:B.message,...D.values}}}function V(z){let B=z.workerId;if(!U(B))return Q("invalid_message","heartbeat.workerId must be a non-empty string");return{ok:!0,message:{type:"heartbeat",workerId:B}}}function O(z,B){let D=B.value;if(!x(D))return Q("invalid_message","completed taskResult.value must be valid JSON");return{ok:!0,message:{type:"taskResult",operationId:z,status:"completed",value:D}}}function m(z,B){let D=B.error;if(typeof D!=="string")return Q("invalid_message","failed taskResult.error must be a string");return{ok:!0,message:{type:"taskResult",operationId:z,status:"failed",error:D}}}function R(z,B){let D=B.error;if(typeof D!=="string")return Q("invalid_message","cancelled taskResult.error must be a string");let X=B.cancelled;if(X!==void 0&&X!==!0)return Q("invalid_message","taskResult.cancelled must be true when present");return{ok:!0,message:{type:"taskResult",operationId:z,status:"cancelled",error:D,...X===!0?{cancelled:X}:{}}}}var p={completed:O,failed:m,cancelled:R};function n(z){return z==="completed"||z==="failed"||z==="cancelled"}function i(z){let B=z.operationId;if(!U(B))return Q("invalid_message","taskResult.operationId must be a non-empty string");let D=z.status;if(!n(D))return Q("invalid_message","taskResult.status must be completed, failed, or cancelled");return p[D](B,z)}var v=[["operationId",!0,U,"task.operationId must be a non-empty string"],["activityName",!0,U,"task.activityName must be a non-empty string"],["input",!0,x,"task.input must be valid JSON"],["attempt",!1,G,"task.attempt must be a finite number"],["headers",!1,K,"task.headers must be a string map"]];function t(z){let B=A("invalid_message",z,v);if(!B.ok)return B.error;return{ok:!0,message:{type:"task",...B.values}}}function d(z){let B=z.operationId;if(!U(B))return Q("invalid_message","cancel.operationId must be a non-empty string");return{ok:!0,message:{type:"cancel",operationId:B}}}function s(){return{ok:!0,message:{type:"shutdown"}}}function u(z){let B=z.protocolVersion;if(B!==Z)return Q("invalid_message",`registerAck.protocolVersion must be ${String(Z)}`);let{workerId:D,queue:X,activities:Y,concurrency:$}=z;if(!U(D))return Q("invalid_message","registerAck.workerId must be a non-empty string");if(!U(X))return Q("invalid_message","registerAck.queue must be a non-empty string");if(!L(Y))return Q("invalid_message","registerAck.activities must be a string array");if(typeof $!=="number"||!Number.isFinite($))return Q("invalid_message","registerAck.concurrency must be a finite number");return{ok:!0,message:{type:"registerAck",protocolVersion:B,workerId:D,queue:X,activities:Y,concurrency:$}}}function c(z){let{code:B,message:D,supportedProtocolVersions:X,requestedProtocolVersion:Y}=z;if(B!=="invalid_registration"&&B!=="unsupported_protocol_version")return Q("invalid_message","registerError.code is not recognized");if(typeof D!=="string")return Q("invalid_message","registerError.message must be a string");if(!Array.isArray(X)||!X.every((b)=>b===Z))return Q("invalid_message","registerError.supportedProtocolVersions is invalid");if(Y!==void 0&&!G(Y))return Q("invalid_message","registerError.requestedProtocolVersion must be a finite number");return{ok:!0,message:{type:"registerError",code:B,message:D,supportedProtocolVersions:X,...Y!==void 0?{requestedProtocolVersion:Y}:{}}}}function l(z){let{code:B,message:D}=z;if(B!=="invalid_json"&&B!=="invalid_message"&&B!=="unknown_message_type"&&B!=="registration_required")return Q("invalid_message","protocolError.code is not recognized");if(typeof D!=="string")return Q("invalid_message","protocolError.message must be a string");return{ok:!0,message:{type:"protocolError",code:B,message:D}}}function Yz(z){if(!F(z))return Q("invalid_message","Worker protocol message must be a JSON object");let B=z.type;if(typeof B!=="string")return Q("invalid_message","Worker protocol message.type must be a string");if(!g.has(B))return Q("unknown_message_type",`Unknown worker message type: ${B}`);switch(B){case"register":return E(z);case"heartbeat":return V(z);case"taskResult":return i(z);default:return Q("unknown_message_type",`Unknown worker message type: ${B}`)}}function Zz(z){if(!F(z))return Q("invalid_message","Server protocol message must be a JSON object");let B=z.type;if(typeof B!=="string")return Q("invalid_message","Server protocol message.type must be a string");if(!_.has(B))return Q("unknown_message_type",`Unknown server message type: ${B}`);switch(B){case"registerAck":return u(z);case"registerError":return c(z);case"protocolError":return l(z);case"task":return t(z);case"cancel":return d(z);case"shutdown":return s();default:return Q("unknown_message_type",`Unknown server message type: ${B}`)}}export{Yz as parseWorkerToServerMessage,Zz as parseServerToWorkerMessage,x as isRemoteWorkerJsonValue,I as REMOTE_WORKER_SUPPORTED_PROTOCOL_VERSIONS,Z as REMOTE_WORKER_PROTOCOL_VERSION,P as REMOTE_WORKER_PROTOCOL_JSON_SCHEMA,W as REMOTE_WORKER_MIN_PROTOCOL_VERSION,N as REMOTE_WORKER_MESSAGE_SCHEMAS,k as REMOTE_WORKER_MAX_PROTOCOL_VERSION};

package/dist/worker/registry/fair-share.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Minimal snapshot of per-worker state needed to compute a fair-share score.
+ * Callers construct this from live registry data in a single synchronous pass
+ * before scoring, so the comparison is consistent across the full candidate set.
+ */
+export type WorkerScoreSnapshot = {
+    /** Worker identifier — used for stable tiebreaking. */
+    id: string;
+    /** Number of in-flight tasks this worker is currently handling overall. */
+    inFlight: number;
+    /** Number of in-flight tasks for the specific fair-share partition key. */
+    keyLoad: number;
+};
+/**
+ * Computed score for a single candidate worker.
+ * Lower `keyLoad` wins; `inFlight` and `id` break ties deterministically.
+ */
+export type WorkerScore = {
+    snapshot: WorkerScoreSnapshot;
+    keyLoad: number;
+    inFlight: number;
+    id: string;
+};
+/**
+ * Produce a {@link WorkerScore} for `snapshot`.
+ *
+ * The score captures the fair-share key load, overall in-flight count, and
+ * worker id so `compareScores` can rank candidates without accessing live
+ * state a second time.
+ *
+ * @example
+ * ```ts
+ * import { scoreWorker } from './fair-share.ts';
+ * const score = scoreWorker({ id: 'w1', inFlight: 3, keyLoad: 1 });
+ * console.log(score.keyLoad); // 1
+ * ```
+ */
+export declare function scoreWorker(snapshot: WorkerScoreSnapshot): WorkerScore;
+/**
+ * Compare two worker scores for fair-share selection.
+ *
+ * Ordering (ascending — lower is better):
+ * 1. `keyLoad` — prefer the worker carrying fewer tasks for this partition key.
+ * 2. `inFlight` — break ties by overall load.
+ * 3. `id` — lexicographic tiebreak for determinism across runs.
+ *
+ * Returns a negative number when `a` is preferred, positive when `b` is
+ * preferred, and `0` when they are equivalent (not expected in practice
+ * because worker ids are unique).
+ *
+ * @example
+ * ```ts
+ * import { compareScores, scoreWorker } from './fair-share.ts';
+ * const a = scoreWorker({ id: 'w1', inFlight: 2, keyLoad: 0 });
+ * const b = scoreWorker({ id: 'w2', inFlight: 1, keyLoad: 1 });
+ * console.log(compareScores(a, b) < 0); // true — a has lower keyLoad
+ * ```
+ */
+export declare function compareScores(a: WorkerScore, b: WorkerScore): number;

package/dist/worker/registry/fair-share.js

@@ -0,0 +1,15 @@
+export function scoreWorker(snapshot) {
+  return {
+    snapshot,
+    keyLoad: snapshot.keyLoad,
+    inFlight: snapshot.inFlight,
+    id: snapshot.id
+  };
+}
+export function compareScores(a, b) {
+  if (a.keyLoad !== b.keyLoad)
+    return a.keyLoad - b.keyLoad;
+  if (a.inFlight !== b.inFlight)
+    return a.inFlight - b.inFlight;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}

package/dist/worker/registry/routing.d.ts

@@ -0,0 +1,17 @@
+import type { WorkerInfo } from './types.ts';
+/**
+ * Return `true` when `worker` is eligible for the given `activityName` and
+ * optional `queue` constraint, and has spare capacity.
+ *
+ * This is the single canonical gate every routing policy relies on — it
+ * extracts the capacity+queue+activity filter out of `findWorker` so the loop
+ * body reads as a simple linear scan.
+ */
+export declare function matchesWorkerCapabilities(worker: WorkerInfo, activityName: string, queue: string | undefined): boolean;
+/**
+ * Pick the worker with the lowest in-flight count. Ties broken by stable
+ * worker id ordering so the choice is deterministic across runs.
+ *
+ * `eligible` must be non-empty — the caller is responsible for this precondition.
+ */
+export declare function pickLeastLoaded(eligible: WorkerInfo[]): WorkerInfo;

package/dist/worker/registry/routing.js

@@ -0,0 +1,16 @@
+export function matchesWorkerCapabilities(worker, activityName, queue) {
+  if (queue !== void 0 && worker.queue !== queue)
+    return !1;
+  if (!worker.activities.includes(activityName))
+    return !1;
+  return worker.inFlight < worker.concurrency;
+}
+export function pickLeastLoaded(eligible) {
+  let best = eligible[0];
+  for (let index = 1;index < eligible.length; index += 1) {
+    const candidate = eligible[index];
+    if (candidate.inFlight < best.inFlight || candidate.inFlight === best.inFlight && candidate.id < best.id)
+      best = candidate;
+  }
+  return best;
+}

package/dist/worker/registry/summary.d.ts

@@ -0,0 +1,87 @@
+import type { RemoteWorkerCapabilities } from '../protocol.ts';
+import type { WorkerHealth, WorkerSummary } from './types.ts';
+/**
+ * Minimal read-only snapshot of a single worker's state, as held by the
+ * registry. The projection functions below operate on this shape so they
+ * remain pure and independently testable without a live registry instance.
+ */
+export type WorkerSnapshot = {
+    id: string;
+    queue: string;
+    activities: readonly string[];
+    concurrency: number;
+    inFlight: number;
+    connectedAt: number;
+    lastHeartbeat: number;
+    startedAt: number;
+    capabilities: RemoteWorkerCapabilities;
+    health: WorkerHealth;
+    deploymentName?: string | undefined;
+    buildId?: string | undefined;
+    runtimeVersion?: string | undefined;
+    gitSha?: string | undefined;
+};
+/**
+ * Project a single worker snapshot into a {@link WorkerSummary}.
+ *
+ * `now` should be the same timestamp used for all workers in a single response
+ * so heartbeat ages are consistent across the payload.
+ */
+export declare function projectWorkerSummary(snapshot: WorkerSnapshot, now: number): WorkerSummary;
+/**
+ * Project an array of worker snapshots into sorted {@link WorkerSummary} entries.
+ *
+ * Output is sorted ascending by worker id so the list is stable across calls.
+ */
+export declare function projectWorkerSummaries(snapshots: WorkerSnapshot[], now: number): WorkerSummary[];
+/**
+ * Deployment-level summary for operator views. Workers without deployment
+ * metadata are grouped under `null` identity fields.
+ */
+export type WorkerDeploymentSummary = {
+    deploymentName: string | null;
+    buildId: string | null;
+    runtimeVersion: string | null;
+    gitSha: string | null;
+    health: WorkerHealth;
+    workers: number;
+    activeWorkers: number;
+    drainingWorkers: number;
+    drainedWorkers: number;
+    inFlight: number;
+    oldestStartedAt: number | null;
+};
+type WorkerDeploymentIdentity = {
+    deploymentName?: string | null | undefined;
+    buildId?: string | null | undefined;
+    runtimeVersion?: string | null | undefined;
+    gitSha?: string | null | undefined;
+};
+/** Stable composite key for grouping workers by deployment identity. */
+export declare function deploymentIdentityKey(identity: WorkerDeploymentIdentity): string;
+/** Count workers per health state. */
+export declare function countWorkerHealth(healthValues: WorkerHealth[]): Record<WorkerHealth, number>;
+/**
+ * Compute the aggregate health of a deployment from its individual worker health values.
+ *
+ * `drainActive` should be `true` when the deployment-level drain marker is set
+ * and there are no connected workers, so the result reports `'drained'` rather
+ * than `'active'` for a pre-drained empty deployment.
+ */
+export declare function deploymentHealth(healthValues: WorkerHealth[], drainActive?: boolean): WorkerHealth;
+/** Comparator for sorting deployment summaries by their identity key. */
+export declare function compareDeploymentSummaries(left: WorkerDeploymentSummary, right: WorkerDeploymentSummary): number;
+/**
+ * Project a group of worker snapshots that share the same deployment identity
+ * into a single {@link WorkerDeploymentSummary}.
+ */
+export declare function projectDeploymentSummary(workers: WorkerSnapshot[], drainActive: boolean): WorkerDeploymentSummary;
+/**
+ * Project a flat list of worker snapshots into grouped, sorted
+ * {@link WorkerDeploymentSummary} entries.
+ *
+ * `isDrainActive` receives the deployment name and returns whether a
+ * deployment-level drain marker is set for it.
+ */
+export declare function projectDeploymentSummaries(snapshots: WorkerSnapshot[], isDrainActive: (deploymentName: string) => boolean): WorkerDeploymentSummary[];
+export {};

package/dist/worker/registry/summary.js

@@ -0,0 +1,81 @@
+export function projectWorkerSummary(snapshot, now) {
+  const { inFlight, concurrency } = snapshot;
+  return {
+    id: snapshot.id,
+    queue: snapshot.queue,
+    activities: [...snapshot.activities],
+    concurrency,
+    inFlight,
+    availableCapacity: Math.max(0, concurrency - inFlight),
+    connectedAt: snapshot.connectedAt,
+    lastHeartbeatAt: snapshot.lastHeartbeat,
+    heartbeatAgeMs: now - snapshot.lastHeartbeat,
+    startedAt: snapshot.startedAt,
+    capabilities: { ...snapshot.capabilities },
+    health: snapshot.health,
+    ...snapshot.deploymentName !== void 0 ? { deploymentName: snapshot.deploymentName } : {},
+    ...snapshot.buildId !== void 0 ? { buildId: snapshot.buildId } : {},
+    ...snapshot.runtimeVersion !== void 0 ? { runtimeVersion: snapshot.runtimeVersion } : {},
+    ...snapshot.gitSha !== void 0 ? { gitSha: snapshot.gitSha } : {}
+  };
+}
+export function projectWorkerSummaries(snapshots, now) {
+  return snapshots.map((snapshot) => projectWorkerSummary(snapshot, now)).toSorted((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+export function deploymentIdentityKey(identity) {
+  return [
+    identity.deploymentName ?? "",
+    identity.buildId ?? "",
+    identity.runtimeVersion ?? "",
+    identity.gitSha ?? ""
+  ].join("\x1F");
+}
+export function countWorkerHealth(healthValues) {
+  return healthValues.reduce((counts, health) => {
+    counts[health] += 1;
+    return counts;
+  }, { active: 0, draining: 0, drained: 0 });
+}
+export function deploymentHealth(healthValues, drainActive = !1) {
+  if (healthValues.includes("draining"))
+    return "draining";
+  if (healthValues.length === 0)
+    return drainActive ? "drained" : "active";
+  if (healthValues.every((health) => health === "drained"))
+    return "drained";
+  return "active";
+}
+export function compareDeploymentSummaries(left, right) {
+  const leftKey = deploymentIdentityKey(left), rightKey = deploymentIdentityKey(right);
+  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+}
+export function projectDeploymentSummary(workers, drainActive) {
+  const [first] = workers, healthValues = workers.map((w) => w.health), healthCounts = countWorkerHealth(healthValues);
+  return {
+    deploymentName: first?.deploymentName ?? null,
+    buildId: first?.buildId ?? null,
+    runtimeVersion: first?.runtimeVersion ?? null,
+    gitSha: first?.gitSha ?? null,
+    health: deploymentHealth(healthValues, drainActive),
+    workers: workers.length,
+    activeWorkers: healthCounts.active,
+    drainingWorkers: healthCounts.draining,
+    drainedWorkers: healthCounts.drained,
+    inFlight: workers.reduce((total, w) => total + w.inFlight, 0),
+    oldestStartedAt: workers.length === 0 ? null : Math.min(...workers.map((w) => w.startedAt))
+  };
+}
+export function projectDeploymentSummaries(snapshots, isDrainActive) {
+  const groups = new Map;
+  for (const snapshot of snapshots) {
+    const key = deploymentIdentityKey(snapshot), group = groups.get(key);
+    if (group === void 0)
+      groups.set(key, [snapshot]);
+    else
+      group.push(snapshot);
+  }
+  return [...groups.values()].map((group) => {
+    const deploymentName = group[0]?.deploymentName, drainActive = deploymentName !== void 0 ? isDrainActive(deploymentName) : !1;
+    return projectDeploymentSummary(group, drainActive);
+  }).toSorted(compareDeploymentSummaries);
+}