@fluidframework/container-loader 2.100.0 → 2.101.1

package/lib/captureReferencedContents.d.ts

@@ -0,0 +1,154 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { IDocumentStorageService, ISequencedDocumentMessage, ISnapshot, ISnapshotTree } from "@fluidframework/driver-definitions/internal";
+import type { IBase64BlobContents, ISerializableBlobContents } from "./containerStorageAdapter.js";
+/**
+ * Wire-format constants this module needs to walk and filter snapshots.
+ * Authoritative definitions live in `container-runtime` and
+ * `runtime-definitions`; the values are duplicated here to avoid a
+ * loader → runtime layering dependency. A contract test in
+ * `packages/test/local-server-tests` asserts these match the authoritative
+ * values; do not change them in isolation.
+ *
+ * Authoritative sources:
+ * - `blobsTreeName`, `redirectTableBlobName`: `packages/runtime/container-runtime/src/blobManager/blobManagerSnapSum.ts`
+ * - `blobManagerBasePath`: `packages/runtime/container-runtime/src/blobManager/blobManager.ts`
+ * - `gcTreeKey`, `gcBlobPrefix`, `gcTombstoneBlobKey`, `gcDeletedBlobKey`: `packages/runtime/runtime-definitions/src/garbageCollectionDefinitions.ts`
+ *
+ * @internal
+ */
+export declare const wireFormatConstants: {
+    readonly blobsTreeName: ".blobs";
+    readonly redirectTableBlobName: ".redirectTable";
+    readonly blobManagerBasePath: "_blobs";
+    readonly gcTreeKey: "gc";
+    readonly gcBlobPrefix: "__gc";
+    readonly gcTombstoneBlobKey: "__tombstones";
+    readonly gcDeletedBlobKey: "__deletedNodes";
+};
+interface IGcNodeData {
+    outboundRoutes: string[];
+    unreferencedTimestampMs?: number;
+}
+interface IGcState {
+    gcNodes: {
+        [id: string]: IGcNodeData;
+    };
+}
+/**
+ * The parsed subset of the `gc` subtree that drives reachability decisions.
+ */
+export interface IGcSnapshotData {
+    gcState: IGcState | undefined;
+    tombstones: string[] | undefined;
+    deletedNodes: string[] | undefined;
+}
+/**
+ * Runs `fn` over `items` with at most `limit` promises in flight. Preserves
+ * input order on output (not that any caller depends on it today).
+ *
+ * Exported for unit tests; not part of the package public API.
+ *
+ * @internal
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+/**
+ * Parses the `gc` subtree of a base snapshot. Returns `undefined` if the
+ * snapshot has no GC tree (GC disabled or pre-GC document).
+ */
+export declare function parseGcSnapshotData(baseSnapshot: ISnapshotTree, storage: Pick<IDocumentStorageService, "readBlob">): Promise<IGcSnapshotData | undefined>;
+/**
+ * Walks a snapshot and inlines the contents of every blob reachable without
+ * crossing an `unreferenced` subtree boundary. Subtrees flagged
+ * `unreferenced: true` are skipped entirely — the summarizer sets that flag
+ * from GC state, so honouring it filters out dead subtrees without a
+ * separate GC-path traversal.
+ *
+ * The root-level `.blobs` subtree is special-cased: only its `.redirectTable`
+ * blob is read, because attachment blob contents are captured separately via
+ * {@link captureReferencedAttachmentBlobs}.
+ */
+export declare function readReferencedSnapshotBlobs(snapshot: ISnapshot | ISnapshotTree, storage: Pick<IDocumentStorageService, "readBlob">): Promise<ISerializableBlobContents>;
+/**
+ * Fetches attachment blob contents from a snapshot, filtered by GC
+ * reachability. Blobs GC has explicitly marked unreferenced, tombstoned, or
+ * deleted are skipped. Blobs absent from the GC graph are kept — GC state
+ * lags behind recent attachments and dropping them would lose live data.
+ * If `gcData` is `undefined`, every attachment blob is returned.
+ *
+ * The returned map is keyed by attachment blob storage id. Values are the
+ * raw bytes encoded as **base64** strings — attachment blobs may carry
+ * arbitrary binary payloads (images, encrypted data, etc.) and a
+ * UTF-8 round-trip would silently corrupt non-UTF-8 byte sequences with
+ * replacement characters. The runtime's own pending-blob serializer uses
+ * base64 for the same reason. This diverges from the structural-blob path
+ * in {@link readReferencedSnapshotBlobs}, which encodes UTF-8 because those
+ * blobs are JSON or other text the runtime authored. Callers must keep the
+ * two encodings on separate fields of the pending state so the load side
+ * can decode each correctly.
+ */
+export declare function captureReferencedAttachmentBlobs(baseSnapshot: ISnapshotTree, storage: Pick<IDocumentStorageService, "readBlob">, gcData: IGcSnapshotData | undefined): Promise<IBase64BlobContents>;
+/**
+ * A blob reference extracted from a `BlobAttach` op. `localId` is the
+ * `BlobManager` GC identity for the blob; `storageId` is the id used for
+ * `IDocumentStorageService.readBlob`.
+ *
+ * @internal
+ */
+export interface IBlobAttachReference {
+    readonly localId: string;
+    readonly storageId: string;
+}
+/**
+ * Extracts every `BlobAttach` reference an op carries. Returns an empty array
+ * for non-blobAttach ops.
+ *
+ * This is the single place in the loader that interprets the BlobAttach
+ * wire format. Capture and load-side reasoning about ops should call into
+ * this function rather than reading `op.metadata` directly, so a future
+ * protocol change touches one site.
+ *
+ * BlobAttach ops carry `(localId, storageId)` directly on
+ * `ISequencedDocumentMessage.metadata` and are not grouped — the container
+ * runtime routes them through a separate `outbox.submitBlobAttach` lane,
+ * and `OpGroupingManager.groupBatch` asserts (0x5dd) that no op carrying
+ * non-batch metadata enters a grouped batch. If either guarantee changes,
+ * extend this function rather than each call site.
+ *
+ * @internal
+ */
+export declare function extractBlobAttachReferences(op: Pick<ISequencedDocumentMessage, "metadata">): IBlobAttachReference[];
+/**
+ * Set of attachment-blob localIds that GC has marked unreferenced,
+ * tombstoned, or deleted in the base snapshot. `undefined` if `gcData`
+ * is `undefined` (GC disabled / pre-GC document).
+ *
+ * @internal
+ */
+export declare function unreferencedAttachmentBlobLocalIds(gcData: IGcSnapshotData | undefined): Set<string> | undefined;
+/**
+ * Inline attachment blob contents for the given `(localId, storageId)`
+ * references. Skips entries already present in `existing` (de-dupe with
+ * the snapshot path) and entries whose `localId` is in
+ * `unreferencedLocalIds`. Returns only the freshly-read entries; the
+ * caller merges them into the existing map.
+ *
+ * @internal
+ */
+export declare function inlineAttachmentBlobsByReference(references: readonly IBlobAttachReference[], storage: Pick<IDocumentStorageService, "readBlob">, unreferencedLocalIds: ReadonlySet<string> | undefined, existing: Readonly<IBase64BlobContents>): Promise<IBase64BlobContents>;
+/**
+ * Returns true if any referenced subtree of `baseSnapshot` declares a
+ * `groupId` — the snapshot-tree wire field that carries the runtime's
+ * loading-group identifier. Subtrees flagged `unreferenced` are skipped —
+ * a dead subtree's `groupId` would not be loaded by the runtime either.
+ *
+ * `captureFullContainerState` does not yet support loading groups: prefetching
+ * per-group snapshots adds a code path that has no end-to-end coverage and no
+ * known production consumer. Callers use this to fail fast with a `UsageError`
+ * rather than silently producing a pending state that omits group data.
+ */
+export declare function snapshotHasLoadingGroups(baseSnapshot: ISnapshotTree): boolean;
+export {};
+//# sourceMappingURL=captureReferencedContents.d.ts.map

package/lib/captureReferencedContents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureReferencedContents.d.ts","sourceRoot":"","sources":["../src/captureReferencedContents.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACX,uBAAuB,EACvB,yBAAyB,EACzB,SAAS,EACT,aAAa,EACb,MAAM,6CAA6C,CAAC;AAGrD,OAAO,KAAK,EACX,mBAAmB,EACnB,yBAAyB,EACzB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAQtB,CAAC;AAYX,UAAU,WAAW;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,UAAU,QAAQ;IACjB,OAAO,EAAE;QAAE,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,YAAY,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACnC;AAaD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC5C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,EAAE,CAAC,CAed;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACxC,YAAY,EAAE,aAAa,EAC3B,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAChD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAyBtC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAChD,QAAQ,EAAE,SAAS,GAAG,aAAa,EACnC,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAChD,OAAO,CAAC,yBAAyB,CAAC,CAUpC;AA8CD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gCAAgC,CACrD,YAAY,EAAE,aAAa,EAC3B,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,EAClD,MAAM,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA0B9B;AAwDD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CAC1C,EAAE,EAAE,IAAI,CAAC,yBAAyB,EAAE,UAAU,CAAC,GAC7C,oBAAoB,EAAE,CAKxB;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CACjD,MAAM,EAAE,eAAe,GAAG,SAAS,GACjC,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAEzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gCAAgC,CACrD,UAAU,EAAE,SAAS,oBAAoB,EAAE,EAC3C,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,EAClD,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EACrD,QAAQ,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAoB9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,aAAa,GAAG,OAAO,CAa7E"}

package/lib/captureReferencedContents.js

@@ -0,0 +1,338 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { bufferToString } from "@fluid-internal/client-utils";
+import { readAndParse } from "@fluidframework/driver-utils/internal";
+/**
+ * Wire-format constants this module needs to walk and filter snapshots.
+ * Authoritative definitions live in `container-runtime` and
+ * `runtime-definitions`; the values are duplicated here to avoid a
+ * loader → runtime layering dependency. A contract test in
+ * `packages/test/local-server-tests` asserts these match the authoritative
+ * values; do not change them in isolation.
+ *
+ * Authoritative sources:
+ * - `blobsTreeName`, `redirectTableBlobName`: `packages/runtime/container-runtime/src/blobManager/blobManagerSnapSum.ts`
+ * - `blobManagerBasePath`: `packages/runtime/container-runtime/src/blobManager/blobManager.ts`
+ * - `gcTreeKey`, `gcBlobPrefix`, `gcTombstoneBlobKey`, `gcDeletedBlobKey`: `packages/runtime/runtime-definitions/src/garbageCollectionDefinitions.ts`
+ *
+ * @internal
+ */
+export const wireFormatConstants = {
+    blobsTreeName: ".blobs",
+    redirectTableBlobName: ".redirectTable",
+    blobManagerBasePath: "_blobs",
+    gcTreeKey: "gc",
+    gcBlobPrefix: "__gc",
+    gcTombstoneBlobKey: "__tombstones",
+    gcDeletedBlobKey: "__deletedNodes",
+};
+const { blobsTreeName, redirectTableBlobName, blobManagerBasePath, gcTreeKey, gcBlobPrefix, gcTombstoneBlobKey, gcDeletedBlobKey, } = wireFormatConstants;
+/**
+ * Upper bound on concurrent `readBlob` calls. Driver/service back-pressure is
+ * real for large documents, and unbounded `Promise.all` can trigger throttling
+ * or spike memory. The value is a pragmatic middle ground — high enough to
+ * keep a typical driver's request pipeline full, low enough to avoid storms.
+ */
+const maxReadConcurrency = 32;
+/**
+ * Runs `fn` over `items` with at most `limit` promises in flight. Preserves
+ * input order on output (not that any caller depends on it today).
+ *
+ * Exported for unit tests; not part of the package public API.
+ *
+ * @internal
+ */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = Array.from({ length: items.length });
+    let cursor = 0;
+    const workerCount = Math.min(limit, items.length);
+    const workers = Array.from({ length: workerCount }, async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            const item = items[index];
+            if (item !== undefined) {
+                results[index] = await fn(item);
+            }
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Parses the `gc` subtree of a base snapshot. Returns `undefined` if the
+ * snapshot has no GC tree (GC disabled or pre-GC document).
+ */
+export async function parseGcSnapshotData(baseSnapshot, storage) {
+    const gcSnapshotTree = baseSnapshot.trees[gcTreeKey];
+    if (gcSnapshotTree === undefined) {
+        return undefined;
+    }
+    let gcState;
+    let tombstones;
+    let deletedNodes;
+    for (const [key, blobId] of Object.entries(gcSnapshotTree.blobs)) {
+        if (key === gcDeletedBlobKey) {
+            deletedNodes = await readAndParse(storage, blobId);
+        }
+        else if (key === gcTombstoneBlobKey) {
+            tombstones = await readAndParse(storage, blobId);
+        }
+        else if (key.startsWith(gcBlobPrefix)) {
+            const partial = await readAndParse(storage, blobId);
+            if (gcState === undefined) {
+                gcState = { gcNodes: { ...partial.gcNodes } };
+            }
+            else {
+                for (const [nodeId, nodeData] of Object.entries(partial.gcNodes)) {
+                    gcState.gcNodes[nodeId] ??= nodeData;
+                }
+            }
+        }
+    }
+    return { gcState, tombstones, deletedNodes };
+}
+/**
+ * Walks a snapshot and inlines the contents of every blob reachable without
+ * crossing an `unreferenced` subtree boundary. Subtrees flagged
+ * `unreferenced: true` are skipped entirely — the summarizer sets that flag
+ * from GC state, so honouring it filters out dead subtrees without a
+ * separate GC-path traversal.
+ *
+ * The root-level `.blobs` subtree is special-cased: only its `.redirectTable`
+ * blob is read, because attachment blob contents are captured separately via
+ * {@link captureReferencedAttachmentBlobs}.
+ */
+export async function readReferencedSnapshotBlobs(snapshot, storage) {
+    const { tree, read } = toTreeAndReader(snapshot, storage);
+    const ids = new Set();
+    collectReferencedBlobIds(tree, true, ids);
+    const blobs = {};
+    await mapWithConcurrency([...ids], maxReadConcurrency, async (id) => {
+        const data = await read(id);
+        blobs[id] = bufferToString(data, "utf8");
+    });
+    return blobs;
+}
+/**
+ * Synchronously walks the snapshot tree and gathers the set of blob ids that
+ * should be inlined. Subtrees flagged `unreferenced: true` are skipped
+ * entirely. The root-level `.blobs` subtree is special-cased: only its
+ * `.redirectTable` id is collected, because attachment blob contents are
+ * captured separately via {@link captureReferencedAttachmentBlobs}.
+ */
+function collectReferencedBlobIds(tree, isRoot, ids) {
+    if (tree.unreferenced === true) {
+        return;
+    }
+    for (const blobId of Object.values(tree.blobs)) {
+        ids.add(blobId);
+    }
+    for (const [key, subTree] of Object.entries(tree.trees)) {
+        if (isRoot && key === blobsTreeName) {
+            const tableBlobId = subTree.blobs[redirectTableBlobName];
+            if (tableBlobId !== undefined) {
+                ids.add(tableBlobId);
+            }
+        }
+        else {
+            collectReferencedBlobIds(subTree, false, ids);
+        }
+    }
+}
+function toTreeAndReader(snapshot, storage) {
+    if ("snapshotTree" in snapshot) {
+        const blobContents = snapshot.blobContents;
+        return {
+            tree: snapshot.snapshotTree,
+            read: async (id) => blobContents.get(id) ?? storage.readBlob(id),
+        };
+    }
+    return { tree: snapshot, read: async (id) => storage.readBlob(id) };
+}
+/**
+ * Fetches attachment blob contents from a snapshot, filtered by GC
+ * reachability. Blobs GC has explicitly marked unreferenced, tombstoned, or
+ * deleted are skipped. Blobs absent from the GC graph are kept — GC state
+ * lags behind recent attachments and dropping them would lose live data.
+ * If `gcData` is `undefined`, every attachment blob is returned.
+ *
+ * The returned map is keyed by attachment blob storage id. Values are the
+ * raw bytes encoded as **base64** strings — attachment blobs may carry
+ * arbitrary binary payloads (images, encrypted data, etc.) and a
+ * UTF-8 round-trip would silently corrupt non-UTF-8 byte sequences with
+ * replacement characters. The runtime's own pending-blob serializer uses
+ * base64 for the same reason. This diverges from the structural-blob path
+ * in {@link readReferencedSnapshotBlobs}, which encodes UTF-8 because those
+ * blobs are JSON or other text the runtime authored. Callers must keep the
+ * two encodings on separate fields of the pending state so the load side
+ * can decode each correctly.
+ */
+export async function captureReferencedAttachmentBlobs(baseSnapshot, storage, gcData) {
+    const blobsTree = baseSnapshot.trees[blobsTreeName];
+    if (blobsTree === undefined) {
+        return {};
+    }
+    const localIdToStorageId = await readRedirectTable(blobsTree, storage);
+    if (localIdToStorageId.size === 0) {
+        return {};
+    }
+    const unreferencedLocalIds = gcData === undefined ? undefined : collectUnreferencedBlobLocalIds(gcData);
+    const storageIdsToFetch = new Set();
+    for (const [localId, storageId] of localIdToStorageId) {
+        if (unreferencedLocalIds?.has(localId) !== true) {
+            storageIdsToFetch.add(storageId);
+        }
+    }
+    const contents = {};
+    await mapWithConcurrency([...storageIdsToFetch], maxReadConcurrency, async (storageId) => {
+        const buffer = await storage.readBlob(storageId);
+        contents[storageId] = bufferToString(buffer, "base64");
+    });
+    return contents;
+}
+/**
+ * Reconstructs the BlobManager's redirect table from a `.blobs` subtree.
+ * Mirrors `toRedirectTable` in blobManagerSnapSum.ts.
+ */
+async function readRedirectTable(blobsTree, storage) {
+    const redirectTable = new Map();
+    const tableBlobId = blobsTree.blobs[redirectTableBlobName];
+    if (tableBlobId !== undefined) {
+        const entries = await readAndParse(storage, tableBlobId);
+        for (const [localId, storageId] of entries) {
+            redirectTable.set(localId, storageId);
+        }
+    }
+    for (const [key, storageId] of Object.entries(blobsTree.blobs)) {
+        if (key !== redirectTableBlobName) {
+            // Identity mapping: storage ids referenced directly in handles (legacy).
+            redirectTable.set(storageId, storageId);
+        }
+    }
+    return redirectTable;
+}
+/**
+ * Collects the set of blob localIds that GC has explicitly marked as
+ * unreferenced (via `unreferencedTimestampMs` on a gc node), tombstoned, or
+ * deleted. Tombstones and deletedNodes are applied regardless of whether
+ * `gcState` is present — they are authoritative on their own and must not
+ * be silently dropped when gc state is absent but tombstone/deleted lists
+ * exist.
+ */
+function collectUnreferencedBlobLocalIds(gcData) {
+    const blobPathPrefix = `/${blobManagerBasePath}/`;
+    const unreferenced = new Set();
+    if (gcData.gcState !== undefined) {
+        for (const [nodePath, nodeData] of Object.entries(gcData.gcState.gcNodes)) {
+            if (nodePath.startsWith(blobPathPrefix) &&
+                nodeData.unreferencedTimestampMs !== undefined) {
+                unreferenced.add(nodePath.slice(blobPathPrefix.length));
+            }
+        }
+    }
+    for (const nodePath of [...(gcData.tombstones ?? []), ...(gcData.deletedNodes ?? [])]) {
+        if (nodePath.startsWith(blobPathPrefix)) {
+            unreferenced.add(nodePath.slice(blobPathPrefix.length));
+        }
+    }
+    return unreferenced;
+}
+function isBlobAttachLikeMetadata(metadata) {
+    if (typeof metadata !== "object" || metadata === null) {
+        return false;
+    }
+    const candidate = metadata;
+    return typeof candidate.localId === "string" && typeof candidate.blobId === "string";
+}
+/**
+ * Extracts every `BlobAttach` reference an op carries. Returns an empty array
+ * for non-blobAttach ops.
+ *
+ * This is the single place in the loader that interprets the BlobAttach
+ * wire format. Capture and load-side reasoning about ops should call into
+ * this function rather than reading `op.metadata` directly, so a future
+ * protocol change touches one site.
+ *
+ * BlobAttach ops carry `(localId, storageId)` directly on
+ * `ISequencedDocumentMessage.metadata` and are not grouped — the container
+ * runtime routes them through a separate `outbox.submitBlobAttach` lane,
+ * and `OpGroupingManager.groupBatch` asserts (0x5dd) that no op carrying
+ * non-batch metadata enters a grouped batch. If either guarantee changes,
+ * extend this function rather than each call site.
+ *
+ * @internal
+ */
+export function extractBlobAttachReferences(op) {
+    if (!isBlobAttachLikeMetadata(op.metadata)) {
+        return [];
+    }
+    return [{ localId: op.metadata.localId, storageId: op.metadata.blobId }];
+}
+/**
+ * Set of attachment-blob localIds that GC has marked unreferenced,
+ * tombstoned, or deleted in the base snapshot. `undefined` if `gcData`
+ * is `undefined` (GC disabled / pre-GC document).
+ *
+ * @internal
+ */
+export function unreferencedAttachmentBlobLocalIds(gcData) {
+    return gcData === undefined ? undefined : collectUnreferencedBlobLocalIds(gcData);
+}
+/**
+ * Inline attachment blob contents for the given `(localId, storageId)`
+ * references. Skips entries already present in `existing` (de-dupe with
+ * the snapshot path) and entries whose `localId` is in
+ * `unreferencedLocalIds`. Returns only the freshly-read entries; the
+ * caller merges them into the existing map.
+ *
+ * @internal
+ */
+export async function inlineAttachmentBlobsByReference(references, storage, unreferencedLocalIds, existing) {
+    const storageIdsToFetch = new Set();
+    for (const { localId, storageId } of references) {
+        if (unreferencedLocalIds?.has(localId) === true) {
+            continue;
+        }
+        if (existing[storageId] !== undefined) {
+            continue;
+        }
+        storageIdsToFetch.add(storageId);
+    }
+    const added = {};
+    if (storageIdsToFetch.size === 0) {
+        return added;
+    }
+    await mapWithConcurrency([...storageIdsToFetch], maxReadConcurrency, async (storageId) => {
+        const buffer = await storage.readBlob(storageId);
+        added[storageId] = bufferToString(buffer, "base64");
+    });
+    return added;
+}
+/**
+ * Returns true if any referenced subtree of `baseSnapshot` declares a
+ * `groupId` — the snapshot-tree wire field that carries the runtime's
+ * loading-group identifier. Subtrees flagged `unreferenced` are skipped —
+ * a dead subtree's `groupId` would not be loaded by the runtime either.
+ *
+ * `captureFullContainerState` does not yet support loading groups: prefetching
+ * per-group snapshots adds a code path that has no end-to-end coverage and no
+ * known production consumer. Callers use this to fail fast with a `UsageError`
+ * rather than silently producing a pending state that omits group data.
+ */
+export function snapshotHasLoadingGroups(baseSnapshot) {
+    if (baseSnapshot.unreferenced === true) {
+        return false;
+    }
+    if (baseSnapshot.groupId !== undefined) {
+        return true;
+    }
+    for (const child of Object.values(baseSnapshot.trees)) {
+        if (snapshotHasLoadingGroups(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=captureReferencedContents.js.map

package/lib/captureReferencedContents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureReferencedContents.js","sourceRoot":"","sources":["../src/captureReferencedContents.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 { bufferToString } from \"@fluid-internal/client-utils\";\nimport type {\n\tIDocumentStorageService,\n\tISequencedDocumentMessage,\n\tISnapshot,\n\tISnapshotTree,\n} from \"@fluidframework/driver-definitions/internal\";\nimport { readAndParse } from \"@fluidframework/driver-utils/internal\";\n\nimport type {\n\tIBase64BlobContents,\n\tISerializableBlobContents,\n} from \"./containerStorageAdapter.js\";\n\n/**\n * Wire-format constants this module needs to walk and filter snapshots.\n * Authoritative definitions live in `container-runtime` and\n * `runtime-definitions`; the values are duplicated here to avoid a\n * loader → runtime layering dependency. A contract test in\n * `packages/test/local-server-tests` asserts these match the authoritative\n * values; do not change them in isolation.\n *\n * Authoritative sources:\n * - `blobsTreeName`, `redirectTableBlobName`: `packages/runtime/container-runtime/src/blobManager/blobManagerSnapSum.ts`\n * - `blobManagerBasePath`: `packages/runtime/container-runtime/src/blobManager/blobManager.ts`\n * - `gcTreeKey`, `gcBlobPrefix`, `gcTombstoneBlobKey`, `gcDeletedBlobKey`: `packages/runtime/runtime-definitions/src/garbageCollectionDefinitions.ts`\n *\n * @internal\n */\nexport const wireFormatConstants = {\n\tblobsTreeName: \".blobs\",\n\tredirectTableBlobName: \".redirectTable\",\n\tblobManagerBasePath: \"_blobs\",\n\tgcTreeKey: \"gc\",\n\tgcBlobPrefix: \"__gc\",\n\tgcTombstoneBlobKey: \"__tombstones\",\n\tgcDeletedBlobKey: \"__deletedNodes\",\n} as const;\n\nconst {\n\tblobsTreeName,\n\tredirectTableBlobName,\n\tblobManagerBasePath,\n\tgcTreeKey,\n\tgcBlobPrefix,\n\tgcTombstoneBlobKey,\n\tgcDeletedBlobKey,\n} = wireFormatConstants;\n\ninterface IGcNodeData {\n\toutboundRoutes: string[];\n\tunreferencedTimestampMs?: number;\n}\n\ninterface IGcState {\n\tgcNodes: { [id: string]: IGcNodeData };\n}\n\n/**\n * The parsed subset of the `gc` subtree that drives reachability decisions.\n */\nexport interface IGcSnapshotData {\n\tgcState: IGcState | undefined;\n\ttombstones: string[] | undefined;\n\tdeletedNodes: string[] | undefined;\n}\n\n/** Reader that returns a blob's contents for a given storage id. */\ntype BlobReader = (id: string) => Promise<ArrayBufferLike>;\n\n/**\n * Upper bound on concurrent `readBlob` calls. Driver/service back-pressure is\n * real for large documents, and unbounded `Promise.all` can trigger throttling\n * or spike memory. The value is a pragmatic middle ground — high enough to\n * keep a typical driver's request pipeline full, low enough to avoid storms.\n */\nconst maxReadConcurrency = 32;\n\n/**\n * Runs `fn` over `items` with at most `limit` promises in flight. Preserves\n * input order on output (not that any caller depends on it today).\n *\n * Exported for unit tests; not part of the package public API.\n *\n * @internal\n */\nexport async function mapWithConcurrency<T, R>(\n\titems: readonly T[],\n\tlimit: number,\n\tfn: (item: T) => Promise<R>,\n): Promise<R[]> {\n\tconst results: R[] = Array.from({ length: items.length });\n\tlet cursor = 0;\n\tconst workerCount = Math.min(limit, items.length);\n\tconst workers = Array.from({ length: workerCount }, async () => {\n\t\twhile (cursor < items.length) {\n\t\t\tconst index = cursor++;\n\t\t\tconst item = items[index];\n\t\t\tif (item !== undefined) {\n\t\t\t\tresults[index] = await fn(item);\n\t\t\t}\n\t\t}\n\t});\n\tawait Promise.all(workers);\n\treturn results;\n}\n\n/**\n * Parses the `gc` subtree of a base snapshot. Returns `undefined` if the\n * snapshot has no GC tree (GC disabled or pre-GC document).\n */\nexport async function parseGcSnapshotData(\n\tbaseSnapshot: ISnapshotTree,\n\tstorage: Pick<IDocumentStorageService, \"readBlob\">,\n): Promise<IGcSnapshotData | undefined> {\n\tconst gcSnapshotTree: ISnapshotTree | undefined = baseSnapshot.trees[gcTreeKey];\n\tif (gcSnapshotTree === undefined) {\n\t\treturn undefined;\n\t}\n\tlet gcState: IGcState | undefined;\n\tlet tombstones: string[] | undefined;\n\tlet deletedNodes: string[] | undefined;\n\tfor (const [key, blobId] of Object.entries(gcSnapshotTree.blobs)) {\n\t\tif (key === gcDeletedBlobKey) {\n\t\t\tdeletedNodes = await readAndParse<string[]>(storage, blobId);\n\t\t} else if (key === gcTombstoneBlobKey) {\n\t\t\ttombstones = await readAndParse<string[]>(storage, blobId);\n\t\t} else if (key.startsWith(gcBlobPrefix)) {\n\t\t\tconst partial = await readAndParse<IGcState>(storage, blobId);\n\t\t\tif (gcState === undefined) {\n\t\t\t\tgcState = { gcNodes: { ...partial.gcNodes } };\n\t\t\t} else {\n\t\t\t\tfor (const [nodeId, nodeData] of Object.entries(partial.gcNodes)) {\n\t\t\t\t\tgcState.gcNodes[nodeId] ??= nodeData;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\treturn { gcState, tombstones, deletedNodes };\n}\n\n/**\n * Walks a snapshot and inlines the contents of every blob reachable without\n * crossing an `unreferenced` subtree boundary. Subtrees flagged\n * `unreferenced: true` are skipped entirely — the summarizer sets that flag\n * from GC state, so honouring it filters out dead subtrees without a\n * separate GC-path traversal.\n *\n * The root-level `.blobs` subtree is special-cased: only its `.redirectTable`\n * blob is read, because attachment blob contents are captured separately via\n * {@link captureReferencedAttachmentBlobs}.\n */\nexport async function readReferencedSnapshotBlobs(\n\tsnapshot: ISnapshot | ISnapshotTree,\n\tstorage: Pick<IDocumentStorageService, \"readBlob\">,\n): Promise<ISerializableBlobContents> {\n\tconst { tree, read } = toTreeAndReader(snapshot, storage);\n\tconst ids = new Set<string>();\n\tcollectReferencedBlobIds(tree, true, ids);\n\tconst blobs: ISerializableBlobContents = {};\n\tawait mapWithConcurrency([...ids], maxReadConcurrency, async (id) => {\n\t\tconst data = await read(id);\n\t\tblobs[id] = bufferToString(data, \"utf8\");\n\t});\n\treturn blobs;\n}\n\n/**\n * Synchronously walks the snapshot tree and gathers the set of blob ids that\n * should be inlined. Subtrees flagged `unreferenced: true` are skipped\n * entirely. The root-level `.blobs` subtree is special-cased: only its\n * `.redirectTable` id is collected, because attachment blob contents are\n * captured separately via {@link captureReferencedAttachmentBlobs}.\n */\nfunction collectReferencedBlobIds(\n\ttree: ISnapshotTree,\n\tisRoot: boolean,\n\tids: Set<string>,\n): void {\n\tif (tree.unreferenced === true) {\n\t\treturn;\n\t}\n\tfor (const blobId of Object.values(tree.blobs)) {\n\t\tids.add(blobId);\n\t}\n\tfor (const [key, subTree] of Object.entries(tree.trees)) {\n\t\tif (isRoot && key === blobsTreeName) {\n\t\t\tconst tableBlobId = subTree.blobs[redirectTableBlobName];\n\t\t\tif (tableBlobId !== undefined) {\n\t\t\t\tids.add(tableBlobId);\n\t\t\t}\n\t\t} else {\n\t\t\tcollectReferencedBlobIds(subTree, false, ids);\n\t\t}\n\t}\n}\n\nfunction toTreeAndReader(\n\tsnapshot: ISnapshot | ISnapshotTree,\n\tstorage: Pick<IDocumentStorageService, \"readBlob\">,\n): { tree: ISnapshotTree; read: BlobReader } {\n\tif (\"snapshotTree\" in snapshot) {\n\t\tconst blobContents = snapshot.blobContents;\n\t\treturn {\n\t\t\ttree: snapshot.snapshotTree,\n\t\t\tread: async (id) => blobContents.get(id) ?? storage.readBlob(id),\n\t\t};\n\t}\n\treturn { tree: snapshot, read: async (id) => storage.readBlob(id) };\n}\n\n/**\n * Fetches attachment blob contents from a snapshot, filtered by GC\n * reachability. Blobs GC has explicitly marked unreferenced, tombstoned, or\n * deleted are skipped. Blobs absent from the GC graph are kept — GC state\n * lags behind recent attachments and dropping them would lose live data.\n * If `gcData` is `undefined`, every attachment blob is returned.\n *\n * The returned map is keyed by attachment blob storage id. Values are the\n * raw bytes encoded as **base64** strings — attachment blobs may carry\n * arbitrary binary payloads (images, encrypted data, etc.) and a\n * UTF-8 round-trip would silently corrupt non-UTF-8 byte sequences with\n * replacement characters. The runtime's own pending-blob serializer uses\n * base64 for the same reason. This diverges from the structural-blob path\n * in {@link readReferencedSnapshotBlobs}, which encodes UTF-8 because those\n * blobs are JSON or other text the runtime authored. Callers must keep the\n * two encodings on separate fields of the pending state so the load side\n * can decode each correctly.\n */\nexport async function captureReferencedAttachmentBlobs(\n\tbaseSnapshot: ISnapshotTree,\n\tstorage: Pick<IDocumentStorageService, \"readBlob\">,\n\tgcData: IGcSnapshotData | undefined,\n): Promise<IBase64BlobContents> {\n\tconst blobsTree: ISnapshotTree | undefined = baseSnapshot.trees[blobsTreeName];\n\tif (blobsTree === undefined) {\n\t\treturn {};\n\t}\n\tconst localIdToStorageId = await readRedirectTable(blobsTree, storage);\n\tif (localIdToStorageId.size === 0) {\n\t\treturn {};\n\t}\n\n\tconst unreferencedLocalIds =\n\t\tgcData === undefined ? undefined : collectUnreferencedBlobLocalIds(gcData);\n\n\tconst storageIdsToFetch = new Set<string>();\n\tfor (const [localId, storageId] of localIdToStorageId) {\n\t\tif (unreferencedLocalIds?.has(localId) !== true) {\n\t\t\tstorageIdsToFetch.add(storageId);\n\t\t}\n\t}\n\n\tconst contents: IBase64BlobContents = {};\n\tawait mapWithConcurrency([...storageIdsToFetch], maxReadConcurrency, async (storageId) => {\n\t\tconst buffer = await storage.readBlob(storageId);\n\t\tcontents[storageId] = bufferToString(buffer, \"base64\");\n\t});\n\treturn contents;\n}\n\n/**\n * Reconstructs the BlobManager's redirect table from a `.blobs` subtree.\n * Mirrors `toRedirectTable` in blobManagerSnapSum.ts.\n */\nasync function readRedirectTable(\n\tblobsTree: ISnapshotTree,\n\tstorage: Pick<IDocumentStorageService, \"readBlob\">,\n): Promise<Map<string, string>> {\n\tconst redirectTable = new Map<string, string>();\n\tconst tableBlobId: string | undefined = blobsTree.blobs[redirectTableBlobName];\n\tif (tableBlobId !== undefined) {\n\t\tconst entries = await readAndParse<[string, string][]>(storage, tableBlobId);\n\t\tfor (const [localId, storageId] of entries) {\n\t\t\tredirectTable.set(localId, storageId);\n\t\t}\n\t}\n\tfor (const [key, storageId] of Object.entries(blobsTree.blobs)) {\n\t\tif (key !== redirectTableBlobName) {\n\t\t\t// Identity mapping: storage ids referenced directly in handles (legacy).\n\t\t\tredirectTable.set(storageId, storageId);\n\t\t}\n\t}\n\treturn redirectTable;\n}\n\n/**\n * Collects the set of blob localIds that GC has explicitly marked as\n * unreferenced (via `unreferencedTimestampMs` on a gc node), tombstoned, or\n * deleted. Tombstones and deletedNodes are applied regardless of whether\n * `gcState` is present — they are authoritative on their own and must not\n * be silently dropped when gc state is absent but tombstone/deleted lists\n * exist.\n */\nfunction collectUnreferencedBlobLocalIds(gcData: IGcSnapshotData): Set<string> {\n\tconst blobPathPrefix = `/${blobManagerBasePath}/`;\n\tconst unreferenced = new Set<string>();\n\tif (gcData.gcState !== undefined) {\n\t\tfor (const [nodePath, nodeData] of Object.entries(gcData.gcState.gcNodes)) {\n\t\t\tif (\n\t\t\t\tnodePath.startsWith(blobPathPrefix) &&\n\t\t\t\tnodeData.unreferencedTimestampMs !== undefined\n\t\t\t) {\n\t\t\t\tunreferenced.add(nodePath.slice(blobPathPrefix.length));\n\t\t\t}\n\t\t}\n\t}\n\tfor (const nodePath of [...(gcData.tombstones ?? []), ...(gcData.deletedNodes ?? [])]) {\n\t\tif (nodePath.startsWith(blobPathPrefix)) {\n\t\t\tunreferenced.add(nodePath.slice(blobPathPrefix.length));\n\t\t}\n\t}\n\treturn unreferenced;\n}\n\n/**\n * A blob reference extracted from a `BlobAttach` op. `localId` is the\n * `BlobManager` GC identity for the blob; `storageId` is the id used for\n * `IDocumentStorageService.readBlob`.\n *\n * @internal\n */\nexport interface IBlobAttachReference {\n\treadonly localId: string;\n\treadonly storageId: string;\n}\n\ninterface IBlobAttachLikeMetadata {\n\treadonly localId: string;\n\treadonly blobId: string;\n}\n\nfunction isBlobAttachLikeMetadata(metadata: unknown): metadata is IBlobAttachLikeMetadata {\n\tif (typeof metadata !== \"object\" || metadata === null) {\n\t\treturn false;\n\t}\n\tconst candidate = metadata as { localId?: unknown; blobId?: unknown };\n\treturn typeof candidate.localId === \"string\" && typeof candidate.blobId === \"string\";\n}\n\n/**\n * Extracts every `BlobAttach` reference an op carries. Returns an empty array\n * for non-blobAttach ops.\n *\n * This is the single place in the loader that interprets the BlobAttach\n * wire format. Capture and load-side reasoning about ops should call into\n * this function rather than reading `op.metadata` directly, so a future\n * protocol change touches one site.\n *\n * BlobAttach ops carry `(localId, storageId)` directly on\n * `ISequencedDocumentMessage.metadata` and are not grouped — the container\n * runtime routes them through a separate `outbox.submitBlobAttach` lane,\n * and `OpGroupingManager.groupBatch` asserts (0x5dd) that no op carrying\n * non-batch metadata enters a grouped batch. If either guarantee changes,\n * extend this function rather than each call site.\n *\n * @internal\n */\nexport function extractBlobAttachReferences(\n\top: Pick<ISequencedDocumentMessage, \"metadata\">,\n): IBlobAttachReference[] {\n\tif (!isBlobAttachLikeMetadata(op.metadata)) {\n\t\treturn [];\n\t}\n\treturn [{ localId: op.metadata.localId, storageId: op.metadata.blobId }];\n}\n\n/**\n * Set of attachment-blob localIds that GC has marked unreferenced,\n * tombstoned, or deleted in the base snapshot. `undefined` if `gcData`\n * is `undefined` (GC disabled / pre-GC document).\n *\n * @internal\n */\nexport function unreferencedAttachmentBlobLocalIds(\n\tgcData: IGcSnapshotData | undefined,\n): Set<string> | undefined {\n\treturn gcData === undefined ? undefined : collectUnreferencedBlobLocalIds(gcData);\n}\n\n/**\n * Inline attachment blob contents for the given `(localId, storageId)`\n * references. Skips entries already present in `existing` (de-dupe with\n * the snapshot path) and entries whose `localId` is in\n * `unreferencedLocalIds`. Returns only the freshly-read entries; the\n * caller merges them into the existing map.\n *\n * @internal\n */\nexport async function inlineAttachmentBlobsByReference(\n\treferences: readonly IBlobAttachReference[],\n\tstorage: Pick<IDocumentStorageService, \"readBlob\">,\n\tunreferencedLocalIds: ReadonlySet<string> | undefined,\n\texisting: Readonly<IBase64BlobContents>,\n): Promise<IBase64BlobContents> {\n\tconst storageIdsToFetch = new Set<string>();\n\tfor (const { localId, storageId } of references) {\n\t\tif (unreferencedLocalIds?.has(localId) === true) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (existing[storageId] !== undefined) {\n\t\t\tcontinue;\n\t\t}\n\t\tstorageIdsToFetch.add(storageId);\n\t}\n\tconst added: IBase64BlobContents = {};\n\tif (storageIdsToFetch.size === 0) {\n\t\treturn added;\n\t}\n\tawait mapWithConcurrency([...storageIdsToFetch], maxReadConcurrency, async (storageId) => {\n\t\tconst buffer = await storage.readBlob(storageId);\n\t\tadded[storageId] = bufferToString(buffer, \"base64\");\n\t});\n\treturn added;\n}\n\n/**\n * Returns true if any referenced subtree of `baseSnapshot` declares a\n * `groupId` — the snapshot-tree wire field that carries the runtime's\n * loading-group identifier. Subtrees flagged `unreferenced` are skipped —\n * a dead subtree's `groupId` would not be loaded by the runtime either.\n *\n * `captureFullContainerState` does not yet support loading groups: prefetching\n * per-group snapshots adds a code path that has no end-to-end coverage and no\n * known production consumer. Callers use this to fail fast with a `UsageError`\n * rather than silently producing a pending state that omits group data.\n */\nexport function snapshotHasLoadingGroups(baseSnapshot: ISnapshotTree): boolean {\n\tif (baseSnapshot.unreferenced === true) {\n\t\treturn false;\n\t}\n\tif (baseSnapshot.groupId !== undefined) {\n\t\treturn true;\n\t}\n\tfor (const child of Object.values(baseSnapshot.trees)) {\n\t\tif (snapshotHasLoadingGroups(child)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n"]}

package/lib/connectionManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connectionManager.d.ts","sourceRoot":"","sources":["../src/connectionManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connectionManager.d.ts","sourceRoot":"","sources":["../src/connectionManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AACrF,OAAO,KAAK,EACX,WAAW,EACX,YAAY,EACZ,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAAE,KAAK,wBAAwB,EAAY,MAAM,iCAAiC,CAAC;AAI1F,OAAO,KAAK,EACX,cAAc,EACd,OAAO,EACP,cAAc,EACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAEN,KAAK,gBAAgB,EAGrB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EAOrB,KAAK,yBAAyB,EAE9B,MAAM,6CAA6C,CAAC;AAYrD,OAAO,EACN,KAAK,mBAAmB,EAOxB,MAAM,0CAA0C,CAAC;AAElD,OAAO,EACN,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,aAAa,EACb,MAAM,gBAAgB,CAAC;AAuExB;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IA6M1D,OAAO,CAAC,QAAQ,CAAC,eAAe;aAChB,cAAc,EAAE,MAAM,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,4BAA4B,CAAC;IAlNtC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAiB;IAEzD;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAAiC;IAC1D,OAAO,CAAC,UAAU,CAAuC;IAEzD;;OAEG;IACH,OAAO,CAAC,kBAAkB,CAAC,CAA6B;IAExD;;OAEG;IACH,OAAO,CAAC,oBAAoB,CAAsB;IAElD;;OAEG;IACH,OAAO,CAAC,cAAc,CAAS;IAE/B;;OAEG;IACH,OAAO,CAAC,cAAc,CAAgB;IAEtC;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,4BAA4B,CAAK;IACzC;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAK;IAE7B;;OAEG;IACH,OAAO,CAAC,qBAAqB,CAAqB;IAElD,OAAO,CAAC,sBAAsB,CAAQ;IAEtC,OAAO,CAAC,uBAAuB,CAAuC;IAEtE,OAAO,CAAC,gBAAgB,CAAgC;IAExD,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D,IAAW,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAEnE;IAED,SAAgB,aAAa,EAAE,cAAc,CAAC;IAE9C;;OAEG;IACH,IAAW,cAAc,IAAI,cAAc,CAE1C;IAED,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,IAAW,QAAQ,IAAI,MAAM,GAAG,SAAS,CAExC;IAED;;OAEG;IACH,IAAW,iBAAiB,IAAI,0BAA0B,GAAG,SAAS,CAErE;IAED;;;OAGG;IACH,IAAW,aAAa,IAAI,aAAa,CAExC;IAED,IAAW,cAAc,IAAI,MAAM,CAElC;IAED,IAAW,OAAO,IAAI,MAAM,CAK3B;IAED,IAAW,oBAAoB,IAAI,oBAAoB,GAAG,SAAS,CAElE;IAED,IAAW,MAAM,IAAI,MAAM,EAAE,GAAG,SAAS,CAExC;IAED,IAAW,QAAQ,IAAI,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAErD;IAED;;;OAGG;IACH,IAAW,eAAe,IAAI,wBAAwB,CAQrD;IAEM,eAAe,IAAI,OAAO;IAmBjC;;;;;;;;OAQG;IACH,OAAO,KAAK,QAAQ,GAEnB;IAED,IAAW,YAAY,IAAI,YAAY,CAkBtC;IAED,OAAO,CAAC,MAAM,CAAC,qBAAqB;gBAmBlB,eAAe,EAAE,MAAM,gBAAgB,GAAG,SAAS,EACpD,cAAc,EAAE,MAAM,OAAO,EAC5B,MAAM,EAAE,OAAO,EAChC,gBAAgB,EAAE,OAAO,EACR,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,6BAA6B,EAC7C,4BAA4B,CAAC,oBAAQ;IAoBvC,OAAO,CAAC,KAAK,CAAC,EAAE,uBAAuB,EAAE,gBAAgB,GAAE,OAAc,GAAG,IAAI;IA4BvF;;;OAGG;IACI,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,4BAA4B,GAAG,IAAI;IAcxF;;OAEG;IACI,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAoC7C,OAAO,CAAC,uBAAuB;IAWxB,OAAO,CAAC,MAAM,EAAE,4BAA4B,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI;YAO7E,WAAW;IAgPzB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAyCjC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IA0JpC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;OAMG;YACW,SAAS;IA8DhB,oBAAoB,CAC1B,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,CAAC,GACrD,gBAAgB,GAAG,SAAS;IAuCxB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ5D,YAAY,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAkDhD,0BAA0B,CAAC,OAAO,EAAE,yBAAyB,GAAG,IAAI;IAgD3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAMxB;IAEF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAI5B;IAGF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAkB1B;IAGF,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAIxC;IAEF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAE3B;CACF"}

package/lib/connectionManager.js

@@ -11,7 +11,7 @@ import { calculateMaxWaitTime, canRetryOnError, createGenericNetworkError, creat
 import { GenericError, UsageError, formatTick, generateStack, isFluidError, normalizeError, } from "@fluidframework/telemetry-utils/internal";
 import { ReconnectMode, } from "./contracts.js";
 import { DeltaQueue } from "./deltaQueue.js";
-import { FrozenDeltaStream, isFrozenDeltaStreamConnection } from "./frozenServices.js";
+import { FrozenDeltaStream, isFrozenDeltaStreamConnection, isWritableFrozenDeltaStreamConnection, } from "./frozenServices.js";
 import { SignalType } from "./protocol.js";
 import { isDeltaStreamConnectionForbiddenError } from "./utils.js";
 // We double this value in first try in when we calculate time to wait for in "calculateMaxWaitTime" function.
@@ -418,20 +418,19 @@ export class ConnectionManager {
                     connected: connection !== undefined && connection.disposed === false,
                 }, undefined, LogLevel.verbose);
                 if (isDeltaStreamConnectionForbiddenError(origError)) {
-                    connection = new FrozenDeltaStream(origError.storageOnlyReason, {
-                        text: origError.message,
-                        error: origError,
+                    connection = new FrozenDeltaStream({
+                        storageOnlyReason: origError.storageOnlyReason,
+                        readonlyConnectionReason: { text: origError.message, error: origError },
                     });
                     requestedMode = "read";
                     break;
                 }
                 else if (isFluidError(origError) &&
                     origError.errorType === DriverErrorTypes.outOfStorageError) {
-                    // If we get out of storage error from calling joinsession, then use the NoDeltaStream object so
+                    // If we get out of storage error from calling joinsession, then use the FrozenDeltaStream object so
                     // that user can at least load the container.
-                    connection = new FrozenDeltaStream(undefined, {
-                        text: origError.message,
-                        error: origError,
+                    connection = new FrozenDeltaStream({
+                        readonlyConnectionReason: { text: origError.message, error: origError },
                     });
                     requestedMode = "read";
                     break;
@@ -804,6 +803,25 @@ export class ConnectionManager {
     }
     sendMessages(messages) {
         assert(this.connected, 0x2b4 /* "not connected on sending ops!" */);
+        // WritableFrozenDeltaStream short-circuit: writable-frozen containers
+        // (`loadFrozenContainerFromPendingState({ readOnly: false })`) attach a
+        // WritableFrozenDeltaStream as the live connection. Its `mode` is "read" (advertising
+        // "write" would imply quorum membership we cannot honor), so a runtime submit
+        // would otherwise fall into the read-mode reconnect branch below. That branch
+        // schedules `reconnect("write")`, which under `ReconnectMode.Never`
+        // (`allowReconnect: false`) calls `closeHandler` and closes the container — the
+        // opposite of what writable-frozen wants. Drop the messages here: the runtime's
+        // outbox keeps them in `pendingStateManager` so `getPendingLocalState()` can
+        // capture them, which is the entire point of the writable-frozen flow.
+        //
+        // Match only the writable variant (a sibling class, not a subclass) so the read-only
+        // `FrozenDeltaStream` retains its `submit` 403-nack tripwire — a stray submit on a
+        // storage-only frozen connection signals an upstream invariant break and should
+        // remain observable. The read-only variant shouldn't reach here in normal flow anyway
+        // (its `storageOnly` policy keeps the runtime from submitting).
+        if (isWritableFrozenDeltaStreamConnection(this.connection)) {
+            return;
+        }
         // If connection is "read" or implicit "read" (got leave op for "write" connection),
         // then op can't make it through - we will get a nack if op is sent.
         // We can short-circuit this process.