@classytic/arc 2.41.1 → 2.43.0

package/dist/integrations/streamline.d.mts

@@ -2,13 +2,9 @@
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/integrations/streamline.d.ts
 /**
- * Start options — matches @classytic/streamline v2.3+ `StartOptions`.
- *
- * v2.3 additions:
- *   - `tenantId` — required when streamline's `multiTenant.strict: true`.
- *     Hosts should NOT accept this from the request body in untrusted
- *     contexts; use `tenantResolver` to extract from auth context instead.
- *   - `bypassTenant` — admin/cross-tenant operations. Same caveat.
+ * Start options — matches streamline's `StartOptions`. `tenantId` /
+ * `bypassTenant` must come from auth context (`tenantResolver`), never the
+ * request body.
  */
 interface WorkflowStartOptions {
   meta?: Record<string, unknown>;
@@ -40,6 +36,13 @@ interface WorkflowLike {
       timeout?: number;
     }): Promise<WorkflowRunLike>;
     shutdown?(): void;
+    /**
+     * Read for `compensationHandlers` only — whether a failed run will roll
+     * back, which decides if `workflow:failed` ends its stream. Absent = no saga.
+     */
+    options?: {
+      compensationHandlers?: unknown;
+    };
   };
   start(input: unknown, options?: WorkflowStartOptions): Promise<WorkflowRunLike>;
   resume(runId: string, payload?: unknown): Promise<WorkflowRunLike>;
@@ -48,7 +51,7 @@ interface WorkflowLike {
   }): Promise<WorkflowRunLike>;
   get(runId: string): Promise<WorkflowRunLike | null>;
   shutdown?(): void;
-  /** Streamline container for event bridging + repository access (streamline >=2.1) */
+  /** Streamline container for event bridging + repository access. */
   container?: {
     eventBus: {
       on(event: string, listener: (...args: unknown[]) => void): void;
@@ -58,38 +61,20 @@ interface WorkflowLike {
     repository?: {
       getAll(params: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
       /**
-       * Tenant-scoped lookup by id. Used by the DELETE handler for a
-       * defense-in-depth pre-flight: streamline 2.3.3's `wf.get(runId)` /
-       * `engine.get` does NOT accept tenant options, so a cross-tenant
-       * runId can leak data through the engine path. Going through the
-       * repository here means mongokit's tenant-filter plugin scopes the
-       * read — cross-tenant requests get a clean 404 and DELETEs only
-       * touch rows the caller actually owns.
+       * Tenant-scoped lookup — the per-run ownership pre-flight. The engine's
+       * `get` takes no tenant options, so the tenant-filtered repository read
+       * is what stops cross-tenant access (clean 404).
        */
       getById?(id: string, options?: Record<string, unknown>): Promise<WorkflowRunLike | null>;
-      /**
-       * Hard-delete a run by id. Routed through mongokit's inherited
-       * `Repository.delete()` so multi-tenant scope + audit/cache plugins
-       * fire. Wired into `DELETE /:workflowId/runs/:runId` — operator
-       * escape hatch for dead-lettered or stuck rows.
-       */
+      /** Tenant-scoped hard delete, backing `DELETE /:workflowId/runs/:runId`. */
       delete?(id: string, options?: Record<string, unknown>): Promise<unknown>;
     };
     /**
-     * Streamline >= 2.3.2 — explicit deploy-time index sync (TTL on
-     * terminal runs + tenant compounds). When the host configured
-     * `createContainer({ retention })`, arc's app-level deploy hook
-     * should call `await container.syncRetentionIndexes()` after
-     * `mongoose.connect`. Optional so older streamline versions
-     * (and partial mocks) still satisfy the structural shape.
+     * Deploy-time index sync (retention TTL + tenant compounds). Hosts using
+     * `createContainer({ retention })` call it after connecting.
      */
     syncRetentionIndexes?: () => Promise<void>;
-    /**
-     * Streamline >= 2.3.2 — stop background sweepers and release timers.
-     * Arc's `onClose` hook below calls this on every workflow's container
-     * during graceful shutdown so SIGTERM doesn't leave the stale-run
-     * sweeper running. Optional + idempotent.
-     */
+    /** Stop background sweepers; called on `onClose`. Idempotent. */
     dispose?: () => void;
   };
 }
@@ -107,36 +92,19 @@ interface WorkflowRunLike {
   stepLogs?: unknown[];
   createdAt?: Date;
   updatedAt?: Date;
-  /**
-   * Streamline >= 2.3.3 — pinned definition version (semver) the run
-   * started under. Hosts surfacing a "stuck on old version" UI read this
-   * to decide whether to nudge a migration. Optional for back-compat
-   * with runs created before 2.3.3.
-   */
+  /** Definition version (semver) the run started under. */
   definitionVersion?: string;
-  /**
-   * Streamline >= 2.3.3 — count of stale-recovery / sweeper transitions
-   * applied to this run. Sweeper dead-letters once this hits
-   * `RetentionOptions.maxStaleRecoveries`; UIs can highlight runs trending
-   * toward dead-letter.
-   */
+  /** Stale-recovery transitions so far; dead-lettered at `maxStaleRecoveries`. */
   recoveryAttempts?: number;
-  /**
-   * Streamline >= 2.7 — operator-supplied cancellation reason, set when
-   * `cancel(runId, { reason })` was called. Absent on runs cancelled without
-   * a reason or under older streamline. Surfaced so dashboards can show WHY.
-   */
+  /** Reason passed to `cancel(runId, { reason })`, if any. */
   cancellationReason?: string;
 }
 /**
- * Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
- * `'failed'`; the discrimination is `error.code`:
+ * Dead-letter discriminator: `run.status` stays `'failed'`; `error.code` says why:
  *   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
  *   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
  *   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
  *     resume against; admin must rewind / migrate / cancel.
- *
- * Hosts switch on `error.code` for dashboards / alerting.
  */
 declare const STREAMLINE_FAILURE_CODES: {
   readonly STALE_HEARTBEAT: "stale_heartbeat";
@@ -153,65 +121,35 @@ interface StreamlinePluginOptions {
   /** Connect workflow lifecycle events to Arc's event bus (default: true) */
   bridgeEvents?: boolean;
   /**
-   * Bridge the workflow's internal event bus (step + workflow lifecycle +
-   * engine telemetry) to Arc's event bus, topic-scoped as
-   * `workflow.${workflowId}.${eventName}`.
-   *
-   * Covers the full streamline 2.3 event surface:
-   *   - Step events: started, completed, failed, waiting, skipped,
-   *     retry-scheduled, compensated
-   *   - Workflow lifecycle: started, completed, failed, waiting, resumed,
-   *     cancelled, recovered, retry, compensating, paused (>= 2.7)
-   *   - Engine telemetry: engine:error, scheduler:error,
-   *     scheduler:circuit-open
-   *
-   * Subscriptions use structural `container.eventBus.on(...)` — future
-   * streamline releases can add events without breaking arc; missing
-   * events are simply never handled (no crash). Requires the workflow
-   * to expose `container.eventBus`.
-   *
-   * Disabled by default — enable for dashboards or monitoring.
+   * Bridge every {@link STREAMLINE_BUS_EVENTS} event (step, workflow
+   * lifecycle, engine telemetry) from `container.eventBus` to Arc's event bus
+   * as `workflow.${workflowId}.${eventName}`.
    * @default false
    */
   bridgeBusEvents?: boolean;
   /**
    * Enable SSE streaming endpoint: GET /:workflowId/runs/:runId/stream
    * Streams step-level + lifecycle events as Server-Sent Events for live
-   * UI updates. Auto-closes the stream on terminal workflow events
-   * (completed / failed / cancelled).
+   * UI updates. Auto-closes the stream when the run ends: completed /
+   * cancelled / compensated / compensation_failed, and failed only for a
+   * workflow with no compensation (a saga keeps streaming its rollback).
    * @default false
    */
   enableStreaming?: boolean;
   /**
-   * Enable webhook resume endpoint: POST /hooks/:token
-   *
-   * Routes incoming webhook calls through streamline's `resumeHook(token,
-   * body)` — which validates the token against the stored `hookToken` on
-   * the waiting step (fail-closed since streamline 2.3). Hosts use this
-   * for "wait for external approval / SaaS callback" patterns.
-   *
-   * Workflows MUST pass `{ hookToken: hook.token }` to `ctx.wait(...)` —
-   * streamline 2.3 rejects resume otherwise (security). The endpoint is
-   * registered at the plugin's `prefix` root, NOT scoped per workflow,
-   * because the token encodes the runId.
-   *
-   * Auth is OPTIONAL on this route by design — the token IS the
-   * authentication. If you also want to gate by user (e.g. only the
-   * inviting user can approve), set `auth: true` and a permission check.
+   * Enable `POST /hooks/:token` (at the prefix root — the token encodes the
+   * runId), routed through streamline's `resumeHook(token, body)`, which
+   * validates against the waiting step's stored `hookToken` (fail-closed).
+   * Workflows MUST pass `{ hookToken: hook.token }` to `ctx.wait(...)`.
    *
+   * The token IS the authentication; `auth` adds a user gate on top.
    * @default false
    */
   enableHookEndpoint?: boolean;
   /**
-   * Resolve the tenant id for a request — extract from auth context
-   * (JWT claim, session, header), NOT from the request body. Returning
-   * `undefined` skips tenant injection (use for non-multi-tenant routes
-   * or admin paths that pass `bypassTenant` explicitly).
-   *
-   * When set, the resolved tenantId is forwarded to every streamline
-   * call (`start`, `resume`, `cancel`, `get`, `list`, etc.) so
-   * streamline's `multiTenant.strict` mode never throws "missing
-   * tenantId" inside arc's request lifecycle.
+   * Resolve the request's tenant id from auth context — NEVER the request
+   * body. Forwarded to streamline calls, and enables the per-run tenant
+   * ownership check. `undefined` skips tenant scoping.
    *
    * @example
    * tenantResolver: (req) => req.user?.organizationId
@@ -224,63 +162,67 @@ interface StreamlinePluginOptions {
    * (`allowBypass: true`, the default).
    */
   bypassTenantResolver?: (request: FastifyRequest) => boolean;
-  /** Custom permission check for workflow operations */
+  /**
+   * Custom permission check for workflow operations. `execute` falls back to
+   * `start`, and `pause` / `rewind` to `cancel`, when not set — so restricting
+   * the broader operation also covers these.
+   */
   permissions?: {
     start?: (request: unknown) => boolean | Promise<boolean>;
     resume?: (request: unknown) => boolean | Promise<boolean>;
     cancel?: (request: unknown) => boolean | Promise<boolean>;
     list?: (request: unknown) => boolean | Promise<boolean>;
     get?: (request: unknown) => boolean | Promise<boolean>;
+    execute?: (request: unknown) => boolean | Promise<boolean>;
+    pause?: (request: unknown) => boolean | Promise<boolean>;
+    rewind?: (request: unknown) => boolean | Promise<boolean>;
+  };
+  /**
+   * Operations whose call requires an idempotency key (400 `arc.idempotency_key_required`
+   * when absent; a keyed retry replays). `workflows` narrows it to those ids (default: all).
+   * On `start` the header key IS the run's `idempotencyKey`; a different body key is refused.
+   * Needs `idempotencyPlugin` enabled.
+   */
+  idempotency?: {
+    readonly required: readonly ("start" | "execute" | "resume" | "rewind")[];
+    readonly workflows?: readonly string[];
   };
 }
 /**
- * Full event list published on a streamline workflow's internal `eventBus`
- * (tracks streamline 2.3's `EventPayloadMap` in
- * `@classytic/streamline/src/core/events.ts`).
- *
- * Hardcoded here by design — arc subscribes via structural
- * `eventBus.on(name, handler)`, which is a no-op for events the running
- * streamline version doesn't emit. New events a future streamline release
- * adds can be bridged by updating this list; arc never breaks just
- * because streamline extended its bus.
+ * Events published on a streamline workflow's internal `eventBus`. Subscribing
+ * to one the running version doesn't emit is a no-op. Pinned against
+ * streamline's `ALL_WORKFLOW_EVENT_NAMES` by `tests/integrations/streamline-drift.test.ts`.
  */
-declare const STREAMLINE_BUS_EVENTS: readonly ["step:started", "step:completed", "step:failed", "step:waiting", "step:skipped", "step:retry-scheduled", "step:compensated", "workflow:started", "workflow:completed", "workflow:failed", "workflow:waiting", "workflow:resumed", "workflow:cancelled", "workflow:recovered", "workflow:retry", "workflow:compensating", "workflow:paused", "engine:error", "scheduler:error", "scheduler:circuit-open"];
+declare const STREAMLINE_BUS_EVENTS: readonly ["step:started", "step:completed", "step:failed", "step:waiting", "step:skipped", "step:retry-scheduled", "step:compensated", "workflow:started", "workflow:completed", "workflow:failed", "workflow:waiting", "workflow:resumed", "workflow:cancelled", "workflow:recovered", "workflow:retry", "workflow:compensating", "workflow:paused", "workflow:compensated", "workflow:compensation_failed", "engine:error", "scheduler:error", "scheduler:circuit-open"];
 /**
- * Non-durable streaming frames from streamline >= 2.6's `ctx.stream(frame)`
- * (LLM tokens, percent-complete, live previews).
- *
- * Delivered on the SSE endpoint ONLY — deliberately excluded from
- * `STREAMLINE_BUS_EVENTS` / `bridgeBusEvents` because frames are
- * high-frequency, at-most-once UI traffic, not domain events: republishing
- * every token onto arc's Redis/Kafka transport would flood it. Subscribers
- * that genuinely want frames on the transport can bridge
- * `streamline:step.stream` from streamline's own arc-shape transport.
- *
- * On streamline < 2.6 the subscription is a structural no-op (the bus never
- * emits the event) — no version gate needed.
+ * Non-durable `ctx.stream(frame)` frames (LLM tokens, progress). SSE ONLY —
+ * excluded from `bridgeBusEvents` because high-frequency at-most-once UI
+ * traffic would flood arc's event transport.
  */
 declare const STREAMLINE_STREAM_EVENTS: readonly ["step:stream"];
 /**
- * Workflow events that should auto-close an SSE stream when observed.
- * Recovered / waiting / resumed / retry / compensating are NOT terminal —
- * the run is still active after them.
+ * Workflow events that end a run and auto-close an SSE stream.
+ *
+ * `workflow:failed` is terminal ONLY without compensation handlers: a saga
+ * emits `failed` THEN rolls back, so closing there would hide the rollback.
+ * See {@link isStreamTerminal}.
  */
-declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workflow:failed", "workflow:cancelled"];
+declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workflow:failed", "workflow:cancelled", "workflow:compensated", "workflow:compensation_failed"];
 /**
- * Terminal run STATUSES (distinct from the terminal EVENT names above).
- * Mirrors streamline's `isTerminalState()` — a run in one of these will
- * emit no further bus events, so the SSE handler sends its snapshot and
- * closes immediately rather than holding a connection open on a dead run.
+ * Terminal run STATUSES (vs. the event names above). A run in one emits no
+ * further events, so SSE sends its snapshot and closes. Pinned against
+ * streamline's own list by `tests/integrations/streamline-drift.test.ts`.
  */
 declare const TERMINAL_RUN_STATUSES: Set<string>;
 /**
- * Pluggable streamline integration for Arc.
- *
- * Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
- * plain plugin option (NOT an encapsulation prefix). Without the wrapper,
- * Fastify would prepend `options.prefix` to every route, then the plugin
- * code would prepend it again — the duplicate-prefix bug.
+ * Whether a run has ended, for the purpose of closing its stream — by event
+ * name or by status. `failed` ends a run only when nothing will compensate it.
+ */
+declare function isStreamTerminal(eventOrStatus: string, compensates: boolean, kind: "event" | "status"): boolean;
+/**
+ * Streamline integration for Arc. Wrapped in `fastify-plugin` so `prefix` is
+ * a plain option, not an encapsulation prefix (which would apply it twice).
  */
 declare const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions>;
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_STREAM_EVENTS, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, TERMINAL_RUN_STATUSES, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_STREAM_EVENTS, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, TERMINAL_RUN_STATUSES, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, isStreamTerminal, streamlinePlugin };

package/dist/integrations/streamline.mjs

@@ -1,17 +1,38 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { f as createError, i as NotFoundError, r as ForbiddenError } from "../errors-BH7YU_9O.mjs";
-import { a as promoteStreamTokenToHeader, n as forwardedStreamHeaders } from "../streaming-IcRFjWQU.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { f as createError, i as NotFoundError, r as ForbiddenError } from "../errors-CtrywMHP.mjs";
+import { a as promoteStreamTokenToHeader, n as forwardedStreamHeaders } from "../streaming-DjTQhZrN.mjs";
+import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";
 //#region src/integrations/streamline.ts
 /**
-* Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
-* `'failed'`; the discrimination is `error.code`:
+* Streamline integration — wires `@classytic/streamline` workflows into arc.
+*
+* REST endpoints for workflow management, auto-connected to arc's event bus,
+* honouring arc auth/permissions and surfacing streamline's repo-core-aligned
+* `HttpError`s with their real status codes rather than a blanket 500.
+*
+* A separate subpath, loaded only when used:
+* `@classytic/arc/integrations/streamline`. Peer: `@classytic/streamline`.
+*
+* Routes mounted under `prefix`: `POST /:workflow/start`,
+* `GET /:workflow/runs[/:runId]`, `POST /:workflow/runs/:runId/{resume,cancel}`,
+* and `POST /hooks/:token` when `enableHookEndpoint` is set.
+*
+* @example
+* ```typescript
+* await fastify.register(streamlinePlugin, {
+*   workflows: [orderWorkflow],
+*   prefix: '/api/workflows',
+*   tenantResolver: (req) => req.user?.organizationId,
+* });
+* ```
+*/
+/**
+* Dead-letter discriminator: `run.status` stays `'failed'`; `error.code` says why:
 *   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
 *   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
 *   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
 *     resume against; admin must rewind / migrate / cancel.
-*
-* Hosts switch on `error.code` for dashboards / alerting.
 */
 const STREAMLINE_FAILURE_CODES = {
 	STALE_HEARTBEAT: "stale_heartbeat",
@@ -19,15 +40,9 @@ const STREAMLINE_FAILURE_CODES = {
 	VERSION_MISMATCH: "VERSION_MISMATCH"
 };
 /**
-* Full event list published on a streamline workflow's internal `eventBus`
-* (tracks streamline 2.3's `EventPayloadMap` in
-* `@classytic/streamline/src/core/events.ts`).
-*
-* Hardcoded here by design — arc subscribes via structural
-* `eventBus.on(name, handler)`, which is a no-op for events the running
-* streamline version doesn't emit. New events a future streamline release
-* adds can be bridged by updating this list; arc never breaks just
-* because streamline extended its bus.
+* Events published on a streamline workflow's internal `eventBus`. Subscribing
+* to one the running version doesn't emit is a no-op. Pinned against
+* streamline's `ALL_WORKFLOW_EVENT_NAMES` by `tests/integrations/streamline-drift.test.ts`.
 */
 const STREAMLINE_BUS_EVENTS = [
 	"step:started",
@@ -47,48 +62,63 @@ const STREAMLINE_BUS_EVENTS = [
 	"workflow:retry",
 	"workflow:compensating",
 	"workflow:paused",
+	"workflow:compensated",
+	"workflow:compensation_failed",
 	"engine:error",
 	"scheduler:error",
 	"scheduler:circuit-open"
 ];
 /**
-* Non-durable streaming frames from streamline >= 2.6's `ctx.stream(frame)`
-* (LLM tokens, percent-complete, live previews).
-*
-* Delivered on the SSE endpoint ONLY — deliberately excluded from
-* `STREAMLINE_BUS_EVENTS` / `bridgeBusEvents` because frames are
-* high-frequency, at-most-once UI traffic, not domain events: republishing
-* every token onto arc's Redis/Kafka transport would flood it. Subscribers
-* that genuinely want frames on the transport can bridge
-* `streamline:step.stream` from streamline's own arc-shape transport.
-*
-* On streamline < 2.6 the subscription is a structural no-op (the bus never
-* emits the event) — no version gate needed.
+* Non-durable `ctx.stream(frame)` frames (LLM tokens, progress). SSE ONLY —
+* excluded from `bridgeBusEvents` because high-frequency at-most-once UI
+* traffic would flood arc's event transport.
 */
 const STREAMLINE_STREAM_EVENTS = ["step:stream"];
 /**
-* Workflow events that should auto-close an SSE stream when observed.
-* Recovered / waiting / resumed / retry / compensating are NOT terminal —
-* the run is still active after them.
+* Workflow events that end a run and auto-close an SSE stream.
+*
+* `workflow:failed` is terminal ONLY without compensation handlers: a saga
+* emits `failed` THEN rolls back, so closing there would hide the rollback.
+* See {@link isStreamTerminal}.
 */
 const STREAMLINE_TERMINAL_EVENTS = [
 	"workflow:completed",
 	"workflow:failed",
-	"workflow:cancelled"
+	"workflow:cancelled",
+	"workflow:compensated",
+	"workflow:compensation_failed"
 ];
 /**
-* Terminal run STATUSES (distinct from the terminal EVENT names above).
-* Mirrors streamline's `isTerminalState()` — a run in one of these will
-* emit no further bus events, so the SSE handler sends its snapshot and
-* closes immediately rather than holding a connection open on a dead run.
+* Terminal run STATUSES (vs. the event names above). A run in one emits no
+* further events, so SSE sends its snapshot and closes. Pinned against
+* streamline's own list by `tests/integrations/streamline-drift.test.ts`.
 */
 const TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
 	"done",
 	"failed",
-	"cancelled"
+	"cancelled",
+	"compensated",
+	"compensation_failed"
 ]);
+/** Whether a workflow rolls back on failure (has any `onCompensate` step). */
+function hasCompensation(wf) {
+	const handlers = wf.engine.options?.compensationHandlers;
+	return !!handlers && typeof handlers === "object" && Object.keys(handlers).length > 0;
+}
+/**
+* Whether a run has ended, for the purpose of closing its stream — by event
+* name or by status. `failed` ends a run only when nothing will compensate it.
+*/
+function isStreamTerminal(eventOrStatus, compensates, kind) {
+	if (kind === "event") {
+		if (eventOrStatus === "workflow:failed") return !compensates;
+		return STREAMLINE_TERMINAL_EVENTS.includes(eventOrStatus);
+	}
+	if (eventOrStatus === "failed") return !compensates;
+	return TERMINAL_RUN_STATUSES.has(eventOrStatus);
+}
 const streamlinePluginImpl = async (fastify, options) => {
-	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms } = options;
+	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms, idempotency } = options;
 	const routeScope = prefix;
 	const bridgeBus = options.bridgeBusEvents ?? false;
 	const registry = /* @__PURE__ */ new Map();
@@ -110,11 +140,38 @@ const streamlinePluginImpl = async (fastify, options) => {
 		if (tenantId !== void 0) opts.tenantId = tenantId;
 		return opts;
 	};
+	const PERM_FALLBACK = {
+		execute: "start",
+		pause: "cancel",
+		rewind: "cancel"
+	};
 	const checkPerm = async (op, request) => {
-		const check = perms?.[op];
+		const fallback = PERM_FALLBACK[op];
+		const check = perms?.[op] ?? (fallback ? perms?.[fallback] : void 0);
 		if (!check) return true;
 		return check(request);
 	};
+	const fencedOps = new Set(idempotency?.required ?? []);
+	if (fencedOps.size > 0 && !fastify.hasDecorator("idempotency")) throw new Error("[Arc/Streamline] `idempotency.required` is declared, but idempotencyPlugin is not registered — register it (enabled) before streamlinePlugin, or drop the declaration.");
+	for (const wfId of idempotency?.workflows ?? []) if (!workflows.some((wf) => wf.definition.id === wfId)) throw new Error(`[Arc/Streamline] idempotency.workflows names unknown workflow '${wfId}'.`);
+	/**
+	* Route options for a mutating op: a fenced op gets `config.idempotency.required` and
+	* runs auth → permission → idempotency, so a refused caller never reaches the key check.
+	*/
+	const routeOpts = (wfId, op, permOp = op) => {
+		if (!(fencedOps.has(op) && (!idempotency?.workflows || idempotency.workflows.includes(wfId)))) return { preHandler: authPreHandler };
+		const permGate = async (request) => {
+			if (!await checkPerm(permOp, request)) throw new ForbiddenError();
+		};
+		return {
+			config: { idempotency: { required: true } },
+			preHandler: [
+				...authPreHandler,
+				permGate,
+				fastify.idempotency.middleware
+			]
+		};
+	};
 	for (const [id, wf] of registry) {
 		const routePrefix = `${routeScope}/${id}`;
 		const visibilityRepo = wf.container?.repository;
@@ -125,7 +182,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			if (tenantOpts.bypassTenant || tenantOpts.tenantId === void 0) return;
 			if (!await visibilityGetById(runId, { tenantId: tenantOpts.tenantId })) throw new NotFoundError("Workflow run", runId);
 		};
-		fastify.post(`${routePrefix}/start`, { preHandler: authPreHandler }, async (request, reply) => {
+		fastify.post(`${routePrefix}/start`, routeOpts(id, "start"), async (request, reply) => {
 			if (!await checkPerm("start", request)) throw new ForbiddenError();
 			const body = request.body;
 			if (body !== null && body !== void 0 && typeof body !== "object") throw createError(422, `[Arc/Streamline] '/${id}/start' body must be a JSON object.`, {
@@ -152,7 +209,13 @@ const streamlinePluginImpl = async (fastify, options) => {
 				workflowId: id,
 				unknown: unknownKeys
 			});
-			const { input, meta, idempotencyKey, priority } = bodyRecord;
+			const { input, meta, idempotencyKey: bodyKey, priority } = bodyRecord;
+			const headerKey = request.idempotencyKey;
+			if (headerKey !== void 0 && bodyKey !== void 0 && bodyKey !== headerKey) throw createError(422, `[Arc/Streamline] '/${id}/start' got an idempotency-key header and a different body \`idempotencyKey\` — send one key, or the same key in both.`, {
+				code: ARC_ERROR_CODES.IDEMPOTENCY_KEY_REUSED,
+				workflowId: id
+			});
+			const idempotencyKey = bodyKey ?? headerKey;
 			const tenantOpts = resolveTenantOpts(request);
 			const run = await wf.start(input, {
 				meta,
@@ -201,7 +264,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			if (!run) throw new NotFoundError("Workflow run", runId);
 			return run;
 		});
-		fastify.post(`${routePrefix}/runs/:runId/resume`, { preHandler: authPreHandler }, async (request, _reply) => {
+		fastify.post(`${routePrefix}/runs/:runId/resume`, routeOpts(id, "resume"), async (request, _reply) => {
 			if (!await checkPerm("resume", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
@@ -241,7 +304,8 @@ const streamlinePluginImpl = async (fastify, options) => {
 			}
 			return run;
 		});
-		fastify.post(`${routePrefix}/runs/:runId/execute`, { preHandler: authPreHandler }, async (request, _reply) => {
+		fastify.post(`${routePrefix}/runs/:runId/execute`, routeOpts(id, "execute"), async (request, _reply) => {
+			if (!await checkPerm("execute", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
 			return await wf.engine.execute(runId);
@@ -273,12 +337,14 @@ const streamlinePluginImpl = async (fastify, options) => {
 			return await wf.engine.waitFor?.(runId, { timeout: Math.min(timeoutMs, 12e4) });
 		});
 		if (wf.engine.pause) fastify.post(`${routePrefix}/runs/:runId/pause`, { preHandler: authPreHandler }, async (request, _reply) => {
+			if (!await checkPerm("pause", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
 			const { reason: pauseReason } = request.body ?? {};
 			return await wf.engine.pause?.(runId, pauseReason !== void 0 ? { reason: pauseReason } : void 0);
 		});
-		if (wf.engine.rewindTo) fastify.post(`${routePrefix}/runs/:runId/rewind`, { preHandler: authPreHandler }, async (request, _reply) => {
+		if (wf.engine.rewindTo) fastify.post(`${routePrefix}/runs/:runId/rewind`, routeOpts(id, "rewind"), async (request, _reply) => {
+			if (!await checkPerm("rewind", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
 			const { stepId } = request.body ?? {};
@@ -315,7 +381,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 				...forwardedStreamHeaders(reply)
 			});
 			reply.raw.flushHeaders();
-			const terminalEvents = new Set(STREAMLINE_TERMINAL_EVENTS);
+			const compensates = hasCompensation(wf);
 			const listeners = [];
 			let closed = false;
 			let heartbeat;
@@ -339,7 +405,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			};
 			send("workflow:snapshot", run);
 			const runStatus = run.status;
-			if (runStatus && TERMINAL_RUN_STATUSES.has(runStatus)) {
+			if (runStatus && isStreamTerminal(runStatus, compensates, "status")) {
 				cleanup();
 				return;
 			}
@@ -357,7 +423,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 					const p = payload;
 					if (typeof p?.runId === "string" && p.runId !== runId) return;
 					send(eventName, p);
-					if (terminalEvents.has(eventName) && p?.runId === runId) cleanup();
+					if (p?.runId === runId && isStreamTerminal(eventName, compensates, "event")) cleanup();
 				};
 				wf.container?.eventBus.on(eventName, fn);
 				listeners.push({
@@ -395,16 +461,12 @@ const streamlinePluginImpl = async (fastify, options) => {
 	});
 };
 /**
-* Pluggable streamline integration for Arc.
-*
-* Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
-* plain plugin option (NOT an encapsulation prefix). Without the wrapper,
-* Fastify would prepend `options.prefix` to every route, then the plugin
-* code would prepend it again — the duplicate-prefix bug.
+* Streamline integration for Arc. Wrapped in `fastify-plugin` so `prefix` is
+* a plain option, not an encapsulation prefix (which would apply it twice).
 */
 const streamlinePlugin = fp(streamlinePluginImpl, {
 	name: "streamline-routes",
 	fastify: "5.x"
 });
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_STREAM_EVENTS, STREAMLINE_TERMINAL_EVENTS, TERMINAL_RUN_STATUSES, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_STREAM_EVENTS, STREAMLINE_TERMINAL_EVENTS, TERMINAL_RUN_STATUSES, isStreamTerminal, streamlinePlugin };