agenthooksprotocol 0.1.1 → 0.2.0

package/dist/src/client/content.d.ts

@@ -1,16 +1,42 @@
 import { type ContentSelection, type ContentUpload } from "../draft/generated.js";
-/** An owned native content stream, distinct from a receiver content reference.
- * Construction does not read, lock, or upload the stream. Passing this source to
- * an awaited SDK operation transfers cleanup responsibility to that operation;
- * callers must not consume or reuse the underlying stream afterward. Native
- * streams can prefetch independently; use highWaterMark: 0 to disable that.
- */
+/** Compatibility adapter for a native lazy stream. The stream is consumed by
+ * its attachment owner, not staged in an invocation store. */
 export declare class ContentSource {
     #private;
     constructor(stream: ReadableStream<Uint8Array>);
-    /** Native stream identity is preserved for snapshot sharing and cleanup. */
     get stream(): ReadableStream<Uint8Array>;
 }
+type ContentMetadata = {
+    size?: number | undefined;
+    sha256?: string | undefined;
+};
+/** Sole backing owner for immutable bytes or an unread lazy source. Metadata
+ * stays on content items. A handle may be shared within, but not across, calls. */
+export declare class Attachment extends ContentSource {
+    #private;
+    private constructor();
+    /** One defensive input copy, retained directly by this owner. */
+    static bytes(bytes: Uint8Array): Attachment;
+    /** Evaluated once, on demand. The returned mutable buffer is copied once. */
+    static lazy(open: (signal: AbortSignal) => Uint8Array | Promise<Uint8Array>, dispose?: () => void | Promise<void>): Attachment;
+    /** Adapt a native source without a second snapshot cache. */
+    static fromStream(stream: ReadableStream<Uint8Array>): Attachment;
+    /** Defensive caller copy; uploads use the same private materialization. */
+    read(signal?: AbortSignal, metadata?: ContentMetadata): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+/** Effective slot index. Owners, not an invocation manager, outlive Hooks. */
+export declare class AttachmentContent {
+    private readonly bodies;
+    private readonly owners;
+    private closed;
+    constructor(event: unknown);
+    get ids(): readonly string[];
+    /** @internal Transfer cleanup responsibility without copying backing bytes. */
+    detachFrom(pending: Set<Attachment>): void;
+    read(id: string, signal?: AbortSignal): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
 /** Producer content is metadata with an owned source or raw stream in `body`. */
 export interface StreamContentItem {
     id: string;
@@ -34,19 +60,23 @@ export interface ContentManagerOptions {
     maxSnapshotBytes?: number;
     allowLoopback?: boolean;
 }
-/** One manager per producer/session. Selection is NOT authorization: callers must
- * authorize/project opaque native/input/output data before prepare. References
- * are deliberately never cached: each prepare uploads in its receiver's scope.
+/** Per-invocation delivery and cleanup coordinator, not a content store.
+ * Byte materialization lives only in Attachment. This class retains owner
+ * identities and non-owning aggregate budget counters, never byte buffers.
+ * Selection is not authorization; project opaque host data before prepare.
  */
 export declare class ContentManager {
-    private snapshots;
-    private readers;
-    private seenStreams;
+    private hasAttachments;
+    private readonly ownership;
+    /** @internal Build a slot index retaining the existing owners. */
+    resultContent(event: unknown): AttachmentContent | undefined;
+    private readonly attachments;
     private lifetime;
-    private retainedBytes;
     private closePromise;
-    private readonly limit;
+    private readonly budget;
     private readonly allowLoopback;
+    /** @internal Detach returned owners; dispose everything else in close(). */
+    transfer(content: AttachmentContent): void;
     constructor(options?: ContentManagerOptions);
     /** Take cleanup ownership without selecting or reading any body. Call before
      * routing/projection so unmatched and unauthorized sources are also closed.
@@ -57,19 +87,25 @@ export declare class ContentManager {
      * Reuses the same bounded snapshot as prepare; returns an independent copy.
      * Aborting the initial read cancels the stream and leaves that snapshot failed.
      */
-    readBody(body: ContentSource | ReadableStream<Uint8Array>, signal?: AbortSignal): Promise<Uint8Array>;
+    readBody(body: ContentSource | ReadableStream<Uint8Array>, signal?: AbortSignal, metadata?: ContentMetadata): Promise<Uint8Array>;
     /** Returns a fresh wire tree; never mutates the producer event or reads an
      * omitted/metadata stream. All selected uploads finish before this resolves.
      */
     prepare(event: any, selection: ContentSelection, upload: ContentUpload | undefined, send: ContentUploadRequest, signal?: AbortSignal): Promise<any>;
-    /** Copy an already selected snapshot without reading unselected sources. */
-    copySnapshot(body: ReadableStream<Uint8Array>): Promise<Uint8Array | undefined>;
-    /** Initiates cancellation and releases snapshots; repeated calls return the
-     * same promise. Never waits for producer-controlled cancellation promises.
-     */
+    /** @internal A protocol correlation lease shares the same owner, never bytes. */
+    retainBody(body: ReadableStream<Uint8Array>, signal: AbortSignal): Promise<{
+        owner: Attachment;
+        size: number;
+        release: () => Promise<void>;
+    }>;
+    /** @internal Project compatibility results, or preserve the actual owner. */
+    resultBody(body: ReadableStream<Uint8Array>, synthesized: boolean): Promise<Attachment | ReadableStream<Uint8Array> | undefined>;
+    /** @internal Invocation-scoped borrow of an active protocol exchange. */
+    lease(owner: Attachment): () => Promise<void>;
+    /** Cancel and dispose remaining owners. No backing bytes live here. */
     close(): Promise<void>;
     private validateUpload;
     private snapshot;
-    private readSnapshot;
 }
+export {};
 //# sourceMappingURL=content.d.ts.map

package/dist/src/client/content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../src/client/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,qBAAa,aAAa;;gBAGZ,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC;IAM9C,4EAA4E;IAC5E,IAAI,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAEvC;CACF;AAOD,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,KAClB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAID;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAGb;IACJ,OAAO,CAAC,OAAO,CAAsD;IACrE,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAE5B,OAAO,GAAE,qBAA0B;IAO/C;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAiBzB;;;OAGG;IACG,QAAQ,CACZ,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC,UAAU,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC;IA4BtB;;OAEG;IACG,OAAO,CACX,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,gBAAgB,EAC3B,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,IAAI,EAAE,oBAAoB,EAC1B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC;IA+If,4EAA4E;IACtE,YAAY,CAChB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAC/B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAWlC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAetB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,QAAQ;YAWF,YAAY;CAuD3B"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../src/client/content.ts"],"names":[],"mappings":"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"}

package/dist/src/client/content.js

@@ -1,10 +1,6 @@
 import { parseContentUploadReceipt, } from "../draft/generated.js";
-/** An owned native content stream, distinct from a receiver content reference.
- * Construction does not read, lock, or upload the stream. Passing this source to
- * an awaited SDK operation transfers cleanup responsibility to that operation;
- * callers must not consume or reuse the underlying stream afterward. Native
- * streams can prefetch independently; use highWaterMark: 0 to disable that.
- */
+/** Compatibility adapter for a native lazy stream. The stream is consumed by
+ * its attachment owner, not staged in an invocation store. */
 export class ContentSource {
     #stream;
     constructor(stream) {
@@ -12,9 +8,268 @@ export class ContentSource {
             throw new Error("Content source requires a native ReadableStream");
         this.#stream = stream;
     }
-    /** Native stream identity is preserved for snapshot sharing and cleanup. */
-    get stream() {
-        return this.#stream;
+    get stream() { return this.#stream; }
+}
+// This is only an identity index for legacy native streams, never a byte store.
+const streamOwners = new WeakMap();
+const retainedOwners = new WeakSet();
+let ownerAccess;
+/** Sole backing owner for immutable bytes or an unread lazy source. Metadata
+ * stays on content items. A handle may be shared within, but not across, calls. */
+export class Attachment extends ContentSource {
+    #load;
+    #snapshot;
+    #lifetime = new AbortController();
+    #invocation;
+    #budget = { used: 0, limit: 64 * 1024 * 1024 };
+    #reserved = 0;
+    #dispose;
+    #disposal;
+    #closed;
+    #primaryRelease;
+    #leases = 1;
+    constructor(load, dispose, retained = true) {
+        let owner;
+        super(new ReadableStream({
+            async pull(controller) {
+                try {
+                    controller.enqueue(await owner.read());
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            cancel() { return owner.close(); },
+        }, { highWaterMark: 0 }));
+        owner = this;
+        this.#load = load;
+        this.#dispose = dispose;
+        streamOwners.set(this.stream, this);
+        if (retained)
+            retainedOwners.add(this);
+    }
+    static {
+        ownerAccess = {
+            claim(owner, invocation, budget) {
+                if (owner.#invocation && owner.#invocation !== invocation)
+                    throw new Error("Attachment already belongs to another invocation");
+                if (owner.#closed)
+                    throw new Error("Attachment closed");
+                if (!owner.#invocation) {
+                    if (owner.#snapshot !== undefined)
+                        throw new Error("Read attachments cannot be transferred to an invocation");
+                    owner.#invocation = invocation;
+                    owner.#budget = budget;
+                }
+            },
+            snapshot: (owner, signal) => owner.#materialize(signal),
+            peek: (owner) => owner.#snapshot,
+            adapt: (stream) => Attachment.#fromStream(stream),
+            retain(owner) {
+                owner.#lifetime.signal.throwIfAborted();
+                owner.#leases++;
+                let released;
+                return () => released ??= owner.#release();
+            },
+        };
+    }
+    /** One defensive input copy, retained directly by this owner. */
+    static bytes(bytes) {
+        let initial = new Uint8Array(bytes);
+        return new Attachment(async (_signal, reserve) => {
+            const bytes = initial;
+            reserve(bytes.byteLength);
+            initial = undefined;
+            return bytes;
+        }, () => { initial = undefined; });
+    }
+    /** Evaluated once, on demand. The returned mutable buffer is copied once. */
+    static lazy(open, dispose = () => { }) {
+        return new Attachment(async (signal, reserve) => {
+            const bytes = await open(signal);
+            signal.throwIfAborted();
+            if (!(bytes instanceof Uint8Array))
+                throw new TypeError("Attachment source must return Uint8Array");
+            reserve(bytes.byteLength);
+            return new Uint8Array(bytes);
+        }, dispose);
+    }
+    /** Adapt a native source without a second snapshot cache. */
+    static fromStream(stream) {
+        if (!(stream instanceof ReadableStream))
+            throw new TypeError("Attachment source requires a native ReadableStream");
+        const owner = Attachment.#fromStream(stream);
+        retainedOwners.add(owner);
+        return owner;
+    }
+    static #fromStream(stream) {
+        const existing = streamOwners.get(stream);
+        if (existing)
+            return existing;
+        let reader;
+        const owner = new Attachment(async (signal, reserve) => {
+            reader = stream.getReader();
+            const chunks = [];
+            let size = 0;
+            const cancel = () => { void reader?.cancel(signal.reason).catch(() => { }); };
+            signal.addEventListener("abort", cancel, { once: true });
+            try {
+                for (;;) {
+                    const next = await abortable(reader.read(), signal);
+                    signal.throwIfAborted();
+                    if (next.done)
+                        break;
+                    if (!(next.value instanceof Uint8Array))
+                        throw new Error("Content stream must yield Uint8Array chunks");
+                    reserve(next.value.byteLength);
+                    chunks.push(new Uint8Array(next.value));
+                    size += next.value.byteLength;
+                }
+                const bytes = new Uint8Array(size);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    bytes.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                return bytes;
+            }
+            finally {
+                signal.removeEventListener("abort", cancel);
+                reader.releaseLock();
+                reader = undefined;
+            }
+        }, () => {
+            // Request cancellation without awaiting producer cleanup, which may never settle.
+            if (reader)
+                void reader.cancel().catch(() => { });
+            else if (!stream.locked)
+                void stream.cancel().catch(() => { });
+        }, false);
+        streamOwners.set(stream, owner);
+        return owner;
+    }
+    #cleanup() {
+        if (!this.#disposal) {
+            const dispose = this.#dispose;
+            this.#dispose = () => { };
+            this.#disposal = Promise.resolve().then(dispose);
+        }
+        return this.#disposal;
+    }
+    #materialize(signal) {
+        this.#lifetime.signal.throwIfAborted();
+        signal?.throwIfAborted();
+        if (!this.#snapshot) {
+            const load = this.#load;
+            this.#load = undefined;
+            const abort = () => this.#lifetime.abort(signal?.reason);
+            signal?.addEventListener("abort", abort, { once: true });
+            this.#snapshot = (async () => {
+                try {
+                    const bytes = await abortable(load(this.#lifetime.signal, (size) => {
+                        this.#lifetime.signal.throwIfAborted();
+                        if (this.#budget.used + size > this.#budget.limit)
+                            throw new Error("Content snapshot memory limit exceeded");
+                        this.#budget.used += size;
+                        this.#reserved += size;
+                    }), this.#lifetime.signal);
+                    this.#lifetime.signal.throwIfAborted();
+                    // All loaders allocate ordinary ArrayBuffers before returning bytes.
+                    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+                    this.#lifetime.signal.throwIfAborted();
+                    return { bytes, size: bytes.length,
+                        sha256: Array.from(digest, byte => byte.toString(16).padStart(2, "0")).join("") };
+                }
+                catch (error) {
+                    this.#budget.used -= this.#reserved;
+                    this.#reserved = 0;
+                    throw error;
+                }
+                finally {
+                    signal?.removeEventListener("abort", abort);
+                    await this.#cleanup();
+                }
+            })();
+        }
+        return signal ? abortable(this.#snapshot, signal) : this.#snapshot;
+    }
+    /** Defensive caller copy; uploads use the same private materialization. */
+    async read(signal, metadata = {}) {
+        const snapshot = await this.#materialize(signal);
+        validateSnapshotMetadata(snapshot, metadata);
+        return snapshot.bytes.slice();
+    }
+    close() {
+        return this.#primaryRelease ??= this.#release();
+    }
+    #release() {
+        if (--this.#leases !== 0)
+            return Promise.resolve();
+        if (this.#closed)
+            return this.#closed;
+        this.#lifetime.abort(new Error("Attachment closed"));
+        this.#load = undefined;
+        this.#snapshot = undefined;
+        this.#budget.used -= this.#reserved;
+        this.#reserved = 0;
+        return this.#closed = this.#cleanup();
+    }
+}
+/** Effective slot index. Owners, not an invocation manager, outlive Hooks. */
+export class AttachmentContent {
+    bodies = new Map();
+    owners = new Set();
+    closed;
+    constructor(event) {
+        const seen = new WeakSet();
+        const visit = (value, path) => {
+            if (!value || typeof value !== "object" || seen.has(value))
+                return;
+            const stream = sourceStream(value);
+            if (stream) {
+                const owner = ownerAccess.adapt(stream);
+                this.bodies.set(path, { owner });
+                this.owners.add(owner);
+                return;
+            }
+            seen.add(value);
+            const body = sourceStream(value.body);
+            if (typeof value.id === "string" && body) {
+                const owner = ownerAccess.adapt(body);
+                const previous = this.bodies.get(value.id);
+                if (previous && (previous.owner !== owner || previous.size !== value.size || previous.sha256 !== value.sha256))
+                    throw new Error("Ambiguous content item id");
+                this.bodies.set(value.id, { owner, size: value.size, sha256: value.sha256 });
+                this.owners.add(owner);
+            }
+            for (const [key, child] of Object.entries(value)) {
+                if (key === "body" && body && typeof value.id === "string")
+                    continue;
+                visit(child, path + "/" + key.replaceAll("~", "~0").replaceAll("/", "~1"));
+            }
+        };
+        visit(event, "");
+    }
+    get ids() { return [...this.bodies.keys()]; }
+    /** @internal Transfer cleanup responsibility without copying backing bytes. */
+    detachFrom(pending) {
+        for (const owner of this.owners)
+            pending.delete(owner);
+    }
+    async read(id, signal) {
+        const body = this.bodies.get(id);
+        if (!body)
+            throw new Error("Unknown local content item id");
+        return body.owner.read(signal, body);
+    }
+    close() {
+        if (this.closed)
+            return this.closed;
+        this.bodies.clear();
+        this.closed = Promise.all([...this.owners].map(owner => owner.close())).then(() => { });
+        this.owners.clear();
+        return this.closed;
     }
 }
 function sourceStream(value) {
@@ -22,22 +277,35 @@ function sourceStream(value) {
         return value.stream;
     return value instanceof ReadableStream ? value : undefined;
 }
-/** One manager per producer/session. Selection is NOT authorization: callers must
- * authorize/project opaque native/input/output data before prepare. References
- * are deliberately never cached: each prepare uploads in its receiver's scope.
+function validateSnapshotMetadata(snapshot, metadata) {
+    if (metadata.size !== undefined && metadata.size !== snapshot.size)
+        throw new Error("Content size mismatch");
+    if (metadata.sha256 !== undefined && metadata.sha256 !== snapshot.sha256)
+        throw new Error("Content SHA-256 mismatch");
+}
+/** Per-invocation delivery and cleanup coordinator, not a content store.
+ * Byte materialization lives only in Attachment. This class retains owner
+ * identities and non-owning aggregate budget counters, never byte buffers.
+ * Selection is not authorization; project opaque host data before prepare.
  */
 export class ContentManager {
-    snapshots = new WeakMap();
-    readers = new Set();
-    seenStreams = new Set();
+    hasAttachments = false;
+    ownership = {};
+    /** @internal Build a slot index retaining the existing owners. */
+    resultContent(event) {
+        return this.hasAttachments ? new AttachmentContent(event) : undefined;
+    }
+    attachments = new Set();
     lifetime = new AbortController();
-    retainedBytes = 0;
     closePromise;
-    limit;
+    budget;
     allowLoopback;
+    /** @internal Detach returned owners; dispose everything else in close(). */
+    transfer(content) { content.detachFrom(this.attachments); }
     constructor(options = {}) {
-        this.limit = options.maxSnapshotBytes ?? 64 * 1024 * 1024;
-        if (!Number.isSafeInteger(this.limit) || this.limit < 0)
+        const limit = options.maxSnapshotBytes ?? 64 * 1024 * 1024;
+        this.budget = { used: 0, limit };
+        if (!Number.isSafeInteger(limit) || limit < 0)
             throw new Error("Invalid snapshot byte limit");
         this.allowLoopback = options.allowLoopback ?? false;
     }
@@ -48,25 +316,40 @@ export class ContentManager {
     own(event) {
         this.lifetime.signal.throwIfAborted();
         const visited = new WeakSet();
+        let conflict = false;
         const visit = (value) => {
             if (value === null || typeof value !== "object" || visited.has(value))
                 return;
             visited.add(value);
             const stream = sourceStream(value);
             if (stream) {
-                this.seenStreams.add(stream);
+                const existing = streamOwners.get(stream);
+                const owner = ownerAccess.adapt(stream);
+                try {
+                    ownerAccess.claim(owner, this.ownership, this.budget);
+                }
+                catch {
+                    conflict = true;
+                    return;
+                }
+                // Explicit Attachment sources opt into retained result ownership.
+                if (existing && retainedOwners.has(existing))
+                    this.hasAttachments = true;
+                this.attachments.add(owner);
                 return;
             }
             for (const child of Object.values(value))
                 visit(child);
         };
         visit(event);
+        if (conflict)
+            throw new Error("Attachment already belongs to another invocation");
     }
     /** Reads local producer bytes for composition, never remote references.
      * Reuses the same bounded snapshot as prepare; returns an independent copy.
      * Aborting the initial read cancels the stream and leaves that snapshot failed.
      */
-    async readBody(body, signal) {
+    async readBody(body, signal, metadata = {}) {
         this.lifetime.signal.throwIfAborted();
         this.own(body);
         signal?.throwIfAborted();
@@ -82,6 +365,7 @@ export class ContentManager {
         try {
             const snapshot = await abortable(this.snapshot(stream, controller.signal), controller.signal);
             controller.signal.throwIfAborted();
+            validateSnapshotMetadata(snapshot, metadata);
             return snapshot.bytes.slice();
         }
         finally {
@@ -155,10 +439,7 @@ export class ContentManager {
                 const timeout = setTimeout(() => controller.abort(new DOMException("Content upload timed out", "TimeoutError")), upload.timeoutMs);
                 try {
                     const snapshot = await abortable(this.snapshot(stream, controller.signal), controller.signal);
-                    if (value.size !== undefined && value.size !== snapshot.size)
-                        throw new Error("Content size mismatch");
-                    if (value.sha256 !== undefined && value.sha256 !== snapshot.sha256)
-                        throw new Error("Content SHA-256 mismatch");
+                    validateSnapshotMetadata(snapshot, value);
                     if (snapshot.size > upload.maxBytes)
                         throw new Error("Content exceeds upload maxBytes");
                     const response = await abortable(send(upload.endpoint, {
@@ -206,37 +487,56 @@ export class ContentManager {
         };
         return visit(event);
     }
-    /** Copy an already selected snapshot without reading unselected sources. */
-    async copySnapshot(body) {
-        const snapshot = this.snapshots.get(body);
-        if (!snapshot)
+    /** @internal A protocol correlation lease shares the same owner, never bytes. */
+    async retainBody(body, signal) {
+        const owner = ownerAccess.adapt(body);
+        const snapshot = await ownerAccess.snapshot(owner, signal);
+        return { owner, size: snapshot.size, release: ownerAccess.retain(owner) };
+    }
+    /** @internal Project compatibility results, or preserve the actual owner. */
+    async resultBody(body, synthesized) {
+        const owner = ownerAccess.adapt(body);
+        if (this.hasAttachments)
+            return owner;
+        const pending = ownerAccess.peek(owner);
+        if (!synthesized && !pending)
             return undefined;
         try {
-            return (await snapshot).bytes.slice();
+            if (synthesized)
+                await ownerAccess.snapshot(owner);
+            else
+                await pending;
         }
         catch {
-            // Failed reads have no reusable result payload; delivery reports the error.
             return undefined;
         }
+        // Legacy callers receive a lazy view of this same owner, not a queued copy.
+        const release = ownerAccess.retain(owner);
+        return new ReadableStream({
+            async pull(controller) {
+                try {
+                    controller.enqueue(await owner.read());
+                    controller.close();
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+                finally {
+                    await release();
+                }
+            },
+            cancel() { return release(); },
+        }, { highWaterMark: 0 });
     }
-    /** Initiates cancellation and releases snapshots; repeated calls return the
-     * same promise. Never waits for producer-controlled cancellation promises.
-     */
+    /** @internal Invocation-scoped borrow of an active protocol exchange. */
+    lease(owner) { return ownerAccess.retain(owner); }
+    /** Cancel and dispose remaining owners. No backing bytes live here. */
     close() {
         if (this.closePromise)
             return this.closePromise;
-        this.closePromise = Promise.resolve();
         this.lifetime.abort(new Error("Content manager closed"));
-        const readers = [...this.readers];
-        this.snapshots = new WeakMap();
-        const unread = [...this.seenStreams].filter((stream) => !stream.locked);
-        this.seenStreams.clear();
-        this.readers.clear();
-        for (const reader of readers)
-            void reader.cancel().catch(() => undefined);
-        for (const stream of unread)
-            void stream.cancel().catch(() => undefined);
-        this.retainedBytes = 0;
+        this.closePromise = Promise.all([...this.attachments].map(owner => owner.close())).then(() => { });
+        this.attachments.clear();
         return this.closePromise;
     }
     validateUpload(upload) {
@@ -256,65 +556,7 @@ export class ContentManager {
             throw new Error("Invalid upload budget");
     }
     snapshot(stream, signal) {
-        const existing = this.snapshots.get(stream);
-        if (existing)
-            return existing;
-        const pending = this.readSnapshot(stream, signal);
-        this.snapshots.set(stream, pending);
-        return pending;
-    }
-    async readSnapshot(stream, signal) {
-        signal.throwIfAborted();
-        const reader = stream.getReader();
-        this.readers.add(reader);
-        const chunks = [];
-        let size = 0;
-        const cancel = () => {
-            void reader.cancel(signal.reason).catch(() => undefined);
-        };
-        signal.addEventListener("abort", cancel, { once: true });
-        try {
-            for (;;) {
-                const next = await abortable(reader.read(), signal);
-                signal.throwIfAborted();
-                if (next.done)
-                    break;
-                if (!(next.value instanceof Uint8Array))
-                    throw new Error("Content stream must yield Uint8Array chunks");
-                if (this.retainedBytes + next.value.byteLength > this.limit)
-                    throw new Error("Content snapshot memory limit exceeded");
-                if (next.value.byteLength === 0)
-                    continue;
-                chunks.push(next.value.slice());
-                size += next.value.byteLength;
-                this.retainedBytes += next.value.byteLength;
-            }
-            const bytes = new Uint8Array(size);
-            let offset = 0;
-            for (const chunk of chunks) {
-                bytes.set(chunk, offset);
-                offset += chunk.byteLength;
-            }
-            chunks.length = 0;
-            const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
-            signal.throwIfAborted();
-            return {
-                bytes,
-                size,
-                sha256: Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join(""),
-            };
-        }
-        catch (error) {
-            if (!this.lifetime.signal.aborted)
-                this.retainedBytes -= size;
-            void reader.cancel(error).catch(() => undefined);
-            throw error;
-        }
-        finally {
-            signal.removeEventListener("abort", cancel);
-            this.readers.delete(reader);
-            reader.releaseLock();
-        }
+        return ownerAccess.snapshot(ownerAccess.adapt(stream), signal);
     }
 }
 function isFileReferencePath(path) {