@fluidframework/container-loader 2.93.0 → 2.101.0

package/lib/frozenServices.d.ts

@@ -7,49 +7,132 @@ import type { IDisposable } from "@fluidframework/core-interfaces";
 import { type ConnectionMode, type IClientConfiguration, type IDocumentDeltaConnection, type IDocumentDeltaConnectionEvents, type IDocumentMessage, type IDocumentService, type IDocumentServiceFactory, type IResolvedUrl, type ISequencedDocumentMessage, type ISignalClient, type ISignalMessage, type ITokenClaims } from "@fluidframework/driver-definitions/internal";
 import type { IConnectionStateChangeReason } from "./contracts.js";
 /**
- * Creation of a FrozenDocumentServiceFactory which wraps an existing
- * DocumentServiceFactory to provide a storage-only document service.
+ * Creates an `IDocumentServiceFactory` that produces a "frozen" document service: one whose
+ * delta stream never sends or receives ops, and whose storage service only supports
+ * `IDocumentStorageService.readBlob`. Used to load a container from pending local state
+ * without re-establishing a live connection.
  *
- * @param documentServiceFactory - The underlying DocumentServiceFactory to wrap.
- * @returns A FrozenDocumentServiceFactory
+ * @param factory - The underlying factory to wrap. Its storage backs blob reads; all other
+ * storage operations throw. May be omitted when blob fetches are not required.
+ * @param readOnly - When `true` (the default), the document service advertises the
+ * `IDocumentServicePolicies.storageOnly` policy, which causes the loader to surface the
+ * container as read-only (see `IContainer.readOnlyInfo`).
+ *
+ * When `false`, the container is loaded as writable so the runtime will accept DDS submissions.
+ * The connection itself stays `Connected`: `ConnectionManager.sendMessages` recognizes the
+ * `WritableFrozenDeltaStream` as the live connection and short-circuits — the message is dropped
+ * at the network layer rather than triggering a read→write reconnect. Local DDS state continues
+ * to update via optimistic apply, and submitted ops accumulate in the runtime's pending-state
+ * manager, which is exactly the state needed to capture pending local state. Use `false` when
+ * callers want to accrue and capture pending state without publishing it.
+ * @returns A factory that produces frozen document services.
  * @legacy @alpha
  */
-export declare function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>): IDocumentServiceFactory;
+export declare function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>, readOnly?: boolean): IDocumentServiceFactory;
 export declare class FrozenDocumentServiceFactory implements IDocumentServiceFactory {
-    private readonly documentServiceFactory?;
-    constructor(documentServiceFactory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory> | undefined);
+    readonly readOnly: boolean;
+    readonly inner?: IDocumentServiceFactory | Promise<IDocumentServiceFactory> | undefined;
+    constructor(readOnly: boolean, inner?: IDocumentServiceFactory | Promise<IDocumentServiceFactory> | undefined);
     createDocumentService(resolvedUrl: IResolvedUrl): Promise<IDocumentService>;
     createContainer(): Promise<IDocumentService>;
 }
 /**
- * Implementation of IDocumentDeltaConnection that does not support submitting
- * or receiving ops. Used in storage-only mode and in frozen loads.
+ * Inert `IDocumentDeltaConnection` for frozen container loads. Has no server upstream:
+ * op and signal streams are empty, and `initialClients` contains only its own synthetic
+ * read-only client — which lets the connection state handler observe "self" in the audience
+ * and transition the container to Connected without waiting for a real join op or signal.
+ *
+ * Two concrete variants share this base — see their JSDoc for variant-specific details:
+ *
+ * - {@link FrozenDeltaStream} — read-only.
+ * - {@link WritableFrozenDeltaStream} — writable.
+ *
+ * Both variants nack any incoming `submit`: this connection has no upstream and
+ * `ConnectionManager.sendMessages` recognizes `WritableFrozenDeltaStream` and drops messages
+ * before they reach `submit`, so under normal flow it should never fire. A nack reaching the
+ * connectionManager surfaces the misuse — and may close the container — which is the right
+ * defensive signal that something has bypassed the expected flow.
+ *
+ * `submitSignal` is a silent no-op for both variants. Signals are ephemeral and best-effort —
+ * runtime/presence subsystems may submit them at any point in the writable-frozen lifetime, and
+ * dropping them is the correct behavior here (we have no upstream). Closing the container or
+ * triggering a reconnect on a stray signal would be strictly worse than dropping it.
  */
-export declare class FrozenDeltaStream extends TypedEventEmitter<IDocumentDeltaConnectionEvents> implements IDocumentDeltaConnection, IDisposable {
-    readonly storageOnlyReason?: string | undefined;
-    readonly readonlyConnectionReason?: IConnectionStateChangeReason<import("@fluidframework/core-interfaces").IErrorBase> | undefined;
-    clientId: string;
-    claims: ITokenClaims;
-    mode: ConnectionMode;
-    existing: boolean;
-    maxMessageSize: number;
-    version: string;
-    initialMessages: ISequencedDocumentMessage[];
-    initialSignals: ISignalMessage[];
-    initialClients: ISignalClient[];
-    serviceConfiguration: IClientConfiguration;
-    checkpointSequenceNumber?: number | undefined;
-    /**
-     * Connection which is not connected to socket.
-     * @param storageOnlyReason - Reason on why the connection to delta stream is not allowed.
-     * @param readonlyConnectionReason - reason/error if any which lead to using FrozenDeltaStream.
-     */
-    constructor(storageOnlyReason?: string | undefined, readonlyConnectionReason?: IConnectionStateChangeReason<import("@fluidframework/core-interfaces").IErrorBase> | undefined);
+declare abstract class FrozenDeltaStreamBase extends TypedEventEmitter<IDocumentDeltaConnectionEvents> implements IDocumentDeltaConnection, IDisposable {
+    readonly clientId: string;
+    readonly claims: ITokenClaims;
+    readonly initialClients: ISignalClient[];
+    readonly mode: ConnectionMode;
+    readonly existing: boolean;
+    readonly maxMessageSize: number;
+    readonly version: string;
+    readonly initialMessages: ISequencedDocumentMessage[];
+    readonly initialSignals: ISignalMessage[];
+    readonly serviceConfiguration: IClientConfiguration;
+    readonly checkpointSequenceNumber?: number | undefined;
+    constructor(clientId: string, claims: ITokenClaims);
     submit(messages: IDocumentMessage[]): void;
-    submitSignal(message: unknown): void;
+    submitSignal(_message: unknown): void;
     private _disposed;
     get disposed(): boolean;
     dispose(): void;
 }
+/**
+ * Read-only variant of {@link FrozenDeltaStreamBase}. Claims show only `DocRead`. Used by
+ * storage-only loads (where `connectionManager` synthesizes one directly via
+ * `policies.storageOnly`) and by the forbidden / out-of-storage fallback paths.
+ * {@link isFrozenDeltaStreamConnection} matches this variant and drives the read-only forcing
+ * in `ConnectionManager.readOnlyInfo`. Uses the historical `"storage-only client"` constant
+ * `clientId`, preserving existing behavior for any consumer that keys off it.
+ *
+ * `storageOnlyReason` and `readonlyConnectionReason` are surfaced through `IContainer.readOnlyInfo`
+ * for diagnostics on the fallback paths (`isDeltaStreamConnectionForbiddenError`,
+ * `outOfStorageError`).
+ */
+export declare class FrozenDeltaStream extends FrozenDeltaStreamBase {
+    readonly storageOnlyReason: string | undefined;
+    readonly readonlyConnectionReason: IConnectionStateChangeReason | undefined;
+    constructor(options?: {
+        storageOnlyReason?: string;
+        readonlyConnectionReason?: IConnectionStateChangeReason;
+    });
+}
+/**
+ * Variant of {@link FrozenDeltaStreamBase} that appears to support writing but remains
+ * "frozen" — no messages are actually sent or received. The stream itself does not enforce
+ * the no-send guarantee; that lives in `ConnectionManager.sendMessages`, which recognizes
+ * any `WritableFrozenDeltaStream` (via {@link isWritableFrozenDeltaStreamConnection}) and
+ * short-circuits before its read-mode upgrade branch. Submitted ops are dropped at the
+ * connection-manager layer, so the container stays `Connected` and the runtime accumulates
+ * them in `pendingStateManager`.
+ *
+ * "Appears writable" mechanics: claims include `DocWrite` so the container surfaces as
+ * writable; not matched by {@link isFrozenDeltaStreamConnection}, so `readOnlyInfo` reports
+ * `readonly: false`. Connection mode stays `"read"` (advertising `"write"` would imply quorum
+ * membership we cannot honor).
+ *
+ * Each instance mints a fresh `frozen-delta-stream/<uuid>` `clientId` to avoid
+ * `pendingStateManager` `0x173` (`replayPendingStates called twice for same clientId!`) on
+ * reconnect with dirty pending ops. Sibling (not subclass) of `FrozenDeltaStream` so
+ * `instanceof` cleanly distinguishes the two for `ConnectionManager`'s short-circuits.
+ */
+export declare class WritableFrozenDeltaStream extends FrozenDeltaStreamBase {
+    constructor();
+}
+/**
+ * Recognizes the read-only variant of {@link FrozenDeltaStreamBase}. Drives the storage-only
+ * forcing in `ConnectionManager.readOnlyInfo`: only the read-only variant should make the
+ * container surface as read-only. {@link WritableFrozenDeltaStream} is a sibling class, not
+ * a subclass, so `instanceof FrozenDeltaStream` already excludes it.
+ */
 export declare function isFrozenDeltaStreamConnection(connection: unknown): connection is FrozenDeltaStream;
+/**
+ * Recognizes the writable variant of {@link FrozenDeltaStreamBase}. Drives the
+ * `ConnectionManager.sendMessages` short-circuit: writable-frozen submits must be dropped at
+ * the network layer instead of triggering a read→write reconnect. Sibling (not subclass) of
+ * {@link FrozenDeltaStream}, so `instanceof WritableFrozenDeltaStream` excludes the read-only
+ * variant.
+ */
+export declare function isWritableFrozenDeltaStreamConnection(connection: unknown): connection is WritableFrozenDeltaStream;
+export {};
 //# sourceMappingURL=frozenServices.d.ts.map

package/lib/frozenServices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frozenServices.d.ts","sourceRoot":"","sources":["../src/frozenServices.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EAEN,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EAEnC,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EAErB,KAAK,uBAAuB,EAG5B,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,MAAM,6CAA6C,CAAC;AAErD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CACjD,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,GAClE,uBAAuB,CAKzB;AAED,qBAAa,4BAA6B,YAAW,uBAAuB;IAE1E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC;gBAAvB,sBAAsB,CAAC,wEAEL;IAG9B,qBAAqB,CAAC,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAU3E,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;CAGlD;AA8DD;;;GAGG;AACH,qBAAa,iBACZ,SAAQ,iBAAiB,CAAC,8BAA8B,CACxD,YAAW,wBAAwB,EAAE,WAAW;aA2B/B,iBAAiB,CAAC;aAClB,wBAAwB,CAAC;IA1B1C,QAAQ,SAA6B;IAErC,MAAM,eAEY;IAClB,IAAI,EAAE,cAAc,CAAU;IAC9B,QAAQ,EAAE,OAAO,CAAQ;IACzB,cAAc,EAAE,MAAM,CAAK;IAC3B,OAAO,EAAE,MAAM,CAAM;IACrB,eAAe,EAAE,yBAAyB,EAAE,CAAM;IAClD,cAAc,EAAE,cAAc,EAAE,CAAM;IACtC,cAAc,EAAE,aAAa,EAAE,CAE7B;IACF,oBAAoB,EAAE,oBAAoB,CAGxC;IACF,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAa;IAC1D;;;;OAIG;gBAEc,iBAAiB,CAAC,oBAAQ,EAC1B,wBAAwB,CAAC,gGAA8B;IAIxE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAY1C,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAOpC,OAAO,CAAC,SAAS,CAAS;IAC1B,IAAW,QAAQ,IAAI,OAAO,CAE7B;IACM,OAAO,IAAI,IAAI;CAGtB;AACD,wBAAgB,6BAA6B,CAC5C,UAAU,EAAE,OAAO,GACjB,UAAU,IAAI,iBAAiB,CAEjC"}
+{"version":3,"file":"frozenServices.d.ts","sourceRoot":"","sources":["../src/frozenServices.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EAEN,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EAEnC,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EAErB,KAAK,uBAAuB,EAG5B,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kCAAkC,CACjD,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,EACpE,QAAQ,GAAE,OAAc,GACtB,uBAAuB,CAUzB;AAED,qBAAa,4BAA6B,YAAW,uBAAuB;aAE1D,QAAQ,EAAE,OAAO;aACjB,KAAK,CAAC;gBADN,QAAQ,EAAE,OAAO,EACjB,KAAK,CAAC,wEAA4D;IAG7E,qBAAqB,CAAC,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQ3E,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;CAGlD;AAoLD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,uBAAe,qBACd,SAAQ,iBAAiB,CAAC,8BAA8B,CACxD,YAAW,wBAAwB,EAAE,WAAW;IAEhD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChD,SAAgB,IAAI,EAAE,cAAc,CAAU;IAC9C,SAAgB,QAAQ,EAAE,OAAO,CAAQ;IACzC,SAAgB,cAAc,EAAE,MAAM,CAAK;IAC3C,SAAgB,OAAO,EAAE,MAAM,CAAM;IACrC,SAAgB,eAAe,EAAE,yBAAyB,EAAE,CAAM;IAClE,SAAgB,cAAc,EAAE,cAAc,EAAE,CAAM;IACtD,SAAgB,oBAAoB,EAAE,oBAAoB,CAGxD;IACF,SAAgB,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAa;gBAE9D,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY;IASlD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAa1C,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIrC,OAAO,CAAC,SAAS,CAAS;IAC1B,IAAW,QAAQ,IAAI,OAAO,CAE7B;IACM,OAAO,IAAI,IAAI;CAGtB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,qBAAqB;IAC3D,SAAgB,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtD,SAAgB,wBAAwB,EAAE,4BAA4B,GAAG,SAAS,CAAC;gBAEvE,OAAO,CAAC,EAAE;QACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,wBAAwB,CAAC,EAAE,4BAA4B,CAAC;KACxD;CASD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,yBAA0B,SAAQ,qBAAqB;;CAInE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC5C,UAAU,EAAE,OAAO,GACjB,UAAU,IAAI,iBAAiB,CAEjC;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CACpD,UAAU,EAAE,OAAO,GACjB,UAAU,IAAI,yBAAyB,CAEzC"}

package/lib/frozenServices.js

@@ -5,69 +5,165 @@
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
 import { isPromiseLike } from "@fluidframework/core-utils/internal";
 import { ScopeType, } from "@fluidframework/driver-definitions/internal";
+import { v4 as uuid } from "uuid";
 /**
- * Creation of a FrozenDocumentServiceFactory which wraps an existing
- * DocumentServiceFactory to provide a storage-only document service.
+ * Creates an `IDocumentServiceFactory` that produces a "frozen" document service: one whose
+ * delta stream never sends or receives ops, and whose storage service only supports
+ * `IDocumentStorageService.readBlob`. Used to load a container from pending local state
+ * without re-establishing a live connection.
  *
- * @param documentServiceFactory - The underlying DocumentServiceFactory to wrap.
- * @returns A FrozenDocumentServiceFactory
+ * @param factory - The underlying factory to wrap. Its storage backs blob reads; all other
+ * storage operations throw. May be omitted when blob fetches are not required.
+ * @param readOnly - When `true` (the default), the document service advertises the
+ * `IDocumentServicePolicies.storageOnly` policy, which causes the loader to surface the
+ * container as read-only (see `IContainer.readOnlyInfo`).
+ *
+ * When `false`, the container is loaded as writable so the runtime will accept DDS submissions.
+ * The connection itself stays `Connected`: `ConnectionManager.sendMessages` recognizes the
+ * `WritableFrozenDeltaStream` as the live connection and short-circuits — the message is dropped
+ * at the network layer rather than triggering a read→write reconnect. Local DDS state continues
+ * to update via optimistic apply, and submitted ops accumulate in the runtime's pending-state
+ * manager, which is exactly the state needed to capture pending local state. Use `false` when
+ * callers want to accrue and capture pending state without publishing it.
+ * @returns A factory that produces frozen document services.
  * @legacy @alpha
  */
-export function createFrozenDocumentServiceFactory(factory) {
-    // Sync path
-    return factory instanceof FrozenDocumentServiceFactory
-        ? factory
-        : new FrozenDocumentServiceFactory(factory);
+export function createFrozenDocumentServiceFactory(factory, readOnly = true) {
+    if (factory instanceof FrozenDocumentServiceFactory) {
+        // Already wrapped. Reuse if readOnly matches; otherwise unwrap and rewrap so the caller's
+        // most recent readOnly intent wins (silently honoring caller intent rather than dropping
+        // the new argument).
+        return factory.readOnly === readOnly
+            ? factory
+            : new FrozenDocumentServiceFactory(readOnly, factory.inner);
+    }
+    return new FrozenDocumentServiceFactory(readOnly, factory);
 }
 export class FrozenDocumentServiceFactory {
-    constructor(documentServiceFactory) {
-        this.documentServiceFactory = documentServiceFactory;
+    constructor(readOnly, inner) {
+        this.readOnly = readOnly;
+        this.inner = inner;
     }
     async createDocumentService(resolvedUrl) {
-        let factory = this.documentServiceFactory;
-        if (isPromiseLike(factory)) {
-            factory = await this.documentServiceFactory;
-        }
-        return new FrozenDocumentService(resolvedUrl, await factory?.createDocumentService(resolvedUrl));
+        const factory = isPromiseLike(this.inner) ? await this.inner : this.inner;
+        return new FrozenDocumentService(resolvedUrl, this.readOnly, await factory?.createDocumentService(resolvedUrl));
     }
     async createContainer() {
         throw new Error("The FrozenDocumentServiceFactory cannot be used to create containers.");
     }
 }
 class FrozenDocumentService extends TypedEventEmitter {
-    constructor(resolvedUrl, documentService) {
+    constructor(resolvedUrl, readOnly, documentService) {
         super();
         this.resolvedUrl = resolvedUrl;
+        this.readOnly = readOnly;
         this.documentService = documentService;
-        this.policies = {
-            storageOnly: true,
-        };
+        // Tracks every storage instance handed out by `connectToStorage` so `dispose()` can cascade
+        // disposal to each one (rejecting their hanging `createBlob` deferreds). A Set rather than
+        // a single field because `IDocumentService.connectToStorage` is a public API that can be
+        // called more than once — we cannot assume the Container holds a single instance.
+        this.storageServices = new Set();
+        // When readOnly, advertise the storageOnly policy. The connectionManager short-circuits
+        // on it: it synthesizes a FrozenDeltaStream itself and never calls
+        // connectToDeltaStream, and the readOnlyInfo getter forces the container to read-only
+        // because the live connection is a FrozenDeltaStream.
+        //
+        // Audit (2026-05-05): the only consumer of `policies.storageOnly` as a frozen-container
+        // signal is `ConnectionManager` (synthesizing a `FrozenDeltaStream` when set). All other
+        // matches in the loader/runtime/driver layers are either drivers reading their own
+        // policies (e.g. local-driver) or `IReadOnlyInfo.storageOnly`, which is derived from the
+        // live connection — not the policy. So the writable-frozen container is intentionally
+        // indistinguishable from a normal container at the policies layer; downstream behavior
+        // flows through the live `WritableFrozenDeltaStream` instead.
+        this.policies = readOnly ? { storageOnly: true } : {};
     }
     async connectToStorage() {
-        return new FrozenDocumentStorageService(await this.documentService?.connectToStorage());
+        const storage = new FrozenDocumentStorageService(this.readOnly, await this.documentService?.connectToStorage());
+        this.storageServices.add(storage);
+        return storage;
     }
     async connectToDeltaStorage() {
         return frozenDocumentDeltaStorageService;
     }
-    async connectToDeltaStream(client) {
-        return new FrozenDeltaStream();
+    async connectToDeltaStream(_client) {
+        if (this.readOnly) {
+            // connectionManager short-circuits via policies.storageOnly before reaching here
+            // in the read-only path; reaching this branch indicates a non-connectionManager
+            // consumer or a regression of the short-circuit. Throw to surface the misuse
+            // rather than silently produce a working stream.
+            throw new Error("FrozenDocumentService is read-only; connectToDeltaStream should not be called (connectionManager short-circuits via policies.storageOnly)");
+        }
+        // Writable path: hand out a fresh WritableFrozenDeltaStream regardless of client.mode
+        // or whether this is the initial connect or a reconnect. The stream's own mode is
+        // "read" (advertising "write" would imply quorum membership we cannot honor), and
+        // `ConnectionManager.sendMessages` short-circuits on WritableFrozenDeltaStream so
+        // outbound writes never reach a real network. The per-instance clientId minted in
+        // FrozenDeltaStreamBase prevents pendingStateManager 0x173 on replay across reconnects.
+        return new WritableFrozenDeltaStream();
+    }
+    dispose(error) {
+        // Cascade disposal to each storage instance so any hanging `createBlob` promises (the
+        // writable-frozen pending-blob mechanism) reject and the BlobManager can release its
+        // references. Without this, hung promises remain held by BlobManager closures for the
+        // lifetime of the process.
+        for (const storage of this.storageServices) {
+            storage.dispose();
+        }
+        this.storageServices.clear();
+        // Forward disposal to the wrapped service. We own its lifetime (it was created for us
+        // by the wrapping factory and is never exposed to callers), so the contract from
+        // `IDocumentService.dispose` ("called by storage consumer when done with storage")
+        // applies here.
+        this.documentService?.dispose(error);
     }
-    dispose() { }
 }
 const frozenDocumentStorageServiceHandler = () => {
     throw new Error("Operations are not supported on the FrozenDocumentStorageService.");
 };
 class FrozenDocumentStorageService {
-    constructor(documentStorageService) {
+    get disposed() {
+        return this._disposed;
+    }
+    constructor(readOnly, documentStorageService) {
         this.documentStorageService = documentStorageService;
+        this._disposed = false;
         this.getSnapshotTree = frozenDocumentStorageServiceHandler;
         this.getSnapshot = frozenDocumentStorageServiceHandler;
         this.getVersions = frozenDocumentStorageServiceHandler;
-        this.createBlob = frozenDocumentStorageServiceHandler;
         this.readBlob = this.documentStorageService?.readBlob.bind(this.documentStorageService) ??
             frozenDocumentStorageServiceHandler;
         this.uploadSummaryWithContext = frozenDocumentStorageServiceHandler;
         this.downloadSummary = frozenDocumentStorageServiceHandler;
+        let rejectFn;
+        const promise = new Promise((_, reject) => {
+            rejectFn = reject;
+        });
+        // Attach a no-op catch so node doesn't log an unhandled-rejection warning when
+        // dispose runs before any caller has awaited the promise. Callers awaiting the
+        // original promise still observe the rejection.
+        promise.catch(() => { });
+        this.disposalDeferred = { promise, reject: rejectFn };
+        // In the writable-frozen path, `createBlob` returns a never-resolving promise instead
+        // of throwing. This keeps the BlobManager's `localBlobCache` entry in the `uploading`
+        // state: `getPendingBlobs` downgrades `uploading` blobs to `localOnly` in pending
+        // state, so the blob survives `getPendingLocalState`. A subsequent live load runs
+        // `sharePendingBlobs`, which re-enters `uploadAndAttach` against the real storage to
+        // complete the upload. Throwing here would instead delete the cache entry (in
+        // `uploadAndAttach`'s catch handler) and lose the blob — defeating the whole point of
+        // accruing pending state.
+        this.createBlob = readOnly
+            ? frozenDocumentStorageServiceHandler
+            : async () => this.disposalDeferred.promise;
+    }
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        // Don't propagate any caller-supplied error here. `IDocumentService.dispose` already
+        // logs the Container's error path; the createBlob deferred's consumer (BlobManager)
+        // only needs the "this storage is going away" signal — not a chain of error causes.
+        this.disposalDeferred.reject(new Error("FrozenDocumentStorageService is disposed"));
     }
 }
 const frozenDocumentDeltaStorageService = {
@@ -85,54 +181,71 @@ const clientFrozenDeltaStream = {
     scopes: [],
 };
 const clientIdFrozenDeltaStream = "storage-only client";
+// Cast rationale: ITokenClaims requires tenantId/documentId/user/iat/exp/ver, but a frozen
+// delta stream has no tenant or session to draw real values from — it's a synthetic
+// in-process connection that never reaches a service. Inventing sentinel values would imply
+// quorum membership we cannot honor; only `scopes` actually drives behavior here (DocRead vs
+// DocWrite gates readOnlyInfo). The cast is the honest representation of "this connection
+// has no claims worth populating."
+/* eslint-disable @typescript-eslint/consistent-type-assertions */
+const readOnlyClaims = { scopes: [ScopeType.DocRead] };
+const writableClaims = {
+    scopes: [ScopeType.DocRead, ScopeType.DocWrite],
+};
+/* eslint-enable @typescript-eslint/consistent-type-assertions */
 /**
- * Implementation of IDocumentDeltaConnection that does not support submitting
- * or receiving ops. Used in storage-only mode and in frozen loads.
+ * Inert `IDocumentDeltaConnection` for frozen container loads. Has no server upstream:
+ * op and signal streams are empty, and `initialClients` contains only its own synthetic
+ * read-only client — which lets the connection state handler observe "self" in the audience
+ * and transition the container to Connected without waiting for a real join op or signal.
+ *
+ * Two concrete variants share this base — see their JSDoc for variant-specific details:
+ *
+ * - {@link FrozenDeltaStream} — read-only.
+ * - {@link WritableFrozenDeltaStream} — writable.
+ *
+ * Both variants nack any incoming `submit`: this connection has no upstream and
+ * `ConnectionManager.sendMessages` recognizes `WritableFrozenDeltaStream` and drops messages
+ * before they reach `submit`, so under normal flow it should never fire. A nack reaching the
+ * connectionManager surfaces the misuse — and may close the container — which is the right
+ * defensive signal that something has bypassed the expected flow.
+ *
+ * `submitSignal` is a silent no-op for both variants. Signals are ephemeral and best-effort —
+ * runtime/presence subsystems may submit them at any point in the writable-frozen lifetime, and
+ * dropping them is the correct behavior here (we have no upstream). Closing the container or
+ * triggering a reconnect on a stray signal would be strictly worse than dropping it.
  */
-export class FrozenDeltaStream extends TypedEventEmitter {
-    /**
-     * Connection which is not connected to socket.
-     * @param storageOnlyReason - Reason on why the connection to delta stream is not allowed.
-     * @param readonlyConnectionReason - reason/error if any which lead to using FrozenDeltaStream.
-     */
-    constructor(storageOnlyReason, readonlyConnectionReason) {
+class FrozenDeltaStreamBase extends TypedEventEmitter {
+    constructor(clientId, claims) {
         super();
-        this.storageOnlyReason = storageOnlyReason;
-        this.readonlyConnectionReason = readonlyConnectionReason;
-        this.clientId = clientIdFrozenDeltaStream;
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        this.claims = {
-            scopes: [ScopeType.DocRead],
-        };
         this.mode = "read";
         this.existing = true;
         this.maxMessageSize = 0;
         this.version = "";
         this.initialMessages = [];
         this.initialSignals = [];
-        this.initialClients = [
-            { client: clientFrozenDeltaStream, clientId: clientIdFrozenDeltaStream },
-        ];
         this.serviceConfiguration = {
             maxMessageSize: 0,
             blockSize: 0,
         };
         this.checkpointSequenceNumber = undefined;
         this._disposed = false;
+        this.clientId = clientId;
+        this.claims = claims;
+        // initialClients mirrors clientId so the audience handler observes "self" and
+        // transitions the container to Connected without waiting for a real join op or signal.
+        this.initialClients = [{ client: clientFrozenDeltaStream, clientId }];
     }
     submit(messages) {
-        this.emit("nack", this.clientId, messages.map((operation) => {
-            return {
-                operation,
-                content: { message: "Cannot submit with storage-only connection", code: 403 },
-            };
-        }));
-    }
-    submitSignal(message) {
-        this.emit("nack", this.clientId, {
-            operation: message,
-            content: { message: "Cannot submit signal with storage-only connection", code: 403 },
-        });
+        // Defensive nack: nothing should send on a frozen delta stream. If this fires, an
+        // invariant in connectionManager has changed and we want it to surface loudly.
+        this.emit("nack", this.clientId, messages.map((operation) => ({
+            operation,
+            content: { message: "Cannot submit on a frozen delta stream", code: 403 },
+        })));
+    }
+    submitSignal(_message) {
+        // Intentional no-op. See class JSDoc for rationale.
     }
     get disposed() {
         return this._disposed;
@@ -141,7 +254,70 @@ export class FrozenDeltaStream extends TypedEventEmitter {
         this._disposed = true;
     }
 }
+/**
+ * Read-only variant of {@link FrozenDeltaStreamBase}. Claims show only `DocRead`. Used by
+ * storage-only loads (where `connectionManager` synthesizes one directly via
+ * `policies.storageOnly`) and by the forbidden / out-of-storage fallback paths.
+ * {@link isFrozenDeltaStreamConnection} matches this variant and drives the read-only forcing
+ * in `ConnectionManager.readOnlyInfo`. Uses the historical `"storage-only client"` constant
+ * `clientId`, preserving existing behavior for any consumer that keys off it.
+ *
+ * `storageOnlyReason` and `readonlyConnectionReason` are surfaced through `IContainer.readOnlyInfo`
+ * for diagnostics on the fallback paths (`isDeltaStreamConnectionForbiddenError`,
+ * `outOfStorageError`).
+ */
+export class FrozenDeltaStream extends FrozenDeltaStreamBase {
+    constructor(options) {
+        // Constant clientId: preserves the pre-PR `"storage-only client"` identity for any
+        // consumer that keys off it. The 0x173 replay-assert risk that motivates per-instance
+        // clientIds applies only to the writable variant, where the runtime accumulates dirty
+        // pending ops across reconnects; the read-only variant does not.
+        super(clientIdFrozenDeltaStream, readOnlyClaims);
+        this.storageOnlyReason = options?.storageOnlyReason;
+        this.readonlyConnectionReason = options?.readonlyConnectionReason;
+    }
+}
+/**
+ * Variant of {@link FrozenDeltaStreamBase} that appears to support writing but remains
+ * "frozen" — no messages are actually sent or received. The stream itself does not enforce
+ * the no-send guarantee; that lives in `ConnectionManager.sendMessages`, which recognizes
+ * any `WritableFrozenDeltaStream` (via {@link isWritableFrozenDeltaStreamConnection}) and
+ * short-circuits before its read-mode upgrade branch. Submitted ops are dropped at the
+ * connection-manager layer, so the container stays `Connected` and the runtime accumulates
+ * them in `pendingStateManager`.
+ *
+ * "Appears writable" mechanics: claims include `DocWrite` so the container surfaces as
+ * writable; not matched by {@link isFrozenDeltaStreamConnection}, so `readOnlyInfo` reports
+ * `readonly: false`. Connection mode stays `"read"` (advertising `"write"` would imply quorum
+ * membership we cannot honor).
+ *
+ * Each instance mints a fresh `frozen-delta-stream/<uuid>` `clientId` to avoid
+ * `pendingStateManager` `0x173` (`replayPendingStates called twice for same clientId!`) on
+ * reconnect with dirty pending ops. Sibling (not subclass) of `FrozenDeltaStream` so
+ * `instanceof` cleanly distinguishes the two for `ConnectionManager`'s short-circuits.
+ */
+export class WritableFrozenDeltaStream extends FrozenDeltaStreamBase {
+    constructor() {
+        super(`frozen-delta-stream/${uuid()}`, writableClaims);
+    }
+}
+/**
+ * Recognizes the read-only variant of {@link FrozenDeltaStreamBase}. Drives the storage-only
+ * forcing in `ConnectionManager.readOnlyInfo`: only the read-only variant should make the
+ * container surface as read-only. {@link WritableFrozenDeltaStream} is a sibling class, not
+ * a subclass, so `instanceof FrozenDeltaStream` already excludes it.
+ */
 export function isFrozenDeltaStreamConnection(connection) {
     return connection instanceof FrozenDeltaStream;
 }
+/**
+ * Recognizes the writable variant of {@link FrozenDeltaStreamBase}. Drives the
+ * `ConnectionManager.sendMessages` short-circuit: writable-frozen submits must be dropped at
+ * the network layer instead of triggering a read→write reconnect. Sibling (not subclass) of
+ * {@link FrozenDeltaStream}, so `instanceof WritableFrozenDeltaStream` excludes the read-only
+ * variant.
+ */
+export function isWritableFrozenDeltaStreamConnection(connection) {
+    return connection instanceof WritableFrozenDeltaStream;
+}
 //# sourceMappingURL=frozenServices.js.map

package/lib/frozenServices.js.map

@@ -1 +1 @@
-{"version":3,"file":"frozenServices.js","sourceRoot":"","sources":["../src/frozenServices.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 { TypedEventEmitter } from \"@fluid-internal/client-utils\";\nimport type { IDisposable } from \"@fluidframework/core-interfaces\";\nimport { isPromiseLike } from \"@fluidframework/core-utils/internal\";\nimport {\n\tScopeType,\n\ttype ConnectionMode,\n\ttype IClient,\n\ttype IClientConfiguration,\n\ttype IDocumentDeltaConnection,\n\ttype IDocumentDeltaConnectionEvents,\n\ttype IDocumentDeltaStorageService,\n\ttype IDocumentMessage,\n\ttype IDocumentService,\n\ttype IDocumentServiceEvents,\n\ttype IDocumentServiceFactory,\n\ttype IDocumentServicePolicies,\n\ttype IDocumentStorageService,\n\ttype IResolvedUrl,\n\ttype ISequencedDocumentMessage,\n\ttype ISignalClient,\n\ttype ISignalMessage,\n\ttype ITokenClaims,\n} from \"@fluidframework/driver-definitions/internal\";\n\nimport type { IConnectionStateChangeReason } from \"./contracts.js\";\n\n/**\n * Creation of a FrozenDocumentServiceFactory which wraps an existing\n * DocumentServiceFactory to provide a storage-only document service.\n *\n * @param documentServiceFactory - The underlying DocumentServiceFactory to wrap.\n * @returns A FrozenDocumentServiceFactory\n * @legacy @alpha\n */\nexport function createFrozenDocumentServiceFactory(\n\tfactory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>,\n): IDocumentServiceFactory {\n\t// Sync path\n\treturn factory instanceof FrozenDocumentServiceFactory\n\t\t? factory\n\t\t: new FrozenDocumentServiceFactory(factory);\n}\n\nexport class FrozenDocumentServiceFactory implements IDocumentServiceFactory {\n\tconstructor(\n\t\tprivate readonly documentServiceFactory?:\n\t\t\t| IDocumentServiceFactory\n\t\t\t| Promise<IDocumentServiceFactory>,\n\t) {}\n\n\tasync createDocumentService(resolvedUrl: IResolvedUrl): Promise<IDocumentService> {\n\t\tlet factory = this.documentServiceFactory;\n\t\tif (isPromiseLike(factory)) {\n\t\t\tfactory = await this.documentServiceFactory;\n\t\t}\n\t\treturn new FrozenDocumentService(\n\t\t\tresolvedUrl,\n\t\t\tawait factory?.createDocumentService(resolvedUrl),\n\t\t);\n\t}\n\tasync createContainer(): Promise<IDocumentService> {\n\t\tthrow new Error(\"The FrozenDocumentServiceFactory cannot be used to create containers.\");\n\t}\n}\n\nclass FrozenDocumentService\n\textends TypedEventEmitter<IDocumentServiceEvents>\n\timplements IDocumentService\n{\n\tconstructor(\n\t\tpublic readonly resolvedUrl: IResolvedUrl,\n\t\tprivate readonly documentService?: IDocumentService,\n\t) {\n\t\tsuper();\n\t}\n\n\tpublic readonly policies: IDocumentServicePolicies = {\n\t\tstorageOnly: true,\n\t};\n\tasync connectToStorage(): Promise<IDocumentStorageService> {\n\t\treturn new FrozenDocumentStorageService(await this.documentService?.connectToStorage());\n\t}\n\tasync connectToDeltaStorage(): Promise<IDocumentDeltaStorageService> {\n\t\treturn frozenDocumentDeltaStorageService;\n\t}\n\tasync connectToDeltaStream(client: IClient): Promise<IDocumentDeltaConnection> {\n\t\treturn new FrozenDeltaStream();\n\t}\n\tdispose(): void {}\n}\n\nconst frozenDocumentStorageServiceHandler = (): never => {\n\tthrow new Error(\"Operations are not supported on the FrozenDocumentStorageService.\");\n};\nclass FrozenDocumentStorageService implements IDocumentStorageService {\n\tconstructor(private readonly documentStorageService?: IDocumentStorageService) {}\n\n\tgetSnapshotTree = frozenDocumentStorageServiceHandler;\n\tgetSnapshot = frozenDocumentStorageServiceHandler;\n\tgetVersions = frozenDocumentStorageServiceHandler;\n\tcreateBlob = frozenDocumentStorageServiceHandler;\n\treadBlob =\n\t\tthis.documentStorageService?.readBlob.bind(this.documentStorageService) ??\n\t\tfrozenDocumentStorageServiceHandler;\n\tuploadSummaryWithContext = frozenDocumentStorageServiceHandler;\n\tdownloadSummary = frozenDocumentStorageServiceHandler;\n}\n\nconst frozenDocumentDeltaStorageService: IDocumentDeltaStorageService = {\n\tfetchMessages: () => ({\n\t\tread: async () => ({\n\t\t\tdone: true,\n\t\t}),\n\t}),\n};\n\nconst clientFrozenDeltaStream: IClient = {\n\tmode: \"read\",\n\tdetails: { capabilities: { interactive: true } },\n\tpermission: [],\n\tuser: { id: \"storage-only client\" }, // we need some \"fake\" ID here.\n\tscopes: [],\n};\nconst clientIdFrozenDeltaStream: string = \"storage-only client\";\n\n/**\n * Implementation of IDocumentDeltaConnection that does not support submitting\n * or receiving ops. Used in storage-only mode and in frozen loads.\n */\nexport class FrozenDeltaStream\n\textends TypedEventEmitter<IDocumentDeltaConnectionEvents>\n\timplements IDocumentDeltaConnection, IDisposable\n{\n\tclientId = clientIdFrozenDeltaStream;\n\t// eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n\tclaims = {\n\t\tscopes: [ScopeType.DocRead],\n\t} as ITokenClaims;\n\tmode: ConnectionMode = \"read\";\n\texisting: boolean = true;\n\tmaxMessageSize: number = 0;\n\tversion: string = \"\";\n\tinitialMessages: ISequencedDocumentMessage[] = [];\n\tinitialSignals: ISignalMessage[] = [];\n\tinitialClients: ISignalClient[] = [\n\t\t{ client: clientFrozenDeltaStream, clientId: clientIdFrozenDeltaStream },\n\t];\n\tserviceConfiguration: IClientConfiguration = {\n\t\tmaxMessageSize: 0,\n\t\tblockSize: 0,\n\t};\n\tcheckpointSequenceNumber?: number | undefined = undefined;\n\t/**\n\t * Connection which is not connected to socket.\n\t * @param storageOnlyReason - Reason on why the connection to delta stream is not allowed.\n\t * @param readonlyConnectionReason - reason/error if any which lead to using FrozenDeltaStream.\n\t */\n\tconstructor(\n\t\tpublic readonly storageOnlyReason?: string,\n\t\tpublic readonly readonlyConnectionReason?: IConnectionStateChangeReason,\n\t) {\n\t\tsuper();\n\t}\n\tsubmit(messages: IDocumentMessage[]): void {\n\t\tthis.emit(\n\t\t\t\"nack\",\n\t\t\tthis.clientId,\n\t\t\tmessages.map((operation) => {\n\t\t\t\treturn {\n\t\t\t\t\toperation,\n\t\t\t\t\tcontent: { message: \"Cannot submit with storage-only connection\", code: 403 },\n\t\t\t\t};\n\t\t\t}),\n\t\t);\n\t}\n\tsubmitSignal(message: unknown): void {\n\t\tthis.emit(\"nack\", this.clientId, {\n\t\t\toperation: message,\n\t\t\tcontent: { message: \"Cannot submit signal with storage-only connection\", code: 403 },\n\t\t});\n\t}\n\n\tprivate _disposed = false;\n\tpublic get disposed(): boolean {\n\t\treturn this._disposed;\n\t}\n\tpublic dispose(): void {\n\t\tthis._disposed = true;\n\t}\n}\nexport function isFrozenDeltaStreamConnection(\n\tconnection: unknown,\n): connection is FrozenDeltaStream {\n\treturn connection instanceof FrozenDeltaStream;\n}\n"]}
+{"version":3,"file":"frozenServices.js","sourceRoot":"","sources":["../src/frozenServices.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 { TypedEventEmitter } from \"@fluid-internal/client-utils\";\nimport type { IDisposable } from \"@fluidframework/core-interfaces\";\nimport { isPromiseLike } from \"@fluidframework/core-utils/internal\";\nimport {\n\tScopeType,\n\ttype ConnectionMode,\n\ttype IClient,\n\ttype IClientConfiguration,\n\ttype IDocumentDeltaConnection,\n\ttype IDocumentDeltaConnectionEvents,\n\ttype IDocumentDeltaStorageService,\n\ttype IDocumentMessage,\n\ttype IDocumentService,\n\ttype IDocumentServiceEvents,\n\ttype IDocumentServiceFactory,\n\ttype IDocumentServicePolicies,\n\ttype IDocumentStorageService,\n\ttype IResolvedUrl,\n\ttype ISequencedDocumentMessage,\n\ttype ISignalClient,\n\ttype ISignalMessage,\n\ttype ITokenClaims,\n} from \"@fluidframework/driver-definitions/internal\";\nimport { v4 as uuid } from \"uuid\";\n\nimport type { IConnectionStateChangeReason } from \"./contracts.js\";\n\n/**\n * Creates an `IDocumentServiceFactory` that produces a \"frozen\" document service: one whose\n * delta stream never sends or receives ops, and whose storage service only supports\n * `IDocumentStorageService.readBlob`. Used to load a container from pending local state\n * without re-establishing a live connection.\n *\n * @param factory - The underlying factory to wrap. Its storage backs blob reads; all other\n * storage operations throw. May be omitted when blob fetches are not required.\n * @param readOnly - When `true` (the default), the document service advertises the\n * `IDocumentServicePolicies.storageOnly` policy, which causes the loader to surface the\n * container as read-only (see `IContainer.readOnlyInfo`).\n *\n * When `false`, the container is loaded as writable so the runtime will accept DDS submissions.\n * The connection itself stays `Connected`: `ConnectionManager.sendMessages` recognizes the\n * `WritableFrozenDeltaStream` as the live connection and short-circuits — the message is dropped\n * at the network layer rather than triggering a read→write reconnect. Local DDS state continues\n * to update via optimistic apply, and submitted ops accumulate in the runtime's pending-state\n * manager, which is exactly the state needed to capture pending local state. Use `false` when\n * callers want to accrue and capture pending state without publishing it.\n * @returns A factory that produces frozen document services.\n * @legacy @alpha\n */\nexport function createFrozenDocumentServiceFactory(\n\tfactory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>,\n\treadOnly: boolean = true,\n): IDocumentServiceFactory {\n\tif (factory instanceof FrozenDocumentServiceFactory) {\n\t\t// Already wrapped. Reuse if readOnly matches; otherwise unwrap and rewrap so the caller's\n\t\t// most recent readOnly intent wins (silently honoring caller intent rather than dropping\n\t\t// the new argument).\n\t\treturn factory.readOnly === readOnly\n\t\t\t? factory\n\t\t\t: new FrozenDocumentServiceFactory(readOnly, factory.inner);\n\t}\n\treturn new FrozenDocumentServiceFactory(readOnly, factory);\n}\n\nexport class FrozenDocumentServiceFactory implements IDocumentServiceFactory {\n\tconstructor(\n\t\tpublic readonly readOnly: boolean,\n\t\tpublic readonly inner?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>,\n\t) {}\n\n\tasync createDocumentService(resolvedUrl: IResolvedUrl): Promise<IDocumentService> {\n\t\tconst factory = isPromiseLike(this.inner) ? await this.inner : this.inner;\n\t\treturn new FrozenDocumentService(\n\t\t\tresolvedUrl,\n\t\t\tthis.readOnly,\n\t\t\tawait factory?.createDocumentService(resolvedUrl),\n\t\t);\n\t}\n\tasync createContainer(): Promise<IDocumentService> {\n\t\tthrow new Error(\"The FrozenDocumentServiceFactory cannot be used to create containers.\");\n\t}\n}\n\nclass FrozenDocumentService\n\textends TypedEventEmitter<IDocumentServiceEvents>\n\timplements IDocumentService\n{\n\t// Tracks every storage instance handed out by `connectToStorage` so `dispose()` can cascade\n\t// disposal to each one (rejecting their hanging `createBlob` deferreds). A Set rather than\n\t// a single field because `IDocumentService.connectToStorage` is a public API that can be\n\t// called more than once — we cannot assume the Container holds a single instance.\n\tprivate readonly storageServices = new Set<FrozenDocumentStorageService>();\n\n\tconstructor(\n\t\tpublic readonly resolvedUrl: IResolvedUrl,\n\t\tprivate readonly readOnly: boolean,\n\t\tprivate readonly documentService?: IDocumentService,\n\t) {\n\t\tsuper();\n\t\t// When readOnly, advertise the storageOnly policy. The connectionManager short-circuits\n\t\t// on it: it synthesizes a FrozenDeltaStream itself and never calls\n\t\t// connectToDeltaStream, and the readOnlyInfo getter forces the container to read-only\n\t\t// because the live connection is a FrozenDeltaStream.\n\t\t//\n\t\t// Audit (2026-05-05): the only consumer of `policies.storageOnly` as a frozen-container\n\t\t// signal is `ConnectionManager` (synthesizing a `FrozenDeltaStream` when set). All other\n\t\t// matches in the loader/runtime/driver layers are either drivers reading their own\n\t\t// policies (e.g. local-driver) or `IReadOnlyInfo.storageOnly`, which is derived from the\n\t\t// live connection — not the policy. So the writable-frozen container is intentionally\n\t\t// indistinguishable from a normal container at the policies layer; downstream behavior\n\t\t// flows through the live `WritableFrozenDeltaStream` instead.\n\t\tthis.policies = readOnly ? { storageOnly: true } : {};\n\t}\n\n\tpublic readonly policies: IDocumentServicePolicies;\n\tasync connectToStorage(): Promise<IDocumentStorageService> {\n\t\tconst storage = new FrozenDocumentStorageService(\n\t\t\tthis.readOnly,\n\t\t\tawait this.documentService?.connectToStorage(),\n\t\t);\n\t\tthis.storageServices.add(storage);\n\t\treturn storage;\n\t}\n\tasync connectToDeltaStorage(): Promise<IDocumentDeltaStorageService> {\n\t\treturn frozenDocumentDeltaStorageService;\n\t}\n\tasync connectToDeltaStream(_client: IClient): Promise<IDocumentDeltaConnection> {\n\t\tif (this.readOnly) {\n\t\t\t// connectionManager short-circuits via policies.storageOnly before reaching here\n\t\t\t// in the read-only path; reaching this branch indicates a non-connectionManager\n\t\t\t// consumer or a regression of the short-circuit. Throw to surface the misuse\n\t\t\t// rather than silently produce a working stream.\n\t\t\tthrow new Error(\n\t\t\t\t\"FrozenDocumentService is read-only; connectToDeltaStream should not be called (connectionManager short-circuits via policies.storageOnly)\",\n\t\t\t);\n\t\t}\n\t\t// Writable path: hand out a fresh WritableFrozenDeltaStream regardless of client.mode\n\t\t// or whether this is the initial connect or a reconnect. The stream's own mode is\n\t\t// \"read\" (advertising \"write\" would imply quorum membership we cannot honor), and\n\t\t// `ConnectionManager.sendMessages` short-circuits on WritableFrozenDeltaStream so\n\t\t// outbound writes never reach a real network. The per-instance clientId minted in\n\t\t// FrozenDeltaStreamBase prevents pendingStateManager 0x173 on replay across reconnects.\n\t\treturn new WritableFrozenDeltaStream();\n\t}\n\tdispose(error?: unknown): void {\n\t\t// Cascade disposal to each storage instance so any hanging `createBlob` promises (the\n\t\t// writable-frozen pending-blob mechanism) reject and the BlobManager can release its\n\t\t// references. Without this, hung promises remain held by BlobManager closures for the\n\t\t// lifetime of the process.\n\t\tfor (const storage of this.storageServices) {\n\t\t\tstorage.dispose();\n\t\t}\n\t\tthis.storageServices.clear();\n\t\t// Forward disposal to the wrapped service. We own its lifetime (it was created for us\n\t\t// by the wrapping factory and is never exposed to callers), so the contract from\n\t\t// `IDocumentService.dispose` (\"called by storage consumer when done with storage\")\n\t\t// applies here.\n\t\tthis.documentService?.dispose(error);\n\t}\n}\n\nconst frozenDocumentStorageServiceHandler = (): never => {\n\tthrow new Error(\"Operations are not supported on the FrozenDocumentStorageService.\");\n};\n\nclass FrozenDocumentStorageService implements IDocumentStorageService, IDisposable {\n\t// Single deferred shared by every in-flight `createBlob` call. The writable-frozen\n\t// `createBlob` returns this promise so the BlobManager keeps the blob in `uploading`\n\t// state (see comment in the constructor). Rejecting the deferred on disposal fans the\n\t// rejection out to every awaiter at once — and to any future `createBlob` calls too,\n\t// since they receive the already-rejected promise.\n\tprivate readonly disposalDeferred: {\n\t\treadonly promise: Promise<never>;\n\t\treadonly reject: (error: Error) => void;\n\t};\n\n\tprivate _disposed = false;\n\tpublic get disposed(): boolean {\n\t\treturn this._disposed;\n\t}\n\n\tconstructor(\n\t\treadOnly: boolean,\n\t\tprivate readonly documentStorageService?: IDocumentStorageService,\n\t) {\n\t\tlet rejectFn!: (error: Error) => void;\n\t\tconst promise = new Promise<never>((_, reject) => {\n\t\t\trejectFn = reject;\n\t\t});\n\t\t// Attach a no-op catch so node doesn't log an unhandled-rejection warning when\n\t\t// dispose runs before any caller has awaited the promise. Callers awaiting the\n\t\t// original promise still observe the rejection.\n\t\tpromise.catch(() => {});\n\t\tthis.disposalDeferred = { promise, reject: rejectFn };\n\n\t\t// In the writable-frozen path, `createBlob` returns a never-resolving promise instead\n\t\t// of throwing. This keeps the BlobManager's `localBlobCache` entry in the `uploading`\n\t\t// state: `getPendingBlobs` downgrades `uploading` blobs to `localOnly` in pending\n\t\t// state, so the blob survives `getPendingLocalState`. A subsequent live load runs\n\t\t// `sharePendingBlobs`, which re-enters `uploadAndAttach` against the real storage to\n\t\t// complete the upload. Throwing here would instead delete the cache entry (in\n\t\t// `uploadAndAttach`'s catch handler) and lose the blob — defeating the whole point of\n\t\t// accruing pending state.\n\t\tthis.createBlob = readOnly\n\t\t\t? frozenDocumentStorageServiceHandler\n\t\t\t: async () => this.disposalDeferred.promise;\n\t}\n\n\tgetSnapshotTree = frozenDocumentStorageServiceHandler;\n\tgetSnapshot = frozenDocumentStorageServiceHandler;\n\tgetVersions = frozenDocumentStorageServiceHandler;\n\tcreateBlob: IDocumentStorageService[\"createBlob\"];\n\treadBlob =\n\t\tthis.documentStorageService?.readBlob.bind(this.documentStorageService) ??\n\t\tfrozenDocumentStorageServiceHandler;\n\tuploadSummaryWithContext = frozenDocumentStorageServiceHandler;\n\tdownloadSummary = frozenDocumentStorageServiceHandler;\n\n\tpublic dispose(): void {\n\t\tif (this._disposed) {\n\t\t\treturn;\n\t\t}\n\t\tthis._disposed = true;\n\t\t// Don't propagate any caller-supplied error here. `IDocumentService.dispose` already\n\t\t// logs the Container's error path; the createBlob deferred's consumer (BlobManager)\n\t\t// only needs the \"this storage is going away\" signal — not a chain of error causes.\n\t\tthis.disposalDeferred.reject(new Error(\"FrozenDocumentStorageService is disposed\"));\n\t}\n}\n\nconst frozenDocumentDeltaStorageService: IDocumentDeltaStorageService = {\n\tfetchMessages: () => ({\n\t\tread: async () => ({\n\t\t\tdone: true,\n\t\t}),\n\t}),\n};\n\nconst clientFrozenDeltaStream: IClient = {\n\tmode: \"read\",\n\tdetails: { capabilities: { interactive: true } },\n\tpermission: [],\n\tuser: { id: \"storage-only client\" }, // we need some \"fake\" ID here.\n\tscopes: [],\n};\n\nconst clientIdFrozenDeltaStream: string = \"storage-only client\";\n\n// Cast rationale: ITokenClaims requires tenantId/documentId/user/iat/exp/ver, but a frozen\n// delta stream has no tenant or session to draw real values from — it's a synthetic\n// in-process connection that never reaches a service. Inventing sentinel values would imply\n// quorum membership we cannot honor; only `scopes` actually drives behavior here (DocRead vs\n// DocWrite gates readOnlyInfo). The cast is the honest representation of \"this connection\n// has no claims worth populating.\"\n/* eslint-disable @typescript-eslint/consistent-type-assertions */\nconst readOnlyClaims: ITokenClaims = { scopes: [ScopeType.DocRead] } as ITokenClaims;\nconst writableClaims: ITokenClaims = {\n\tscopes: [ScopeType.DocRead, ScopeType.DocWrite],\n} as ITokenClaims;\n/* eslint-enable @typescript-eslint/consistent-type-assertions */\n\n/**\n * Inert `IDocumentDeltaConnection` for frozen container loads. Has no server upstream:\n * op and signal streams are empty, and `initialClients` contains only its own synthetic\n * read-only client — which lets the connection state handler observe \"self\" in the audience\n * and transition the container to Connected without waiting for a real join op or signal.\n *\n * Two concrete variants share this base — see their JSDoc for variant-specific details:\n *\n * - {@link FrozenDeltaStream} — read-only.\n * - {@link WritableFrozenDeltaStream} — writable.\n *\n * Both variants nack any incoming `submit`: this connection has no upstream and\n * `ConnectionManager.sendMessages` recognizes `WritableFrozenDeltaStream` and drops messages\n * before they reach `submit`, so under normal flow it should never fire. A nack reaching the\n * connectionManager surfaces the misuse — and may close the container — which is the right\n * defensive signal that something has bypassed the expected flow.\n *\n * `submitSignal` is a silent no-op for both variants. Signals are ephemeral and best-effort —\n * runtime/presence subsystems may submit them at any point in the writable-frozen lifetime, and\n * dropping them is the correct behavior here (we have no upstream). Closing the container or\n * triggering a reconnect on a stray signal would be strictly worse than dropping it.\n */\nabstract class FrozenDeltaStreamBase\n\textends TypedEventEmitter<IDocumentDeltaConnectionEvents>\n\timplements IDocumentDeltaConnection, IDisposable\n{\n\tpublic readonly clientId: string;\n\tpublic readonly claims: ITokenClaims;\n\tpublic readonly initialClients: ISignalClient[];\n\tpublic readonly mode: ConnectionMode = \"read\";\n\tpublic readonly existing: boolean = true;\n\tpublic readonly maxMessageSize: number = 0;\n\tpublic readonly version: string = \"\";\n\tpublic readonly initialMessages: ISequencedDocumentMessage[] = [];\n\tpublic readonly initialSignals: ISignalMessage[] = [];\n\tpublic readonly serviceConfiguration: IClientConfiguration = {\n\t\tmaxMessageSize: 0,\n\t\tblockSize: 0,\n\t};\n\tpublic readonly checkpointSequenceNumber?: number | undefined = undefined;\n\n\tconstructor(clientId: string, claims: ITokenClaims) {\n\t\tsuper();\n\t\tthis.clientId = clientId;\n\t\tthis.claims = claims;\n\t\t// initialClients mirrors clientId so the audience handler observes \"self\" and\n\t\t// transitions the container to Connected without waiting for a real join op or signal.\n\t\tthis.initialClients = [{ client: clientFrozenDeltaStream, clientId }];\n\t}\n\n\tsubmit(messages: IDocumentMessage[]): void {\n\t\t// Defensive nack: nothing should send on a frozen delta stream. If this fires, an\n\t\t// invariant in connectionManager has changed and we want it to surface loudly.\n\t\tthis.emit(\n\t\t\t\"nack\",\n\t\t\tthis.clientId,\n\t\t\tmessages.map((operation) => ({\n\t\t\t\toperation,\n\t\t\t\tcontent: { message: \"Cannot submit on a frozen delta stream\", code: 403 },\n\t\t\t})),\n\t\t);\n\t}\n\n\tsubmitSignal(_message: unknown): void {\n\t\t// Intentional no-op. See class JSDoc for rationale.\n\t}\n\n\tprivate _disposed = false;\n\tpublic get disposed(): boolean {\n\t\treturn this._disposed;\n\t}\n\tpublic dispose(): void {\n\t\tthis._disposed = true;\n\t}\n}\n\n/**\n * Read-only variant of {@link FrozenDeltaStreamBase}. Claims show only `DocRead`. Used by\n * storage-only loads (where `connectionManager` synthesizes one directly via\n * `policies.storageOnly`) and by the forbidden / out-of-storage fallback paths.\n * {@link isFrozenDeltaStreamConnection} matches this variant and drives the read-only forcing\n * in `ConnectionManager.readOnlyInfo`. Uses the historical `\"storage-only client\"` constant\n * `clientId`, preserving existing behavior for any consumer that keys off it.\n *\n * `storageOnlyReason` and `readonlyConnectionReason` are surfaced through `IContainer.readOnlyInfo`\n * for diagnostics on the fallback paths (`isDeltaStreamConnectionForbiddenError`,\n * `outOfStorageError`).\n */\nexport class FrozenDeltaStream extends FrozenDeltaStreamBase {\n\tpublic readonly storageOnlyReason: string | undefined;\n\tpublic readonly readonlyConnectionReason: IConnectionStateChangeReason | undefined;\n\n\tconstructor(options?: {\n\t\tstorageOnlyReason?: string;\n\t\treadonlyConnectionReason?: IConnectionStateChangeReason;\n\t}) {\n\t\t// Constant clientId: preserves the pre-PR `\"storage-only client\"` identity for any\n\t\t// consumer that keys off it. The 0x173 replay-assert risk that motivates per-instance\n\t\t// clientIds applies only to the writable variant, where the runtime accumulates dirty\n\t\t// pending ops across reconnects; the read-only variant does not.\n\t\tsuper(clientIdFrozenDeltaStream, readOnlyClaims);\n\t\tthis.storageOnlyReason = options?.storageOnlyReason;\n\t\tthis.readonlyConnectionReason = options?.readonlyConnectionReason;\n\t}\n}\n\n/**\n * Variant of {@link FrozenDeltaStreamBase} that appears to support writing but remains\n * \"frozen\" — no messages are actually sent or received. The stream itself does not enforce\n * the no-send guarantee; that lives in `ConnectionManager.sendMessages`, which recognizes\n * any `WritableFrozenDeltaStream` (via {@link isWritableFrozenDeltaStreamConnection}) and\n * short-circuits before its read-mode upgrade branch. Submitted ops are dropped at the\n * connection-manager layer, so the container stays `Connected` and the runtime accumulates\n * them in `pendingStateManager`.\n *\n * \"Appears writable\" mechanics: claims include `DocWrite` so the container surfaces as\n * writable; not matched by {@link isFrozenDeltaStreamConnection}, so `readOnlyInfo` reports\n * `readonly: false`. Connection mode stays `\"read\"` (advertising `\"write\"` would imply quorum\n * membership we cannot honor).\n *\n * Each instance mints a fresh `frozen-delta-stream/<uuid>` `clientId` to avoid\n * `pendingStateManager` `0x173` (`replayPendingStates called twice for same clientId!`) on\n * reconnect with dirty pending ops. Sibling (not subclass) of `FrozenDeltaStream` so\n * `instanceof` cleanly distinguishes the two for `ConnectionManager`'s short-circuits.\n */\nexport class WritableFrozenDeltaStream extends FrozenDeltaStreamBase {\n\tconstructor() {\n\t\tsuper(`frozen-delta-stream/${uuid()}`, writableClaims);\n\t}\n}\n\n/**\n * Recognizes the read-only variant of {@link FrozenDeltaStreamBase}. Drives the storage-only\n * forcing in `ConnectionManager.readOnlyInfo`: only the read-only variant should make the\n * container surface as read-only. {@link WritableFrozenDeltaStream} is a sibling class, not\n * a subclass, so `instanceof FrozenDeltaStream` already excludes it.\n */\nexport function isFrozenDeltaStreamConnection(\n\tconnection: unknown,\n): connection is FrozenDeltaStream {\n\treturn connection instanceof FrozenDeltaStream;\n}\n\n/**\n * Recognizes the writable variant of {@link FrozenDeltaStreamBase}. Drives the\n * `ConnectionManager.sendMessages` short-circuit: writable-frozen submits must be dropped at\n * the network layer instead of triggering a read→write reconnect. Sibling (not subclass) of\n * {@link FrozenDeltaStream}, so `instanceof WritableFrozenDeltaStream` excludes the read-only\n * variant.\n */\nexport function isWritableFrozenDeltaStreamConnection(\n\tconnection: unknown,\n): connection is WritableFrozenDeltaStream {\n\treturn connection instanceof WritableFrozenDeltaStream;\n}\n"]}