@lostgradient/weft 0.18.0 → 0.20.0

package/dist/worker/index.js

@@ -6,7 +6,9 @@ import {
 } from "./execute-with-interceptors.js";
 import { HeartbeatManager } from "./heartbeat.js";
 import {
-  buildRegisterMessage
+  assertManifestMatchesWorkflows,
+  buildRegisterMessage,
+  snapshotWorkflows
 } from "./options.js";
 import {
   parseServerToWorkerMessage
@@ -25,10 +27,29 @@ function createWorkerWebSocket(url, headers) {
     return new WebSocket(url);
   return new WebSocket(url, { headers });
 }
+const WORKER_STREAM_PATH_RE = /^(?:\/api)?\/v1\/tasks\/([^/]+)\/stream$/, QUEUE_NAME_RE = /^[\w-]+$/;
+function assertValidQueueName(queue) {
+  if (!QUEUE_NAME_RE.test(queue))
+    throw Error(`RemoteWorker queue "${queue}" is not a valid queue name \u2014 the server's worker-stream ` + "route only accepts word characters and hyphens ([\\w-]+).");
+}
+function resolveWorkerConnectUrl(serverUrl, explicitQueue) {
+  const parsed = new URL(serverUrl), match = WORKER_STREAM_PATH_RE.exec(parsed.pathname);
+  if (match !== null) {
+    const embeddedQueue = decodeURIComponent(match[1]);
+    assertValidQueueName(embeddedQueue);
+    if (explicitQueue !== void 0 && explicitQueue !== embeddedQueue)
+      throw Error(`RemoteWorker serverUrl "${serverUrl}" already encodes queue "${embeddedQueue}", which conflicts with the "queue" option "${explicitQueue}". Pass either a bare server origin with the "queue" option, or a complete worker-stream serverUrl with no ` + '"queue" option \u2014 not both.');
+    return { url: serverUrl, queue: embeddedQueue };
+  }
+  const queue = explicitQueue ?? DEFAULT_QUEUE;
+  assertValidQueueName(queue);
+  return { url: new URL(`/v1/tasks/${encodeURIComponent(queue)}/stream`, serverUrl).toString(), queue };
+}
 
 export class RemoteWorker {
   #options;
   #activityTable;
+  #connectUrl;
   #ws;
   #inFlight;
   #abortController;
@@ -42,11 +63,16 @@ export class RemoteWorker {
   #workerId;
   constructor(options) {
     this.#activityTable = resolveActivityTable(options);
+    if (options.manifest !== void 0)
+      assertManifestMatchesWorkflows(options.manifest, options.workflows);
     this.#workerId = options.workerId ?? crypto.randomUUID();
+    const resolvedConnection = resolveWorkerConnectUrl(options.serverUrl, options.queue);
+    this.#connectUrl = resolvedConnection.url;
     this.#options = {
       ...options,
+      workflows: snapshotWorkflows(options.workflows),
       concurrency: options.concurrency ?? DEFAULT_CONCURRENCY,
-      queue: options.queue ?? DEFAULT_QUEUE,
+      queue: resolvedConnection.queue,
       workerId: this.#workerId
     };
     this.#ws = null;
@@ -70,11 +96,11 @@ export class RemoteWorker {
       return;
     this.#teardownActiveConnection("Superseded by a new connect() call");
     return new Promise((resolve, reject) => {
-      const ws = createWorkerWebSocket(this.#options.serverUrl, this.#options.headers);
+      const ws = createWorkerWebSocket(this.#connectUrl, this.#options.headers);
       this.#ws = ws;
       this.#pendingRegistration = { resolve, reject };
       ws.addEventListener("open", () => {
-        this.#sendMessage(buildRegisterMessage(this.#workerId, Object.keys(this.#activityTable), this.#options));
+        this.#sendMessage(buildRegisterMessage(this.#workerId, this.#options));
       }, { signal: this.#abortController.signal });
       ws.addEventListener("message", (event) => {
         this.#handleMessage(event);

package/dist/worker/manifest/canonical-json.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Deterministic canonical JSON serialization for arbitrary values.
+ *
+ * Object keys are sorted at every depth so two values that differ only in
+ * key order serialize identically — the property any hash-then-compare
+ * scheme (manifest digests, contract hashes) depends on.
+ *
+ * @module worker/manifest/canonical-json
+ */
+/**
+ * Serialize an arbitrary value with object keys sorted at every depth.
+ *
+ * Accepts `unknown` rather than a `JSONValue` bound because callers such as
+ * a JSON-Schema converter's output are structurally JSON-safe by
+ * construction (trusted, already-serialized-once data) without necessarily
+ * satisfying that type at the TypeScript level. `undefined` values inside
+ * objects are dropped, matching `JSON.stringify`'s own behavior, since this
+ * function is a drop-in canonical replacement for it.
+ */
+export declare function canonicalJsonStringify(value: unknown): string;

package/dist/worker/manifest/canonical-json.js

@@ -0,0 +1,13 @@
+function sortedEntryKeys(record) {
+  return Object.keys(record).toSorted();
+}
+export function canonicalJsonStringify(value) {
+  if (value === void 0)
+    return "null";
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map((entry) => canonicalJsonStringify(entry)).join(",")}]`;
+  const record = value;
+  return `{${sortedEntryKeys(record).filter((key) => record[key] !== void 0).map((key) => `${JSON.stringify(key)}:${canonicalJsonStringify(record[key])}`).join(",")}}`;
+}

package/dist/worker/manifest/capabilities.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bounded validation for the open-ended `capabilities` record on a worker
+ * manifest.
+ *
+ * `isJSONValue()` already rejects the values JSON cannot round-trip — cycles,
+ * `-0`, exotic prototypes — but it is deliberately unbounded in depth, key
+ * count, and string size. A manifest arrives from a worker we do not trust, so
+ * the depth and size ceilings have to be imposed here rather than delegated.
+ *
+ * @module worker/manifest/capabilities
+ */
+import { type JSONValue } from '../../core/json.ts';
+import type { ManifestValidationFailure } from './failure.ts';
+/**
+ * Validate the manifest `capabilities` record from untrusted input.
+ *
+ * Capabilities are descriptive only. Nothing here consults their meaning —
+ * a capability never grants authorization or affects routing without an
+ * explicit host policy — so this checks shape and size and nothing else.
+ */
+export declare function parseManifestCapabilities(value: unknown, path: string): {
+    ok: true;
+    capabilities: Readonly<Record<string, JSONValue>>;
+} | ManifestValidationFailure;

package/dist/worker/manifest/capabilities.js

@@ -0,0 +1,74 @@
+import { isJSONValue } from "../../core/json.js";
+import { manifestFailure } from "./failure.js";
+import { isRecord } from "./is-record.js";
+import {
+  MAX_MANIFEST_CAPABILITY_COUNT,
+  MAX_MANIFEST_CAPABILITY_DEPTH,
+  MAX_MANIFEST_CAPABILITY_STRING_BYTES
+} from "./limits.js";
+import { utf8ByteLength } from "./utf8.js";
+function exceedsCapabilityDepth(value, depth, limit) {
+  if (depth > limit)
+    return !0;
+  if (Array.isArray(value))
+    return value.some((entry) => exceedsCapabilityDepth(entry, depth + 1, limit));
+  if (value !== null && typeof value === "object")
+    return Object.values(value).some((entry) => exceedsCapabilityDepth(entry, depth + 1, limit));
+  return !1;
+}
+function checkCapabilityValue(value, path) {
+  if (typeof value === "string")
+    return checkCapabilityString(value, path);
+  if (Array.isArray(value))
+    return checkCapabilityArray(value, path);
+  if (value !== null && typeof value === "object")
+    return checkCapabilityObject(value, path);
+  return;
+}
+function checkCapabilityString(value, path) {
+  const bytes = utf8ByteLength(value);
+  if (bytes > MAX_MANIFEST_CAPABILITY_STRING_BYTES)
+    return manifestFailure("capability_string_too_long", `is ${bytes} bytes, exceeding the maximum capability string size of ${MAX_MANIFEST_CAPABILITY_STRING_BYTES}`, path);
+  return;
+}
+function checkCapabilityArray(value, path) {
+  for (const [index, entry] of value.entries()) {
+    const failure = checkCapabilityValue(entry, `${path}[${String(index)}]`);
+    if (failure !== void 0)
+      return failure;
+  }
+  return;
+}
+function checkCapabilityObject(record, path) {
+  for (const key of Object.keys(record)) {
+    const keyPath = `${path}.${key}`, keyFailure = checkCapabilityString(key, keyPath);
+    if (keyFailure !== void 0)
+      return keyFailure;
+    const failure = checkCapabilityValue(record[key], keyPath);
+    if (failure !== void 0)
+      return failure;
+  }
+  return;
+}
+export function parseManifestCapabilities(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const record = value, keys = Object.keys(record);
+  if (keys.length > MAX_MANIFEST_CAPABILITY_COUNT)
+    return manifestFailure("too_many_capabilities", `declares ${keys.length} capabilities, exceeding the maximum of ${MAX_MANIFEST_CAPABILITY_COUNT}`, path);
+  const capabilities = Object.create(null);
+  for (const key of keys) {
+    const entry = record[key], keyPath = `${path}.${key}`, keyFailure = checkCapabilityString(key, keyPath);
+    if (keyFailure !== void 0)
+      return keyFailure;
+    if (exceedsCapabilityDepth(entry, 1, MAX_MANIFEST_CAPABILITY_DEPTH))
+      return manifestFailure("capability_too_deep", `exceeds the maximum capability nesting depth of ${MAX_MANIFEST_CAPABILITY_DEPTH}`, keyPath);
+    if (!isJSONValue(entry))
+      return manifestFailure("invalid_capability_value", "must be a JSON value", keyPath);
+    const failure = checkCapabilityValue(entry, keyPath);
+    if (failure !== void 0)
+      return failure;
+    capabilities[key] = entry;
+  }
+  return { ok: !0, capabilities };
+}

package/dist/worker/manifest/content-digest.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generic SHA-256 content digest, tagged with its algorithm.
+ *
+ * Extracted from the manifest digest so any canonical-JSON content — not
+ * only a full {@link WorkerManifest} — can be hashed with the same
+ * collision-resistant, algorithm-tagged scheme. `hashString` (FNV-1a) stays
+ * reserved for cache-key-quality placeholders; anything a host trusts as a
+ * real content identity goes through this function instead.
+ *
+ * @module worker/manifest/content-digest
+ */
+/**
+ * Algorithm tag prefixed to every digest this function produces.
+ *
+ * Carrying the algorithm in the value means a future change reads as a
+ * difference rather than as a silent reinterpretation of the same hex.
+ */
+export declare const CONTENT_DIGEST_ALGORITHM = "sha256";
+/** Digest a UTF-8 string with SHA-256, returning `sha256:<hex>`. */
+export declare function sha256Hex(input: string): Promise<string>;

package/dist/worker/manifest/content-digest.js

@@ -0,0 +1,13 @@
+import { copyBytesToArrayBuffer } from "../../core/byte-arrays.js";
+import { utf8Encode } from "./utf8.js";
+export const CONTENT_DIGEST_ALGORITHM = "sha256";
+function bytesToHex(bytes) {
+  let hex = "";
+  for (const byte of bytes)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+export async function sha256Hex(input) {
+  const digest = await crypto.subtle.digest("SHA-256", copyBytesToArrayBuffer(utf8Encode(input)));
+  return `${CONTENT_DIGEST_ALGORITHM}:${bytesToHex(new Uint8Array(digest))}`;
+}

package/dist/worker/manifest/declared-shape-digest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Placeholder content-identity digest shared by every manifest builder that
+ * has no real build-tool-supplied digest to report yet.
+ *
+ * @module worker/manifest/declared-shape-digest
+ */
+/**
+ * Tag a derived placeholder value so it is never mistaken for a real,
+ * build-tool-supplied content digest. `hashString` is FNV-1a — cache-key
+ * quality, not cryptographic — which is exactly why the tag exists: a reader
+ * (or a future deterministic builder) can tell a `declared-shape:` value
+ * apart from a trusted `sha256:` one at a glance.
+ */
+export declare function declaredShapeDigest(input: string): string;

package/dist/worker/manifest/declared-shape-digest.js

@@ -0,0 +1,4 @@
+import { hashString } from "../../runtime/portable.js";
+export function declaredShapeDigest(input) {
+  return `declared-shape:${hashString(input)}`;
+}

package/dist/worker/manifest/digest.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Content-addressed digest of a worker manifest.
+ *
+ * The digest is what `(deploymentName, buildId)` consistency, registration
+ * acknowledgement, and persisted execution provenance all compare, so a
+ * collision would let two different workers pass for one another. That rules
+ * out the repository's FNV-1a helpers, which are documented as cache-key
+ * quality, and calls for SHA-256 — the same choice, and the same
+ * bounded-input-then-hash shape, as the worker replay signature.
+ *
+ * The digest carries its algorithm as a prefix so a future change is a
+ * readable difference rather than a silent reinterpretation of 64 hex
+ * characters.
+ *
+ * @module worker/manifest/digest
+ */
+import type { WorkerManifest } from './types.ts';
+/**
+ * Algorithm tag prefixed to every manifest digest this version produces.
+ *
+ * Carrying the algorithm in the value means a future change reads as a
+ * difference rather than as a silent reinterpretation of the same hex.
+ *
+ * @example
+ * ```ts
+ * import { WORKER_MANIFEST_DIGEST_ALGORITHM } from '@lostgradient/weft';
+ *
+ * const digest = 'sha256:41d0e2';
+ * console.log(digest.startsWith(`${WORKER_MANIFEST_DIGEST_ALGORITHM}:`)); // true
+ * ```
+ */
+export declare const WORKER_MANIFEST_DIGEST_ALGORITHM = "sha256";
+/**
+ * Digest canonical manifest bytes.
+ *
+ * Separate from {@link computeWorkerManifestDigest} so a caller that already
+ * holds the canonical serialization — the manifest parser returns one — does
+ * not serialize the manifest twice.
+ *
+ * @example
+ * ```ts
+ * import { canonicalWorkerManifestJson, digestCanonicalWorkerManifest } from '@lostgradient/weft';
+ *
+ * const canonical = canonicalWorkerManifestJson({
+ *   manifestVersion: 1,
+ *   protocolVersion: 2,
+ *   sdkVersion: '0.18.0',
+ *   runtime: { name: 'bun', version: '1.3.14' },
+ *   deployment: { name: 'billing', buildId: 'b3', artifactDigest: 'sha256:41d0' },
+ *   workflows: {},
+ *   capabilities: {},
+ * });
+ *
+ * console.log((await digestCanonicalWorkerManifest(canonical)).startsWith('sha256:'));
+ * ```
+ */
+export declare function digestCanonicalWorkerManifest(canonicalJson: string): Promise<string>;
+/**
+ * Compute the content-addressed digest of a worker manifest.
+ *
+ * Determined entirely by canonical content, so two manifests that differ only
+ * in key order digest identically, and any difference the host cares about
+ * changes the digest.
+ *
+ * @example
+ * ```ts
+ * import { computeWorkerManifestDigest, WORKER_MANIFEST_VERSION } from '@lostgradient/weft';
+ *
+ * const digest = await computeWorkerManifestDigest({
+ *   manifestVersion: WORKER_MANIFEST_VERSION,
+ *   protocolVersion: 2,
+ *   sdkVersion: '0.18.0',
+ *   runtime: { name: 'bun', version: '1.3.14' },
+ *   deployment: { name: 'billing', buildId: 'b3', artifactDigest: 'sha256:41d0' },
+ *   workflows: {},
+ *   capabilities: {},
+ * });
+ *
+ * console.log(digest.startsWith('sha256:')); // true
+ * ```
+ */
+export declare function computeWorkerManifestDigest(manifest: WorkerManifest): Promise<string>;

package/dist/worker/manifest/digest.js

@@ -0,0 +1,9 @@
+import { sha256Hex } from "./content-digest.js";
+import { canonicalWorkerManifestJson } from "./normalize.js";
+export const WORKER_MANIFEST_DIGEST_ALGORITHM = "sha256";
+export async function digestCanonicalWorkerManifest(canonicalJson) {
+  return sha256Hex(canonicalJson);
+}
+export async function computeWorkerManifestDigest(manifest) {
+  return digestCanonicalWorkerManifest(canonicalWorkerManifestJson(manifest));
+}

package/dist/worker/manifest/execution-identity.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Deriving and matching worker execution identity.
+ *
+ * Routing asks a question — {@link WorkerExecutionRequirement} — and a lease
+ * answers it completely — {@link WorkerExecutionIdentity}. Keeping the two
+ * types apart is what stops a partially specified routing hint from being
+ * mistaken for an observed fact, and building the identity from the accepted
+ * manifest rather than from a worker's result is what stops a worker from
+ * claiming it ran something it did not.
+ *
+ * @module worker/manifest/execution-identity
+ */
+import type { WorkerExecutionIdentity, WorkerExecutionRequirement, WorkerManifest } from './types.ts';
+/**
+ * Build the complete execution identity for an attempt.
+ *
+ * Every field comes from the accepted manifest, the accepted manifest digest,
+ * and the live session — never from anything the worker reports later.
+ * Returns `undefined` when the manifest does not actually advertise the
+ * workflow and activity being leased, which is the caller's signal that the
+ * worker was never eligible for this task.
+ *
+ * @example
+ * ```ts
+ * import { buildWorkerExecutionIdentity, WORKER_MANIFEST_VERSION } from '@lostgradient/weft';
+ *
+ * const identity = buildWorkerExecutionIdentity({
+ *   manifest: {
+ *     manifestVersion: WORKER_MANIFEST_VERSION,
+ *     protocolVersion: 2,
+ *     sdkVersion: '0.18.0',
+ *     runtime: { name: 'bun', version: '1.3.14' },
+ *     deployment: { name: 'billing', buildId: 'b3', artifactDigest: 'sha256:41d0' },
+ *     workflows: {
+ *       checkout: {
+ *         workflowVersion: '1.0.0',
+ *         workflowRevision: 'rev-8',
+ *         contractHash: 'sha256:aa',
+ *         activities: { charge: { contractHash: 'sha256:bb', implementationRevision: 'r1' } },
+ *       },
+ *     },
+ *     capabilities: {},
+ *   },
+ *   manifestDigest: 'sha256:deadbeef',
+ *   workerId: 'worker-1',
+ *   workflowType: 'checkout',
+ *   activityName: 'charge',
+ * });
+ *
+ * console.log(identity?.activityContractHash); // 'sha256:bb'
+ * ```
+ */
+export declare function buildWorkerExecutionIdentity(source: Readonly<{
+    manifest: WorkerManifest;
+    manifestDigest: string;
+    workerId: string;
+    workflowType: string;
+    activityName: string;
+}>): WorkerExecutionIdentity | undefined;
+/**
+ * Test whether an execution identity satisfies a routing requirement.
+ *
+ * An omitted requirement field means policy may choose any eligible value, so
+ * it matches anything. It is deliberately not treated as a demand for an empty
+ * string, which is why this cannot be written as a plain field-by-field
+ * equality check.
+ *
+ * @example
+ * ```ts
+ * import { executionIdentitySatisfies, type WorkerExecutionIdentity } from '@lostgradient/weft';
+ *
+ * const identity: WorkerExecutionIdentity = {
+ *   workerId: 'worker-1',
+ *   manifestDigest: 'sha256:deadbeef',
+ *   protocolVersion: 2,
+ *   sdkVersion: '0.18.0',
+ *   runtimeName: 'bun',
+ *   runtimeVersion: '1.3.14',
+ *   deploymentName: 'billing',
+ *   buildId: 'b3',
+ *   artifactDigest: 'sha256:41d0',
+ *   workflowType: 'checkout',
+ *   workflowRevision: 'rev-8',
+ *   activityName: 'charge',
+ *   activityContractHash: 'sha256:bb',
+ * };
+ *
+ * console.log(executionIdentitySatisfies({ deploymentName: 'billing' }, identity)); // true
+ * console.log(executionIdentitySatisfies({ buildId: 'b4' }, identity)); // false
+ * ```
+ */
+export declare function executionIdentitySatisfies(requirement: WorkerExecutionRequirement, identity: WorkerExecutionIdentity): boolean;

package/dist/worker/manifest/execution-identity.js

@@ -0,0 +1,36 @@
+export function buildWorkerExecutionIdentity(source) {
+  const workflow = source.manifest.workflows[source.workflowType];
+  if (workflow === void 0)
+    return;
+  const activity = workflow.activities[source.activityName];
+  if (activity === void 0)
+    return;
+  return {
+    workerId: source.workerId,
+    manifestDigest: source.manifestDigest,
+    protocolVersion: source.manifest.protocolVersion,
+    sdkVersion: source.manifest.sdkVersion,
+    runtimeName: source.manifest.runtime.name,
+    runtimeVersion: source.manifest.runtime.version,
+    deploymentName: source.manifest.deployment.name,
+    buildId: source.manifest.deployment.buildId,
+    artifactDigest: source.manifest.deployment.artifactDigest,
+    workflowType: source.workflowType,
+    workflowRevision: workflow.workflowRevision,
+    activityName: source.activityName,
+    activityContractHash: activity.contractHash
+  };
+}
+export function executionIdentitySatisfies(requirement, identity) {
+  return ROUTING_FIELDS.every((field) => {
+    const required = requirement[field];
+    return required === void 0 || required === identity[field];
+  });
+}
+const ROUTING_FIELDS = [
+  "deploymentName",
+  "buildId",
+  "artifactDigest",
+  "workflowRevision",
+  "activityContractHash"
+];

package/dist/worker/manifest/failure.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bounded failure vocabulary for worker manifest validation.
+ *
+ * Rejections are returned rather than thrown, matching the RemoteWorker
+ * protocol parser: a malformed manifest is an expected wire condition on an
+ * untrusted boundary, not an exceptional one.
+ *
+ * `reason` is a closed union precisely so operators can count manifest
+ * rejections by reason without a high-cardinality label. The human-readable
+ * `message` and the `path` locating the offending field are for diagnostics
+ * and must never be used as metric labels.
+ *
+ * @module worker/manifest/failure
+ */
+/**
+ * Why a worker manifest was rejected.
+ *
+ * Closed by design — a bounded reason is safe to use as a metric label,
+ * unlike the message or path that accompany it.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerManifestRejectionReason } from '@lostgradient/weft';
+ *
+ * const counts = new Map<WorkerManifestRejectionReason, number>();
+ * counts.set('unsupported_manifest_version', 1);
+ * console.log(counts.get('unsupported_manifest_version'));
+ * ```
+ */
+export type WorkerManifestRejectionReason = 'not_an_object' | 'unsupported_manifest_version' | 'invalid_field' | 'identifier_too_long' | 'too_many_workflows' | 'too_many_activities' | 'too_many_capabilities' | 'capability_too_deep' | 'capability_string_too_long' | 'invalid_capability_value' | 'manifest_too_large' | 'duplicate_key' | 'invalid_json';
+/**
+ * A rejected worker manifest, with enough detail to fix the worker and not so
+ * much that it leaks manifest content into logs.
+ *
+ * @example
+ * ```ts
+ * import { parseWorkerManifest, type ManifestValidationFailure } from '@lostgradient/weft';
+ *
+ * const result = parseWorkerManifest({ manifestVersion: 99 });
+ * if (!result.ok) {
+ *   const rejection: ManifestValidationFailure = result;
+ *   console.log(rejection.reason); // 'unsupported_manifest_version'
+ * }
+ * ```
+ */
+export type ManifestValidationFailure = Readonly<{
+    ok: false;
+    /** Bounded rejection reason, safe as a metric label. */
+    reason: WorkerManifestRejectionReason;
+    /** Human-readable diagnostic. Never use as a metric label. */
+    message: string;
+    /** Dotted path to the offending field, when one applies. */
+    path?: string;
+}>;
+/**
+ * Build a validation failure whose message reads as one sentence about the
+ * offending path — `manifest.deployment.buildId must be a non-empty string`.
+ */
+export declare function manifestFailure(reason: WorkerManifestRejectionReason, message: string, path?: string): ManifestValidationFailure;

package/dist/worker/manifest/failure.js

@@ -0,0 +1,4 @@
+export function manifestFailure(reason, message, path) {
+  const described = path === void 0 ? message : `${path} ${message}`;
+  return path === void 0 ? { ok: !1, reason, message: described } : { ok: !1, reason, message: described, path };
+}

package/dist/worker/manifest/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonical worker manifest and execution-identity vocabulary.
+ *
+ * This is the single definition of how a worker describes itself and how the
+ * host records what actually executed an attempt. The durable task ledger,
+ * provenance, routing, workflow versioning, and operator diagnostics all
+ * consume these types rather than defining their own.
+ *
+ * @module worker/manifest
+ */
+export { MAX_MANIFEST_ACTIVITY_COUNT, MAX_MANIFEST_CAPABILITY_COUNT, MAX_MANIFEST_CAPABILITY_DEPTH, MAX_MANIFEST_CAPABILITY_STRING_BYTES, MAX_MANIFEST_IDENTIFIER_BYTES, MAX_MANIFEST_WORKFLOW_COUNT, MAX_NORMALIZED_MANIFEST_BYTES, } from './limits.ts';
+export { WORKER_MANIFEST_VERSION } from './types.ts';
+export type { WorkerActivityContract, WorkerDeploymentIdentity, WorkerExecutionIdentity, WorkerExecutionRequirement, WorkerManifest, WorkerRuntimeIdentity, WorkerWorkflowContract, } from './types.ts';
+export { canonicalWorkerManifestJson, normalizeWorkerManifest } from './normalize.ts';
+export { parseWorkerManifest } from './parse.ts';
+export type { WorkerManifestParseResult, WorkerManifestParseSuccess } from './parse.ts';
+export { parseWorkerManifestJson } from './parse-json.ts';
+export type { ManifestValidationFailure, WorkerManifestRejectionReason } from './failure.ts';
+export { WORKER_MANIFEST_DIGEST_ALGORITHM, computeWorkerManifestDigest, digestCanonicalWorkerManifest, } from './digest.ts';
+export { buildWorkerExecutionIdentity, executionIdentitySatisfies } from './execution-identity.ts';
+export { WorkerManifestBuildError, buildWorkerManifestFromRegistry, } from './registry-contract-builder.ts';
+export type { WorkerManifestFromRegistryOptions } from './registry-contract-builder.ts';

package/dist/worker/manifest/index.js

@@ -0,0 +1,23 @@
+export {
+  MAX_MANIFEST_ACTIVITY_COUNT,
+  MAX_MANIFEST_CAPABILITY_COUNT,
+  MAX_MANIFEST_CAPABILITY_DEPTH,
+  MAX_MANIFEST_CAPABILITY_STRING_BYTES,
+  MAX_MANIFEST_IDENTIFIER_BYTES,
+  MAX_MANIFEST_WORKFLOW_COUNT,
+  MAX_NORMALIZED_MANIFEST_BYTES
+} from "./limits.js";
+export { WORKER_MANIFEST_VERSION } from "./types.js";
+export { canonicalWorkerManifestJson, normalizeWorkerManifest } from "./normalize.js";
+export { parseWorkerManifest } from "./parse.js";
+export { parseWorkerManifestJson } from "./parse-json.js";
+export {
+  WORKER_MANIFEST_DIGEST_ALGORITHM,
+  computeWorkerManifestDigest,
+  digestCanonicalWorkerManifest
+} from "./digest.js";
+export { buildWorkerExecutionIdentity, executionIdentitySatisfies } from "./execution-identity.js";
+export {
+  WorkerManifestBuildError,
+  buildWorkerManifestFromRegistry
+} from "./registry-contract-builder.js";

package/dist/worker/manifest/internal-realm.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Manifest builder shared by both sides of the internal Worker realm
+ * handshake (WFT-28).
+ *
+ * Unlike the RemoteWorker SDK, an internal `workflowExecutionMode: 'worker'`
+ * realm has no per-workflow activity list or version metadata to report —
+ * workflow generators are opaque functions, not a declared activity table —
+ * so this builder only asserts the one thing both sides can honestly derive:
+ * the identity of a registered workflow *type name*. `workflowVersion` is
+ * the uniform {@link DEFAULT_WORKFLOW_VERSION} placeholder rather than each
+ * definition's real declared version, so the host and the realm never need
+ * to keep a second copy of version metadata in sync (the exact class of
+ * drift this handshake exists to catch elsewhere). Real per-workflow
+ * contract generation is WFT-29 scope, same as the RemoteWorker SDK's
+ * `declared-shape:` placeholders.
+ *
+ * The host validates that every workflow type it has registered is present
+ * in the realm's manifest with a matching contract — a *subset* check, not
+ * exact-set equality. A realm bootstrap script legitimately advertises more
+ * workflow types than any one host process dispatches (a shared worker pool
+ * serving several engines, each using a different slice of it); what must
+ * never happen is the host dispatching to a realm that is missing a type it
+ * expects. {@link declaredWorkflowContractsMatch} is what the host compares
+ * per expected type; {@link buildInternalRealmManifest} is what the realm
+ * uses to build its own full advertised manifest.
+ *
+ * `runtime` is a fixed constant rather than `detectRuntime()`: a browser Web
+ * Worker has no `window`/`document` in its own scope, so it detects as
+ * `'edge'` while the hosting page detects as `'browser'` — real detection
+ * would make otherwise-identical manifests diverge on every browser
+ * deployment. Both sides call this same function, so a constant is exactly
+ * as comparable and avoids that divergence entirely.
+ *
+ * @module worker/manifest/internal-realm
+ */
+import { type WorkerManifest, type WorkerWorkflowContract } from './index.ts';
+/** Fixed deployment name for every internal Worker realm manifest. */
+export declare const INTERNAL_WORKER_REALM_DEPLOYMENT_NAME = "internal-worker-realm";
+/** Fixed runtime identity reported by every internal Worker realm manifest. See {@link buildInternalRealmManifest}. */
+export declare const INTERNAL_WORKER_REALM_RUNTIME_NAME = "internal-worker-realm";
+/** Pure function of `workflowType` alone — identical on the host and the realm for the same name. */
+export declare function buildDeclaredWorkflowContract(workflowType: string): WorkerWorkflowContract;
+/** Whether a realm-reported contract for one workflow type matches what the host expects for that same type name. */
+export declare function declaredWorkflowContractsMatch(reported: WorkerWorkflowContract, expected: WorkerWorkflowContract): boolean;
+/**
+ * Build the manifest an internal Worker realm advertises, or the manifest
+ * the engine host expects a realm to advertise — the same function computes
+ * both sides so an honest mismatch is the only way the digests can differ.
+ */
+export declare function buildInternalRealmManifest(workflowTypes: readonly string[]): WorkerManifest;