@lostgradient/weft 0.17.0 → 0.19.0

package/dist/worker/manifest/parse.js

@@ -0,0 +1,188 @@
+import { validateWorkflowOrActivityName } from "../../core/types/name-grammar.js";
+import { parseManifestCapabilities } from "./capabilities.js";
+import { manifestFailure } from "./failure.js";
+import { isRecord } from "./is-record.js";
+import {
+  MAX_MANIFEST_ACTIVITY_COUNT,
+  MAX_MANIFEST_IDENTIFIER_BYTES,
+  MAX_MANIFEST_WORKFLOW_COUNT,
+  MAX_NORMALIZED_MANIFEST_BYTES
+} from "./limits.js";
+import { canonicalWorkerManifestJson, normalizeWorkerManifest } from "./normalize.js";
+import { WORKER_MANIFEST_VERSION } from "./types.js";
+import { utf8ByteLength } from "./utf8.js";
+function parseIdentifier(value, path) {
+  if (typeof value !== "string" || value.length === 0)
+    return manifestFailure("invalid_field", "must be a non-empty string", path);
+  const bytes = utf8ByteLength(value);
+  if (bytes > MAX_MANIFEST_IDENTIFIER_BYTES)
+    return manifestFailure("identifier_too_long", `is ${bytes} bytes, exceeding the maximum identifier size of ${MAX_MANIFEST_IDENTIFIER_BYTES}`, path);
+  return { ok: !0, value };
+}
+function checkKey(key, kind, path) {
+  if (key.length === 0)
+    return manifestFailure("invalid_field", "must not be an empty string", path);
+  const bytes = utf8ByteLength(key);
+  if (bytes > MAX_MANIFEST_IDENTIFIER_BYTES)
+    return manifestFailure("identifier_too_long", `is ${bytes} bytes, exceeding the maximum identifier size of ${MAX_MANIFEST_IDENTIFIER_BYTES}`, path);
+  try {
+    validateWorkflowOrActivityName(key, kind);
+  } catch (error) {
+    return manifestFailure("invalid_field", error instanceof Error ? error.message : "is not a wire-safe name", path);
+  }
+  return;
+}
+function parseProtocolVersion(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+    return manifestFailure("invalid_field", "must be a positive safe integer", "manifest.protocolVersion");
+  return { ok: !0, value };
+}
+function parseRuntime(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const name = parseIdentifier(value.name, `${path}.name`);
+  if (!name.ok)
+    return name;
+  const rawVersion = value.version;
+  if (typeof rawVersion !== "string")
+    return manifestFailure("invalid_field", "must be a string", `${path}.version`);
+  const versionBytes = utf8ByteLength(rawVersion);
+  if (versionBytes > MAX_MANIFEST_IDENTIFIER_BYTES)
+    return manifestFailure("identifier_too_long", `is ${versionBytes} bytes, exceeding the maximum identifier size of ${MAX_MANIFEST_IDENTIFIER_BYTES}`, `${path}.version`);
+  return { ok: !0, runtime: { name: name.value, version: rawVersion } };
+}
+function parseDeployment(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const name = parseIdentifier(value.name, `${path}.name`);
+  if (!name.ok)
+    return name;
+  const buildId = parseIdentifier(value.buildId, `${path}.buildId`);
+  if (!buildId.ok)
+    return buildId;
+  const artifactDigest = parseIdentifier(value.artifactDigest, `${path}.artifactDigest`);
+  if (!artifactDigest.ok)
+    return artifactDigest;
+  return {
+    ok: !0,
+    deployment: {
+      name: name.value,
+      buildId: buildId.value,
+      artifactDigest: artifactDigest.value
+    }
+  };
+}
+function parseActivity(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const contractHash = parseIdentifier(value.contractHash, `${path}.contractHash`);
+  if (!contractHash.ok)
+    return contractHash;
+  const implementationRevision = parseIdentifier(value.implementationRevision, `${path}.implementationRevision`);
+  if (!implementationRevision.ok)
+    return implementationRevision;
+  return {
+    ok: !0,
+    activity: {
+      contractHash: contractHash.value,
+      implementationRevision: implementationRevision.value
+    }
+  };
+}
+function parseActivities(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const names = Object.keys(value);
+  if (names.length > MAX_MANIFEST_ACTIVITY_COUNT)
+    return manifestFailure("too_many_activities", `declares ${names.length} activities, exceeding the maximum of ${MAX_MANIFEST_ACTIVITY_COUNT}`, path);
+  const activities = Object.create(null);
+  for (const name of names) {
+    const keyFailure = checkKey(name, "activity", `${path} key ${JSON.stringify(name)}`);
+    if (keyFailure !== void 0)
+      return keyFailure;
+    const activity = parseActivity(value[name], `${path}.${name}`);
+    if (!activity.ok)
+      return activity;
+    activities[name] = activity.activity;
+  }
+  return { ok: !0, activities };
+}
+function parseWorkflow(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const workflowVersion = parseIdentifier(value.workflowVersion, `${path}.workflowVersion`);
+  if (!workflowVersion.ok)
+    return workflowVersion;
+  const workflowRevision = parseIdentifier(value.workflowRevision, `${path}.workflowRevision`);
+  if (!workflowRevision.ok)
+    return workflowRevision;
+  const contractHash = parseIdentifier(value.contractHash, `${path}.contractHash`);
+  if (!contractHash.ok)
+    return contractHash;
+  const activities = parseActivities(value.activities, `${path}.activities`);
+  if (!activities.ok)
+    return activities;
+  return {
+    ok: !0,
+    workflow: {
+      workflowVersion: workflowVersion.value,
+      workflowRevision: workflowRevision.value,
+      contractHash: contractHash.value,
+      activities: activities.activities
+    }
+  };
+}
+function parseWorkflows(value, path) {
+  if (!isRecord(value))
+    return manifestFailure("invalid_field", "must be a JSON object", path);
+  const names = Object.keys(value);
+  if (names.length > MAX_MANIFEST_WORKFLOW_COUNT)
+    return manifestFailure("too_many_workflows", `declares ${names.length} workflows, exceeding the maximum of ${MAX_MANIFEST_WORKFLOW_COUNT}`, path);
+  const workflows = Object.create(null);
+  for (const name of names) {
+    const keyFailure = checkKey(name, "workflow", `${path} key ${JSON.stringify(name)}`);
+    if (keyFailure !== void 0)
+      return keyFailure;
+    const workflow = parseWorkflow(value[name], `${path}.${name}`);
+    if (!workflow.ok)
+      return workflow;
+    workflows[name] = workflow.workflow;
+  }
+  return { ok: !0, workflows };
+}
+export function parseWorkerManifest(value) {
+  if (!isRecord(value))
+    return manifestFailure("not_an_object", "manifest must be a JSON object");
+  if (value.manifestVersion !== WORKER_MANIFEST_VERSION)
+    return manifestFailure("unsupported_manifest_version", `manifest.manifestVersion must be ${String(WORKER_MANIFEST_VERSION)}`);
+  const protocolVersion = parseProtocolVersion(value.protocolVersion);
+  if (!protocolVersion.ok)
+    return protocolVersion;
+  const sdkVersion = parseIdentifier(value.sdkVersion, "manifest.sdkVersion");
+  if (!sdkVersion.ok)
+    return sdkVersion;
+  const runtime = parseRuntime(value.runtime, "manifest.runtime");
+  if (!runtime.ok)
+    return runtime;
+  const deployment = parseDeployment(value.deployment, "manifest.deployment");
+  if (!deployment.ok)
+    return deployment;
+  const workflows = parseWorkflows(value.workflows, "manifest.workflows");
+  if (!workflows.ok)
+    return workflows;
+  const capabilities = parseManifestCapabilities(value.capabilities, "manifest.capabilities");
+  if (!capabilities.ok)
+    return capabilities;
+  const manifest = normalizeWorkerManifest({
+    manifestVersion: WORKER_MANIFEST_VERSION,
+    protocolVersion: protocolVersion.value,
+    sdkVersion: sdkVersion.value,
+    runtime: runtime.runtime,
+    deployment: deployment.deployment,
+    workflows: workflows.workflows,
+    capabilities: capabilities.capabilities
+  }), canonicalJson = canonicalWorkerManifestJson(manifest), canonicalBytes = utf8ByteLength(canonicalJson);
+  if (canonicalBytes > MAX_NORMALIZED_MANIFEST_BYTES)
+    return manifestFailure("manifest_too_large", `normalizes to ${canonicalBytes} bytes, exceeding the maximum of ${MAX_NORMALIZED_MANIFEST_BYTES}`, "manifest");
+  return { ok: !0, manifest, canonicalJson };
+}

package/dist/worker/manifest/registry-contract-builder.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Real worker manifest production from an engine's canonical workflow
+ * registry (WFT-29).
+ *
+ * `RemoteWorkerOptions` and the internal Worker realm both fall back to
+ * `declared-shape:` placeholders when no real build tooling supplies a
+ * manifest — see {@link declaredShapeDigest}. This module is that build
+ * tooling: it derives `WorkerWorkflowContract`/`WorkerActivityContract`
+ * values from the *same* normalized representation `buildRegistrySnapshot`
+ * produces for `GET /v1/registry` and `weft codegen`, hashed with the
+ * collision-resistant {@link sha256Hex} rather than the cache-key-quality
+ * FNV-1a scheme those placeholders use.
+ *
+ * Intended use is a build script: construct an `Engine` with every workflow
+ * the artifact bundles registered (never started), call
+ * {@link buildWorkerManifestFromRegistry}, and pass the result as
+ * `RemoteWorkerOptions.manifest`.
+ *
+ * @module worker/manifest/registry-contract-builder
+ */
+import type { Engine } from '../../core/engine.ts';
+import { WeftError } from '../../core/weft-error.ts';
+import type { WorkerDeploymentIdentity, WorkerManifest, WorkerRuntimeIdentity } from './types.ts';
+/**
+ * Thrown when {@link buildWorkerManifestFromRegistry} is asked to advertise a
+ * workflow or activity name that the source `Engine` has not registered.
+ *
+ * This is a build-time tooling error, thrown before any manifest reaches the
+ * wire — analogous to the engine's own `RegistrySchemaConversionError`.
+ *
+ * @example
+ * ```ts
+ * import { WorkerManifestBuildError } from '@lostgradient/weft';
+ *
+ * try {
+ *   throw new WorkerManifestBuildError('workflow "checkout" is not registered');
+ * } catch (error) {
+ *   console.log(error instanceof WorkerManifestBuildError); // true
+ * }
+ * ```
+ */
+export declare class WorkerManifestBuildError extends WeftError<'WorkerManifestBuildError'> {
+    constructor(message: string);
+}
+/**
+ * Options accepted by {@link buildWorkerManifestFromRegistry}.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerManifestFromRegistryOptions } from '@lostgradient/weft';
+ *
+ * const options: WorkerManifestFromRegistryOptions = {
+ *   workflows: { checkout: ['charge'] },
+ *   deployment: { name: 'billing', buildId: '2026.08.18-3', artifactDigest: 'sha256:41d0e2' },
+ *   runtime: { name: 'bun', version: '1.3.14' },
+ * };
+ * console.log(options.workflows['checkout']);
+ * ```
+ */
+export interface WorkerManifestFromRegistryOptions {
+    /**
+     * Workflow types this worker instance can execute, each mapped to the
+     * activity names it invokes. Every key must name a workflow the source
+     * `Engine` has registered, and every activity name must be one the same
+     * `Engine` has registered — the engine's activity registry is a flat
+     * namespace, not partitioned per workflow, so this association is the one
+     * thing the registry genuinely cannot supply on its own.
+     */
+    workflows: Readonly<Record<string, readonly string[]>>;
+    /** Immutable deployment artifact identity. Required — never derived. */
+    deployment: WorkerDeploymentIdentity;
+    /**
+     * Runtime that will execute the deployed artifact. Required rather than
+     * defaulted: a build script's own process (often a CI runner) is not
+     * necessarily the runtime the artifact deploys to, so live detection here
+     * would silently assert the wrong identity.
+     */
+    runtime: WorkerRuntimeIdentity;
+    /** Weft worker SDK release the deployed artifact bundles. Defaults to this package's `VERSION`. */
+    sdkVersion?: string;
+    /** RemoteWorker wire protocol version. Defaults to `REMOTE_WORKER_PROTOCOL_VERSION`. */
+    protocolVersion?: number;
+    /** Bounded descriptive capability data. Defaults to `{}`. */
+    capabilities?: WorkerManifest['capabilities'];
+}
+/**
+ * Build a real worker manifest from an engine's canonical workflow and
+ * activity registrations.
+ *
+ * `implementationRevision` on every activity contract is set to
+ * `options.deployment.buildId`: a schema identifies the *contract*, not the
+ * code behind it, so there is no honest schema-derived source for "which
+ * implementation" — the build that produced this artifact is the closest
+ * available honest answer.
+ *
+ * Throws {@link WorkerManifestBuildError} if `options.workflows` names a
+ * workflow or activity the source `Engine` has not registered, and a
+ * (non-public) schema-conversion error if a registered schema cannot be
+ * converted to JSON Schema.
+ *
+ * @example
+ * ```ts
+ * import { buildWorkerManifestFromRegistry, Engine, workflow } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'checkout', version: '2.1.0' }).execute(async function* () {}),
+ * );
+ *
+ * const manifest = await buildWorkerManifestFromRegistry(engine, {
+ *   workflows: { checkout: [] },
+ *   deployment: { name: 'billing', buildId: '2026.08.18-3', artifactDigest: 'sha256:41d0e2' },
+ *   runtime: { name: 'bun', version: '1.3.14' },
+ * });
+ *
+ * console.log(manifest.workflows['checkout']?.workflowVersion); // '2.1.0'
+ * engine[Symbol.dispose]();
+ * ```
+ */
+export declare function buildWorkerManifestFromRegistry(engine: Engine, options: WorkerManifestFromRegistryOptions): Promise<WorkerManifest>;

package/dist/worker/manifest/registry-contract-builder.js

@@ -0,0 +1,65 @@
+import {
+  buildRegistrySnapshot
+} from "../../core/registry-snapshot.js";
+import { WeftError } from "../../core/weft-error.js";
+import { VERSION } from "../../version.js";
+import { REMOTE_WORKER_PROTOCOL_VERSION } from "../protocol.js";
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex } from "./content-digest.js";
+import { WORKER_MANIFEST_VERSION } from "./types.js";
+
+export class WorkerManifestBuildError extends WeftError {
+  constructor(message) {
+    super("WorkerManifestBuildError", message);
+  }
+}
+function findWorkflowEntry(snapshot, workflowType) {
+  const entry = snapshot.workflows[workflowType];
+  if (entry === void 0)
+    throw new WorkerManifestBuildError(`Cannot build a worker manifest: workflow type "${workflowType}" is not registered on the source Engine.`);
+  return entry;
+}
+function findActivityEntry(snapshot, workflowType, activityName) {
+  const entry = snapshot.activities[activityName];
+  if (entry === void 0)
+    throw new WorkerManifestBuildError(`Cannot build a worker manifest: activity "${activityName}" declared under workflow "${workflowType}" is not registered on the source Engine.`);
+  return entry;
+}
+function workflowContractPayload(entry) {
+  return {
+    inputSchema: entry.inputSchema,
+    outputSchema: entry.outputSchema,
+    signals: entry.signals,
+    updates: entry.updates,
+    queries: entry.queries
+  };
+}
+function activityContractPayload(entry) {
+  return { inputSchema: entry.inputSchema, outputSchema: entry.outputSchema };
+}
+async function buildActivityContract(snapshot, workflowType, activityName, implementationRevision) {
+  const entry = findActivityEntry(snapshot, workflowType, activityName);
+  return { contractHash: await sha256Hex(canonicalJsonStringify(activityContractPayload(entry))), implementationRevision };
+}
+async function buildWorkflowContract(snapshot, workflowVersionsByType, workflowType, activityNames, implementationRevision) {
+  const entry = findWorkflowEntry(snapshot, workflowType), workflowVersion = workflowVersionsByType.get(workflowType), contractHash = await sha256Hex(canonicalJsonStringify(workflowContractPayload(entry))), workflowRevision = await sha256Hex(canonicalJsonStringify({ ...entry, version: workflowVersion })), sortedActivityNames = [...activityNames].toSorted(), activityContracts = await Promise.all(sortedActivityNames.map((activityName) => buildActivityContract(snapshot, workflowType, activityName, implementationRevision))), activities = {};
+  sortedActivityNames.forEach((activityName, index) => {
+    activities[activityName] = activityContracts[index];
+  });
+  return { workflowVersion, workflowRevision, contractHash, activities };
+}
+export async function buildWorkerManifestFromRegistry(engine, options) {
+  const snapshot = buildRegistrySnapshot(engine), workflowVersionsByType = new Map(engine.listWorkflowDefinitions().map((definition) => [definition.type, definition.version])), sortedWorkflowTypes = Object.keys(options.workflows).toSorted(), workflowContracts = await Promise.all(sortedWorkflowTypes.map((workflowType) => buildWorkflowContract(snapshot, workflowVersionsByType, workflowType, options.workflows[workflowType] ?? [], options.deployment.buildId))), workflows = {};
+  sortedWorkflowTypes.forEach((workflowType, index) => {
+    workflows[workflowType] = workflowContracts[index];
+  });
+  return {
+    manifestVersion: WORKER_MANIFEST_VERSION,
+    protocolVersion: options.protocolVersion ?? REMOTE_WORKER_PROTOCOL_VERSION,
+    sdkVersion: options.sdkVersion ?? VERSION,
+    runtime: options.runtime,
+    deployment: options.deployment,
+    workflows,
+    capabilities: options.capabilities ?? {}
+  };
+}

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

@@ -0,0 +1,263 @@
+/**
+ * Canonical worker manifest and execution-identity vocabulary.
+ *
+ * One manifest answers every identity question about a worker at once, with
+ * each question in its own field:
+ *
+ * | Field             | Question answered                                | Stability                       |
+ * | ----------------- | ------------------------------------------------ | ------------------------------- |
+ * | `manifestVersion` | Can the host parse this manifest shape?          | Changes with manifest schema    |
+ * | `protocolVersion` | Can these peers exchange wire messages?          | Changes with wire semantics     |
+ * | `sdkVersion`      | Which Weft worker SDK produced this worker?      | Package release                 |
+ * | `runtime`         | Which runtime executes the worker?               | Runtime deployment              |
+ * | `deployment.name` | Which logical service owns this worker?          | Stable service identity         |
+ * | `buildId`         | Which operator-visible release is this?          | Immutable within a deployment   |
+ * | `artifactDigest`  | Which exact executable bytes are loaded?         | Content-addressed and immutable |
+ * | `workflowVersion` | Which replay compatibility boundary is declared? | Workflow author controlled      |
+ * | `contractHash`    | Which public payload contract is implemented?    | Deterministic contract identity |
+ *
+ * A Git SHA is deliberately absent from that table: repositories may be dirty,
+ * builds may inject configuration, and one commit may produce several
+ * artifacts, so a commit is metadata rather than an executable identity.
+ *
+ * @module worker/manifest/types
+ */
+import type { JSONValue } from '../../core/json.ts';
+/**
+ * Current worker manifest schema version.
+ *
+ * This is a different axis from the RemoteWorker wire protocol version:
+ * `manifestVersion` answers "can the host parse this shape", while
+ * `protocolVersion` answers "can these peers exchange messages". Bump this
+ * only when the manifest's own structure changes incompatibly; unknown
+ * versions are rejected before registration rather than best-effort parsed.
+ *
+ * @example
+ * ```ts
+ * import { WORKER_MANIFEST_VERSION } from '@lostgradient/weft';
+ *
+ * const canParse = (received: number): boolean => received === WORKER_MANIFEST_VERSION;
+ * console.log(canParse(1));
+ * ```
+ */
+export declare const WORKER_MANIFEST_VERSION = 1;
+/**
+ * Deterministic identity of one activity implementation inside a workflow.
+ *
+ * `contractHash` identifies the public payload contract — what callers may
+ * send and expect back. `implementationRevision` identifies the code behind
+ * that contract, which may change without changing the contract.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerActivityContract } from '@lostgradient/weft';
+ *
+ * const charge: WorkerActivityContract = {
+ *   contractHash: 'sha256:2b1f0c9d',
+ *   implementationRevision: 'rev-41',
+ * };
+ * console.log(charge.contractHash);
+ * ```
+ */
+export type WorkerActivityContract = Readonly<{
+    /** Deterministic identity of this activity's public payload contract. */
+    contractHash: string;
+    /** Identity of the implementation currently bound to that contract. */
+    implementationRevision: string;
+}>;
+/**
+ * Deterministic identity of one workflow an artifact can execute, including
+ * every activity it exposes.
+ *
+ * Activity keys are canonical runtime activity names. An activity is qualified
+ * structurally by the workflow that contains it rather than only through a
+ * dotted string, so the same activity name may appear under two workflows
+ * without collision.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerWorkflowContract } from '@lostgradient/weft';
+ *
+ * const checkout: WorkerWorkflowContract = {
+ *   workflowVersion: '2.1.0',
+ *   workflowRevision: 'rev-88',
+ *   contractHash: 'sha256:9ab3',
+ *   activities: { charge: { contractHash: 'sha256:2b1f', implementationRevision: 'rev-41' } },
+ * };
+ * console.log(Object.keys(checkout.activities));
+ * ```
+ */
+export type WorkerWorkflowContract = Readonly<{
+    /** Semantic replay-compatibility boundary declared by the workflow author. */
+    workflowVersion: string;
+    /** Identity of the exact workflow definition loaded from this artifact. */
+    workflowRevision: string;
+    /** Deterministic identity of the workflow's public payload contract. */
+    contractHash: string;
+    /** Activities this workflow exposes, keyed by canonical activity name. */
+    activities: Readonly<Record<string, WorkerActivityContract>>;
+}>;
+/**
+ * Immutable deployment artifact identity.
+ *
+ * `(name, buildId)` identifies exactly one `artifactDigest` within one server
+ * scope. Shipping different bytes means choosing a new `buildId` — reusing one
+ * is a registration conflict, not an update.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerDeploymentIdentity } from '@lostgradient/weft';
+ *
+ * const deployment: WorkerDeploymentIdentity = {
+ *   name: 'billing',
+ *   buildId: '2026.08.18-3',
+ *   artifactDigest: 'sha256:41d0e2',
+ * };
+ * console.log(deployment.buildId);
+ * ```
+ */
+export type WorkerDeploymentIdentity = Readonly<{
+    /** Logical service that owns this worker. */
+    name: string;
+    /** Operator-visible release identity, immutable within the deployment. */
+    buildId: string;
+    /** Content-addressed digest of the complete executable artifact. */
+    artifactDigest: string;
+}>;
+/**
+ * Runtime that executes a worker process.
+ *
+ * `version` is an empty string on runtimes that expose none — a browser or
+ * edge worker — rather than being omitted, so the field is always answerable.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerRuntimeIdentity } from '@lostgradient/weft';
+ *
+ * const runtime: WorkerRuntimeIdentity = { name: 'bun', version: '1.3.14' };
+ * console.log(`${runtime.name} ${runtime.version}`);
+ * ```
+ */
+export type WorkerRuntimeIdentity = Readonly<{
+    /** Runtime name, such as `bun` or `node`. */
+    name: string;
+    /** Runtime version, or an empty string where the runtime exposes none. */
+    version: string;
+}>;
+/**
+ * Everything a worker asserts about itself, validated by the host before the
+ * worker becomes routing-eligible.
+ *
+ * Worker readiness means the server accepted a validated manifest — not merely
+ * that a socket opened. Digests and contract hashes carried here are checked
+ * against trusted records rather than believed because the worker asserted
+ * them, and `capabilities` never grants authorization on its own.
+ *
+ * @example
+ * ```ts
+ * import { WORKER_MANIFEST_VERSION, type WorkerManifest } from '@lostgradient/weft';
+ *
+ * const manifest: WorkerManifest = {
+ *   manifestVersion: WORKER_MANIFEST_VERSION,
+ *   protocolVersion: 2,
+ *   sdkVersion: '0.18.0',
+ *   runtime: { name: 'bun', version: '1.3.14' },
+ *   deployment: { name: 'billing', buildId: '2026.08.18-3', artifactDigest: 'sha256:41d0e2' },
+ *   workflows: {},
+ *   capabilities: {},
+ * };
+ * console.log(manifest.deployment.name);
+ * ```
+ */
+export type WorkerManifest = Readonly<{
+    /** Manifest schema version; unknown values are rejected, not tolerated. */
+    manifestVersion: typeof WORKER_MANIFEST_VERSION;
+    /** RemoteWorker wire protocol version these peers will speak. */
+    protocolVersion: number;
+    /** Weft worker SDK release that produced this worker. */
+    sdkVersion: string;
+    /** Runtime executing the worker process. */
+    runtime: WorkerRuntimeIdentity;
+    /** Immutable deployment artifact identity. */
+    deployment: WorkerDeploymentIdentity;
+    /** Workflows this artifact can execute, keyed by canonical workflow name. */
+    workflows: Readonly<Record<string, WorkerWorkflowContract>>;
+    /** Bounded descriptive capability data; never an authorization claim. */
+    capabilities: Readonly<Record<string, JSONValue>>;
+}>;
+/**
+ * Routing input: the constraints a task places on the worker that may execute
+ * it.
+ *
+ * An omitted field lets policy choose any eligible value. It is *not* an
+ * empty-string wildcard, and it is not a claim that the field does not matter
+ * once the task is leased — see {@link WorkerExecutionIdentity}, which is
+ * always complete.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerExecutionRequirement } from '@lostgradient/weft';
+ *
+ * // Pin the deployment, let policy pick any eligible build within it.
+ * const requirement: WorkerExecutionRequirement = { deploymentName: 'billing' };
+ * console.log(requirement.buildId === undefined);
+ * ```
+ */
+export type WorkerExecutionRequirement = Readonly<{
+    /** Required logical service, when the task pins one. */
+    deploymentName?: string;
+    /** Required operator-visible release, when the task pins one. */
+    buildId?: string;
+    /** Required executable artifact, when the task pins exact bytes. */
+    artifactDigest?: string;
+    /** Required workflow definition revision, when the task pins one. */
+    workflowRevision?: string;
+    /** Required activity contract identity, when the task pins one. */
+    activityContractHash?: string;
+}>;
+/**
+ * Observed execution: the complete identity of the worker that actually holds
+ * a lease on an attempt.
+ *
+ * Every field is populated from the accepted manifest plus the live session.
+ * A worker cannot self-report a different execution identity in its result,
+ * which is what makes this safe to persist as provenance.
+ *
+ * @example
+ * ```ts
+ * import type { WorkerExecutionIdentity } from '@lostgradient/weft';
+ *
+ * function describe(identity: WorkerExecutionIdentity): string {
+ *   return `${identity.deploymentName}@${identity.buildId} (${identity.workerId})`;
+ * }
+ * console.log(typeof describe);
+ * ```
+ */
+export type WorkerExecutionIdentity = Readonly<{
+    /** Live process instance that holds the lease. */
+    workerId: string;
+    /** Digest of the manifest the server accepted from that instance. */
+    manifestDigest: string;
+    /** Wire protocol version negotiated with that instance. */
+    protocolVersion: number;
+    /** Weft worker SDK release that produced the instance. */
+    sdkVersion: string;
+    /** Runtime name executing the instance. */
+    runtimeName: string;
+    /** Runtime version executing the instance. */
+    runtimeVersion: string;
+    /** Logical service that owns the instance. */
+    deploymentName: string;
+    /** Operator-visible release the instance is running. */
+    buildId: string;
+    /** Executable artifact the instance loaded. */
+    artifactDigest: string;
+    /** Workflow that executed the attempt. */
+    workflowType: string;
+    /** Workflow definition revision that executed the attempt. */
+    workflowRevision: string;
+    /** Activity that executed the attempt. */
+    activityName: string;
+    /** Contract identity of that activity. */
+    activityContractHash: string;
+}>;

package/dist/worker/manifest/types.js

@@ -0,0 +1 @@
+export const WORKER_MANIFEST_VERSION = 1;

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

@@ -0,0 +1,13 @@
+/**
+ * UTF-8 byte measurement for manifest bounds.
+ *
+ * Manifest limits are expressed in bytes rather than code units so a worker
+ * cannot smuggle several times the intended payload through astral-plane
+ * characters, each of which costs one UTF-16 `.length` but four UTF-8 bytes.
+ *
+ * @module worker/manifest/utf8
+ */
+/** UTF-8 byte length of a string. */
+export declare function utf8ByteLength(value: string): number;
+/** Encode a string to UTF-8 bytes. */
+export declare function utf8Encode(value: string): Uint8Array;

package/dist/worker/manifest/utf8.js

@@ -0,0 +1,7 @@
+const encoder = new TextEncoder;
+export function utf8ByteLength(value) {
+  return encoder.encode(value).byteLength;
+}
+export function utf8Encode(value) {
+  return encoder.encode(value);
+}