@workflow/core 5.0.0-beta.5 → 5.0.0-beta.51

package/dist/flushable-stream.d.ts

@@ -1,4 +1,51 @@
 import { type PromiseWithResolvers } from '@workflow/utils';
+/**
+ * A durability barrier a sink may expose under {@link STREAM_DRAIN_SYMBOL}:
+ * resolves once every chunk the sink has accepted is durably written, rejects
+ * if any server write failed. See `WorkflowServerWritableStream`.
+ */
+type DrainBarrier = () => Promise<void>;
+/**
+ * Flow-control knob: upper bound on chunks read-but-not-yet-durably-written
+ * while coalescing. Once this many chunks are outstanding the producer stops
+ * reading until the consumer drains a batch, so a fast producer paired with a
+ * slow server can't grow the in-memory queue without bound. Override:
+ * `WORKFLOW_STREAM_MAX_INFLIGHT_CHUNKS`.
+ *
+ * This is deliberately distinct from the per-request batch caps below: this
+ * bounds how much is *buffered*, those bound how much goes out in one
+ * `writeMulti`. Raising this must never let a single request exceed a wire
+ * limit, since batch sizing enforces that independently.
+ */
+export declare const MAX_INFLIGHT_CHUNKS = 1000;
+export declare const getMaxInflightChunks: () => number;
+/**
+ * Wire limit: maximum number of chunks in a single coalesced `writeMulti`.
+ * The server enforces a per-multi-write chunk cap (1,000 today); a batch is
+ * split at this bound so it can never be rejected wholesale, independently of
+ * the backpressure knob above. Override: `WORKFLOW_STREAM_MAX_CHUNKS_PER_BATCH`.
+ */
+export declare const MAX_CHUNKS_PER_BATCH = 1000;
+export declare const getMaxChunksPerBatch: () => number;
+/**
+ * Wire limit: maximum cumulative bytes in a single coalesced `writeMulti`.
+ * Chunk *count* alone is not enough: 1,000 small chunks are ~100KB but 1,000
+ * file-sized chunks can be hundreds of MB, which platform request-body limits
+ * reject long before the count cap matters. A batch is split once adding the
+ * next chunk would exceed this (a single chunk larger than the cap still goes
+ * out alone). Default 1 MiB. Override: `WORKFLOW_STREAM_MAX_BYTES_PER_BATCH`.
+ */
+export declare const MAX_BYTES_PER_BATCH: number;
+export declare const getMaxBytesPerBatch: () => number;
+/**
+ * Buffer bound (bytes) for the server writable's group-commit buffer, the
+ * byte-denominated counterpart of {@link MAX_INFLIGHT_CHUNKS}. `write()`
+ * blocks once this much data is buffered-but-not-durable, so a fast producer
+ * of large chunks can't grow client memory without bound. Default 8 MiB
+ * (eight request-sized groups). Override: `WORKFLOW_STREAM_MAX_BUFFERED_BYTES`.
+ */
+export declare const MAX_BUFFERED_BYTES: number;
+export declare const getMaxBufferedBytes: () => number;
 /**
  * Polling interval (in ms) for lock release detection.
  *
@@ -12,7 +59,7 @@ import { type PromiseWithResolvers } from '@workflow/utils';
  * after each step body returns, so a coarser interval (the previous 100ms)
  * adds visible per-step latency to streaming workflows. With a uniformly
  * distributed offset between step return and the next tick, the expected
- * wait is half the interval — so 10ms means ~5ms average wait per step
+ * wait is half the interval, so 10ms means ~5ms average wait per step
  * instead of ~50ms. The per-tick work is `writable.locked` plus a
  * `getWriter()`/`releaseLock()` probe, both microsecond-scale; 10× more
  * ticks during a stream's lifetime is not measurable in practice.
@@ -35,6 +82,30 @@ export declare const LOCK_POLL_INTERVAL_MS = 10;
 export interface FlushableStreamState extends PromiseWithResolvers<void> {
     /** Number of write operations currently in flight to the server */
     pendingOps: number;
+    /** Frames emitted by this pipe's producer. */
+    producedFrames: number;
+    /** Produced frames accepted by this pipe's sink. */
+    acceptedFrames: number;
+    /** Terminal pipe error, retained for snapshots registered after failure. */
+    pipeError?: unknown;
+    /**
+     * If the user-facing writable is unlocked, enqueue an ordered checkpoint and
+     * durably drain every write ahead of it. Returns false while a writer remains
+     * locked, so lock-held streams never block step completion.
+     */
+    settleReleasedWrites?: () => Promise<boolean>;
+    /** Whether release settlement waits for explicit step-end arming. */
+    deferReleaseSettlement?: boolean;
+    /** Whether step-end processing has armed released-writer settlement. */
+    releaseSettlementArmed?: boolean;
+    /** Whether the user-facing writable has begun a normal close. */
+    userWritableClosing?: boolean;
+    /** Step-end snapshot waiters blocked until their target reaches the sink. */
+    frameWaiters: Array<{
+        target: number;
+        resolve: () => void;
+        reject: (error: unknown) => void;
+    }>;
     /** Whether the `done` promise has been resolved */
     doneResolved: boolean;
     /** Whether the underlying stream has actually closed/errored */
@@ -43,8 +114,32 @@ export interface FlushableStreamState extends PromiseWithResolvers<void> {
     writablePollingInterval?: ReturnType<typeof setInterval>;
     /** Interval ID for readable lock polling (if active) */
     readablePollingInterval?: ReturnType<typeof setInterval>;
+    /**
+     * Durability barrier of the pipe's sink, when it acks writes on buffer
+     * entry (see {@link STREAM_DRAIN_SYMBOL}). Lock-release completion awaits
+     * this before resolving so `pendingOps === 0` (fast, buffered acks) can't
+     * complete a step while data is still client-side.
+     */
+    drainBarrier?: DrainBarrier;
 }
 export declare function createFlushableState(): FlushableStreamState;
+/**
+ * Capture a step-end producer watermark, wait until the pipe has handed every
+ * frame through that watermark to its sink, then await the sink's durability
+ * barrier. Unlike {@link FlushableStreamState.promise}, this never waits for a
+ * user writer lock to be released.
+ */
+export declare function drainFlushableSnapshot(state: FlushableStreamState): Promise<void>;
+/**
+ * Mark byte-stream chunks at the producer side of a flushable pipe. Serialized
+ * streams should instead use `getSerializeStream`'s synchronous output hook.
+ */
+/**
+ * Wrap the user-facing producer boundary of a flushable writable. A completed
+ * write through this handle has a sequence number before step-end snapshots,
+ * while the original writable remains the input to the serialization pipe.
+ */
+export declare function trackFlushableWritable<T>(writable: WritableStream<T>, state: FlushableStreamState, WritableStreamConstructor?: typeof WritableStream): WritableStream<T>;
 /**
  * Polls a WritableStream to check if the user has released their lock.
  * Resolves the done promise when lock is released and no pending ops remain.
@@ -79,4 +174,5 @@ export declare function pollReadableLock(readable: ReadableStream, state: Flusha
  * @returns Promise that resolves when stream ends (not when done promise resolves)
  */
 export declare function flushablePipe(source: ReadableStream, sink: WritableStream, state: FlushableStreamState): Promise<void>;
+export {};
 //# sourceMappingURL=flushable-stream.d.ts.map

package/dist/flushable-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flushable-stream.d.ts","sourceRoot":"","sources":["../src/flushable-stream.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,iBAAiB,CAAC;AAE3E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB,CAAC,IAAI,CAAC;IACtE,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,gEAAgE;IAChE,WAAW,EAAE,OAAO,CAAC;IACrB,wDAAwD;IACxD,uBAAuB,CAAC,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;IACzD,wDAAwD;IACxD,uBAAuB,CAAC,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;CAC1D;AAED,wBAAgB,oBAAoB,IAAI,oBAAoB,CAO3D;AA2DD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,oBAAoB,GAC1B,IAAI,CAwBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,oBAAoB,GAC1B,IAAI,CAwBN;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoEf"}
+{"version":3,"file":"flushable-stream.d.ts","sourceRoot":"","sources":["../src/flushable-stream.ts"],"names":[],"mappings":"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"}