@fluidframework/container-loader 2.100.0 → 2.101.0

package/dist/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/dist/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/dist/frozenServices.js

@@ -4,35 +4,53 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isFrozenDeltaStreamConnection = exports.FrozenDeltaStream = exports.FrozenDocumentServiceFactory = exports.createFrozenDocumentServiceFactory = void 0;
+exports.isWritableFrozenDeltaStreamConnection = exports.isFrozenDeltaStreamConnection = exports.WritableFrozenDeltaStream = exports.FrozenDeltaStream = exports.FrozenDocumentServiceFactory = exports.createFrozenDocumentServiceFactory = void 0;
 const client_utils_1 = require("@fluid-internal/client-utils");
 const internal_1 = require("@fluidframework/core-utils/internal");
 const internal_2 = require("@fluidframework/driver-definitions/internal");
+const uuid_1 = require("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
  */
-function createFrozenDocumentServiceFactory(factory) {
-    // Sync path
-    return factory instanceof FrozenDocumentServiceFactory
-        ? factory
-        : new FrozenDocumentServiceFactory(factory);
+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);
 }
 exports.createFrozenDocumentServiceFactory = createFrozenDocumentServiceFactory;
 class FrozenDocumentServiceFactory {
-    constructor(documentServiceFactory) {
-        this.documentServiceFactory = documentServiceFactory;
+    constructor(readOnly, inner) {
+        this.readOnly = readOnly;
+        this.inner = inner;
     }
     async createDocumentService(resolvedUrl) {
-        let factory = this.documentServiceFactory;
-        if ((0, internal_1.isPromiseLike)(factory)) {
-            factory = await this.documentServiceFactory;
-        }
-        return new FrozenDocumentService(resolvedUrl, await factory?.createDocumentService(resolvedUrl));
+        const factory = (0, internal_1.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.");
@@ -40,39 +58,117 @@ class FrozenDocumentServiceFactory {
 }
 exports.FrozenDocumentServiceFactory = FrozenDocumentServiceFactory;
 class FrozenDocumentService extends client_utils_1.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 = {
@@ -90,54 +186,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: [internal_2.ScopeType.DocRead] };
+const writableClaims = {
+    scopes: [internal_2.ScopeType.DocRead, internal_2.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.
  */
-class FrozenDeltaStream extends client_utils_1.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 client_utils_1.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: [internal_2.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;
@@ -146,9 +259,74 @@ class FrozenDeltaStream extends client_utils_1.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`).
+ */
+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;
+    }
+}
 exports.FrozenDeltaStream = FrozenDeltaStream;
+/**
+ * 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.
+ */
+class WritableFrozenDeltaStream extends FrozenDeltaStreamBase {
+    constructor() {
+        super(`frozen-delta-stream/${(0, uuid_1.v4)()}`, writableClaims);
+    }
+}
+exports.WritableFrozenDeltaStream = WritableFrozenDeltaStream;
+/**
+ * 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.
+ */
 function isFrozenDeltaStreamConnection(connection) {
     return connection instanceof FrozenDeltaStream;
 }
 exports.isFrozenDeltaStreamConnection = isFrozenDeltaStreamConnection;
+/**
+ * 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.
+ */
+function isWritableFrozenDeltaStreamConnection(connection) {
+    return connection instanceof WritableFrozenDeltaStream;
+}
+exports.isWritableFrozenDeltaStreamConnection = isWritableFrozenDeltaStreamConnection;
 //# sourceMappingURL=frozenServices.js.map