@lostgradient/weft 0.8.0 → 0.10.0

package/dist/server/json-rpc-dispatch.d.ts

@@ -5,8 +5,8 @@
  * body, resolves each request via `executeOperation`, and produces the
  * wire-level response shape.
  *
- * Track 8 design decision 13: batches dispatch SEQUENTIALLY in request
- * order. Response order matches request order by construction —
+ * The stable JSON-RPC operation-catalog contract mandates sequential dispatch
+ * in request order. Response order matches request order by construction —
  * notifications are dropped from the response array, so the returned
  * indices are the non-notification request indices.
  *

package/dist/server/json-rpc-parse.d.ts

@@ -3,7 +3,7 @@
  * parsed JSON) and returns a discriminated-union `ParseResult` that
  * describes what the transport should dispatch.
  *
- * Track 8 design decisions this parser enforces:
+ * The stable JSON-RPC operation-catalog contract enforces:
  *   - `params` MUST be absent or a JSON object. Array-form positional
  *     params are rejected with `InvalidRequest` (-32600). This matches
  *     OpenRPC's `paramStructure: "by-name"` contract and eliminates a

package/dist/server/json-rpc-protocol.d.ts

@@ -10,8 +10,8 @@
  *   - Runtime stdio session (`stdio-session.ts`, Phase 13)
  *
  * Reserved-spec error codes (-32700..-32603) keep their JSON-RPC 2.0
- * meanings. Weft domain codes live in the -32010..-32099 band per
- * Track 8 design decision 4.
+ * meanings. Weft domain codes live in the -32010..-32099 band; this stable
+ * error-code allocation preserves compatibility across JSON-RPC transports.
  */
 /** Literal `"2.0"` — the only `jsonrpc` version this runtime accepts. */
 export declare const JSON_RPC_VERSION: "2.0";

package/dist/server/json-rpc-websocket.d.ts

@@ -5,7 +5,7 @@
  * that binds the authenticated principal at upgrade time and reuses it
  * for every frame. The session:
  *   - Parses incoming frames as single JSON-RPC requests (batches over
- *     WS are rejected per Track 8 design decision 13).
+ *     WS are rejected per stable operation-catalog contract).
  *   - Dispatches `weft.workflows.subscribe` / `weft.workflows.unsubscribe`
  *     as first-class session primitives against the `WorkflowEventFeed`.
  *   - Delegates all other methods to the standard `dispatchJsonRpc`.

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

@@ -30,7 +30,9 @@
  * adapters never branch on `data === undefined`. This uniformity is what
  * lets the exhaustive switch in `extractFaultDataPayload` stay small.
  *
- * See Track 8 design decision 4.
+ * The stable fault model with transport-neutral code, message, and typed
+ * `data` payload forms the basis of cross-transport parity: every fault is
+ * serialized consistently across REST and JSON-RPC transports.
  */
 import type { FaultCode } from '../core/fault-code.ts';
 import type { WeftErrorCode } from '../core/weft-error.ts';

package/dist/server/operations/async-activity.js

@@ -41,7 +41,7 @@ export const completeAsyncActivityOperation = defineOperation({
   name: "weft.activities.complete",
   mcpExposable: !1,
   summary: "Complete a deferred activity by task token",
-  description: 'Resolve an out-of-band ("async") activity with a result, resuming its parked workflow as though the activity had returned that result inline. Requires the durable task token announced through the `activity:async-pending` event. Faults with NotFound when the token is unknown or already completed/failed (tokens are single-use), and InvalidParams when the result exceeds the payload size limit.',
+  description: 'Resolve an out-of-band ("async") activity with a result, resuming its parked workflow as though the activity had returned that result inline. Requires the durable task token announced through the `activity:async-pending` event. Faults with NotFound when the token is unknown or already completed/failed (tokens are single-use), and InvalidParams when the result exceeds the payload size limit. ' + "A success response is durable \u2014 the completion is persisted before the operation " + "returns, and a crash afterward cannot lose it. A failed call leaves the token completable, so treat storage-side faults as retryable.",
   destructive: !0,
   tags: ["Activities"],
   inputSchema: completeAsyncActivityInput,
@@ -63,7 +63,7 @@ export const completeAsyncActivityOperation = defineOperation({
   name: "weft.activities.fail",
   mcpExposable: !1,
   summary: "Fail a deferred activity by task token",
-  description: 'Fail an out-of-band ("async") activity, throwing the supplied error into its ' + "parked workflow at the deferred step \u2014 identical to an inline activity that threw, " + "so the workflow\u2019s own try/catch and retry policy apply unchanged. Requires the " + "durable task token from the `activity:async-pending` event. Faults with NotFound when the token is unknown or already completed/failed (tokens are single-use), and InvalidParams when the failure message exceeds the payload size limit.",
+  description: 'Fail an out-of-band ("async") activity, throwing the supplied error into its ' + "parked workflow at the deferred step \u2014 identical to an inline activity that threw, " + "so the workflow\u2019s own try/catch and retry policy apply unchanged. Requires the " + "durable task token from the `activity:async-pending` event. Faults with NotFound when the token is unknown or already completed/failed (tokens are single-use), and InvalidParams when the failure message exceeds the payload size limit. " + "A success response is durable \u2014 the failure outcome is persisted before the " + "operation returns, and a crash afterward cannot lose it. A failed call leaves the token completable, so treat storage-side faults as retryable.",
   destructive: !0,
   tags: ["Activities"],
   inputSchema: failAsyncActivityInput,

package/dist/server/operations/create-schedule.d.ts

@@ -6,6 +6,7 @@ declare const createScheduleInput: z.ZodObject<{
     every: z.ZodOptional<z.ZodUnknown>;
     input: z.ZodOptional<z.ZodUnknown>;
     id: z.ZodOptional<z.ZodUnknown>;
+    description: z.ZodOptional<z.ZodUnknown>;
     overlap: z.ZodOptional<z.ZodUnknown>;
     backfill: z.ZodOptional<z.ZodUnknown>;
     jitter: z.ZodOptional<z.ZodUnknown>;
@@ -21,6 +22,7 @@ export declare const createScheduleOperation: import("../operation-catalog.ts").
     every?: unknown;
     input?: unknown;
     id?: unknown;
+    description?: unknown;
     overlap?: unknown;
     backfill?: unknown;
     jitter?: unknown;

package/dist/server/operations/create-schedule.js

@@ -14,6 +14,7 @@ const VALID_SCHEDULE_OVERLAP_POLICIES = new Set([
   every: z.unknown().optional().describe("Interval period (duration string or milliseconds). Supply exactly one of cronExpression or every."),
   input: z.unknown().optional(),
   id: z.unknown().optional(),
+  description: z.unknown().optional().describe("Operator-facing schedule description. Runtime validation requires a string."),
   overlap: z.unknown().optional(),
   backfill: z.unknown().optional(),
   jitter: z.unknown().optional()
@@ -32,6 +33,12 @@ function validateOptionalScheduleFields(input) {
       throw invalidParamsFault('Field "id" must be a non-empty string');
     validatedId = input.id;
   }
+  let validatedDescription;
+  if (input.description !== void 0) {
+    if (typeof input.description !== "string")
+      throw invalidParamsFault('Field "description" must be a string');
+    validatedDescription = input.description;
+  }
   let validatedOverlap;
   if (input.overlap !== void 0) {
     if (typeof input.overlap !== "string" || !isScheduleOverlapPolicy(input.overlap))
@@ -52,14 +59,15 @@ function validateOptionalScheduleFields(input) {
   }
   return {
     id: validatedId,
+    description: validatedDescription,
     overlap: validatedOverlap,
     backfill: validatedBackfill,
     jitter: validatedJitter
   };
 }
 function validateCreateScheduleInput(input) {
-  const { type, spec } = validateRequiredScheduleFields(input), { id, overlap, backfill, jitter } = validateOptionalScheduleFields(input);
-  return { type, spec, id, overlap, backfill, jitter };
+  const { type, spec } = validateRequiredScheduleFields(input), { id, description, overlap, backfill, jitter } = validateOptionalScheduleFields(input);
+  return { type, spec, id, description, overlap, backfill, jitter };
 }
 export const createScheduleOperation = defineOperation({
   name: "weft.schedules.create",
@@ -77,6 +85,7 @@ export const createScheduleOperation = defineOperation({
   invoke: async ({ input, engine }) => {
     const typedEngine = engine, validated = validateCreateScheduleInput(input), options = {
       ...validated.id !== void 0 ? { id: validated.id } : {},
+      ...validated.description !== void 0 ? { description: validated.description } : {},
       ...validated.overlap !== void 0 ? { overlap: validated.overlap } : {},
       ...validated.backfill !== void 0 ? { backfill: validated.backfill } : {},
       ...validated.jitter !== void 0 ? { jitter: validated.jitter } : {}
@@ -102,6 +111,7 @@ export const createScheduleRestBinding = {
     every: { kind: "body-field", bodyField: "every" },
     input: { kind: "body-field", bodyField: "input" },
     id: { kind: "body-field", bodyField: "id" },
+    description: { kind: "body-field", bodyField: "description" },
     overlap: { kind: "body-field", bodyField: "overlap" },
     backfill: { kind: "body-field", bodyField: "backfill" },
     jitter: { kind: "body-field", bodyField: "jitter" }
@@ -124,6 +134,7 @@ export const createScheduleRestBinding = {
       every: Object.hasOwn(record, "every") ? record.every : void 0,
       input: record.input,
       id: record.id,
+      description: record.description,
       overlap: record.overlap,
       backfill: record.backfill,
       jitter: record.jitter

package/dist/server/principal.d.ts

@@ -9,12 +9,12 @@
  * Credential *validation* (signature verification, expiry, revocation, format
  * checks) is the transport edge's responsibility — these factories assume the
  * inputs they receive describe a credential that has already been accepted.
+ * This stable principal model ensures consistent authentication across all
+ * transport layers.
  *
  * The discriminator string for API keys is `'api-key'` (kebab-case) to match
  * the existing `AuthMethod` literal in `authentication.ts`. Keep them aligned;
  * the bridge from `AuthResult` to `Principal` relies on byte-identical strings.
- *
- * See Track 8 design decisions 3 and 10.
  */
 import { type AuthorizationScope } from './authorization-scope.ts';
 /**

package/dist/server/rest-binding.d.ts

@@ -131,7 +131,7 @@ export type RestBinding<Input, Output> = {
      * detail (for example, `get-workflow-result` returns the custom message
      * `"Timeout waiting for workflow result"` on a `Timeout`, and `get-stream-chunks`
      * handles `InvalidParams` inline). This per-operation hook is the current
-     * contract, not a transitional shim.
+     * contract.
      */
     readonly shapeFault?: (fault: OperationFault) => Response;
 };

package/dist/server/runtime/task-dispatch.js

@@ -74,6 +74,7 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
     visibilityTimeout,
     retryPolicy: task.retryPolicy,
     workflowId: task.workflowId,
+    workflowExecutionToken: task.workflowExecutionToken,
     attemptToken
   }, normalizedInflightRecord = await transitionQueuedToInflight(options.engine.storage, task.operationId, inflightRecord, {
     queuedRecord: existingQueuedRecord,
@@ -86,6 +87,9 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
     input: task.input === void 0 ? null : task.input,
     attempt: task.attempt ?? 1,
     attemptToken,
+    ...task.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: task.workflowExecutionToken
+    },
     ...task.headers ? { headers: task.headers } : {}
   }));
   recordTaskQueueLatencyMetric(context.metricsCollector, normalizedInflightRecord);
@@ -116,6 +120,7 @@ async function enqueueTaskForLongPoll(context, options, task, queue, visibilityT
     retryPolicy: task.retryPolicy,
     queuedAt: Date.now(),
     workflowId: task.workflowId,
+    workflowExecutionToken: task.workflowExecutionToken,
     retryCount: Math.max(0, attempt - 1),
     requeueCount: 0
   }, existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId), normalizedQueuedRecord = await markQueued(options.engine.storage, mergeQueuedRecordLifecycle(freshRecord, existingQueuedRecord)), enqueued = context.taskQueue.enqueue(queue, {
@@ -126,6 +131,7 @@ async function enqueueTaskForLongPoll(context, options, task, queue, visibilityT
     retryPolicy: task.retryPolicy,
     visibilityTimeout,
     workflowId: task.workflowId,
+    workflowExecutionToken: task.workflowExecutionToken,
     firstQueuedAt: normalizedQueuedRecord.firstQueuedAt,
     lastQueuedAt: normalizedQueuedRecord.lastQueuedAt,
     lastDispatchedAt: normalizedQueuedRecord.lastDispatchedAt,

package/dist/server/runtime/task-polling.js

@@ -98,6 +98,7 @@ export function createLongPollInflightRecord(queue, task) {
     visibilityTimeout,
     retryPolicy: task.retryPolicy,
     workflowId: task.workflowId,
+    workflowExecutionToken: task.workflowExecutionToken,
     attemptToken: crypto.randomUUID(),
     firstQueuedAt: task.firstQueuedAt ?? task.enqueuedAt ?? now,
     lastQueuedAt: task.lastQueuedAt ?? task.enqueuedAt ?? now,
@@ -139,7 +140,14 @@ export async function handleTaskPollRequest(context, options, request, url, prin
   const rawTimeout = url.searchParams.get("timeout"), timeout = rawTimeout !== null ? Math.min(Math.max(0, Number(rawTimeout)), MAX_POLL_TIMEOUT) : DEFAULT_POLL_TIMEOUT, task = await context.taskQueue.poll(queue, activities, timeout, request.signal);
   if (task !== null) {
     const claim = await markTaskClaimedByLongPollWorker(context, options, queue, task);
-    return Response.json({ ...task, workerId: claim.workerId, attemptToken: claim.attemptToken });
+    return Response.json({
+      ...task,
+      workerId: claim.workerId,
+      attemptToken: claim.attemptToken,
+      ...task.workflowExecutionToken !== void 0 && {
+        workflowExecutionToken: task.workflowExecutionToken
+      }
+    });
   }
   return new Response(null, { status: 204 });
 }

package/dist/server/runtime/task-reconciliation.js

@@ -68,7 +68,8 @@ function createRequeuedTaskDispatch(record, nextAttempt) {
     queue: record.queue,
     attempt: nextAttempt,
     visibilityTimeout: record.visibilityTimeout,
-    workflowId: record.workflowId
+    workflowId: record.workflowId,
+    workflowExecutionToken: record.workflowExecutionToken
   };
   if (record.retryPolicy !== void 0)
     taskDispatch.retryPolicy = record.retryPolicy;

package/dist/server/stdio-session.d.ts

@@ -2,10 +2,10 @@
  * Runtime JSON-RPC stdio session.
  *
  * `runStdioSession({ input, output, admission, registry, engine, feed, ... })`
- * drives the `weft rpc-stdio` CLI subcommand (Track 8 design decision
- * 19). It reads newline-delimited JSON frames from `input`, runs each
- * through the same `createJsonRpcWebSocketSession` session the WS
- * adapter uses, and writes responses to `output`.
+ * drives the `weft rpc-stdio` CLI subcommand. It implements the stable
+ * JSON-RPC stdio transport: reading newline-delimited JSON frames from
+ * `input`, running each through the JSON-RPC dispatcher, and writing
+ * responses to `output`.
  *
  * Admission is mandatory:
  *   - `{ kind: 'startup-token', token }` — the first frame must be a

package/dist/server/task-queue-types.d.ts

@@ -13,6 +13,8 @@ export interface PendingTask extends TaskLifecycleFields {
     headers?: Record<string, string> | undefined;
     /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
     workflowId?: string | undefined;
+    /** Durable token for the workflow run that dispatched this activity, when known. */
+    workflowExecutionToken?: string | undefined;
     /**
      * Task priority. Higher values are dequeued first. Tasks with equal priority
      * maintain FIFO order. Default: 0. Agent workflow tasks use priority 10.

package/dist/server/task-state.d.ts

@@ -55,6 +55,8 @@ export interface QueuedRecord extends TaskLifecycleFields {
     queuedAt: number;
     /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
     workflowId?: string | undefined;
+    /** Durable token for the workflow run that dispatched this activity, when known. */
+    workflowExecutionToken?: string | undefined;
 }
 /** Persisted record for a task in the inflight state. */
 export interface InflightRecord extends TaskLifecycleFields {
@@ -69,6 +71,8 @@ export interface InflightRecord extends TaskLifecycleFields {
     retryPolicy?: RetryPolicy | undefined;
     /** Workflow that dispatched this activity. Present when the dispatch included a workflowId. */
     workflowId?: string | undefined;
+    /** Durable token for the workflow run that dispatched this activity, when known. */
+    workflowExecutionToken?: string | undefined;
     /**
      * Unique, unguessable token identifying this dispatch attempt. Rotated on every
      * (re-)dispatch because each dispatch writes a fresh InflightRecord. The

package/dist/service-worker/index.d.ts

@@ -7,8 +7,10 @@
  * @module service-worker
  */
 import type { Engine } from '../core/engine';
-import type { ServiceWorkerScheduler } from './scheduler';
+import type { ServiceWorkerScheduler } from './scheduler.ts';
 import type { MinimalExtendableEvent, MinimalFetchEvent, MinimalPeriodicSyncEvent } from './shared.ts';
+export { ServiceWorkerScheduler } from './scheduler.ts';
+export type { ServiceWorkerSchedulerOptions } from './scheduler.ts';
 export { buildDelegatedRequest, DEFAULT_PERIODIC_SYNC_TAG, normalizePathPrefix } from './shared.ts';
 export type { MinimalExtendableEvent, MinimalFetchEvent, MinimalPeriodicSyncEvent, } from './shared.ts';
 /**
@@ -73,21 +75,20 @@ export declare function createFetchHandler(options: ServiceWorkerOptions): (even
  * `event.waitUntil(...)` so the sync extends until the tick promise
  * resolves.
  *
- * Note: `ServiceWorkerScheduler` is the parameter type but is not currently
- * re-exported from `@lostgradient/weft/service-worker` — construct the scheduler in the
- * module that imports it directly (e.g. the dashboard runtime) and pass
- * the instance to this factory.
- *
  * @example
  * ```ts
- * import { createPeriodicSyncHandler } from '@lostgradient/weft/service-worker';
- *
- * // In your Service Worker (with a scheduler from the runtime that imports it):
- * declare const scheduler: { tick(): Promise<void> };
- * const handler = createPeriodicSyncHandler(
- *   scheduler as Parameters<typeof createPeriodicSyncHandler>[0],
- *   'weft-timers',
- * );
+ * import { ServiceWorkerScheduler, createPeriodicSyncHandler } from '@lostgradient/weft/service-worker';
+ * import { MemoryStorage } from '@lostgradient/weft';
+ *
+ * const storage = new MemoryStorage();
+ *
+ * const scheduler = new ServiceWorkerScheduler({
+ *   storage,
+ *   onTimerFired: (entry) => {
+ *     console.log(`Timer ${entry.id} fired.`);
+ *   },
+ * });
+ * const handler = createPeriodicSyncHandler(scheduler, 'weft-timers');
  * // self.addEventListener('periodicsync', handler);
  * console.log(typeof handler); // 'function'
  * ```