@nestm/storage 0.1.0-alpha.10 → 0.1.0-alpha.11

package/dist/bytes/index.js

@@ -0,0 +1,96 @@
+/** Browser-safe bounded byte helpers. No Node, framework, provider or AI imports. */
+export async function sha256StorageBytes(bytes, options) {
+    budget(options.maxBytes);
+    options.signal?.throwIfAborted();
+    if (bytes.byteLength > options.maxBytes)
+        throw new RangeError('Chunk exceeds the byte budget.');
+    const hash = await crypto.subtle.digest('SHA-256', bytes.slice());
+    options.signal?.throwIfAborted();
+    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Defers only a valid incomplete suffix (at most 3 bytes), never malformed data. */
+export function trimStorageUtf8Chunk(bytes, options) {
+    let end = bytes.byteLength;
+    if (!options.final && end > 0) {
+        let start = end - 1;
+        while (start >= 0 && (bytes[start] & 0xc0) === 0x80)
+            start--;
+        if (start >= 0) {
+            const lead = bytes[start];
+            const width = lead >= 0xc2 && lead <= 0xdf
+                ? 2
+                : lead >= 0xe0 && lead <= 0xef
+                    ? 3
+                    : lead >= 0xf0 && lead <= 0xf4
+                        ? 4
+                        : 1;
+            if (end - start < width) {
+                new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes, { stream: true });
+                end = start;
+            }
+        }
+    }
+    const result = bytes.subarray(0, end);
+    new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(result);
+    return result;
+}
+export function encodeStorageBase64(bytes, options) {
+    budget(options.maxBytes);
+    if (bytes.byteLength > options.maxBytes)
+        throw new RangeError('Chunk exceeds the byte budget.');
+    let text = '';
+    for (let offset = 0; offset < bytes.byteLength; offset += 8192)
+        text += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+    return btoa(text);
+}
+/** Verify receipt bounds, ordering and actual local bytes before skipping a chunk. */
+export async function verifyStorageChunkReceipt(blob, receipt, options) {
+    budget(options.maxBytes);
+    options.signal?.throwIfAborted();
+    if (!Number.isSafeInteger(options.offset) ||
+        options.offset < 0 ||
+        receipt.offset !== options.offset ||
+        !Number.isSafeInteger(receipt.size) ||
+        receipt.size < 1 ||
+        receipt.size > options.maxBytes ||
+        !Number.isSafeInteger(receipt.offset + receipt.size) ||
+        receipt.offset + receipt.size > blob.size ||
+        !/^[0-9a-f]{64}$/u.test(receipt.sha256))
+        throw new TypeError('Invalid or out-of-order chunk receipt.');
+    const bytes = new Uint8Array(await blob
+        .slice(receipt.offset, receipt.offset + receipt.size)
+        .arrayBuffer());
+    if ((await sha256StorageBytes(bytes, options)) !== receipt.sha256)
+        throw new Error('The selected bytes differ from the accepted chunk.');
+    return receipt.offset + receipt.size;
+}
+/** Bounded UTF-8 validation; filename/MIME classification remains host policy. */
+export async function isStorageUtf8Blob(blob, options) {
+    budget(options.chunkBytes);
+    const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+    try {
+        options.signal?.throwIfAborted();
+        for (let offset = 0; offset < blob.size; offset += options.chunkBytes) {
+            options.signal?.throwIfAborted();
+            const bytes = await blob
+                .slice(offset, offset + options.chunkBytes)
+                .arrayBuffer();
+            options.signal?.throwIfAborted();
+            const text = decoder.decode(bytes, { stream: true });
+            if (options.rejectNul && text.includes('\0'))
+                return false;
+        }
+        decoder.decode();
+        return true;
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+        return false;
+    }
+}
+function budget(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError('Byte budget must be a positive safe integer.');
+}
+//# sourceMappingURL=index.js.map

package/dist/bytes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bytes/index.ts"],"names":[],"mappings":"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","sourcesContent":["/** Browser-safe bounded byte helpers. No Node, framework, provider or AI imports. */\nexport async function sha256StorageBytes(\n  bytes: Uint8Array,\n  options: {\n    readonly maxBytes: number;\n    readonly signal?: AbortSignal | undefined;\n  },\n): Promise<string> {\n  budget(options.maxBytes);\n  options.signal?.throwIfAborted();\n  if (bytes.byteLength > options.maxBytes)\n    throw new RangeError('Chunk exceeds the byte budget.');\n  const hash = await crypto.subtle.digest('SHA-256', bytes.slice());\n  options.signal?.throwIfAborted();\n  return Array.from(new Uint8Array(hash), (byte) =>\n    byte.toString(16).padStart(2, '0'),\n  ).join('');\n}\n\n/** Defers only a valid incomplete suffix (at most 3 bytes), never malformed data. */\nexport function trimStorageUtf8Chunk(\n  bytes: Uint8Array,\n  options: { readonly final: boolean },\n): Uint8Array {\n  let end = bytes.byteLength;\n  if (!options.final && end > 0) {\n    let start = end - 1;\n    while (start >= 0 && (bytes[start]! & 0xc0) === 0x80) start--;\n    if (start >= 0) {\n      const lead = bytes[start]!;\n      const width =\n        lead >= 0xc2 && lead <= 0xdf\n          ? 2\n          : lead >= 0xe0 && lead <= 0xef\n            ? 3\n            : lead >= 0xf0 && lead <= 0xf4\n              ? 4\n              : 1;\n      if (end - start < width) {\n        new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(\n          bytes,\n          { stream: true },\n        );\n        end = start;\n      }\n    }\n  }\n  const result = bytes.subarray(0, end);\n  new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(result);\n  return result;\n}\n\nexport function encodeStorageBase64(\n  bytes: Uint8Array,\n  options: { readonly maxBytes: number },\n): string {\n  budget(options.maxBytes);\n  if (bytes.byteLength > options.maxBytes)\n    throw new RangeError('Chunk exceeds the byte budget.');\n  let text = '';\n  for (let offset = 0; offset < bytes.byteLength; offset += 8192)\n    text += String.fromCharCode(...bytes.subarray(offset, offset + 8192));\n  return btoa(text);\n}\n\nexport interface StorageChunkIntegrityReceipt {\n  readonly offset: number;\n  readonly size: number;\n  readonly sha256: string;\n}\n/** Verify receipt bounds, ordering and actual local bytes before skipping a chunk. */\nexport async function verifyStorageChunkReceipt(\n  blob: Blob,\n  receipt: StorageChunkIntegrityReceipt,\n  options: {\n    readonly offset: number;\n    readonly maxBytes: number;\n    readonly signal?: AbortSignal | undefined;\n  },\n): Promise<number> {\n  budget(options.maxBytes);\n  options.signal?.throwIfAborted();\n  if (\n    !Number.isSafeInteger(options.offset) ||\n    options.offset < 0 ||\n    receipt.offset !== options.offset ||\n    !Number.isSafeInteger(receipt.size) ||\n    receipt.size < 1 ||\n    receipt.size > options.maxBytes ||\n    !Number.isSafeInteger(receipt.offset + receipt.size) ||\n    receipt.offset + receipt.size > blob.size ||\n    !/^[0-9a-f]{64}$/u.test(receipt.sha256)\n  )\n    throw new TypeError('Invalid or out-of-order chunk receipt.');\n  const bytes = new Uint8Array(\n    await blob\n      .slice(receipt.offset, receipt.offset + receipt.size)\n      .arrayBuffer(),\n  );\n  if ((await sha256StorageBytes(bytes, options)) !== receipt.sha256)\n    throw new Error('The selected bytes differ from the accepted chunk.');\n  return receipt.offset + receipt.size;\n}\n\n/** Bounded UTF-8 validation; filename/MIME classification remains host policy. */\nexport async function isStorageUtf8Blob(\n  blob: Blob,\n  options: {\n    readonly chunkBytes: number;\n    readonly rejectNul?: boolean;\n    readonly signal?: AbortSignal | undefined;\n  },\n): Promise<boolean> {\n  budget(options.chunkBytes);\n  const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });\n  try {\n    options.signal?.throwIfAborted();\n    for (let offset = 0; offset < blob.size; offset += options.chunkBytes) {\n      options.signal?.throwIfAborted();\n      const bytes = await blob\n        .slice(offset, offset + options.chunkBytes)\n        .arrayBuffer();\n      options.signal?.throwIfAborted();\n      const text = decoder.decode(bytes, { stream: true });\n      if (options.rejectNul && text.includes('\\0')) return false;\n    }\n    decoder.decode();\n    return true;\n  } catch (error) {\n    if (options.signal?.aborted) throw error;\n    return false;\n  }\n}\nfunction budget(value: number) {\n  if (!Number.isSafeInteger(value) || value < 1)\n    throw new RangeError('Byte budget must be a positive safe integer.');\n}\n"]}

package/dist/core/index.d.ts

@@ -3,4 +3,7 @@ export type { StorageDriver } from '../storage.driver.js';
 export { StorageError, StorageErrorCode, isStorageError, normalizeStorageError, type StorageErrorOptions, } from '../storage.error.js';
 export { StorageUploadControl, type StorageResumableToken, type StorageUploadStatus, } from '../storage-upload-control.js';
 export type * from '../storage.types.js';
+export { searchStorageText, applyStorageTextEdit, type StorageTextSearchOptions, type StorageTextSearchResult, type StorageTextEdit, } from './storage-text.js';
+export { collectStorageBytes, storageBytesStream, readStorageTextWindow, type StorageTextWindow, type StorageTextWindowOptions, type StorageRangeReader, } from './storage-streams.js';
+export { StorageStagedContentStore, type StorageStagedBody, type StorageStagedContent, type StorageStagedContentStoreOptions, type StorageStagedReadOptions, type StorageStagedWriteOptions, } from './storage-staged-content.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,8BAA8B,CAAC;AACtC,mBAAmB,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,KAAK,iBAAiB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,8BAA8B,CAAC;AACtC,mBAAmB,qBAAqB,CAAC;AACzC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,EACrC,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC"}

package/dist/core/index.js

@@ -1,4 +1,7 @@
 export { DEFAULT_BUFFER_LIMIT, StorageClient, } from '../storage.client.js';
 export { StorageError, StorageErrorCode, isStorageError, normalizeStorageError, } from '../storage.error.js';
 export { StorageUploadControl, } from '../storage-upload-control.js';
+export { searchStorageText, applyStorageTextEdit, } from './storage-text.js';
+export { collectStorageBytes, storageBytesStream, readStorageTextWindow, } from './storage-streams.js';
+export { StorageStagedContentStore, } from './storage-staged-content.js';
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,GAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAGrB,MAAM,8BAA8B,CAAC","sourcesContent":["export {\n  DEFAULT_BUFFER_LIMIT,\n  StorageClient,\n  type StorageFileHandle,\n} from '../storage.client.js';\nexport type { StorageDriver } from '../storage.driver.js';\nexport {\n  StorageError,\n  StorageErrorCode,\n  isStorageError,\n  normalizeStorageError,\n  type StorageErrorOptions,\n} from '../storage.error.js';\nexport {\n  StorageUploadControl,\n  type StorageResumableToken,\n  type StorageUploadStatus,\n} from '../storage-upload-control.js';\nexport type * from '../storage.types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,GAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAGrB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,GAIrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GAItB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,yBAAyB,GAM1B,MAAM,6BAA6B,CAAC","sourcesContent":["export {\n  DEFAULT_BUFFER_LIMIT,\n  StorageClient,\n  type StorageFileHandle,\n} from '../storage.client.js';\nexport type { StorageDriver } from '../storage.driver.js';\nexport {\n  StorageError,\n  StorageErrorCode,\n  isStorageError,\n  normalizeStorageError,\n  type StorageErrorOptions,\n} from '../storage.error.js';\nexport {\n  StorageUploadControl,\n  type StorageResumableToken,\n  type StorageUploadStatus,\n} from '../storage-upload-control.js';\nexport type * from '../storage.types.js';\nexport {\n  searchStorageText,\n  applyStorageTextEdit,\n  type StorageTextSearchOptions,\n  type StorageTextSearchResult,\n  type StorageTextEdit,\n} from './storage-text.js';\nexport {\n  collectStorageBytes,\n  storageBytesStream,\n  readStorageTextWindow,\n  type StorageTextWindow,\n  type StorageTextWindowOptions,\n  type StorageRangeReader,\n} from './storage-streams.js';\nexport {\n  StorageStagedContentStore,\n  type StorageStagedBody,\n  type StorageStagedContent,\n  type StorageStagedContentStoreOptions,\n  type StorageStagedReadOptions,\n  type StorageStagedWriteOptions,\n} from './storage-staged-content.js';\n"]}

package/dist/core/storage-staged-content.d.ts

@@ -0,0 +1,37 @@
+import type { StorageClient } from '../storage.client.js';
+import type { StorageByteRange } from '../storage.types.js';
+export interface StorageStagedBody {
+    readonly payloadId: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly etag: string;
+}
+export interface StorageStagedWriteOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly maxBytes?: number | undefined;
+}
+export interface StorageStagedReadOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly range?: StorageByteRange | undefined;
+}
+export interface StorageStagedContent<Scope> {
+    write(scope: Scope, body: ReadableStream<Uint8Array>, options?: StorageStagedWriteOptions): Promise<StorageStagedBody>;
+    read(scope: Scope, body: StorageStagedBody, options?: StorageStagedReadOptions): Promise<ReadableStream<Uint8Array>>;
+}
+export interface StorageStagedContentStoreOptions<Scope> {
+    readonly client: StorageClient;
+    /** Trusted, injective scope mapping; never accept this function from a model. */
+    readonly key: (scope: Scope, payloadId: string) => string;
+}
+/** Immutable create-only bodies. Retention eligibility and references remain host-owned. */
+export declare class StorageStagedContentStore<Scope> implements StorageStagedContent<Scope> {
+    #private;
+    constructor(options: StorageStagedContentStoreOptions<Scope>);
+    write(scope: Scope, body: ReadableStream<Uint8Array>, options?: StorageStagedWriteOptions): Promise<StorageStagedBody>;
+    read(scope: Scope, body: StorageStagedBody, options?: StorageStagedReadOptions): Promise<ReadableStream<Uint8Array>>;
+    /** Host must prove no durable/in-flight reference can be created before removal. */
+    remove(scope: Scope, body: StorageStagedBody, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+//# sourceMappingURL=storage-staged-content.d.ts.map

package/dist/core/storage-staged-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-staged-content.d.ts","sourceRoot":"","sources":["../../src/core/storage-staged-content.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AACD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AACD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC/C;AACD,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,KAAK,CACH,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,IAAI,CACF,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;CACxC;AACD,MAAM,WAAW,gCAAgC,CAAC,KAAK;IACrD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3D;AAED,4FAA4F;AAC5F,qBAAa,yBAAyB,CACpC,KAAK,CACL,YAAW,oBAAoB,CAAC,KAAK,CAAC;;IAGtC,YAAY,OAAO,EAAE,gCAAgC,CAAC,KAAK,CAAC,EAG3D;IACK,KAAK,CACT,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAgE5B;IACK,IAAI,CACR,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAgBrC;IACD,oFAAoF;IAC9E,MAAM,CACV,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAC9C,OAAO,CAAC,IAAI,CAAC,CAMf;CACF"}

package/dist/core/storage-staged-content.js

@@ -0,0 +1,94 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { StorageError } from '../storage.error.js';
+import { storageInteger } from './storage-streams.js';
+/** Immutable create-only bodies. Retention eligibility and references remain host-owned. */
+export class StorageStagedContentStore {
+    #client;
+    #key;
+    constructor(options) {
+        this.#client = options.client;
+        this.#key = options.key;
+    }
+    async write(scope, body, options = {}) {
+        const { signal } = options;
+        const maxBytes = options.maxBytes ?? Number.MAX_SAFE_INTEGER;
+        storageInteger(maxBytes, 'maxBytes');
+        const capabilities = this.#client.capabilities;
+        if (!capabilities.conditionalCreate?.resultEtag ||
+            !capabilities.conditionalRead?.etag) {
+            await body.cancel().catch(() => { });
+            throw new StorageError('Staged content requires native create-only writes and exact ETag reads.', { code: 'NOT_SUPPORTED' });
+        }
+        const payloadId = randomUUID();
+        const hash = createHash('sha256');
+        let size = 0;
+        let completed = false;
+        const measured = body.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                signal?.throwIfAborted();
+                size += chunk.byteLength;
+                if (!Number.isSafeInteger(size) || size > maxBytes)
+                    throw new StorageError('Staged body exceeds its byte budget.', {
+                        code: 'LIMIT_EXCEEDED',
+                    });
+                hash.update(chunk);
+                controller.enqueue(chunk);
+            },
+            flush() {
+                completed = true;
+            },
+        }), signal === undefined ? {} : { signal });
+        try {
+            signal?.throwIfAborted();
+            const result = await this.#client.uploadConditional(this.#key(scope, payloadId), measured, {
+                condition: { type: 'create' },
+                contentType: 'application/octet-stream',
+                retries: 0,
+                ...(signal === undefined ? {} : { signal }),
+            });
+            if (!completed || result.size !== size || result.etag === undefined)
+                throw new StorageError('Provider did not acknowledge the complete staged body.', { code: 'PROVIDER', applied: true });
+            return Object.freeze({
+                payloadId,
+                size,
+                sha256: hash.digest('hex'),
+                etag: result.etag,
+            });
+        }
+        catch (error) {
+            await measured.cancel(error).catch(() => { });
+            throw error;
+        }
+    }
+    async read(scope, body, options = {}) {
+        validateBody(body);
+        options.signal?.throwIfAborted();
+        if (options.range !== undefined && !this.#client.capabilities.rangeRead)
+            throw new StorageError('Provider does not support byte ranges.', {
+                code: 'NOT_SUPPORTED',
+            });
+        const result = await this.#client.downloadConditional(this.#key(scope, body.payloadId), {
+            condition: { etag: body.etag },
+            ...(options.range === undefined ? {} : { range: options.range }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+        return result.body;
+    }
+    /** Host must prove no durable/in-flight reference can be created before removal. */
+    async remove(scope, body, options = {}) {
+        validateBody(body);
+        await this.#client.deleteConditional(this.#key(scope, body.payloadId), {
+            condition: { etag: body.etag },
+            ...options,
+        });
+    }
+}
+function validateBody(body) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(body.payloadId) ||
+        !/^[0-9a-f]{64}$/u.test(body.sha256))
+        throw new StorageError('Invalid staged body receipt.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    storageInteger(body.size, 'size');
+}
+//# sourceMappingURL=storage-staged-content.js.map

package/dist/core/storage-staged-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-staged-content.js","sourceRoot":"","sources":["../../src/core/storage-staged-content.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport { StorageError } from '../storage.error.js';\nimport type { StorageClient } from '../storage.client.js';\nimport type { StorageByteRange } from '../storage.types.js';\nimport { storageInteger } from './storage-streams.js';\n\nexport interface StorageStagedBody {\n  readonly payloadId: string;\n  readonly size: number;\n  readonly sha256: string;\n  readonly etag: string;\n}\nexport interface StorageStagedWriteOptions {\n  readonly signal?: AbortSignal | undefined;\n  readonly maxBytes?: number | undefined;\n}\nexport interface StorageStagedReadOptions {\n  readonly signal?: AbortSignal | undefined;\n  readonly range?: StorageByteRange | undefined;\n}\nexport interface StorageStagedContent<Scope> {\n  write(\n    scope: Scope,\n    body: ReadableStream<Uint8Array>,\n    options?: StorageStagedWriteOptions,\n  ): Promise<StorageStagedBody>;\n  read(\n    scope: Scope,\n    body: StorageStagedBody,\n    options?: StorageStagedReadOptions,\n  ): Promise<ReadableStream<Uint8Array>>;\n}\nexport interface StorageStagedContentStoreOptions<Scope> {\n  readonly client: StorageClient;\n  /** Trusted, injective scope mapping; never accept this function from a model. */\n  readonly key: (scope: Scope, payloadId: string) => string;\n}\n\n/** Immutable create-only bodies. Retention eligibility and references remain host-owned. */\nexport class StorageStagedContentStore<\n  Scope,\n> implements StorageStagedContent<Scope> {\n  readonly #client: StorageClient;\n  readonly #key: (scope: Scope, payloadId: string) => string;\n  constructor(options: StorageStagedContentStoreOptions<Scope>) {\n    this.#client = options.client;\n    this.#key = options.key;\n  }\n  async write(\n    scope: Scope,\n    body: ReadableStream<Uint8Array>,\n    options: StorageStagedWriteOptions = {},\n  ): Promise<StorageStagedBody> {\n    const { signal } = options;\n    const maxBytes = options.maxBytes ?? Number.MAX_SAFE_INTEGER;\n    storageInteger(maxBytes, 'maxBytes');\n    const capabilities = this.#client.capabilities;\n    if (\n      !capabilities.conditionalCreate?.resultEtag ||\n      !capabilities.conditionalRead?.etag\n    ) {\n      await body.cancel().catch(() => {});\n      throw new StorageError(\n        'Staged content requires native create-only writes and exact ETag reads.',\n        { code: 'NOT_SUPPORTED' },\n      );\n    }\n    const payloadId = randomUUID();\n    const hash = createHash('sha256');\n    let size = 0;\n    let completed = false;\n    const measured = body.pipeThrough(\n      new TransformStream<Uint8Array, Uint8Array>({\n        transform(chunk, controller) {\n          signal?.throwIfAborted();\n          size += chunk.byteLength;\n          if (!Number.isSafeInteger(size) || size > maxBytes)\n            throw new StorageError('Staged body exceeds its byte budget.', {\n              code: 'LIMIT_EXCEEDED',\n            });\n          hash.update(chunk);\n          controller.enqueue(chunk);\n        },\n        flush() {\n          completed = true;\n        },\n      }),\n      signal === undefined ? {} : { signal },\n    );\n    try {\n      signal?.throwIfAborted();\n      const result = await this.#client.uploadConditional(\n        this.#key(scope, payloadId),\n        measured,\n        {\n          condition: { type: 'create' },\n          contentType: 'application/octet-stream',\n          retries: 0,\n          ...(signal === undefined ? {} : { signal }),\n        },\n      );\n      if (!completed || result.size !== size || result.etag === undefined)\n        throw new StorageError(\n          'Provider did not acknowledge the complete staged body.',\n          { code: 'PROVIDER', applied: true },\n        );\n      return Object.freeze({\n        payloadId,\n        size,\n        sha256: hash.digest('hex'),\n        etag: result.etag,\n      });\n    } catch (error) {\n      await measured.cancel(error).catch(() => {});\n      throw error;\n    }\n  }\n  async read(\n    scope: Scope,\n    body: StorageStagedBody,\n    options: StorageStagedReadOptions = {},\n  ): Promise<ReadableStream<Uint8Array>> {\n    validateBody(body);\n    options.signal?.throwIfAborted();\n    if (options.range !== undefined && !this.#client.capabilities.rangeRead)\n      throw new StorageError('Provider does not support byte ranges.', {\n        code: 'NOT_SUPPORTED',\n      });\n    const result = await this.#client.downloadConditional(\n      this.#key(scope, body.payloadId),\n      {\n        condition: { etag: body.etag },\n        ...(options.range === undefined ? {} : { range: options.range }),\n        ...(options.signal === undefined ? {} : { signal: options.signal }),\n      },\n    );\n    return result.body;\n  }\n  /** Host must prove no durable/in-flight reference can be created before removal. */\n  async remove(\n    scope: Scope,\n    body: StorageStagedBody,\n    options: { readonly signal?: AbortSignal } = {},\n  ): Promise<void> {\n    validateBody(body);\n    await this.#client.deleteConditional(this.#key(scope, body.payloadId), {\n      condition: { etag: body.etag },\n      ...options,\n    });\n  }\n}\nfunction validateBody(body: StorageStagedBody): void {\n  if (\n    !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(\n      body.payloadId,\n    ) ||\n    !/^[0-9a-f]{64}$/u.test(body.sha256)\n  )\n    throw new StorageError('Invalid staged body receipt.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  storageInteger(body.size, 'size');\n}\n"]}

package/dist/core/storage-streams.d.ts

@@ -0,0 +1,19 @@
+import type { StorageByteRange } from '../storage.types.js';
+export declare function storageBytesStream(bytes: Uint8Array): ReadableStream<Uint8Array>;
+/** Explicitly buffers no more than maxBytes and cancels the source on failure/abort. */
+export declare function collectStorageBytes(stream: ReadableStream<Uint8Array>, maxBytes: number, signal?: AbortSignal): Promise<Uint8Array>;
+export interface StorageTextWindow {
+    readonly content: string | null;
+    readonly offset: number;
+    readonly nextOffset: number | null;
+}
+export interface StorageTextWindowOptions {
+    readonly size: number;
+    readonly offset?: number | undefined;
+    readonly maxBytes: number;
+    readonly signal?: AbortSignal | undefined;
+}
+export type StorageRangeReader = (range: Required<StorageByteRange>, signal?: AbortSignal) => Promise<ReadableStream<Uint8Array>>;
+/** Byte offsets; inclusive provider ranges. Never trims malformed UTF-8 at EOF. */
+export declare function readStorageTextWindow(read: StorageRangeReader, options: StorageTextWindowOptions): Promise<StorageTextWindow>;
+//# sourceMappingURL=storage-streams.d.ts.map

package/dist/core/storage-streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-streams.d.ts","sourceRoot":"","sources":["../../src/core/storage-streams.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,GAChB,cAAc,CAAC,UAAU,CAAC,CAO5B;AAED,wFAAwF;AACxF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AACD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AACD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EACjC,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;AAEzC,mFAAmF;AACnF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,iBAAiB,CAAC,CA0C5B"}

package/dist/core/storage-streams.js

@@ -0,0 +1,95 @@
+import { StorageError } from '../storage.error.js';
+import { trimStorageUtf8Chunk } from '../bytes/index.js';
+export function storageBytesStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+/** Explicitly buffers no more than maxBytes and cancels the source on failure/abort. */
+export async function collectStorageBytes(stream, maxBytes, signal) {
+    storageInteger(maxBytes, 'maxBytes');
+    const reader = stream.getReader();
+    const abort = () => {
+        void reader.cancel(signal?.reason).catch(() => { });
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+    const chunks = [];
+    let size = 0;
+    try {
+        signal?.throwIfAborted();
+        for (;;) {
+            const next = await reader.read();
+            signal?.throwIfAborted();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (!Number.isSafeInteger(size) || size > maxBytes)
+                throw new StorageError('The stream exceeds its byte budget.', {
+                    code: 'LIMIT_EXCEEDED',
+                });
+            chunks.push(next.value.slice());
+        }
+        const result = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return result;
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Byte offsets; inclusive provider ranges. Never trims malformed UTF-8 at EOF. */
+export async function readStorageTextWindow(read, options) {
+    const { size, maxBytes, signal } = options;
+    const offset = options.offset ?? 0;
+    storageInteger(size, 'size');
+    storageInteger(offset, 'offset');
+    storageInteger(maxBytes, 'maxBytes', 4);
+    if (offset > size)
+        throw new StorageError('Offset exceeds the body size.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    signal?.throwIfAborted();
+    if (offset === size)
+        return { content: '', offset, nextOffset: null };
+    const length = Math.min(maxBytes, size - offset);
+    const bytes = await collectStorageBytes(await read({ start: offset, end: offset + length - 1 }, signal), length, signal);
+    if (bytes.byteLength !== length)
+        throw new StorageError('The range response is incomplete.', {
+            code: 'PROVIDER',
+        });
+    try {
+        const complete = trimStorageUtf8Chunk(bytes, {
+            final: offset + length === size,
+        });
+        const end = complete.byteLength;
+        const content = new TextDecoder('utf-8', {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(complete);
+        return {
+            content,
+            offset,
+            nextOffset: offset + end < size ? offset + end : null,
+        };
+    }
+    catch {
+        throw new StorageError('The window is not valid UTF-8 or its offset splits a character.', { code: 'INVALID_ARGUMENT' });
+    }
+}
+/** @internal */
+export function storageInteger(value, name, minimum = 0) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new StorageError(`${name} must be a safe integer >= ${minimum}.`, {
+            code: 'INVALID_ARGUMENT',
+        });
+}
+//# sourceMappingURL=storage-streams.js.map

package/dist/core/storage-streams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-streams.js","sourceRoot":"","sources":["../../src/core/storage-streams.ts"],"names":[],"mappings":"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","sourcesContent":["import { StorageError } from '../storage.error.js';\nimport type { StorageByteRange } from '../storage.types.js';\nimport { trimStorageUtf8Chunk } from '../bytes/index.js';\n\nexport function storageBytesStream(\n  bytes: Uint8Array,\n): ReadableStream<Uint8Array> {\n  return new ReadableStream({\n    start(controller) {\n      controller.enqueue(bytes);\n      controller.close();\n    },\n  });\n}\n\n/** Explicitly buffers no more than maxBytes and cancels the source on failure/abort. */\nexport async function collectStorageBytes(\n  stream: ReadableStream<Uint8Array>,\n  maxBytes: number,\n  signal?: AbortSignal,\n): Promise<Uint8Array> {\n  storageInteger(maxBytes, 'maxBytes');\n  const reader = stream.getReader();\n  const abort = () => {\n    void reader.cancel(signal?.reason).catch(() => {});\n  };\n  signal?.addEventListener('abort', abort, { once: true });\n  const chunks: Uint8Array[] = [];\n  let size = 0;\n  try {\n    signal?.throwIfAborted();\n    for (;;) {\n      const next = await reader.read();\n      signal?.throwIfAborted();\n      if (next.done) break;\n      size += next.value.byteLength;\n      if (!Number.isSafeInteger(size) || size > maxBytes)\n        throw new StorageError('The stream exceeds its byte budget.', {\n          code: 'LIMIT_EXCEEDED',\n        });\n      chunks.push(next.value.slice());\n    }\n    const result = new Uint8Array(size);\n    let offset = 0;\n    for (const chunk of chunks) {\n      result.set(chunk, offset);\n      offset += chunk.byteLength;\n    }\n    return result;\n  } finally {\n    signal?.removeEventListener('abort', abort);\n    await reader.cancel().catch(() => {});\n    reader.releaseLock();\n  }\n}\n\nexport interface StorageTextWindow {\n  readonly content: string | null;\n  readonly offset: number;\n  readonly nextOffset: number | null;\n}\nexport interface StorageTextWindowOptions {\n  readonly size: number;\n  readonly offset?: number | undefined;\n  readonly maxBytes: number;\n  readonly signal?: AbortSignal | undefined;\n}\nexport type StorageRangeReader = (\n  range: Required<StorageByteRange>,\n  signal?: AbortSignal,\n) => Promise<ReadableStream<Uint8Array>>;\n\n/** Byte offsets; inclusive provider ranges. Never trims malformed UTF-8 at EOF. */\nexport async function readStorageTextWindow(\n  read: StorageRangeReader,\n  options: StorageTextWindowOptions,\n): Promise<StorageTextWindow> {\n  const { size, maxBytes, signal } = options;\n  const offset = options.offset ?? 0;\n  storageInteger(size, 'size');\n  storageInteger(offset, 'offset');\n  storageInteger(maxBytes, 'maxBytes', 4);\n  if (offset > size)\n    throw new StorageError('Offset exceeds the body size.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  signal?.throwIfAborted();\n  if (offset === size) return { content: '', offset, nextOffset: null };\n  const length = Math.min(maxBytes, size - offset);\n  const bytes = await collectStorageBytes(\n    await read({ start: offset, end: offset + length - 1 }, signal),\n    length,\n    signal,\n  );\n  if (bytes.byteLength !== length)\n    throw new StorageError('The range response is incomplete.', {\n      code: 'PROVIDER',\n    });\n  try {\n    const complete = trimStorageUtf8Chunk(bytes, {\n      final: offset + length === size,\n    });\n    const end = complete.byteLength;\n    const content = new TextDecoder('utf-8', {\n      fatal: true,\n      ignoreBOM: true,\n    }).decode(complete);\n    return {\n      content,\n      offset,\n      nextOffset: offset + end < size ? offset + end : null,\n    };\n  } catch {\n    throw new StorageError(\n      'The window is not valid UTF-8 or its offset splits a character.',\n      { code: 'INVALID_ARGUMENT' },\n    );\n  }\n}\n\n/** @internal */\nexport function storageInteger(value: number, name: string, minimum = 0): void {\n  if (!Number.isSafeInteger(value) || value < minimum)\n    throw new StorageError(`${name} must be a safe integer >= ${minimum}.`, {\n      code: 'INVALID_ARGUMENT',\n    });\n}\n"]}

package/dist/core/storage-text.d.ts

@@ -0,0 +1,33 @@
+import { type StorageRangeReader } from './storage-streams.js';
+export interface StorageTextSearchOptions {
+    readonly size: number;
+    readonly query: string;
+    readonly offset?: number | undefined;
+    readonly maxScanBytes: number;
+    readonly maxMatches: number;
+    readonly maxSnippetCharacters: number;
+    readonly maxReadBytes: number;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface StorageTextSearchResult {
+    readonly matches: readonly {
+        readonly offset: number;
+        readonly text: string;
+    }[];
+    readonly nextOffset: number | null;
+}
+/** Literal, non-overlapping matches. Continuations retain cross-window candidates. */
+export declare function searchStorageText(read: StorageRangeReader, options: StorageTextSearchOptions): Promise<StorageTextSearchResult>;
+export type StorageTextEdit = {
+    readonly kind: 'append';
+    readonly text: string;
+} | {
+    readonly kind: 'replace';
+    readonly oldText: string;
+    readonly newText: string;
+};
+/** Whole-text operation; callers must also bound the original buffered read. */
+export declare function applyStorageTextEdit(content: string, change: StorageTextEdit, options: {
+    readonly maxBytes: number;
+}): string;
+//# sourceMappingURL=storage-text.d.ts.map

package/dist/core/storage-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-text.d.ts","sourceRoot":"","sources":["../../src/core/storage-text.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AACD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,EAAE,CAAC;IACJ,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAoElC;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrC,MAAM,CAiCR"}

package/dist/core/storage-text.js

@@ -0,0 +1,98 @@
+import { StorageError } from '../storage.error.js';
+import { readStorageTextWindow, storageInteger, } from './storage-streams.js';
+/** Literal, non-overlapping matches. Continuations retain cross-window candidates. */
+export async function searchStorageText(read, options) {
+    const { query, size, signal } = options;
+    const encode = (text) => new TextEncoder().encode(text).byteLength;
+    if (query.length === 0 ||
+        query.length > 256 ||
+        /[\uD800-\uDFFF]/u.test(query))
+        throw new StorageError('Query must contain 1–256 well-formed characters.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    storageInteger(size, 'size');
+    storageInteger(options.maxReadBytes, 'maxReadBytes', 4);
+    storageInteger(options.maxScanBytes, 'maxScanBytes', encode(query) + 4);
+    storageInteger(options.maxMatches, 'maxMatches', 1);
+    storageInteger(options.maxSnippetCharacters, 'maxSnippetCharacters', 1);
+    let cursor = options.offset ?? 0;
+    storageInteger(cursor, 'offset');
+    if (cursor > size)
+        throw new StorageError('Offset exceeds body size.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    let pending = '';
+    let pendingOffset = cursor;
+    let scanned = 0;
+    const matches = [];
+    signal?.throwIfAborted();
+    while (cursor < size && options.maxScanBytes - scanned >= 4) {
+        const maxBytes = Math.min(options.maxReadBytes, options.maxScanBytes - scanned);
+        const page = await readStorageTextWindow(read, {
+            size,
+            offset: cursor,
+            maxBytes,
+            signal,
+        });
+        scanned += Math.min(maxBytes, size - cursor);
+        const text = pending + page.content;
+        const safeEnd = page.nextOffset === null
+            ? text.length
+            : Math.max(0, text.length - query.length + 1);
+        let at = 0;
+        for (;;) {
+            const found = text.indexOf(query, at);
+            if (found < 0 || found >= safeEnd)
+                break;
+            matches.push({
+                offset: pendingOffset + encode(text.slice(0, found)),
+                text: Array.from(text.slice(found))
+                    .slice(0, options.maxSnippetCharacters)
+                    .join(''),
+            });
+            at = found + query.length;
+            if (matches.length === options.maxMatches) {
+                const next = pendingOffset + encode(text.slice(0, at));
+                return { matches, nextOffset: next < size ? next : null };
+            }
+        }
+        let consumed = Math.max(at, safeEnd);
+        if (consumed > 0 && /[\uDC00-\uDFFF]/u.test(text.charAt(consumed)))
+            consumed--;
+        pendingOffset += encode(text.slice(0, consumed));
+        pending = text.slice(consumed);
+        cursor = page.nextOffset ?? size;
+    }
+    return { matches, nextOffset: cursor < size ? pendingOffset : null };
+}
+/** Whole-text operation; callers must also bound the original buffered read. */
+export function applyStorageTextEdit(content, change, options) {
+    storageInteger(options.maxBytes, 'maxBytes');
+    const strings = change.kind === 'append'
+        ? [content, change.text]
+        : [content, change.oldText, change.newText];
+    if (strings.some((value) => /[\uD800-\uDFFF]/u.test(value)))
+        throw new StorageError('Text must be well-formed UTF-8.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    let result;
+    if (change.kind === 'append')
+        result = content + change.text;
+    else {
+        const first = content.indexOf(change.oldText);
+        if (change.oldText.length === 0 ||
+            first < 0 ||
+            content.indexOf(change.oldText, first + 1) >= 0)
+            throw new StorageError('The replacement target must match exactly once.', { code: 'CONFLICT' });
+        result =
+            content.slice(0, first) +
+                change.newText +
+                content.slice(first + change.oldText.length);
+    }
+    if (new TextEncoder().encode(result).byteLength > options.maxBytes)
+        throw new StorageError('Edited content exceeds the byte budget.', {
+            code: 'LIMIT_EXCEEDED',
+        });
+    return result;
+}
+//# sourceMappingURL=storage-text.js.map

package/dist/core/storage-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-text.js","sourceRoot":"","sources":["../../src/core/storage-text.ts"],"names":[],"mappings":"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","sourcesContent":["import { StorageError } from '../storage.error.js';\nimport {\n  readStorageTextWindow,\n  storageInteger,\n  type StorageRangeReader,\n} from './storage-streams.js';\n\nexport interface StorageTextSearchOptions {\n  readonly size: number;\n  readonly query: string;\n  readonly offset?: number | undefined;\n  readonly maxScanBytes: number;\n  readonly maxMatches: number;\n  readonly maxSnippetCharacters: number;\n  readonly maxReadBytes: number;\n  readonly signal?: AbortSignal | undefined;\n}\nexport interface StorageTextSearchResult {\n  readonly matches: readonly {\n    readonly offset: number;\n    readonly text: string;\n  }[];\n  readonly nextOffset: number | null;\n}\n\n/** Literal, non-overlapping matches. Continuations retain cross-window candidates. */\nexport async function searchStorageText(\n  read: StorageRangeReader,\n  options: StorageTextSearchOptions,\n): Promise<StorageTextSearchResult> {\n  const { query, size, signal } = options;\n  const encode = (text: string) => new TextEncoder().encode(text).byteLength;\n  if (\n    query.length === 0 ||\n    query.length > 256 ||\n    /[\\uD800-\\uDFFF]/u.test(query)\n  )\n    throw new StorageError('Query must contain 1–256 well-formed characters.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  storageInteger(size, 'size');\n  storageInteger(options.maxReadBytes, 'maxReadBytes', 4);\n  storageInteger(options.maxScanBytes, 'maxScanBytes', encode(query) + 4);\n  storageInteger(options.maxMatches, 'maxMatches', 1);\n  storageInteger(options.maxSnippetCharacters, 'maxSnippetCharacters', 1);\n  let cursor = options.offset ?? 0;\n  storageInteger(cursor, 'offset');\n  if (cursor > size)\n    throw new StorageError('Offset exceeds body size.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  let pending = '';\n  let pendingOffset = cursor;\n  let scanned = 0;\n  const matches: { offset: number; text: string }[] = [];\n  signal?.throwIfAborted();\n  while (cursor < size && options.maxScanBytes - scanned >= 4) {\n    const maxBytes = Math.min(\n      options.maxReadBytes,\n      options.maxScanBytes - scanned,\n    );\n    const page = await readStorageTextWindow(read, {\n      size,\n      offset: cursor,\n      maxBytes,\n      signal,\n    });\n    scanned += Math.min(maxBytes, size - cursor);\n    const text = pending + page.content;\n    const safeEnd =\n      page.nextOffset === null\n        ? text.length\n        : Math.max(0, text.length - query.length + 1);\n    let at = 0;\n    for (;;) {\n      const found = text.indexOf(query, at);\n      if (found < 0 || found >= safeEnd) break;\n      matches.push({\n        offset: pendingOffset + encode(text.slice(0, found)),\n        text: Array.from(text.slice(found))\n          .slice(0, options.maxSnippetCharacters)\n          .join(''),\n      });\n      at = found + query.length;\n      if (matches.length === options.maxMatches) {\n        const next = pendingOffset + encode(text.slice(0, at));\n        return { matches, nextOffset: next < size ? next : null };\n      }\n    }\n    let consumed = Math.max(at, safeEnd);\n    if (consumed > 0 && /[\\uDC00-\\uDFFF]/u.test(text.charAt(consumed)))\n      consumed--;\n    pendingOffset += encode(text.slice(0, consumed));\n    pending = text.slice(consumed);\n    cursor = page.nextOffset ?? size;\n  }\n  return { matches, nextOffset: cursor < size ? pendingOffset : null };\n}\n\nexport type StorageTextEdit =\n  | { readonly kind: 'append'; readonly text: string }\n  | {\n      readonly kind: 'replace';\n      readonly oldText: string;\n      readonly newText: string;\n    };\n\n/** Whole-text operation; callers must also bound the original buffered read. */\nexport function applyStorageTextEdit(\n  content: string,\n  change: StorageTextEdit,\n  options: { readonly maxBytes: number },\n): string {\n  storageInteger(options.maxBytes, 'maxBytes');\n  const strings =\n    change.kind === 'append'\n      ? [content, change.text]\n      : [content, change.oldText, change.newText];\n  if (strings.some((value) => /[\\uD800-\\uDFFF]/u.test(value)))\n    throw new StorageError('Text must be well-formed UTF-8.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  let result: string;\n  if (change.kind === 'append') result = content + change.text;\n  else {\n    const first = content.indexOf(change.oldText);\n    if (\n      change.oldText.length === 0 ||\n      first < 0 ||\n      content.indexOf(change.oldText, first + 1) >= 0\n    )\n      throw new StorageError(\n        'The replacement target must match exactly once.',\n        { code: 'CONFLICT' },\n      );\n    result =\n      content.slice(0, first) +\n      change.newText +\n      content.slice(first + change.oldText.length);\n  }\n  if (new TextEncoder().encode(result).byteLength > options.maxBytes)\n    throw new StorageError('Edited content exceeds the byte budget.', {\n      code: 'LIMIT_EXCEEDED',\n    });\n  return result;\n}\n"]}

package/dist/files-sdk/memory.d.ts

@@ -0,0 +1,7 @@
+import { type MemoryAdapter } from 'files-sdk/memory';
+/**
+ * Reuses files-sdk buffering/metadata; comparisons and Map replacement share a
+ * synchronous linearization point AFTER body consumption. raw stays host-only.
+ */
+export declare function withMemoryConditionalOperations(adapter: MemoryAdapter): MemoryAdapter;
+//# sourceMappingURL=memory.d.ts.map

package/dist/files-sdk/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/files-sdk/memory.ts"],"names":[],"mappings":"AAOA,OAAO,EAAU,KAAK,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAKhF;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,aAAa,GACrB,aAAa,CAkFf"}