@foir/sdk 0.10.0 → 0.12.0

package/dist/react.js

@@ -81,7 +81,12 @@ var FoirRequestError = class extends Error {
    * failed on the first attempt for an hour.
    */
   get retryable() {
-    if (this.status === void 0) return true;
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      return true;
+    }
     if (this.status === 429 || this.code === "RATE_LIMITED") return true;
     if (this.status >= 500) return true;
     return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
@@ -95,19 +100,50 @@ var FoirRequestError = class extends Error {
     return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
   }
 };
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
+    if (input.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -123,6 +159,26 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+var FoirSessionExpiredError = class extends FoirRequestError {
+  constructor(options) {
+    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+      cause: options?.cause,
+      graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
+    });
+    this.name = "FoirSessionExpiredError";
+  }
+};
 var warnedDowngrade = null;
 function reportAuthDowngrade(envelope) {
   const downgrade = envelope.extensions?.auth;
@@ -151,12 +207,18 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
   );
 }
+function answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
 function readFoirEnvelope(json, options) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
   reportAuthDowngrade(json);
   refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data && !options?.strict) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
@@ -670,15 +732,54 @@ function operationName(scope, op) {
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
+async function resolveVisitorAddress(config) {
+  const source = config.visitor;
+  const value = typeof source === "function" ? await source() : source;
+  const address = value?.trim();
+  return address ? address : void 0;
+}
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      visitorAddress: await resolveVisitorAddress(config),
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
-  if (input.orgId) return { lane: "origin", reason: "org" };
+  if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
   if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
@@ -693,25 +794,45 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewBearerOnce(refresh) {
+  const running = renewing.get(refresh);
+  if (running) return running;
+  const next = refresh().finally(() => renewing.delete(refresh));
+  renewing.set(refresh, next);
+  return next;
+}
 async function runFoirDocument(config, document2, mutation, variables, options) {
+  try {
+    return await sendFoirDocument(config, document2, mutation, variables, options);
+  } catch (err) {
+    const refresh = config.refreshBearer;
+    if (!(err instanceof FoirAuthDowngradedError) || !refresh || err.downgrade.reason === "wrong_project") {
+      throw err;
+    }
+    const token = err.downgrade.reason === "expired" ? await renewBearerOnce(refresh) : null;
+    if (!token) throw new FoirSessionExpiredError({ cause: err });
+    try {
+      return await sendFoirDocument({ ...config, bearerToken: token }, document2, mutation, variables, options);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
+  }
+}
+async function sendFoirDocument(config, document2, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
-  const bearerToken = await resolveBearerToken(config);
-  const headers = buildFoirHeaders({
-    apiKey: config.apiKey,
-    draftChannel: config.channel === "draft",
-    bearerToken,
-    orgId: config.orgId,
-    extra: config.headers
-  });
+  const { headers, key } = await resolveFoirAuth(config);
   const hash = await documentHash(document2);
-  const route = foirRoute({
-    apiKey: config.apiKey,
-    bearerToken,
+  const sharedKey = key !== void 0 && foirRoute({
+    apiKey: key.apiKey,
+    bearerToken: key.bearerToken,
     orgId: config.orgId,
+    orgUrl: config.orgUrl,
     mutation,
     channel: config.channel
-  });
+  }).lane === "shared" ? key.apiKey : void 0;
   const post = (body) => doFetch(endpoint, {
     method: "POST",
     headers,
@@ -721,8 +842,8 @@ async function runFoirDocument(config, document2, mutation, variables, options)
   const extensions = persistedQueryExtension(hash);
   let res;
   try {
-    if (route.lane === "shared") {
-      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+    if (sharedKey !== void 0) {
+      res = await doFetch(buildCdnUrl(endpoint, sharedKey, hash, variables), {
         method: "GET",
         headers,
         ...config.requestInit
@@ -748,7 +869,7 @@ async function runFoirDocument(config, document2, mutation, variables, options)
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json, options);
+  return readFoirEnvelope(json, { ...options, rejectDowngrade: Boolean(key?.bearerToken) });
 }
 async function readErrorBody(res) {
   try {
@@ -760,20 +881,16 @@ async function readErrorBody(res) {
 }
 
 // src/data/manifest.ts
-async function fetchFoirManifest(config) {
-  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+async function fetchFoirManifest(config, options = {}) {
+  const base = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const url = options.operation === void 0 ? base : `${base}?operation=${encodeURIComponent(options.operation)}`;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const { headers } = await resolveFoirAuth(config);
   let res;
   try {
     res = await doFetch(url, {
       method: "GET",
-      headers: buildFoirHeaders({
-        apiKey: config.apiKey,
-        draftChannel: config.channel === "draft",
-        bearerToken: await resolveBearerToken(config),
-        orgId: config.orgId,
-        extra: config.headers
-      }),
+      headers,
       ...config.requestInit
     });
   } catch (err) {
@@ -845,6 +962,7 @@ function authClientConfig(env, options) {
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
     orgId: options?.orgId,
+    orgUrl: options?.orgUrl,
     headers: options?.headers,
     fetch: options?.fetch
   };
@@ -917,6 +1035,9 @@ async function getAuthProviders(env) {
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
+  if (!result.customerId) {
+    return await getSessionCustomer(adapter) ?? { id: "", email: "" };
+  }
   await adapter.set(CUSTOMER_ID_KEY, result.customerId);
   await adapter.set(EMAIL_KEY, result.email);
   return { id: result.customerId, email: result.email };

package/dist/server/callback-client.d.ts

@@ -17,14 +17,21 @@
  *
  * Each call carries:
  *   - `Authorization: Bearer <callback.token>` — Ed25519 scoped token.
- *   - `X-Foir-Signature: sha256=<hex>` — HMAC of the raw request body
- *     keyed on the project's `operations.signing_secret`. The secret is
- *     out-of-band (CLI publishes it to the extension on push); the SDK
- *     only handles the HMAC computation.
+ *   - `X-Foir-Signature: sha256=<hex>` — HMAC of the raw request body, keyed
+ *     on the run's own key (`callback.signingKey`), which the platform makes
+ *     for each run and sends with it. An endpoint that still holds the
+ *     project's signing secret may pass it as `signingSecret` instead; the
+ *     platform accepts either.
+ *
+ * A call that fails before the platform answers, or that the platform answers
+ * with a 5xx or a 429, is tried again: a report that is lost leaves the run to
+ * be closed by the platform's watchdog as timed out, and every one of these
+ * calls is safe to repeat.
  *
  * Both response body shape and content-type follow the GraphQL spec —
  * extensions importing this client receive typed result data.
  */
+import { type FoirRetryPolicy } from '../transport/retry';
 import type { OperationCallback } from './operation-types.js';
 /** Shape of a successful response from any callback mutation. */
 export interface CallbackResult {
@@ -78,15 +85,29 @@ export interface CallbackClient<TResult = unknown> {
  * `callback`; pass them together so the SDK doesn't have to re-parse the
  * payload structure on every call.
  *
- * `signingSecret` lives on the extension (set as `FOIR_SIGNING_SECRET` or
- * equivalent env var). `foir push` writes it there from the project's
- * signing secret, so it's available before any callback runs.
+ * The signature is keyed on `callback.signingKey`, the run's own key, which
+ * the platform sends with every ASYNC dispatch. `signingSecret` is for an
+ * endpoint that holds the project's signing secret instead (`foir push`
+ * writes it to `FOIR_SIGNING_SECRET`); when it is passed it is the key used.
+ * One of the two must be there.
  *
  * `fetch` is overridable for testability and to support runtimes (CF
- * Workers, Node) where `fetch` may not be the global.
+ * Workers, Node) where `fetch` may not be the global. `retry` is how a call
+ * that got no answer, a 5xx or a 429 is tried again (three attempts unless
+ * told otherwise; `{ attempts: 1 }` turns it off).
+ *
+ * `apiUrl` is the Foir API origin the endpoint is configured with. The
+ * dispatch names the address to report to and that address is the one used; a
+ * platform with no public address of its own configured names none, and the
+ * run then reports to the data API at `apiUrl`.
  */
 export declare function createCallbackClient<TResult = unknown>(callback: OperationCallback, opts: {
     executionId: string;
-    signingSecret: string;
+    signingSecret?: string;
+    /** The Foir API origin, used when the dispatch names no address to report to. */
+    apiUrl?: string;
     fetch?: typeof fetch;
+    retry?: FoirRetryPolicy;
+    /** Aborts a call in flight, and the wait before a retry is not started. */
+    signal?: AbortSignal;
 }): CallbackClient<TResult>;

package/dist/server/continue-run.d.ts

@@ -0,0 +1,56 @@
+/**
+ * continueRun: answer one slice of an ASYNC run and ask to be called again.
+ *
+ * A run that takes longer than one call is cut into slices. Each dispatch does
+ * a bounded amount of work and then either answers `202 Accepted` and reports
+ * the outcome through the callback, as an ASYNC run always has, or answers a
+ * continuation: the cursor the next slice resumes from. The platform queues the
+ * next call, at once or after `delayMs`, and hands the cursor back as
+ * `continuation` on the dispatch body (`readDispatch` reads it). Each slice
+ * gets a fresh callback, so the one that finishes reports through its own.
+ *
+ * ```ts
+ * const payload = await readDispatch(request);
+ * const page = await syncOnePage(payload.continuation?.cursor);
+ * if (page.next) return continueRun({ cursor: page.next, progressPct: page.pct });
+ * await createCallbackClient(payload.callback!, { executionId, signingSecret }).complete(page.summary);
+ * return new Response(null, { status: 202 });
+ * ```
+ *
+ * Only an ASYNC run can continue: a caller waiting on a SYNC call cannot be
+ * answered by a later one, so the platform fails a SYNC call answered this
+ * way. A continuation is not a retry and does not spend the retry budget; a run
+ * takes at most 1000 slices, and one that asks for more is dead-lettered
+ * holding its last cursor, so a retry resumes from it.
+ *
+ * On the wire it is a 200 under {@link CONTINUATION_MEDIA_TYPE} with the
+ * continuation as the JSON body. The content type is what marks it, so a
+ * framework without fetch `Response` objects sends the same thing by setting
+ * that header and writing `JSON.stringify(continuation)`.
+ */
+/** The content type a continuation is answered under. */
+export declare const CONTINUATION_MEDIA_TYPE = "application/vnd.foir.continuation+json";
+/** The longest cursor the platform keeps, in bytes. */
+export declare const MAX_CONTINUATION_CURSOR_BYTES: number;
+/** The longest wait a continuation may ask for, in milliseconds. */
+export declare const MAX_CONTINUATION_DELAY_MS: number;
+/** What a slice answers when the run is not finished. */
+export interface Continuation {
+    /** Where the next slice resumes. Opaque to the platform, never empty. */
+    cursor: string;
+    /**
+     * How long to wait before the next slice, for a slice waiting on a third
+     * party, such as an export that finishes later. At most 15 minutes.
+     */
+    delayMs?: number;
+    /** Progress shown on the execution while it runs, 0 to 100. */
+    progressPct?: number;
+    /** A line shown beside the progress. */
+    progressMessage?: string;
+}
+/**
+ * Build the continuation answer. Throws, before anything is sent, on a
+ * continuation the platform would refuse, so the mistake surfaces in the
+ * endpoint rather than as a failed run.
+ */
+export declare function continueRun(continuation: Continuation): Response;

package/dist/server/index.d.ts

@@ -1,13 +1,16 @@
 export { createServerClient, ServerClientError } from './server-client';
 export { verifyWebhookSignature } from './webhook-helpers';
 export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
-export { requireScopedToken, ScopedTokenError, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
+export { createScopedTokenVerifier, ScopedTokenUnavailableError, type ScopedTokenVerifier, type ScopedTokenVerifierOptions, type ScopedTokenVerifierStats, } from './verify-scoped-token';
+export { requireScopedToken, ScopedTokenError, FOIR_TOKEN_HEADER, FOIR_CONTEXT_HEADER, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
+export { readDispatch, OperationPayloadError, type BodyCarrier, } from './read-dispatch';
 export type { ServerClient, ServerClientOptions, GraphQLResponse, EditorPlacement, } from './types';
-export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, } from './operation-types';
+export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, OperationContinuationBlock, } from './operation-types';
+export { continueRun, CONTINUATION_MEDIA_TYPE, MAX_CONTINUATION_CURSOR_BYTES, MAX_CONTINUATION_DELAY_MS, type Continuation, } from './continue-run';
 export { createCallbackClient } from './callback-client';
 export type { CallbackClient, CallbackResult } from './callback-client';
 export { createEventsClient, FoirEventCursorExpiredError, isFoirEventCursorExpired, FOIR_EVENTS_PATH, FOIR_EVENTS_SCOPE, FOIR_EVENTS_RETENTION_DAYS, } from './events-client';
 export type { FoirEvent, FoirEventActor, FoirEventPage, FoirEventRetention, FoirEventsClient, FoirEventsClientConfig, FoirEventsListParams, FoirEventsStreamParams, FoirEventsSubscribeParams, } from './events-client';
 export type { FoirSubscription, FoirSubscriptionHandlers } from '../data/ws-transport';
-export { FoirRequestError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
+export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
 export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem, FoirAuthDowngrade, } from '../transport/foir-http';

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

@@ -1,54 +1,98 @@
 /**
  * Type definitions for platform operations.
  *
- * These types match the platform's operation execution payload structure.
+ * `OperationPayload` is the body the platform POSTs to an operation endpoint,
+ * field for field. It is written against the worker that builds it
+ * (`buildOperationPayload` in the platform's operation processor), not against
+ * what an endpoint might like to receive: every field here is one the platform
+ * sends, present exactly when the platform sends it. A field the platform does
+ * not send is not here, because a type that promises one is how an endpoint
+ * comes to read `undefined` and refuse every call.
+ *
+ * Read it with `readDispatch(request)`, which parses and checks the body into
+ * this type.
  */
 /**
- * Operation payload sent by the platform to extension endpoints.
+ * The body the platform sends an operation endpoint.
+ *
+ * The same shape however the run was started (a person in the console, an
+ * `execute<Op>` call, a lifecycle hook, a schedule) and whichever way it is
+ * delivered (to the registered endpoint, or down `foir operations dev` to one
+ * on your machine).
  *
- * All operations receive this standardized payload structure regardless
- * of how they're triggered (UI, API, lifecycle hook, schedule).
+ * `TInput` types `input`. It is an assertion, not a check: the platform
+ * validates `input` against the operation's input schema before dispatching,
+ * and this parameter lets the endpoint say what that schema is.
  */
-export interface OperationPayload {
-    /** Execution id — present so the extension can include it in callbacks. */
-    executionId?: string;
-    /** Unique key identifying this operation (e.g., 'tilly-process-note') */
+export interface OperationPayload<TInput extends object = Record<string, unknown>> {
+    /** The run. Always present; quote it in a callback and in your own logs. */
+    executionId: string;
+    /** The key of the operation being run, e.g. `send_quote`. */
     operationKey: string;
-    /** How this operation was triggered */
+    /** How the run was started. */
     trigger: OperationTrigger;
-    /** Input data provided by the caller */
-    input: Record<string, unknown>;
-    /** Content/field value (for field-triggered operations) */
-    content: unknown;
-    /** Record context (if operation was triggered by a record event) */
-    record: OperationRecordContext | null;
-    /** Platform context (tenant, project, user, locale) */
+    /**
+     * What the caller passed as the operation's input. Always an object:
+     * `readDispatch` reads a run started with no input (a schedule that declares
+     * none, which the platform serialises as `null`) as `{}`.
+     */
+    input: TInput;
+    /** The tenant, project and principal the run belongs to. */
     context: OperationContext;
-    /** Extension credentials (auto-injected by platform) */
-    credentials?: Record<string, unknown>;
-    /** Extension config (auto-injected by platform) */
-    config?: Record<string, unknown>;
     /**
-     * Async-callback dispatch metadata. Present iff the operation was
-     * dispatched in `async-callback` mode. Contains the scoped token, the
-     * api-public GraphQL endpoint, and the per-op typed mutation names the
-     * extension should call back to.
+     * The content block the caller attached when it started the run, forwarded
+     * as the caller wrote it. Absent when there was none, which is every run
+     * started by a hook, a schedule or `execute<Op>`.
+     */
+    content?: Record<string, unknown>;
+    /**
+     * The record block the caller attached when it started the run, forwarded
+     * as the caller wrote it. Absent when there was none. For a record event,
+     * the record's id arrives in `input` (for example `input.recordId`), not
+     * here: read the record back as the operation when you need its content.
+     */
+    record?: OperationRecordContext;
+    /**
+     * Caller-supplied context about where the run was started from, forwarded as
+     * written. Absent when there was none.
+     */
+    triggerContext?: Record<string, unknown>;
+    /**
+     * Where and how to report back. Present only when the run was dispatched in
+     * ASYNC mode: the endpoint answers `202 Accepted` and reports the outcome
+     * later through this block (see `createCallbackClient`).
      *
-     * Absent for SYNC operations — the extension returns its result in the
-     * HTTP response body and there's nothing to call back to.
+     * Absent in the blocking (SYNC) mode. A blocking run has no callback path:
+     * the endpoint's response body is the result. Branch on this field being
+     * present to tell the two modes apart.
      */
     callback?: OperationCallback;
+    /**
+     * Where this slice of a run resumes. Present when the previous slice answered
+     * with `continueRun`: the cursor it answered, and which slice this is. Slice
+     * 0 is a run a dead-letter retry resumes. Absent on a run's first call.
+     */
+    continuation?: OperationContinuationBlock;
+}
+/** The dispatch body's continuation block (see `continueRun`). */
+export interface OperationContinuationBlock {
+    /** The cursor the previous slice answered, as it wrote it. */
+    cursor: string;
+    /** Which slice of the run this is. */
+    slice: number;
 }
 /**
- * Callback context the platform hands the extension when it dispatches an
- * async-callback operation. Everything the extension needs to call back is
- * here — endpoint, auth token, signing secret reference (the secret itself
- * lives on the extension, set out of band; the platform only sends the
- * token), and the per-op mutation names so the extension doesn't need to
- * derive them from the operation key.
+ * Callback context the platform hands the endpoint when it dispatches an
+ * ASYNC operation. Everything the endpoint needs to call back is here: the
+ * address, the token, the key this run signs with, and the per-operation
+ * mutation names, so the endpoint derives none of them from the operation key.
  */
 export interface OperationCallback {
-    /** api-public GraphQL endpoint, e.g. https://api.foir.dev/graphql */
+    /**
+     * The address to report to, e.g. https://api.foir.dev/graphql. Empty when the
+     * platform that dispatched has no public address of its own configured;
+     * `createCallbackClient` then reports to the `apiUrl` it is given.
+     */
     gqlEndpoint: string;
     /** Bearer token for the Authorization header (Ed25519, single execution scope) */
     token: string;
@@ -61,53 +105,58 @@ export interface OperationCallback {
         progress: string;
         cancel: string;
     };
+    /**
+     * The operation keys that led to this run, its own last. Present when the
+     * run was caused by another operation's work.
+     */
+    causationChain?: string[];
+    /**
+     * The key this run signs its callbacks with, made by the platform for this
+     * run alone. `createCallbackClient` signs with it, so an endpoint holds no
+     * signing secret of its own. Treat it as a secret: never log or store it.
+     */
+    signingKey?: string;
 }
 /**
- * Trigger information describing how the operation was invoked.
+ * How a run was started. The four values are the platform's own; a caller that
+ * names none is recorded as `api`.
+ *
+ * - `ui`: a console surface that names itself as the trigger, such as an app's
+ *   configure page.
+ * - `api`: an `execute<Op>` call, or any caller that named no trigger.
+ * - `lifecycle`: a hook on a platform event (a record published, an operation
+ *   completed).
+ * - `schedule`: a cron schedule firing.
  */
 export interface OperationTrigger {
-    /** Trigger type */
-    type: 'ui' | 'api' | 'lifecycle' | 'field';
-    /** Field key (for field-triggered operations) */
-    fieldKey?: string;
-    /** Field type (for field-triggered operations) */
-    fieldType?: string;
+    type: 'ui' | 'api' | 'lifecycle' | 'schedule';
 }
 /**
- * Record context provided when operation is triggered by a record event.
+ * The record block a caller attached to a run, forwarded as the caller wrote
+ * it. The platform does not shape it, so neither does this type.
  */
-export interface OperationRecordContext {
-    /** Record ID */
-    id: string;
-    /** Model key (e.g., 'tilly_note') */
-    modelKey: string;
-    /** Version ID (if versioned record) */
-    versionId?: string;
-    /** Record content/data */
-    data: Record<string, unknown>;
-    /** Record metadata */
-    metadata: {
-        /** Natural key (slug, handle, etc.) */
-        naturalKey?: string;
-        /** Additional metadata fields */
-        [key: string]: unknown;
-    };
-}
+export type OperationRecordContext = Record<string, unknown>;
 /**
- * Platform context provided to all operations.
+ * The tenant, project and principal a run belongs to.
  */
 export interface OperationContext {
     /** Tenant ID */
     tenantId: string;
     /** Project ID */
     projectId: string;
-    /** User ID (if user-triggered) */
-    userId?: string;
-    /** Customer ID (if customer-scoped operation) */
+    /**
+     * The principal that started the run. Always present, and the empty string
+     * when the run has none, as a hook's run does.
+     */
+    userId: string;
+    /**
+     * The customer the run acts for, when it acts for one: the signed-in
+     * customer who ran it, or the owner of the record whose event fired the
+     * hook. The dispatch token carries the same customer, so a client built from
+     * it acts for them too.
+     */
     customerId?: string;
-    /** Locale code (if locale-specific) */
-    locale?: string;
-    /** Timestamp when operation was triggered */
+    /** When the platform built this body, RFC 3339 in UTC to the second. */
     timestamp: string;
 }
 /**