@fluidframework/container-runtime 2.114.0 → 2.115.0

package/lib/versionMarks/inboundBatch.js

@@ -0,0 +1,46 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { getEffectiveBatchId } from "../opLifecycle/index.js";
+/**
+ * Maps an inbound batch result to the version-mark resolver update. A batch's resolved point is its last
+ * op's sequence number, so this reports `(batchId, sequenceNumber)` only once a batch completes. It handles
+ * both a batch delivered whole (`fullBatch`, incl. an empty grouped batch via the batch-start key message)
+ * and one delivered piecemeal (`batchStartingMessage` then `nextBatchMessage` with `batchEnd`), carrying the
+ * batch id across the piecemeal messages via `carriedBatchId`.
+ *
+ * @internal
+ */
+export function inboundVersionMarkUpdate(inboundResult, carriedBatchId) {
+    if ("batchStart" in inboundResult) {
+        const batchId = getEffectiveBatchId(inboundResult.batchStart);
+        if (inboundResult.type === "fullBatch") {
+            // The last op is the batch's resolved point; an empty batch falls back to the batch-start key message.
+            const lastMessage = 
+            // eslint-disable-next-line unicorn/prefer-at -- Array.prototype.at is not in this package's lib target
+            inboundResult.messages[inboundResult.messages.length - 1] ??
+                inboundResult.batchStart.keyMessage;
+            return {
+                sequenced: { batchId, sequenceNumber: lastMessage.sequenceNumber },
+                carriedBatchId: undefined,
+            };
+        }
+        // batchStartingMessage: carry the id until the batch's end message arrives.
+        return { carriedBatchId: batchId };
+    }
+    if (inboundResult.type === "nextBatchMessage" &&
+        inboundResult.batchEnd === true &&
+        carriedBatchId !== undefined) {
+        return {
+            sequenced: {
+                batchId: carriedBatchId,
+                sequenceNumber: inboundResult.nextMessage.sequenceNumber,
+            },
+            carriedBatchId: undefined,
+        };
+    }
+    // A mid-batch message, or a batch end with no carried id: no change.
+    return { carriedBatchId };
+}
+//# sourceMappingURL=inboundBatch.js.map

package/lib/versionMarks/inboundBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inboundBatch.js","sourceRoot":"","sources":["../../src/versionMarks/inboundBatch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAA6B,MAAM,yBAAyB,CAAC;AAoBzF;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACvC,aAAmC,EACnC,cAAkC;IAElC,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,mBAAmB,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QAC9D,IAAI,aAAa,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACxC,uGAAuG;YACvG,MAAM,WAAW;YAChB,uGAAuG;YACvG,aAAa,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;gBACzD,aAAa,CAAC,UAAU,CAAC,UAAU,CAAC;YACrC,OAAO;gBACN,SAAS,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,CAAC,cAAc,EAAE;gBAClE,cAAc,EAAE,SAAS;aACzB,CAAC;QACH,CAAC;QACD,4EAA4E;QAC5E,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;IACpC,CAAC;IACD,IACC,aAAa,CAAC,IAAI,KAAK,kBAAkB;QACzC,aAAa,CAAC,QAAQ,KAAK,IAAI;QAC/B,cAAc,KAAK,SAAS,EAC3B,CAAC;QACF,OAAO;YACN,SAAS,EAAE;gBACV,OAAO,EAAE,cAAc;gBACvB,cAAc,EAAE,aAAa,CAAC,WAAW,CAAC,cAAc;aACxD;YACD,cAAc,EAAE,SAAS;SACzB,CAAC;IACH,CAAC;IACD,qEAAqE;IACrE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC3B,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { getEffectiveBatchId, type InboundMessageResult } from \"../opLifecycle/index.js\";\n\n/**\n * The version-mark resolver update derived from an inbound batch result.\n *\n * @internal\n */\nexport interface InboundVersionMarkUpdate {\n\t/**\n\t * A completed batch to record via `processInboundBatch`: its id and its last op's sequence number.\n\t * Undefined when no batch completed on this message (a piecemeal batch still in progress).\n\t */\n\treadonly sequenced?: { readonly batchId: string; readonly sequenceNumber: number };\n\t/**\n\t * The batch id to carry for a piecemeal batch still in progress, or undefined when none is pending.\n\t * The caller stores this and passes it back on the next inbound result.\n\t */\n\treadonly carriedBatchId: string | undefined;\n}\n\n/**\n * Maps an inbound batch result to the version-mark resolver update. A batch's resolved point is its last\n * op's sequence number, so this reports `(batchId, sequenceNumber)` only once a batch completes. It handles\n * both a batch delivered whole (`fullBatch`, incl. an empty grouped batch via the batch-start key message)\n * and one delivered piecemeal (`batchStartingMessage` then `nextBatchMessage` with `batchEnd`), carrying the\n * batch id across the piecemeal messages via `carriedBatchId`.\n *\n * @internal\n */\nexport function inboundVersionMarkUpdate(\n\tinboundResult: InboundMessageResult,\n\tcarriedBatchId: string | undefined,\n): InboundVersionMarkUpdate {\n\tif (\"batchStart\" in inboundResult) {\n\t\tconst batchId = getEffectiveBatchId(inboundResult.batchStart);\n\t\tif (inboundResult.type === \"fullBatch\") {\n\t\t\t// The last op is the batch's resolved point; an empty batch falls back to the batch-start key message.\n\t\t\tconst lastMessage =\n\t\t\t\t// eslint-disable-next-line unicorn/prefer-at -- Array.prototype.at is not in this package's lib target\n\t\t\t\tinboundResult.messages[inboundResult.messages.length - 1] ??\n\t\t\t\tinboundResult.batchStart.keyMessage;\n\t\t\treturn {\n\t\t\t\tsequenced: { batchId, sequenceNumber: lastMessage.sequenceNumber },\n\t\t\t\tcarriedBatchId: undefined,\n\t\t\t};\n\t\t}\n\t\t// batchStartingMessage: carry the id until the batch's end message arrives.\n\t\treturn { carriedBatchId: batchId };\n\t}\n\tif (\n\t\tinboundResult.type === \"nextBatchMessage\" &&\n\t\tinboundResult.batchEnd === true &&\n\t\tcarriedBatchId !== undefined\n\t) {\n\t\treturn {\n\t\t\tsequenced: {\n\t\t\t\tbatchId: carriedBatchId,\n\t\t\t\tsequenceNumber: inboundResult.nextMessage.sequenceNumber,\n\t\t\t},\n\t\t\tcarriedBatchId: undefined,\n\t\t};\n\t}\n\t// A mid-batch message, or a batch end with no carried id: no change.\n\treturn { carriedBatchId };\n}\n"]}

package/lib/versionMarks/index.d.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { VersionMarkResolver, type IVersionMarkResolver, type ResolveResult, type VersionMarkCapture, type VersionMarkResolverRuntimeHooks, } from "./versionMarkResolver.js";
+export { inboundVersionMarkUpdate, type InboundVersionMarkUpdate } from "./inboundBatch.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/versionMarks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/versionMarks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,+BAA+B,GACpC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/lib/versionMarks/index.js

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { VersionMarkResolver, } from "./versionMarkResolver.js";
+export { inboundVersionMarkUpdate } from "./inboundBatch.js";
+//# sourceMappingURL=index.js.map

package/lib/versionMarks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/versionMarks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,mBAAmB,GAKnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAiC,MAAM,mBAAmB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tVersionMarkResolver,\n\ttype IVersionMarkResolver,\n\ttype ResolveResult,\n\ttype VersionMarkCapture,\n\ttype VersionMarkResolverRuntimeHooks,\n} from \"./versionMarkResolver.js\";\nexport { inboundVersionMarkUpdate, type InboundVersionMarkUpdate } from \"./inboundBatch.js\";\n"]}

package/lib/versionMarks/versionMarkResolver.d.ts

@@ -0,0 +1,162 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { ISequencedDocumentMessage, IStream } from "@fluidframework/driver-definitions/internal";
+import type { TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
+import type { InboundMessageResult } from "../opLifecycle/index.js";
+/**
+ * Reads sequenced ops in `[from, to)` from delta storage, injected by the container so the runtime stays
+ * driver-agnostic. `abortSignal` cancels an in-flight fetch.
+ *
+ * @internal
+ */
+export interface IHistoricalOpReader {
+    fetchMessages(from: number, to?: number, abortSignal?: AbortSignal): Promise<IStream<ISequencedDocumentMessage[]>>;
+}
+/**
+ * Result of resolving a pending batchId.
+ *
+ * @legacy @alpha
+ */
+export type ResolveResult = {
+    readonly kind: "resolved";
+    readonly sequenceNumber: number;
+} | {
+    readonly kind: "pending";
+} | {
+    readonly kind: "unresolvable";
+};
+/**
+ * The data captured for a version mark. `pending` when the captured edit is local and not yet sequenced
+ * (resolve it later via {@link IVersionMarkResolver.resolve}); `resolved` when there is no in-flight local
+ * work, so the mark already points at a durable sequence number. The app packs its own stored record from
+ * this — the runtime does not define the stored locator shape.
+ *
+ * @legacy @alpha
+ */
+export type VersionMarkCapture = {
+    readonly kind: "pending";
+    readonly batchId: string;
+    readonly sequenceNumberLowerBound: number;
+} | {
+    readonly kind: "resolved";
+    readonly sequenceNumber: number;
+};
+/**
+ * Runtime-owned resolver for app-stored version mark locators.
+ *
+ * @legacy @alpha
+ */
+export interface IVersionMarkResolver {
+    /**
+     * Captures a version mark at the current point. Seals the current outbound batch first (so a just-made
+     * local edit has a stable `batchId`, which is only assigned when a batch is flushed), then returns the
+     * mark data atomically: a `pending` capture (`batchId` + `sequenceNumberLowerBound`) when there is an
+     * unacked local batch, or a `resolved` capture (`sequenceNumber`) when there is no in-flight local work.
+     *
+     * @remarks Sealing the batch is a side effect (it submits the current batch), so capture at savepoint
+     * boundaries, not per keystroke.
+     *
+     * @returns The pending batch identity and exclusive sequence number lower bound, or the current sequence number
+     * when there is no pending local batch.
+     */
+    sealAndCaptureVersionMark(): VersionMarkCapture;
+    /**
+     * Resolves a pending mark's batchId to a global sequence number (`sequenceNumberLowerBound` is the
+     * exclusive lower bound for a history read). A `resolved` sequence number feeds the loader's
+     * `loadContainerToSequenceNumber`.
+     *
+     * @param batchId - The stable identity of the pending batch.
+     * @param sequenceNumberLowerBound - The exclusive lower bound for the historical op search.
+     * @returns The resolved sequence number, or a result indicating that the batch remains pending or can
+     * no longer be resolved.
+     */
+    resolve(batchId: string, sequenceNumberLowerBound: number): Promise<ResolveResult>;
+    /**
+     * Subscribes to inbound batch sequencing: fires `(batchId, sequenceNumber)` per batch so any connected
+     * client can promote a matching pending mark. Returns an unsubscribe function.
+     *
+     * @param listener - Called with the stable batch identity and its final sequence number.
+     * @returns A function that unsubscribes the listener.
+     */
+    onBatchSequenced(listener: (batchId: string, sequenceNumber: number) => void): () => void;
+}
+/**
+ * @internal
+ */
+export interface VersionMarkResolverRuntimeHooks {
+    readonly getCurrentSequenceNumber: () => number;
+    readonly getCurrentMinimumSequenceNumber: () => number;
+    readonly getCurrentPendingBatchId: () => string | undefined;
+    /** Logs faults from app-supplied `onBatchSequenced` listeners (see {@link VersionMarkResolver.processInboundBatch}). */
+    readonly logger: TelemetryLoggerExt;
+    /**
+     * Seals the current outbound batch (flushes the runtime), so a just-submitted local edit is moved into
+     * the pending state with a stable `batchId` before
+     * {@link IVersionMarkResolver.sealAndCaptureVersionMark} reads it.
+     */
+    readonly flushPendingBatch: () => void;
+    /**
+     * Injected by the container, backed by delta storage. When absent, unknown batchIds resolve as `pending`.
+     */
+    readonly getHistoricalOpReader?: () => IHistoricalOpReader | undefined;
+    /**
+     * Creates a per-scan op unpacker that mirrors the live inbound path (chunk reassembly, ungroup,
+     * decompress), so the history scan observes the same restored `batchId` — in particular for chunked
+     * batches, whose id is stripped from the final chunk's wire metadata and restored only after
+     * reassembly. A fresh unpacker is created per scan since it holds reassembly state. When absent, the
+     * history scan cannot identify batches and reports `pending`/`unresolvable`.
+     */
+    readonly createHistoricalOpUnpacker?: () => (op: ISequencedDocumentMessage) => InboundMessageResult | undefined;
+}
+/**
+ * Resolves a mark's batchId to a global sequence number. The app owns mark storage and promotion; the
+ * runtime exposes the capture point and an ephemeral in-session `batchId -> sequenceNumber` map.
+ *
+ * @internal
+ */
+export declare class VersionMarkResolver implements IVersionMarkResolver {
+    private readonly hooks;
+    private readonly sequenceNumberByBatchId;
+    private readonly batchListeners;
+    /**
+     * Sticky flag: false until the feature is first used this session (a pending capture or a listener).
+     * While false the runtime skips all per-inbound-batch tracking, so a container that never uses version
+     * marks pays nothing on the hot path (mirrors #22497 gating `DuplicateBatchDetector` on offline load).
+     */
+    private tracking;
+    constructor(hooks: VersionMarkResolverRuntimeHooks);
+    /** Whether inbound batches need tracking (see {@link tracking}). Read by the runtime to gate the hot path. */
+    get isTracking(): boolean;
+    sealAndCaptureVersionMark(): VersionMarkCapture;
+    resolve(batchId: string, sequenceNumberLowerBound: number): Promise<ResolveResult>;
+    /**
+     * Scans sequenced ops after `sequenceNumberLowerBound` for `batchId`, returning its last op's
+     * sequence number when found and aborting the fetch once found or exhausted. Each op is routed through
+     * the same unpack pipeline the live inbound path uses (chunk reassembly, ungroup, decompress) and
+     * {@link inboundVersionMarkUpdate} derives its batch identity, so chunked batches resolve here too. The
+     * scan anchor is not guaranteed to be a batch boundary, so a leading batch clipped by the anchor is
+     * tolerated (its orphan end marker is dropped rather than fed to the processor). On a miss,
+     * {@link classifyMiss} distinguishes `pending` (not sequenced yet) from `unresolvable` (ops trimmed).
+     * See DEV.md.
+     */
+    private resolveFromHistory;
+    /**
+     * Classifies a history-scan miss as `pending` or `unresolvable`. See {@link resolveFromHistory}.
+     */
+    private classifyMiss;
+    onBatchSequenced(listener: (batchId: string, sequenceNumber: number) => void): () => void;
+    /** The sequence number for a batch seen live this session, or undefined. */
+    private sessionSequenceFor;
+    /** Records an inbound batch and notifies listeners so any client can promote matching pending marks. */
+    processInboundBatch(batchId: string, sequenceNumber: number): void;
+    /**
+     * Bounds the map to the collaboration window by dropping entries below the MSN (mirrors
+     * `DuplicateBatchDetector`). Safe because below the MSN every client has processed the batch, so its
+     * `onBatchSequenced` already fired; a dropped entry falls back to the history scan. Entries insert in
+     * sequence order, so iteration stops at the first retained one.
+     */
+    private evictBelowMinimumSequenceNumber;
+}
+//# sourceMappingURL=versionMarkResolver.d.ts.map

package/lib/versionMarks/versionMarkResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionMarkResolver.d.ts","sourceRoot":"","sources":["../../src/versionMarks/versionMarkResolver.ts"],"names":[],"mappings":"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"}

package/lib/versionMarks/versionMarkResolver.js

@@ -0,0 +1,194 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/core-utils/internal";
+import { asBatchMetadata } from "../metadata.js";
+import { inboundVersionMarkUpdate } from "./inboundBatch.js";
+/**
+ * Resolves a mark's batchId to a global sequence number. The app owns mark storage and promotion; the
+ * runtime exposes the capture point and an ephemeral in-session `batchId -> sequenceNumber` map.
+ *
+ * @internal
+ */
+export class VersionMarkResolver {
+    constructor(hooks) {
+        this.hooks = hooks;
+        this.sequenceNumberByBatchId = new Map();
+        this.batchListeners = new Set();
+        /**
+         * Sticky flag: false until the feature is first used this session (a pending capture or a listener).
+         * While false the runtime skips all per-inbound-batch tracking, so a container that never uses version
+         * marks pays nothing on the hot path (mirrors #22497 gating `DuplicateBatchDetector` on offline load).
+         */
+        this.tracking = false;
+    }
+    /** Whether inbound batches need tracking (see {@link tracking}). Read by the runtime to gate the hot path. */
+    get isTracking() {
+        return this.tracking;
+    }
+    sealAndCaptureVersionMark() {
+        // Seal the current batch so a just-submitted local edit is flushed into the pending state with a
+        // stable batchId (which is only assigned at flush) before we read it.
+        this.hooks.flushPendingBatch();
+        const sequenceNumberLowerBound = this.hooks.getCurrentSequenceNumber();
+        const batchId = this.hooks.getCurrentPendingBatchId();
+        if (batchId === undefined) {
+            // No unacked local batch: the mark already points at a durable sequence number.
+            return { kind: "resolved", sequenceNumber: sequenceNumberLowerBound };
+        }
+        // A pending mark needs its batch tracked so resolve() can promote it from the live map.
+        this.tracking = true;
+        return { kind: "pending", batchId, sequenceNumberLowerBound };
+    }
+    async resolve(batchId, sequenceNumberLowerBound) {
+        // Fast path: batch sequenced live this session.
+        const sequenceNumber = this.sessionSequenceFor(batchId);
+        if (sequenceNumber !== undefined) {
+            return { kind: "resolved", sequenceNumber };
+        }
+        // Otherwise scan history from the mark's reference point.
+        const reader = this.hooks.getHistoricalOpReader?.();
+        if (reader === undefined) {
+            // No reader: the batch may still sequence live, so report pending.
+            return { kind: "pending" };
+        }
+        return this.resolveFromHistory(reader, batchId, sequenceNumberLowerBound);
+    }
+    /**
+     * Scans sequenced ops after `sequenceNumberLowerBound` for `batchId`, returning its last op's
+     * sequence number when found and aborting the fetch once found or exhausted. Each op is routed through
+     * the same unpack pipeline the live inbound path uses (chunk reassembly, ungroup, decompress) and
+     * {@link inboundVersionMarkUpdate} derives its batch identity, so chunked batches resolve here too. The
+     * scan anchor is not guaranteed to be a batch boundary, so a leading batch clipped by the anchor is
+     * tolerated (its orphan end marker is dropped rather than fed to the processor). On a miss,
+     * {@link classifyMiss} distinguishes `pending` (not sequenced yet) from `unresolvable` (ops trimmed).
+     * See DEV.md.
+     */
+    async resolveFromHistory(reader, batchId, sequenceNumberLowerBound) {
+        const from = sequenceNumberLowerBound + 1;
+        const unpack = this.hooks.createHistoricalOpUnpacker?.();
+        const abortController = new AbortController();
+        try {
+            const stream = await reader.fetchMessages(from, undefined, abortController.signal);
+            let firstScannedSequenceNumber;
+            let carriedBatchId;
+            // Mirrors the processor's batch-in-progress state so we can drop an orphan end marker (below).
+            let inBatch = false;
+            while (true) {
+                const result = await stream.read();
+                if (result.done) {
+                    break;
+                }
+                for (const op of result.value) {
+                    firstScannedSequenceNumber ??= op.sequenceNumber;
+                    if (!inBatch && asBatchMetadata(op.metadata)?.batch === false) {
+                        // The anchor (`sequenceNumberLowerBound + 1`) may land inside a batch whose start
+                        // precedes the window; its orphan end marker would trip the processor's 0x9d5 assert.
+                        // Drop the clipped tail. The target batch is fully in-window, so this can't skip it.
+                        continue;
+                    }
+                    // undefined = a system op, or an incomplete chunk awaiting later fragments.
+                    const inboundResult = unpack?.(op);
+                    if (inboundResult === undefined) {
+                        continue;
+                    }
+                    // Track batch progress with the processor so the guard above skips only orphan ends.
+                    if (inboundResult.type === "batchStartingMessage") {
+                        inBatch = true;
+                    }
+                    else if (inboundResult.type === "nextBatchMessage" &&
+                        inboundResult.batchEnd === true) {
+                        inBatch = false;
+                    }
+                    // Derive batch identity exactly as the live inbound path does, carrying the id across a
+                    // piecemeal batch's messages.
+                    const update = inboundVersionMarkUpdate(inboundResult, carriedBatchId);
+                    carriedBatchId = update.carriedBatchId;
+                    if (update.sequenced?.batchId === batchId) {
+                        return { kind: "resolved", sequenceNumber: update.sequenced.sequenceNumber };
+                    }
+                }
+            }
+            // Not found: distinguish "not sequenced yet" from "trimmed" via the tip and where the scan landed.
+            return this.classifyMiss(from, firstScannedSequenceNumber);
+        }
+        finally {
+            // Cancel any in-flight fetch once we stop reading (found or exhausted).
+            abortController.abort();
+        }
+    }
+    /**
+     * Classifies a history-scan miss as `pending` or `unresolvable`. See {@link resolveFromHistory}.
+     */
+    classifyMiss(from, firstScannedSequenceNumber) {
+        // Invariant: a reader must never return an op before the requested range start. If it does, the
+        // trim inference below is meaningless, so fail loudly rather than misclassify.
+        assert(firstScannedSequenceNumber === undefined || firstScannedSequenceNumber >= from, 0xd1c /* historical op reader returned an op before the requested range start */);
+        const tip = this.hooks.getCurrentSequenceNumber();
+        if (from > tip) {
+            // Nothing is sequenced at/after the mark's reference point yet, so the batch cannot have landed.
+            return { kind: "pending" };
+        }
+        if (firstScannedSequenceNumber === undefined) {
+            // Empty read though ops should exist in `[from, tip]` → trimmed. ODSP-specific: a strict driver
+            // empties a `from`-misaligned trimmed range (validateMessages); a return-from-earliest driver
+            // would instead surface the trim via the `firstScannedSequenceNumber > from` branch below.
+            return { kind: "unresolvable" };
+        }
+        if (firstScannedSequenceNumber > from) {
+            // A trim gap at the anchor: the mark's ops (just after the reference point) are gone.
+            return { kind: "unresolvable" };
+        }
+        // Ops are present from the reference point and the batch is not among them: not yet sequenced.
+        return { kind: "pending" };
+    }
+    onBatchSequenced(listener) {
+        // A subscriber wants live promotions, so start tracking inbound batches from here on.
+        this.tracking = true;
+        this.batchListeners.add(listener);
+        return () => {
+            this.batchListeners.delete(listener);
+        };
+    }
+    /** The sequence number for a batch seen live this session, or undefined. */
+    sessionSequenceFor(batchId) {
+        return this.sequenceNumberByBatchId.get(batchId);
+    }
+    /** Records an inbound batch and notifies listeners so any client can promote matching pending marks. */
+    processInboundBatch(batchId, sequenceNumber) {
+        const existingSequenceNumber = this.sequenceNumberByBatchId.get(batchId);
+        if (existingSequenceNumber === sequenceNumber) {
+            return;
+        }
+        this.sequenceNumberByBatchId.set(batchId, sequenceNumber);
+        this.evictBelowMinimumSequenceNumber();
+        for (const listener of this.batchListeners) {
+            try {
+                listener(batchId, sequenceNumber);
+            }
+            catch (error) {
+                // Isolate each app listener (like the container's EventEmitterWithErrorHandling): one throw
+                // must not abort op processing or starve the rest. Log and continue rather than fault the
+                // container — a missed promotion is recoverable via resolve()'s history scan.
+                this.hooks.logger.sendErrorEvent({ eventName: "VersionMarkListenerException" }, error);
+            }
+        }
+    }
+    /**
+     * Bounds the map to the collaboration window by dropping entries below the MSN (mirrors
+     * `DuplicateBatchDetector`). Safe because below the MSN every client has processed the batch, so its
+     * `onBatchSequenced` already fired; a dropped entry falls back to the history scan. Entries insert in
+     * sequence order, so iteration stops at the first retained one.
+     */
+    evictBelowMinimumSequenceNumber() {
+        const minimumSequenceNumber = this.hooks.getCurrentMinimumSequenceNumber();
+        for (const [id, sequenceNumber] of this.sequenceNumberByBatchId) {
+            if (sequenceNumber >= minimumSequenceNumber) {
+                break;
+            }
+            this.sequenceNumberByBatchId.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=versionMarkResolver.js.map

package/lib/versionMarks/versionMarkResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionMarkResolver.js","sourceRoot":"","sources":["../../src/versionMarks/versionMarkResolver.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tISequencedDocumentMessage,\n\tIStream,\n} from \"@fluidframework/driver-definitions/internal\";\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { TelemetryLoggerExt } from \"@fluidframework/telemetry-utils/internal\";\n\nimport type { InboundMessageResult } from \"../opLifecycle/index.js\";\nimport { asBatchMetadata } from \"../metadata.js\";\n\nimport { inboundVersionMarkUpdate } from \"./inboundBatch.js\";\n\n/**\n * Reads sequenced ops in `[from, to)` from delta storage, injected by the container so the runtime stays\n * driver-agnostic. `abortSignal` cancels an in-flight fetch.\n *\n * @internal\n */\nexport interface IHistoricalOpReader {\n\tfetchMessages(\n\t\tfrom: number,\n\t\tto?: number,\n\t\tabortSignal?: AbortSignal,\n\t): Promise<IStream<ISequencedDocumentMessage[]>>;\n}\n\n/**\n * Result of resolving a pending batchId.\n *\n * @legacy @alpha\n */\nexport type ResolveResult =\n\t| { readonly kind: \"resolved\"; readonly sequenceNumber: number }\n\t| { readonly kind: \"pending\" }\n\t| { readonly kind: \"unresolvable\" };\n\n/**\n * The data captured for a version mark. `pending` when the captured edit is local and not yet sequenced\n * (resolve it later via {@link IVersionMarkResolver.resolve}); `resolved` when there is no in-flight local\n * work, so the mark already points at a durable sequence number. The app packs its own stored record from\n * this — the runtime does not define the stored locator shape.\n *\n * @legacy @alpha\n */\nexport type VersionMarkCapture =\n\t| {\n\t\t\treadonly kind: \"pending\";\n\t\t\treadonly batchId: string;\n\t\t\treadonly sequenceNumberLowerBound: number;\n\t  }\n\t| { readonly kind: \"resolved\"; readonly sequenceNumber: number };\n\n/**\n * Runtime-owned resolver for app-stored version mark locators.\n *\n * @legacy @alpha\n */\nexport interface IVersionMarkResolver {\n\t/**\n\t * Captures a version mark at the current point. Seals the current outbound batch first (so a just-made\n\t * local edit has a stable `batchId`, which is only assigned when a batch is flushed), then returns the\n\t * mark data atomically: a `pending` capture (`batchId` + `sequenceNumberLowerBound`) when there is an\n\t * unacked local batch, or a `resolved` capture (`sequenceNumber`) when there is no in-flight local work.\n\t *\n\t * @remarks Sealing the batch is a side effect (it submits the current batch), so capture at savepoint\n\t * boundaries, not per keystroke.\n\t *\n\t * @returns The pending batch identity and exclusive sequence number lower bound, or the current sequence number\n\t * when there is no pending local batch.\n\t */\n\tsealAndCaptureVersionMark(): VersionMarkCapture;\n\t/**\n\t * Resolves a pending mark's batchId to a global sequence number (`sequenceNumberLowerBound` is the\n\t * exclusive lower bound for a history read). A `resolved` sequence number feeds the loader's\n\t * `loadContainerToSequenceNumber`.\n\t *\n\t * @param batchId - The stable identity of the pending batch.\n\t * @param sequenceNumberLowerBound - The exclusive lower bound for the historical op search.\n\t * @returns The resolved sequence number, or a result indicating that the batch remains pending or can\n\t * no longer be resolved.\n\t */\n\tresolve(batchId: string, sequenceNumberLowerBound: number): Promise<ResolveResult>;\n\t/**\n\t * Subscribes to inbound batch sequencing: fires `(batchId, sequenceNumber)` per batch so any connected\n\t * client can promote a matching pending mark. Returns an unsubscribe function.\n\t *\n\t * @param listener - Called with the stable batch identity and its final sequence number.\n\t * @returns A function that unsubscribes the listener.\n\t */\n\tonBatchSequenced(listener: (batchId: string, sequenceNumber: number) => void): () => void;\n}\n\n/**\n * @internal\n */\nexport interface VersionMarkResolverRuntimeHooks {\n\treadonly getCurrentSequenceNumber: () => number;\n\treadonly getCurrentMinimumSequenceNumber: () => number;\n\treadonly getCurrentPendingBatchId: () => string | undefined;\n\t/** Logs faults from app-supplied `onBatchSequenced` listeners (see {@link VersionMarkResolver.processInboundBatch}). */\n\treadonly logger: TelemetryLoggerExt;\n\t/**\n\t * Seals the current outbound batch (flushes the runtime), so a just-submitted local edit is moved into\n\t * the pending state with a stable `batchId` before\n\t * {@link IVersionMarkResolver.sealAndCaptureVersionMark} reads it.\n\t */\n\treadonly flushPendingBatch: () => void;\n\t/**\n\t * Injected by the container, backed by delta storage. When absent, unknown batchIds resolve as `pending`.\n\t */\n\treadonly getHistoricalOpReader?: () => IHistoricalOpReader | undefined;\n\t/**\n\t * Creates a per-scan op unpacker that mirrors the live inbound path (chunk reassembly, ungroup,\n\t * decompress), so the history scan observes the same restored `batchId` — in particular for chunked\n\t * batches, whose id is stripped from the final chunk's wire metadata and restored only after\n\t * reassembly. A fresh unpacker is created per scan since it holds reassembly state. When absent, the\n\t * history scan cannot identify batches and reports `pending`/`unresolvable`.\n\t */\n\treadonly createHistoricalOpUnpacker?: () => (\n\t\top: ISequencedDocumentMessage,\n\t) => InboundMessageResult | undefined;\n}\n\n/**\n * Resolves a mark's batchId to a global sequence number. The app owns mark storage and promotion; the\n * runtime exposes the capture point and an ephemeral in-session `batchId -> sequenceNumber` map.\n *\n * @internal\n */\nexport class VersionMarkResolver implements IVersionMarkResolver {\n\tprivate readonly sequenceNumberByBatchId = new Map<string, number>();\n\tprivate readonly batchListeners = new Set<\n\t\t(batchId: string, sequenceNumber: number) => void\n\t>();\n\t/**\n\t * Sticky flag: false until the feature is first used this session (a pending capture or a listener).\n\t * While false the runtime skips all per-inbound-batch tracking, so a container that never uses version\n\t * marks pays nothing on the hot path (mirrors #22497 gating `DuplicateBatchDetector` on offline load).\n\t */\n\tprivate tracking = false;\n\n\tpublic constructor(private readonly hooks: VersionMarkResolverRuntimeHooks) {}\n\n\t/** Whether inbound batches need tracking (see {@link tracking}). Read by the runtime to gate the hot path. */\n\tpublic get isTracking(): boolean {\n\t\treturn this.tracking;\n\t}\n\n\tpublic sealAndCaptureVersionMark(): VersionMarkCapture {\n\t\t// Seal the current batch so a just-submitted local edit is flushed into the pending state with a\n\t\t// stable batchId (which is only assigned at flush) before we read it.\n\t\tthis.hooks.flushPendingBatch();\n\t\tconst sequenceNumberLowerBound = this.hooks.getCurrentSequenceNumber();\n\t\tconst batchId = this.hooks.getCurrentPendingBatchId();\n\t\tif (batchId === undefined) {\n\t\t\t// No unacked local batch: the mark already points at a durable sequence number.\n\t\t\treturn { kind: \"resolved\", sequenceNumber: sequenceNumberLowerBound };\n\t\t}\n\t\t// A pending mark needs its batch tracked so resolve() can promote it from the live map.\n\t\tthis.tracking = true;\n\t\treturn { kind: \"pending\", batchId, sequenceNumberLowerBound };\n\t}\n\n\tpublic async resolve(\n\t\tbatchId: string,\n\t\tsequenceNumberLowerBound: number,\n\t): Promise<ResolveResult> {\n\t\t// Fast path: batch sequenced live this session.\n\t\tconst sequenceNumber = this.sessionSequenceFor(batchId);\n\t\tif (sequenceNumber !== undefined) {\n\t\t\treturn { kind: \"resolved\", sequenceNumber };\n\t\t}\n\n\t\t// Otherwise scan history from the mark's reference point.\n\t\tconst reader = this.hooks.getHistoricalOpReader?.();\n\t\tif (reader === undefined) {\n\t\t\t// No reader: the batch may still sequence live, so report pending.\n\t\t\treturn { kind: \"pending\" };\n\t\t}\n\t\treturn this.resolveFromHistory(reader, batchId, sequenceNumberLowerBound);\n\t}\n\n\t/**\n\t * Scans sequenced ops after `sequenceNumberLowerBound` for `batchId`, returning its last op's\n\t * sequence number when found and aborting the fetch once found or exhausted. Each op is routed through\n\t * the same unpack pipeline the live inbound path uses (chunk reassembly, ungroup, decompress) and\n\t * {@link inboundVersionMarkUpdate} derives its batch identity, so chunked batches resolve here too. The\n\t * scan anchor is not guaranteed to be a batch boundary, so a leading batch clipped by the anchor is\n\t * tolerated (its orphan end marker is dropped rather than fed to the processor). On a miss,\n\t * {@link classifyMiss} distinguishes `pending` (not sequenced yet) from `unresolvable` (ops trimmed).\n\t * See DEV.md.\n\t */\n\tprivate async resolveFromHistory(\n\t\treader: IHistoricalOpReader,\n\t\tbatchId: string,\n\t\tsequenceNumberLowerBound: number,\n\t): Promise<ResolveResult> {\n\t\tconst from = sequenceNumberLowerBound + 1;\n\t\tconst unpack = this.hooks.createHistoricalOpUnpacker?.();\n\t\tconst abortController = new AbortController();\n\t\ttry {\n\t\t\tconst stream = await reader.fetchMessages(from, undefined, abortController.signal);\n\t\t\tlet firstScannedSequenceNumber: number | undefined;\n\t\t\tlet carriedBatchId: string | undefined;\n\t\t\t// Mirrors the processor's batch-in-progress state so we can drop an orphan end marker (below).\n\t\t\tlet inBatch = false;\n\t\t\twhile (true) {\n\t\t\t\tconst result = await stream.read();\n\t\t\t\tif (result.done) {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tfor (const op of result.value) {\n\t\t\t\t\tfirstScannedSequenceNumber ??= op.sequenceNumber;\n\t\t\t\t\tif (!inBatch && asBatchMetadata(op.metadata)?.batch === false) {\n\t\t\t\t\t\t// The anchor (`sequenceNumberLowerBound + 1`) may land inside a batch whose start\n\t\t\t\t\t\t// precedes the window; its orphan end marker would trip the processor's 0x9d5 assert.\n\t\t\t\t\t\t// Drop the clipped tail. The target batch is fully in-window, so this can't skip it.\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\t// undefined = a system op, or an incomplete chunk awaiting later fragments.\n\t\t\t\t\tconst inboundResult = unpack?.(op);\n\t\t\t\t\tif (inboundResult === undefined) {\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\t// Track batch progress with the processor so the guard above skips only orphan ends.\n\t\t\t\t\tif (inboundResult.type === \"batchStartingMessage\") {\n\t\t\t\t\t\tinBatch = true;\n\t\t\t\t\t} else if (\n\t\t\t\t\t\tinboundResult.type === \"nextBatchMessage\" &&\n\t\t\t\t\t\tinboundResult.batchEnd === true\n\t\t\t\t\t) {\n\t\t\t\t\t\tinBatch = false;\n\t\t\t\t\t}\n\t\t\t\t\t// Derive batch identity exactly as the live inbound path does, carrying the id across a\n\t\t\t\t\t// piecemeal batch's messages.\n\t\t\t\t\tconst update = inboundVersionMarkUpdate(inboundResult, carriedBatchId);\n\t\t\t\t\tcarriedBatchId = update.carriedBatchId;\n\t\t\t\t\tif (update.sequenced?.batchId === batchId) {\n\t\t\t\t\t\treturn { kind: \"resolved\", sequenceNumber: update.sequenced.sequenceNumber };\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Not found: distinguish \"not sequenced yet\" from \"trimmed\" via the tip and where the scan landed.\n\t\t\treturn this.classifyMiss(from, firstScannedSequenceNumber);\n\t\t} finally {\n\t\t\t// Cancel any in-flight fetch once we stop reading (found or exhausted).\n\t\t\tabortController.abort();\n\t\t}\n\t}\n\n\t/**\n\t * Classifies a history-scan miss as `pending` or `unresolvable`. See {@link resolveFromHistory}.\n\t */\n\tprivate classifyMiss(\n\t\tfrom: number,\n\t\tfirstScannedSequenceNumber: number | undefined,\n\t): ResolveResult {\n\t\t// Invariant: a reader must never return an op before the requested range start. If it does, the\n\t\t// trim inference below is meaningless, so fail loudly rather than misclassify.\n\t\tassert(\n\t\t\tfirstScannedSequenceNumber === undefined || firstScannedSequenceNumber >= from,\n\t\t\t0xd1c /* historical op reader returned an op before the requested range start */,\n\t\t);\n\t\tconst tip = this.hooks.getCurrentSequenceNumber();\n\t\tif (from > tip) {\n\t\t\t// Nothing is sequenced at/after the mark's reference point yet, so the batch cannot have landed.\n\t\t\treturn { kind: \"pending\" };\n\t\t}\n\t\tif (firstScannedSequenceNumber === undefined) {\n\t\t\t// Empty read though ops should exist in `[from, tip]` → trimmed. ODSP-specific: a strict driver\n\t\t\t// empties a `from`-misaligned trimmed range (validateMessages); a return-from-earliest driver\n\t\t\t// would instead surface the trim via the `firstScannedSequenceNumber > from` branch below.\n\t\t\treturn { kind: \"unresolvable\" };\n\t\t}\n\t\tif (firstScannedSequenceNumber > from) {\n\t\t\t// A trim gap at the anchor: the mark's ops (just after the reference point) are gone.\n\t\t\treturn { kind: \"unresolvable\" };\n\t\t}\n\t\t// Ops are present from the reference point and the batch is not among them: not yet sequenced.\n\t\treturn { kind: \"pending\" };\n\t}\n\n\tpublic onBatchSequenced(\n\t\tlistener: (batchId: string, sequenceNumber: number) => void,\n\t): () => void {\n\t\t// A subscriber wants live promotions, so start tracking inbound batches from here on.\n\t\tthis.tracking = true;\n\t\tthis.batchListeners.add(listener);\n\t\treturn () => {\n\t\t\tthis.batchListeners.delete(listener);\n\t\t};\n\t}\n\n\t/** The sequence number for a batch seen live this session, or undefined. */\n\tprivate sessionSequenceFor(batchId: string): number | undefined {\n\t\treturn this.sequenceNumberByBatchId.get(batchId);\n\t}\n\n\t/** Records an inbound batch and notifies listeners so any client can promote matching pending marks. */\n\tpublic processInboundBatch(batchId: string, sequenceNumber: number): void {\n\t\tconst existingSequenceNumber = this.sequenceNumberByBatchId.get(batchId);\n\t\tif (existingSequenceNumber === sequenceNumber) {\n\t\t\treturn;\n\t\t}\n\n\t\tthis.sequenceNumberByBatchId.set(batchId, sequenceNumber);\n\t\tthis.evictBelowMinimumSequenceNumber();\n\t\tfor (const listener of this.batchListeners) {\n\t\t\ttry {\n\t\t\t\tlistener(batchId, sequenceNumber);\n\t\t\t} catch (error) {\n\t\t\t\t// Isolate each app listener (like the container's EventEmitterWithErrorHandling): one throw\n\t\t\t\t// must not abort op processing or starve the rest. Log and continue rather than fault the\n\t\t\t\t// container — a missed promotion is recoverable via resolve()'s history scan.\n\t\t\t\tthis.hooks.logger.sendErrorEvent({ eventName: \"VersionMarkListenerException\" }, error);\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Bounds the map to the collaboration window by dropping entries below the MSN (mirrors\n\t * `DuplicateBatchDetector`). Safe because below the MSN every client has processed the batch, so its\n\t * `onBatchSequenced` already fired; a dropped entry falls back to the history scan. Entries insert in\n\t * sequence order, so iteration stops at the first retained one.\n\t */\n\tprivate evictBelowMinimumSequenceNumber(): void {\n\t\tconst minimumSequenceNumber = this.hooks.getCurrentMinimumSequenceNumber();\n\t\tfor (const [id, sequenceNumber] of this.sequenceNumberByBatchId) {\n\t\t\tif (sequenceNumber >= minimumSequenceNumber) {\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tthis.sequenceNumberByBatchId.delete(id);\n\t\t}\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/container-runtime",
-  "version": "2.114.0",
+  "version": "2.115.0",
   "description": "Fluid container runtime",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -33,6 +33,16 @@
         "default": "./dist/index.js"
       }
     },
+    "./legacy/alpha": {
+      "import": {
+        "types": "./lib/legacyAlpha.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/legacyAlpha.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
     "./internal": {
       "import": {
         "types": "./lib/index.d.ts",
@@ -119,18 +129,18 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.114.0",
-    "@fluidframework/container-definitions": "~2.114.0",
-    "@fluidframework/container-runtime-definitions": "~2.114.0",
-    "@fluidframework/core-interfaces": "~2.114.0",
-    "@fluidframework/core-utils": "~2.114.0",
-    "@fluidframework/datastore": "~2.114.0",
-    "@fluidframework/driver-definitions": "~2.114.0",
-    "@fluidframework/driver-utils": "~2.114.0",
-    "@fluidframework/id-compressor": "~2.114.0",
-    "@fluidframework/runtime-definitions": "~2.114.0",
-    "@fluidframework/runtime-utils": "~2.114.0",
-    "@fluidframework/telemetry-utils": "~2.114.0",
+    "@fluid-internal/client-utils": "~2.115.0",
+    "@fluidframework/container-definitions": "~2.115.0",
+    "@fluidframework/container-runtime-definitions": "~2.115.0",
+    "@fluidframework/core-interfaces": "~2.115.0",
+    "@fluidframework/core-utils": "~2.115.0",
+    "@fluidframework/datastore": "~2.115.0",
+    "@fluidframework/driver-definitions": "~2.115.0",
+    "@fluidframework/driver-utils": "~2.115.0",
+    "@fluidframework/id-compressor": "~2.115.0",
+    "@fluidframework/runtime-definitions": "~2.115.0",
+    "@fluidframework/runtime-utils": "~2.115.0",
+    "@fluidframework/telemetry-utils": "~2.115.0",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "double-ended-queue": "^2.1.0-0",
     "lz4js": "^0.2.0",
@@ -140,16 +150,16 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.114.0",
-    "@fluid-private/stochastic-test-utils": "~2.114.0",
-    "@fluid-private/test-pairwise-generator": "~2.114.0",
+    "@fluid-internal/mocha-test-setup": "~2.115.0",
+    "@fluid-private/stochastic-test-utils": "~2.115.0",
+    "@fluid-private/test-pairwise-generator": "~2.115.0",
     "@fluid-tools/benchmark": "^0.59.0",
     "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.65.0",
     "@fluidframework/container-runtime-previous": "npm:@fluidframework/container-runtime@2.112.0",
     "@fluidframework/eslint-config-fluid": "^13.0.0",
-    "@fluidframework/test-runtime-utils": "~2.114.0",
+    "@fluidframework/test-runtime-utils": "~2.115.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/double-ended-queue": "^2.1.0",
     "@types/lz4js": "^0.2.0",
@@ -183,8 +193,8 @@
     "build:compile": "fluid-build . --task compile",
     "build:docs": "api-extractor run --local",
     "build:entrypoints": "fluid-build . --task build:entrypoints",
-    "build:entrypoints:cjs": "flub generate entrypoints --resolutionConditions require --outFileLegacyBeta legacy --outDir ./dist",
-    "build:entrypoints:esm": "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat",
+    "build:entrypoints:cjs": "flub generate entrypoints --resolutionConditions require --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./dist",
+    "build:entrypoints:esm": "flub generate entrypoints --outFileLegacyBeta legacy --outFileLegacyAlpha legacyAlpha --outDir ./lib --node10TypeCompat",
     "build:esnext": "tsc --project ./tsconfig.json",
     "build:genver": "gen-version",
     "build:test": "concurrently npm:build:test:esm npm:build:test:cjs",
@@ -195,15 +205,17 @@
     "check:exports": "concurrently \"npm:check:exports:*\"",
     "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
     "check:exports:cjs:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.cjs.json",
+    "check:exports:cjs:legacyAlpha": "api-extractor run --config api-extractor/api-extractor-lint-legacyAlpha.cjs.json",
     "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
     "check:exports:esm:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.esm.json",
+    "check:exports:esm:legacyAlpha": "api-extractor run --config api-extractor/api-extractor-lint-legacyAlpha.esm.json",
     "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
     "check:format": "npm run check:biome",
     "ci:build:api-reports": "concurrently \"npm:ci:build:api-reports:*\"",
     "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor.current.json",
     "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor.legacy.json",
     "ci:build:docs": "api-extractor run",
-    "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts legacyAlpha.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
     "depcruise": "depcruise src/",
     "eslint": "eslint --quiet --format stylish src",
     "eslint:fix": "eslint --quiet --format stylish src --fix --fix-type problem,suggestion,layout",