@lostgradient/weft 0.11.0 → 0.13.0

package/dist/client/client-storage.d.ts

@@ -0,0 +1,24 @@
+import { type BatchOperation, type ConditionalBatchCondition, type ScanOptions, type Storage } from '../storage/interface.ts';
+/**
+ * Byte-oriented raw storage surface shared by local and HTTP clients.
+ *
+ * @example
+ * ```ts
+ * import { Engine, LocalClient, MemoryStorage, type WeftClientStorage } from '@lostgradient/weft';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * const client = new LocalClient(engine);
+ * const storage: WeftClientStorage = client.storage;
+ * await storage.put('example:key', new TextEncoder().encode('value'));
+ * ```
+ */
+export interface WeftClientStorage {
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan(prefix: string, options?: ScanOptions): AsyncIterable<[string, Uint8Array]>;
+    batch(operations: BatchOperation[]): Promise<void>;
+    conditionalBatch(conditions: ConditionalBatchCondition[], operations: BatchOperation[]): Promise<boolean>;
+}
+/** Adapt an engine-owned storage backend without exposing adapter-only methods. */
+export declare function createLocalClientStorage(storage: Storage): WeftClientStorage;

package/dist/client/client-storage.js

@@ -0,0 +1,14 @@
+import {
+  storageBatch,
+  storageConditionalBatch
+} from "../storage/interface.js";
+export function createLocalClientStorage(storage) {
+  return {
+    get: (key) => storage.get(key),
+    put: (key, value) => storage.put(key, value),
+    delete: (key) => storage.delete(key),
+    scan: (prefix, options) => storage.scan(prefix, options),
+    batch: (operations) => storageBatch(storage, operations),
+    conditionalBatch: (conditions, operations) => storageConditionalBatch(storage, conditions, operations)
+  };
+}

package/dist/client/handle-delegation.d.ts

@@ -1,5 +1,5 @@
 import type { WeftEventMap } from '../core/events.ts';
-import type { QueryDefinition, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition } from '../core/types.ts';
+import type { QueryDefinition, ScheduleSpec, ScheduleSummary, ScheduleUpdateOptions, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition } from '../core/types.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import type { ClientHandle, ClientScheduleHandle, StartOrSignalOutcome } from './interface.ts';
 export interface WorkflowHandleDelegationClient {
@@ -62,7 +62,7 @@ export interface ScheduleHandleDelegationClient {
     pauseSchedule(id: string): Promise<void>;
     resumeSchedule(id: string): Promise<void>;
     cancelSchedule(id: string): Promise<void>;
-    updateSchedule(id: string, newSpec: string | ScheduleSpec): Promise<void>;
+    updateSchedule(id: string, newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
     getSchedule(id: string): Promise<ScheduleSummary | null>;
 }
 export declare abstract class ScheduleHandleDelegation<TClient extends ScheduleHandleDelegationClient = ScheduleHandleDelegationClient> implements ClientScheduleHandle {
@@ -72,7 +72,7 @@ export declare abstract class ScheduleHandleDelegation<TClient extends ScheduleH
     pause(): Promise<void>;
     resume(): Promise<void>;
     cancel(): Promise<void>;
-    update(newSpec: string | ScheduleSpec): Promise<void>;
+    update(newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
     describe(): Promise<ScheduleSummary | null>;
     abstract [Symbol.dispose](): void;
 }

package/dist/client/handle-delegation.js

@@ -65,8 +65,8 @@ export class ScheduleHandleDelegation {
   async cancel() {
     return this.client.cancelSchedule(this.id);
   }
-  async update(newSpec) {
-    return this.client.updateSchedule(this.id, newSpec);
+  async update(newSpec, options) {
+    return this.client.updateSchedule(this.id, newSpec, options);
   }
   async describe() {
     return this.client.getSchedule(this.id);

package/dist/client/http-client-requests.d.ts

@@ -1,5 +1,5 @@
 import type { StoredStreamChunk } from '../core/context.ts';
-import type { BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PurgeResult, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDeliveryOptions, SubmitReviewOptions, WorkflowReplay, WorkflowState, WorkflowTimelineEntry } from '../core/types.ts';
+import type { BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PendingAsyncActivityListOptions, PendingAsyncActivityPage, PurgeResult, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleSpec, ScheduleSummary, ScheduleUpdateOptions, SearchAttributeValue, SignalDeliveryOptions, SubmitReviewOptions, WorkflowReplay, WorkflowState, WorkflowTimelineEntry } from '../core/types.ts';
 import type { UpdateResult } from './interface.ts';
 export type HttpClientRequestContext = {
     readonly baseUrl: string;
@@ -37,6 +37,8 @@ export declare function signalWorkflowRequest(context: HttpClientRequestContext,
  * workflow with `result`. Mirrors `LocalClient.activity.complete` over HTTP.
  */
 export declare function completeAsyncActivityRequest(context: HttpClientRequestContext, token: string, result?: unknown): Promise<void>;
+/** List durable async activities awaiting completion for one workflow. */
+export declare function listPendingAsyncActivitiesRequest(context: HttpClientRequestContext, workflowId: string, options?: PendingAsyncActivityListOptions): Promise<PendingAsyncActivityPage>;
 /**
  * Fail a deferred ("async") activity by task token. A live `Error` cannot cross
  * the wire, so the error is reduced to `message` + `name` — exactly the fields
@@ -59,8 +61,8 @@ export declare function pauseScheduleRequest(context: HttpClientRequestContext,
 export declare function resumeScheduleRequest(context: HttpClientRequestContext, id: string): Promise<void>;
 /** Cancel a recurring schedule (`DELETE /v1/schedules/:id`). */
 export declare function cancelScheduleRequest(context: HttpClientRequestContext, id: string): Promise<void>;
-/** Update a schedule's recurrence specification (`PATCH /v1/schedules/:id`). */
-export declare function updateScheduleRequest(context: HttpClientRequestContext, id: string, newSpec: string | ScheduleSpec): Promise<void>;
+/** Update a schedule's cadence and mutable options (`PATCH /v1/schedules/:id`). */
+export declare function updateScheduleRequest(context: HttpClientRequestContext, id: string, newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
 /**
  * Query a named read-only accessor on a workflow. A no-input query is a GET;
  * an input payload is sent as a POST body.

package/dist/client/http-client-requests.js

@@ -139,6 +139,15 @@ export async function completeAsyncActivityRequest(context, token, result) {
     body: JSON.stringify({ token, result })
   });
 }
+export async function listPendingAsyncActivitiesRequest(context, workflowId, options) {
+  const search = new URLSearchParams;
+  if (options?.limit !== void 0)
+    search.set("limit", String(options.limit));
+  if (options?.cursor !== void 0)
+    search.set("cursor", options.cursor);
+  const query = search.size > 0 ? `?${search.toString()}` : "";
+  return request(context.baseUrl, `/workflows/${encodeURIComponent(workflowId)}/pending-async-activities${query}`, context.headers);
+}
 export async function failAsyncActivityRequest(context, token, error) {
   const reduced = { message: error instanceof Error ? error.message : String(error) };
   if (error instanceof Error)
@@ -176,10 +185,19 @@ export function cancelScheduleRequest(context, id) {
     method: "DELETE"
   });
 }
-export function updateScheduleRequest(context, id, newSpec) {
+export function updateScheduleRequest(context, id, newSpec, options) {
+  const body = scheduleSpecToWireFields(newSpec);
+  if (options?.description !== void 0)
+    body.description = options.description;
+  if (options?.overlap !== void 0)
+    body.overlap = options.overlap;
+  if (options?.backfill !== void 0)
+    body.backfill = options.backfill;
+  if (options?.jitter !== void 0)
+    body.jitter = options.jitter;
   return request(context.baseUrl, `/schedules/${encodeURIComponent(id)}`, context.headers, {
     method: "PATCH",
-    body: JSON.stringify(scheduleSpecToWireFields(newSpec))
+    body: JSON.stringify(body)
   });
 }
 export async function queryWorkflowRequest(context, id, name, input) {

package/dist/client/http-client-storage.d.ts

@@ -0,0 +1,3 @@
+import type { WeftClientStorage } from './client-storage.ts';
+/** Build the raw-storage facade over the six specialized REST bindings. */
+export declare function createHttpClientStorage(baseUrl: string, headers: Record<string, string>): WeftClientStorage;

package/dist/client/http-client-storage.js

@@ -0,0 +1,110 @@
+import { decodeBase64ToBytes, encodeBytesToBase64, isRecord } from "../storage/byte-encoding.js";
+import {
+  assertStorageBatchOperationCount
+} from "../storage/interface.js";
+import { request, requestResponse } from "./http-request.js";
+const MAX_SCAN_RESPONSE_BYTES = 67108864;
+function encodeOperation(operation) {
+  return operation.type === "put" ? { type: "put", key: operation.key, value: encodeBytesToBase64(operation.value) } : { type: "delete", key: operation.key };
+}
+function scanPath(prefix, options) {
+  const parameters = new URLSearchParams({ prefix });
+  for (const [name, value] of Object.entries(options))
+    if (value !== void 0)
+      parameters.set(name, String(value));
+  return `/storage?${parameters.toString()}`;
+}
+function scanEntry(value) {
+  if (!isRecord(value) || typeof value.key !== "string" || typeof value.value !== "string")
+    throw Error("HttpClient storage scan response contained an invalid NDJSON entry.");
+  return [value.key, decodeBase64ToBytes(value.value)];
+}
+async function releaseScanReader(reader, reachedEndOfStream) {
+  if (!reachedEndOfStream)
+    try {
+      await reader.cancel();
+    } catch {}
+  reader.releaseLock();
+}
+async function* scanResponse(response) {
+  if (response.body === null)
+    return;
+  const reader = response.body.getReader(), decoder = new TextDecoder;
+  let bufferedText = "", bytesRead = 0, reachedEndOfStream = !1;
+  try {
+    while (!0) {
+      const { done, value } = await reader.read();
+      if (done) {
+        reachedEndOfStream = !0;
+        break;
+      }
+      bytesRead += value.byteLength;
+      if (bytesRead > MAX_SCAN_RESPONSE_BYTES)
+        throw Error("HttpClient storage scan response exceeded the maximum allowed size.");
+      bufferedText += decoder.decode(value, { stream: !0 });
+      const lines = bufferedText.split(`
+`);
+      bufferedText = lines.pop() ?? "";
+      for (const line of lines)
+        if (line.trim().length > 0)
+          yield scanEntry(JSON.parse(line));
+    }
+    bufferedText += decoder.decode();
+    if (bufferedText.trim().length > 0)
+      yield scanEntry(JSON.parse(bufferedText));
+  } finally {
+    await releaseScanReader(reader, reachedEndOfStream);
+  }
+}
+export function createHttpClientStorage(baseUrl, headers) {
+  return {
+    async get(key) {
+      const response = await requestResponse(baseUrl, `/storage/${encodeURIComponent(key)}`, headers, { method: "GET" });
+      return response === null ? null : new Uint8Array(await response.arrayBuffer());
+    },
+    async put(key, value) {
+      await requestResponse(baseUrl, `/storage/${encodeURIComponent(key)}`, headers, {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: new Blob([value])
+      });
+    },
+    async delete(key) {
+      await requestResponse(baseUrl, `/storage/${encodeURIComponent(key)}`, headers, {
+        method: "DELETE"
+      });
+    },
+    async* scan(prefix, options = {}) {
+      const response = await requestResponse(baseUrl, scanPath(prefix, options), headers, {
+        method: "GET",
+        headers: { accept: "application/x-ndjson" }
+      });
+      if (response !== null)
+        yield* scanResponse(response);
+    },
+    async batch(operations) {
+      assertStorageBatchOperationCount("batch operations", operations.length);
+      await request(baseUrl, "/storage/-/batch", headers, {
+        method: "POST",
+        body: JSON.stringify({ operations: operations.map(encodeOperation) })
+      });
+    },
+    async conditionalBatch(conditions, operations) {
+      assertStorageBatchOperationCount("conditionalBatch conditions", conditions.length);
+      assertStorageBatchOperationCount("conditionalBatch operations", operations.length);
+      const result = await request(baseUrl, "/storage/-/conditional-batch", headers, {
+        method: "POST",
+        body: JSON.stringify({
+          conditions: conditions.map((condition) => ({
+            key: condition.key,
+            expectedValue: condition.expectedValue === null ? null : encodeBytesToBase64(condition.expectedValue)
+          })),
+          operations: operations.map(encodeOperation)
+        })
+      });
+      if (!isRecord(result) || typeof result.applied !== "boolean")
+        throw Error('HttpClient storage conditional batch response must include a boolean "applied" field.');
+      return result.applied;
+    }
+  };
+}

package/dist/client/http-client.d.ts

@@ -1,6 +1,7 @@
-import { type CatalogOperationName, type CatalogOperationTypes, type WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
+import { type ClientOperationName, type ClientOperationTypes, type ClientOperations } from '../cli/generated/operation-client.generated.ts';
 import type { StoredStreamChunk } from '../core/context.ts';
-import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, ScheduleUpdateOptions, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { WeftClientStorage } from './client-storage.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import { type HttpClientOptions } from './http-request.ts';
 import type { ClientHandle, ClientScheduleHandle, ClientStartOptions, ClientStartOrSignalOptions, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
@@ -49,15 +50,17 @@ export declare class HttpClient implements WeftClient {
     readonly baseUrl: string;
     /** @internal Exposed for handle access. */
     readonly headers: Record<string, string>;
-    /** Typed low-level accessor for every catalog operation over JSON-RPC. */
-    readonly operations: CatalogOperations;
+    /** Typed low-level accessor over JSON-RPC and generated ordinary REST bindings. */
+    readonly operations: ClientOperations;
+    /** Raw storage administration over the byte-oriented REST bindings. */
+    readonly storage: WeftClientStorage;
     /**
      * Out-of-band ("async") activity completion over HTTP. POSTs to
      * `/v1/activities/{complete,fail}`; mirrors {@link LocalClient}'s `activity`.
      */
     readonly activity: WeftClientActivity;
     constructor(options?: HttpClientOptions);
-    call<Name extends CatalogOperationName>(name: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogOperationTypes[Name]['output']>;
+    call<Name extends ClientOperationName>(name: Name, input: ClientOperationTypes[Name]['input']): Promise<ClientOperationTypes[Name]['output']>;
     start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
     start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: ClientStartOptions): Promise<ClientHandle>;
     startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
@@ -75,7 +78,7 @@ export declare class HttpClient implements WeftClient {
     pauseSchedule(id: string): Promise<void>;
     resumeSchedule(id: string): Promise<void>;
     cancelSchedule(id: string): Promise<void>;
-    updateSchedule(id: string, newSpec: string | ScheduleSpec): Promise<void>;
+    updateSchedule(id: string, newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
     signal(id: string, name: SignalDefinition): Promise<void>;
     signal<TInput>(id: string, name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
     signal(id: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;

package/dist/client/http-client.js

@@ -1,5 +1,6 @@
 import {
-  CATALOG_OPERATION_NAMES
+  CLIENT_OPERATION_NAMES,
+  CLIENT_REST_OPERATION_BINDINGS
 } from "../cli/generated/operation-client.generated.js";
 import { createCatalogWeftClient } from "../cli/operation-client-runtime.js";
 import { messageName } from "../core/types.js";
@@ -19,6 +20,7 @@ import {
   getTimelineRequest,
   getUpdateResultRequest,
   getWorkflowRequest,
+  listPendingAsyncActivitiesRequest,
   listReviewRequests,
   pauseScheduleRequest,
   purgeWorkflowRequests,
@@ -38,27 +40,31 @@ import {
   untagAllWorkflowRequests,
   updateScheduleRequest
 } from "./http-client-requests.js";
+import { createHttpClientStorage } from "./http-client-storage.js";
 import { HttpHandle } from "./http-handle.js";
-import { httpClientCatalogTransport } from "./http-operations.js";
+import { httpClientOperationTransport } from "./http-operations.js";
 import { request, resolveHttpClientConnection } from "./http-request.js";
 import { HttpScheduleHandle } from "./http-schedule-handle.js";
 import { openClientEventSubscription } from "./open-event-subscription.js";
 import { buildScheduleListSearchParams } from "./schedule-list-search-params.js";
 import { buildWorkflowListSearchParams } from "./search-params.js";
-import { buildStartBody, buildStartOrSignalBody, scheduleSpecToWireFields } from "./start-body.js";
+import { buildScheduleBody, buildStartBody, buildStartOrSignalBody } from "./start-body.js";
 
 export class HttpClient {
   baseUrl;
   headers;
   operations;
+  storage;
   activity;
   #streamOptions;
   constructor(options = {}) {
     const connection = resolveHttpClientConnection(options);
     this.baseUrl = connection.baseUrl;
     this.headers = connection.headers;
-    this.operations = createCatalogWeftClient(CATALOG_OPERATION_NAMES, httpClientCatalogTransport(this.baseUrl, this.headers));
+    this.operations = createCatalogWeftClient(CLIENT_OPERATION_NAMES, httpClientOperationTransport(this.baseUrl, this.headers, CLIENT_REST_OPERATION_BINDINGS));
+    this.storage = createHttpClientStorage(this.baseUrl, this.headers);
     this.activity = {
+      listPending: (workflowId, listOptions) => listPendingAsyncActivitiesRequest(this, workflowId, listOptions),
       complete: (token, result) => completeAsyncActivityRequest(this, token, result),
       completeExceptionally: (token, error) => failAsyncActivityRequest(this, token, error)
     };
@@ -82,18 +88,7 @@ export class HttpClient {
     return new HttpHandle(response.id, this, response.outcome);
   }
   async schedule(type, input, spec, options) {
-    const body = {
-      type,
-      input,
-      ...scheduleSpecToWireFields(spec)
-    };
-    if (options?.id !== void 0)
-      body.id = options.id;
-    if (options?.overlap !== void 0)
-      body.overlap = options.overlap;
-    if (options?.backfill !== void 0)
-      body.backfill = options.backfill;
-    const response = await request(this.baseUrl, "/schedules", this.headers, {
+    const body = buildScheduleBody(type, input, spec, options), response = await request(this.baseUrl, "/schedules", this.headers, {
       method: "POST",
       body: JSON.stringify(body)
     });
@@ -133,8 +128,8 @@ export class HttpClient {
   async cancelSchedule(id) {
     return cancelScheduleRequest(this, id);
   }
-  async updateSchedule(id, newSpec) {
-    return updateScheduleRequest(this, id, newSpec);
+  async updateSchedule(id, newSpec, options) {
+    return updateScheduleRequest(this, id, newSpec, options);
   }
   async signal(id, nameOrDefinition, payload, options) {
     await signalWorkflowRequest(this, id, messageName(nameOrDefinition), payload, options);

package/dist/client/http-operations.d.ts

@@ -10,7 +10,7 @@
  *
  * @module client/http-operations
  */
-import type { CatalogTransport } from '../cli/operation-client-runtime.ts';
+import type { CatalogTransport, ClientRestOperationBinding } from '../cli/operation-client-runtime.ts';
 /**
  * Build a {@link CatalogTransport} that dispatches catalog operations as
  * JSON-RPC requests to a remote Weft server at `${baseUrl}/jsonrpc`.
@@ -27,3 +27,5 @@ import type { CatalogTransport } from '../cli/operation-client-runtime.ts';
  * `HttpClientError` rather than a raw `SyntaxError`.
  */
 export declare function httpClientCatalogTransport(baseUrl: string, headers: Record<string, string>): CatalogTransport;
+/** Route generated client operations over JSON-RPC or ordinary REST metadata. */
+export declare function httpClientOperationTransport(baseUrl: string, headers: Record<string, string>, restBindings: Readonly<Record<string, ClientRestOperationBinding>>): CatalogTransport;

package/dist/client/http-operations.js

@@ -1,11 +1,14 @@
 import { isFaultCode } from "../core/fault-code.js";
-import { HttpClientError } from "./http-request.js";
+import { HttpClientError, request } from "./http-request.js";
 function isJsonRpcFailure(value) {
   return typeof value === "object" && value !== null && "error" in value && typeof value.error === "object" && value.error !== null && "message" in value.error && typeof value.error.message === "string";
 }
 function isJsonRpcSuccess(value) {
   return typeof value === "object" && value !== null && "result" in value;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 export function httpClientCatalogTransport(baseUrl, headers) {
   const endpoint = `${baseUrl}/jsonrpc`;
   return async (operationName, input) => {
@@ -27,10 +30,89 @@ export function httpClientCatalogTransport(baseUrl, headers) {
     }
     if (isJsonRpcFailure(body)) {
       const { message, data } = body.error, httpStatus = typeof data?.httpStatus === "number" ? data.httpStatus : response.status, faultCode = isFaultCode(data?.weftCode) ? data.weftCode : void 0;
-      throw new HttpClientError(httpStatus, message, { faultCode });
+      throw new HttpClientError(httpStatus, message, {
+        faultCode,
+        data: isRecord(data) ? data : void 0
+      });
     }
     if (isJsonRpcSuccess(body))
       return body.result;
     throw new HttpClientError(response.status, `Invalid JSON-RPC response from ${endpoint}`);
   };
 }
+function inputRecord(operationName, input) {
+  if (isRecord(input))
+    return input;
+  throw new HttpClientError(400, `Operation ${operationName} input must be an object.`);
+}
+function requiredString(operationName, field, value) {
+  if (typeof value === "string" && value.length > 0)
+    return value;
+  throw new HttpClientError(400, `Operation ${operationName} requires a non-empty string "${field}" field.`);
+}
+function restParameterValue(operationName, field, value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  throw new HttpClientError(400, `Operation ${operationName} requires a string, number, or boolean "${field}" field.`);
+}
+function appendQueryValues(projection, operationName, field, queryParameter, value, repeating) {
+  if (repeating && Array.isArray(value)) {
+    for (const entry of value)
+      projection.searchParameters.append(queryParameter, restParameterValue(operationName, field, entry));
+    return;
+  }
+  projection.searchParameters.set(queryParameter, restParameterValue(operationName, field, value));
+}
+function projectRestInput(projection, operationName, field, source, value) {
+  if (source.kind === "path") {
+    const pathValue = requiredString(operationName, field, value);
+    projection.path = projection.path.replaceAll(`:${source.pathParam}`, encodeURIComponent(pathValue));
+    return;
+  }
+  if (value === void 0)
+    return;
+  if (source.kind === "query") {
+    appendQueryValues(projection, operationName, field, source.queryParam, value, source.repeating === !0);
+    return;
+  }
+  if (source.kind === "header") {
+    projection.requestHeaders.set(source.headerName, restParameterValue(operationName, field, value));
+    return;
+  }
+  if (source.kind === "body-field") {
+    projection.bodyFields[source.bodyField] = value;
+    return;
+  }
+  projection.directBody = value;
+  projection.directBodyMediaType = source.mediaType ?? "application/json";
+}
+async function callRestOperation(baseUrl, headers, operationName, binding, input) {
+  const fields = inputRecord(operationName, input), projection = {
+    path: binding.path,
+    searchParameters: new URLSearchParams,
+    requestHeaders: new Headers,
+    bodyFields: {},
+    directBody: void 0,
+    directBodyMediaType: void 0
+  };
+  for (const [field, source] of Object.entries(binding.inputSources))
+    projectRestInput(projection, operationName, field, source, fields[field]);
+  const query = projection.searchParameters.toString();
+  if (query.length > 0)
+    projection.path += `?${query}`;
+  const hasBodyFields = Object.keys(projection.bodyFields).length > 0, body = projection.directBody === void 0 ? hasBodyFields ? projection.bodyFields : void 0 : projection.directBody;
+  if (body !== void 0)
+    projection.requestHeaders.set("content-type", projection.directBodyMediaType ?? "application/json");
+  return request(baseUrl, projection.path, headers, {
+    method: binding.method,
+    ...[...projection.requestHeaders].length === 0 ? {} : { headers: projection.requestHeaders },
+    ...body === void 0 ? {} : { body: JSON.stringify(body) }
+  });
+}
+export function httpClientOperationTransport(baseUrl, headers, restBindings) {
+  const jsonRpc = httpClientCatalogTransport(baseUrl, headers);
+  return (operationName, input) => {
+    const restBinding = restBindings[operationName];
+    return restBinding === void 0 ? jsonRpc(operationName, input) : callRestOperation(baseUrl, headers, operationName, restBinding, input);
+  };
+}

package/dist/client/http-request.d.ts

@@ -63,11 +63,15 @@ export declare function resolveHttpClientConnection(options: HttpClientOptions):
 /**
  * Error thrown when the server returns a non-2xx response.
  *
- * When the server sends a structured fault body (`{ error: { code, message } }`),
- * the wire fault `code` is surfaced as {@link HttpClientError.faultCode} and a
- * derived {@link HttpClientError.category} so callers can branch programmatically
- * instead of string-matching `message`. Both are `undefined` when the body is a
- * plain `{ error: string }` or carries no recognized code.
+ * When the server sends a fault body with a recognized coarse `code`, the wire
+ * value is surfaced as {@link HttpClientError.faultCode} with a derived
+ * {@link HttpClientError.category}, so callers can branch without
+ * string-matching `message`. Both are `undefined` for the production flat REST
+ * body, which carries no coarse code. The fault's typed
+ * `data` payload (e.g. `InvalidParams`'s `issues`, `NotFound`/`Conflict`'s
+ * `resource`/`identifier`) is surfaced verbatim as {@link HttpClientError.data}
+ * when the body carries an audited `data` object; `undefined` otherwise —
+ * including for a masked `EngineFailure`, whose flat body carries no `data`.
  *
  * @example
  * ```ts
@@ -78,7 +82,7 @@ export declare function resolveHttpClientConnection(options: HttpClientOptions):
  *   await client.cancel('nonexistent-id');
  * } catch (err) {
  *   if (err instanceof HttpClientError) {
- *     if (err.faultCode === 'NotFound') {
+ *     if (err.status === 404 && err.data?.['resource'] === 'workflow') {
  *       // handle a missing resource specifically
  *     } else if (err.category === 'resource') {
  *       // back off on rate limits and capacity faults
@@ -110,9 +114,34 @@ export declare class HttpClientError extends WeftError<'HttpClientError'> {
      * carried only the coarse {@link faultCode} (most faults) or no structured body.
      */
     readonly weftCode?: WeftErrorCode | undefined;
+    /**
+     * The fault's wire `data` payload, when the response carried a structured
+     * body (`{ error, data }` for production REST, nested `{ error: { data } }`
+     * for structured REST responses, or `error.data` for JSON-RPC). Shape is
+     * fault-code-dependent — see {@link FaultCode} and the server's
+     * `OperationFault` per-code `data` union for what each code carries (e.g.
+     * `InvalidParams.data.issues`, `NotFound.data.resource`). `undefined` for
+     * plain-string error bodies, bodies with no `data` field, or a `data` field
+     * that is not a JSON object.
+     *
+     * Over JSON-RPC-over-HTTP this is the raw envelope `error.data` verbatim
+     * (see `httpClientCatalogTransport` in `http-operations.ts`), so it also
+     * carries the envelope's own `weftCode` (the coarse {@link FaultCode}, not
+     * a fine-grained {@link WeftErrorCode}) and `httpStatus` keys alongside the
+     * per-code payload — those two are not part of the `OperationFault` data
+     * union.
+     */
+    readonly data?: Readonly<Record<string, unknown>> | undefined;
     constructor(status: number, message: string, options?: {
         faultCode?: FaultCode | undefined;
         weftCode?: WeftErrorCode | undefined;
+        data?: Readonly<Record<string, unknown>> | undefined;
     });
 }
 export declare function request<T>(baseUrl: string, path: string, baseHeaders: Record<string, string>, options?: RequestInit): Promise<T>;
+/**
+ * Execute a REST request with the canonical {@link HttpClientError} shaping
+ * while leaving the successful response body available to binary or streaming
+ * client surfaces.
+ */
+export declare function requestResponse(baseUrl: string, path: string, baseHeaders: Record<string, string>, options?: RequestInit): Promise<Response | null>;

package/dist/client/http-request.js

@@ -17,12 +17,14 @@ export class HttpClientError extends WeftError {
   faultCode;
   category;
   weftCode;
+  data;
   constructor(status, message, options) {
     super("HttpClientError", message);
     this.status = status;
     this.faultCode = options?.faultCode;
     this.category = options?.faultCode === void 0 ? void 0 : failureCategoryForFaultCode(options.faultCode);
     this.weftCode = options?.weftCode;
+    this.data = options?.data;
   }
 }
 function buildRequestHeaders(baseHeaders, options) {
@@ -39,6 +41,14 @@ function buildRequestHeaders(baseHeaders, options) {
 function isFlatErrorBody(value) {
   return value !== null && typeof value === "object" && typeof value.error === "string";
 }
+function parseFlatErrorBody(body) {
+  const weftCode = isWeftErrorCode(body.weftCode) ? body.weftCode : void 0, data = isRecord(body.data) ? body.data : void 0;
+  return {
+    message: body.error,
+    ...weftCode === void 0 ? {} : { weftCode },
+    ...data === void 0 ? {} : { data }
+  };
+}
 function isStructuredErrorBody(value) {
   if (value === null || typeof value !== "object")
     return !1;
@@ -53,31 +63,42 @@ function weftCodeFromData(data) {
   const candidate = data.weftCode;
   return isWeftErrorCode(candidate) ? candidate : void 0;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 async function parseErrorBody(response) {
   try {
     const body = await response.json();
     if (isStructuredErrorBody(body)) {
-      const { code, message, data } = body.error, weftCode = weftCodeFromData(data), base = weftCode === void 0 ? { message } : { message, weftCode };
+      const { code, message, data } = body.error, weftCode = weftCodeFromData(data), base = { message };
+      if (weftCode !== void 0)
+        base.weftCode = weftCode;
+      if (isRecord(data))
+        base.data = data;
       return isFaultCode(code) ? { ...base, faultCode: code } : base;
     }
-    if (isFlatErrorBody(body) && body.error) {
-      const weftCode = isWeftErrorCode(body.weftCode) ? body.weftCode : void 0;
-      return weftCode === void 0 ? { message: body.error } : { message: body.error, weftCode };
-    }
+    if (isFlatErrorBody(body) && body.error)
+      return parseFlatErrorBody(body);
     return { message: response.statusText };
   } catch {
     return { message: response.statusText };
   }
 }
 export async function request(baseUrl, path, baseHeaders, options) {
+  const response = await requestResponse(baseUrl, path, baseHeaders, options);
+  if (response === null)
+    return null;
+  if (response.status === 204)
+    return;
+  return response.json();
+}
+export async function requestResponse(baseUrl, path, baseHeaders, options) {
   const headers = buildRequestHeaders(baseHeaders, options), response = await fetch(`${baseUrl}/v1${path}`, { ...options, headers });
   if (response.status === 404 && (!options?.method || options.method === "GET"))
     return null;
   if (!response.ok) {
-    const { message, faultCode, weftCode } = await parseErrorBody(response);
-    throw new HttpClientError(response.status, message, { faultCode, weftCode });
+    const { message, faultCode, weftCode, data } = await parseErrorBody(response);
+    throw new HttpClientError(response.status, message, { faultCode, weftCode, data });
   }
-  if (response.status === 204)
-    return;
-  return response.json();
+  return response;
 }