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

package/dist/workspace/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workspace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,oCAAoC,EACpC,gCAAgC,EAChC,kCAAkC,GAKnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAuB9B,MAAM,8BAA8B,CAAC","sourcesContent":["export {\n  StorageWorkspaceError,\n  isStorageWorkspaceError,\n} from './storage-workspace.error.js';\nexport {\n  Aes256GcmStorageWorkspaceCursorCodec,\n  STORAGE_WORKSPACE_CURSOR_VERSION,\n  STORAGE_WORKSPACE_MAX_CURSOR_BYTES,\n  type Aes256GcmStorageWorkspaceCursorCodecOptions,\n  type StorageWorkspaceCursorCodec,\n  type StorageWorkspaceCursorConfiguration,\n  type StorageWorkspaceCursorEncodeOptions,\n} from './storage-workspace.cursor.js';\nexport {\n  createStorageWorkspace,\n  mountStorageWorkspace,\n} from './storage-workspace.js';\nexport {\n  DEFAULT_STORAGE_WORKSPACE_LIMITS,\n  STORAGE_WORKSPACE_PERMISSIONS,\n  type MountStorageWorkspaceOptions,\n  type StorageWorkspaceBody,\n  type StorageWorkspaceByteFile,\n  type StorageWorkspaceCopyOptions,\n  type StorageWorkspaceDeleteOptions,\n  type StorageWorkspace,\n  type StorageWorkspaceDirectory,\n  type StorageWorkspaceEntry,\n  type StorageWorkspaceFile,\n  type StorageWorkspaceLimits,\n  type StorageWorkspaceListOptions,\n  type StorageWorkspaceMountOptions,\n  type StorageWorkspaceMutationOptions,\n  type StorageWorkspaceOverwriteOptions,\n  type StorageWorkspacePage,\n  type StorageWorkspacePermission,\n  type StorageWorkspaceReadOptions,\n  type StorageWorkspaceSearchMatch,\n  type StorageWorkspaceSearchOptions,\n  type StorageWorkspaceTextFile,\n  type StorageWorkspaceUnconditionalDeleteOptions,\n  type StorageWorkspaceWriteOptions,\n} from './storage-workspace.types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workspace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,oCAAoC,EAAE,MAAM,kCAAkC,CAAC;AAGxF,OAAO,EACL,mCAAmC,EACnC,mCAAmC,EACnC,sBAAsB,EACtB,qBAAqB,GAItB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,oCAAoC,EACpC,gCAAgC,EAChC,kCAAkC,GAKnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAuB9B,MAAM,8BAA8B,CAAC","sourcesContent":["export {\n  StorageWorkspaceError,\n  isStorageWorkspaceError,\n} from './storage-workspace.error.js';\nexport { StorageFileWorkflow } from './storage-file-workflow.js';\nexport { DEFAULT_STORAGE_FILE_WORKFLOW_LIMITS } from './storage-file-workflow.types.js';\nexport type * from './storage-file-workflow.types.js';\nexport type * from './storage-file-catalog.types.js';\nexport {\n  protectStorageFileWorkflowWorkspace,\n  protectStorageFileWorkflowOperation,\n  getStorageFileWorkflow,\n  getStorageFileCatalog,\n  type StorageFileWorkflowProtection,\n  type StorageFileWorkflowWorkspace,\n  type ProtectStorageFileWorkflowWorkspaceOptions,\n} from './storage-file-workflow.protection.js';\nexport {\n  Aes256GcmStorageWorkspaceCursorCodec,\n  STORAGE_WORKSPACE_CURSOR_VERSION,\n  STORAGE_WORKSPACE_MAX_CURSOR_BYTES,\n  type Aes256GcmStorageWorkspaceCursorCodecOptions,\n  type StorageWorkspaceCursorCodec,\n  type StorageWorkspaceCursorConfiguration,\n  type StorageWorkspaceCursorEncodeOptions,\n} from './storage-workspace.cursor.js';\nexport {\n  createStorageWorkspace,\n  mountStorageWorkspace,\n} from './storage-workspace.js';\nexport {\n  DEFAULT_STORAGE_WORKSPACE_LIMITS,\n  STORAGE_WORKSPACE_PERMISSIONS,\n  type MountStorageWorkspaceOptions,\n  type StorageWorkspaceBody,\n  type StorageWorkspaceByteFile,\n  type StorageWorkspaceCopyOptions,\n  type StorageWorkspaceDeleteOptions,\n  type StorageWorkspace,\n  type StorageWorkspaceDirectory,\n  type StorageWorkspaceEntry,\n  type StorageWorkspaceFile,\n  type StorageWorkspaceLimits,\n  type StorageWorkspaceListOptions,\n  type StorageWorkspaceMountOptions,\n  type StorageWorkspaceMutationOptions,\n  type StorageWorkspaceOverwriteOptions,\n  type StorageWorkspacePage,\n  type StorageWorkspacePermission,\n  type StorageWorkspaceReadOptions,\n  type StorageWorkspaceSearchMatch,\n  type StorageWorkspaceSearchOptions,\n  type StorageWorkspaceTextFile,\n  type StorageWorkspaceUnconditionalDeleteOptions,\n  type StorageWorkspaceWriteOptions,\n} from './storage-workspace.types.js';\n"]}

package/dist/workspace/storage-file-catalog.types.d.ts

@@ -0,0 +1,65 @@
+import type { StorageTextEdit, StorageTextSearchResult } from '../core/storage-text.js';
+import type { StorageTextWindow } from '../core/storage-streams.js';
+import type { StorageFileWorkflowOperation, StorageFileWorkflowPage } from './storage-file-workflow.types.js';
+export interface StorageCatalogFile {
+    readonly path: string;
+    readonly fileId: string;
+    readonly etag: string;
+    readonly size: number;
+    readonly contentType: string;
+}
+export interface StorageFileCatalogLimits {
+    readonly maxReadBytes: number;
+    readonly maxWriteBytes: number;
+    readonly maxPageSize: number;
+    readonly maxSearchScanBytes: number;
+    readonly maxSearchMatches: number;
+    readonly maxPathBytes: number;
+}
+export interface StorageCatalogPath extends StorageFileWorkflowOperation {
+    readonly path: string;
+    readonly expectedEtag?: string | undefined;
+}
+export interface StorageCatalogPage extends StorageFileWorkflowOperation {
+    readonly offset?: number | undefined;
+}
+export interface StorageCatalogCommand extends StorageCatalogPath {
+    /** Opaque host-scoped command identity, stable across response-loss retries. */
+    readonly commandId: string;
+}
+/** Host catalog port. Implementations own persistence, conditional heads and replay. */
+export interface StorageFileCatalogCapability<Receipt = unknown> {
+    readonly kind: 'storage-file-catalog';
+    readonly version: 1;
+    readonly limits: StorageFileCatalogLimits;
+    allows(permission: 'read' | 'write'): boolean;
+    list(input: StorageCatalogPage & {
+        readonly directory?: string | undefined;
+    }): Promise<StorageFileWorkflowPage<StorageCatalogFile>>;
+    stat(input: StorageCatalogPath): Promise<StorageCatalogFile>;
+    search(input: StorageCatalogPage & {
+        readonly query: string;
+    }): Promise<StorageFileWorkflowPage<StorageCatalogFile>>;
+    readWindow(input: StorageCatalogPath & StorageCatalogPage): Promise<StorageTextWindow & {
+        readonly path: string;
+        readonly fileId: string;
+        readonly etag: string;
+        readonly size: number;
+        readonly totalBytes: number;
+    }>;
+    searchContent(input: StorageCatalogPath & StorageCatalogPage & {
+        readonly expectedEtag: string;
+        readonly query: string;
+    }): Promise<StorageTextSearchResult & {
+        readonly path: string;
+        readonly etag: string;
+    }>;
+    write(input: StorageCatalogCommand & {
+        readonly content: string;
+    }): Promise<Receipt>;
+    edit(input: StorageCatalogCommand & {
+        readonly expectedEtag: string;
+        readonly change: StorageTextEdit;
+    }): Promise<Receipt>;
+}
+//# sourceMappingURL=storage-file-catalog.types.d.ts.map

package/dist/workspace/storage-file-catalog.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-file-catalog.types.d.ts","sourceRoot":"","sources":["../../src/workspace/storage-file-catalog.types.ts"],"names":[],"mappings":"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"}

package/dist/workspace/storage-file-catalog.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage-file-catalog.types.js.map

package/dist/workspace/storage-file-catalog.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-file-catalog.types.js","sourceRoot":"","sources":["../../src/workspace/storage-file-catalog.types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  StorageTextEdit,\n  StorageTextSearchResult,\n} from '../core/storage-text.js';\nimport type { StorageTextWindow } from '../core/storage-streams.js';\nimport type {\n  StorageFileWorkflowOperation,\n  StorageFileWorkflowPage,\n} from './storage-file-workflow.types.js';\n\nexport interface StorageCatalogFile {\n  readonly path: string;\n  readonly fileId: string;\n  readonly etag: string;\n  readonly size: number;\n  readonly contentType: string;\n}\nexport interface StorageFileCatalogLimits {\n  readonly maxReadBytes: number;\n  readonly maxWriteBytes: number;\n  readonly maxPageSize: number;\n  readonly maxSearchScanBytes: number;\n  readonly maxSearchMatches: number;\n  readonly maxPathBytes: number;\n}\nexport interface StorageCatalogPath extends StorageFileWorkflowOperation {\n  readonly path: string;\n  readonly expectedEtag?: string | undefined;\n}\nexport interface StorageCatalogPage extends StorageFileWorkflowOperation {\n  readonly offset?: number | undefined;\n}\nexport interface StorageCatalogCommand extends StorageCatalogPath {\n  /** Opaque host-scoped command identity, stable across response-loss retries. */\n  readonly commandId: string;\n}\n/** Host catalog port. Implementations own persistence, conditional heads and replay. */\nexport interface StorageFileCatalogCapability<Receipt = unknown> {\n  readonly kind: 'storage-file-catalog';\n  readonly version: 1;\n  readonly limits: StorageFileCatalogLimits;\n  allows(permission: 'read' | 'write'): boolean;\n  list(\n    input: StorageCatalogPage & { readonly directory?: string | undefined },\n  ): Promise<StorageFileWorkflowPage<StorageCatalogFile>>;\n  stat(input: StorageCatalogPath): Promise<StorageCatalogFile>;\n  search(\n    input: StorageCatalogPage & { readonly query: string },\n  ): Promise<StorageFileWorkflowPage<StorageCatalogFile>>;\n  readWindow(input: StorageCatalogPath & StorageCatalogPage): Promise<\n    StorageTextWindow & {\n      readonly path: string;\n      readonly fileId: string;\n      readonly etag: string;\n      readonly size: number;\n      readonly totalBytes: number;\n    }\n  >;\n  searchContent(\n    input: StorageCatalogPath &\n      StorageCatalogPage & {\n        readonly expectedEtag: string;\n        readonly query: string;\n      },\n  ): Promise<\n    StorageTextSearchResult & { readonly path: string; readonly etag: string }\n  >;\n  write(\n    input: StorageCatalogCommand & { readonly content: string },\n  ): Promise<Receipt>;\n  edit(\n    input: StorageCatalogCommand & {\n      readonly expectedEtag: string;\n      readonly change: StorageTextEdit;\n    },\n  ): Promise<Receipt>;\n}\n"]}

package/dist/workspace/storage-file-workflow.d.ts

@@ -0,0 +1,7 @@
+import { type MountStorageFileWorkflowOptions, type StorageFileWorkflowCapability, type StorageFileWorkflowOptions } from './storage-file-workflow.types.js';
+export declare class StorageFileWorkflow<Scope, Receipt> {
+    #private;
+    constructor(options: StorageFileWorkflowOptions<Scope, Receipt>);
+    mount(scope: Scope, options?: MountStorageFileWorkflowOptions): StorageFileWorkflowCapability<Receipt>;
+}
+//# sourceMappingURL=storage-file-workflow.d.ts.map

package/dist/workspace/storage-file-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-file-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/storage-file-workflow.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,+BAA+B,EAGpC,KAAK,6BAA6B,EAGlC,KAAK,0BAA0B,EAIhC,MAAM,kCAAkC,CAAC;AAE1C,qBAAa,mBAAmB,CAAC,KAAK,EAAE,OAAO;;IAE7C,YAAY,OAAO,EAAE,0BAA0B,CAAC,KAAK,EAAE,OAAO,CAAC,EAE9D;IAED,KAAK,CACH,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,+BAAoC,GAC5C,6BAA6B,CAAC,OAAO,CAAC,CAgYxC;CA6FF"}

package/dist/workspace/storage-file-workflow.js

@@ -0,0 +1,440 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { StorageError } from '../storage.error.js';
+import { assertWorkspacePath } from './storage-workspace.path.js';
+import { collectStorageBytes, readStorageTextWindow, storageBytesStream, storageInteger, } from '../core/storage-streams.js';
+import { DEFAULT_STORAGE_FILE_WORKFLOW_LIMITS, } from './storage-file-workflow.types.js';
+export class StorageFileWorkflow {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    mount(scope, options = {}) {
+        const limits = Object.freeze({
+            ...DEFAULT_STORAGE_FILE_WORKFLOW_LIMITS,
+            ...options.limits,
+        });
+        for (const [name, value] of Object.entries(limits))
+            storageInteger(value, name, name === 'maxReadBytes' ? 4 : 1);
+        const permissions = new Set(options.permissions ?? ['read', 'write', 'commit']);
+        const mutations = new Set(options.mutations ?? ['create', 'replace']);
+        const boundSignal = options.signal;
+        const requireMutation = (expectedEtag) => {
+            if (!mutations.has(expectedEtag == null ? 'create' : 'replace'))
+                throw new StorageError('Draft mutation is not permitted by this capability.', { code: 'UNAUTHORIZED' });
+        };
+        const operationPermissions = new WeakMap();
+        const allows = (permission) => permissions.has(permission) &&
+            (permission === 'read' || mutations.size > 0);
+        const operation = (permission, input) => {
+            if (!allows(permission))
+                throw new StorageError('File workflow operation is not permitted.', {
+                    code: 'UNAUTHORIZED',
+                });
+            const signals = [boundSignal, input.signal].filter((signal) => signal !== undefined);
+            const signal = AbortSignal.any(signals);
+            signal.throwIfAborted();
+            operationPermissions.set(signal, permission);
+            return signal;
+        };
+        const transaction = (signal, work) => this.#transaction(scope, signal, operationPermissions.get(signal), work);
+        const content = this.#options.content;
+        const workflow = {
+            kind: 'storage-file-workflow',
+            version: 1,
+            limits,
+            allows,
+            restrict: (restriction) => {
+                const narrowed = { ...limits };
+                for (const name of Object.keys(limits)) {
+                    const requested = restriction.limits?.[name] ?? limits[name];
+                    storageInteger(requested, name, name === 'maxReadBytes' ? 4 : 1);
+                    narrowed[name] = Math.min(limits[name], requested);
+                }
+                return this.mount(scope, {
+                    limits: narrowed,
+                    permissions: [...(restriction.permissions ?? permissions)].filter((permission) => permissions.has(permission)),
+                    mutations: [...(restriction.mutations ?? mutations)].filter((mutation) => mutations.has(mutation)),
+                    signal: AbortSignal.any([boundSignal, restriction.signal].filter((signal) => signal !== undefined)),
+                });
+            },
+            begin: async (input) => {
+                const signal = operation('write', input);
+                requireMutation(input.expectedEtag);
+                assertWorkspacePath(input.path, limits.maxPathBytes, {
+                    allowRoot: false,
+                });
+                validateIdentity(input.idempotencyKey);
+                if (typeof input.text !== 'boolean' ||
+                    (input.expectedEtag !== undefined &&
+                        (typeof input.expectedEtag !== 'string' ||
+                            input.expectedEtag.length === 0 ||
+                            input.expectedEtag.length > 1024)))
+                    invalid('Invalid draft input.');
+                const fingerprint = digest(new TextEncoder().encode(JSON.stringify([
+                    input.path,
+                    input.expectedEtag ?? null,
+                    input.text,
+                ])));
+                return transaction(signal, async (tx) => {
+                    const prior = await tx.findDraftByKey(input.idempotencyKey);
+                    if (prior !== null) {
+                        if (prior.requestFingerprint !== fingerprint)
+                            conflict('Draft key was already used for different input.');
+                        return summary(prior);
+                    }
+                    const record = {
+                        id: randomUUID(),
+                        path: input.path,
+                        expectedEtag: input.expectedEtag ?? null,
+                        text: input.text,
+                        status: 'open',
+                        size: 0,
+                        result: null,
+                        createdAt: new Date().toISOString(),
+                        idempotencyKey: input.idempotencyKey,
+                        requestFingerprint: fingerprint,
+                        body: null,
+                    };
+                    await tx.saveDraft(record);
+                    return summary(record);
+                });
+            },
+            list: async (input = {}) => {
+                const signal = operation('read', input);
+                const offset = input.offset ?? 0;
+                storageInteger(offset, 'offset');
+                return transaction(signal, async (tx) => {
+                    const records = await tx.listDrafts(offset, limits.maxPageSize + 1);
+                    if (records.length > limits.maxPageSize + 1)
+                        provider('Persistence returned an oversized page.');
+                    return {
+                        items: records.slice(0, limits.maxPageSize).map(summary),
+                        nextOffset: records.length > limits.maxPageSize
+                            ? offset + limits.maxPageSize
+                            : null,
+                    };
+                });
+            },
+            read: async (input) => {
+                const signal = operation('read', input);
+                const draft = await transaction(signal, (tx) => requireDraft(tx, input.draftId));
+                if (draft.status === 'cancelled')
+                    conflict('Draft is cancelled.');
+                const offset = input.offset ?? 0;
+                storageInteger(offset, 'offset');
+                if (offset > draft.size)
+                    invalid('Offset exceeds draft size.');
+                const window = draft.text
+                    ? await readStorageTextWindow(async (range) => this.#stream(scope, draft, limits, signal, range.start, range.end + 1), {
+                        size: draft.size,
+                        offset,
+                        maxBytes: limits.maxReadBytes,
+                        signal,
+                    })
+                    : { content: null, offset, nextOffset: null };
+                return { ...summary(draft), ...window };
+            },
+            append: async (input) => {
+                const signal = operation('write', input);
+                storageInteger(input.offset, 'offset');
+                if (!(input.bytes instanceof Uint8Array) ||
+                    input.bytes.byteLength < 1 ||
+                    input.bytes.byteLength > limits.maxChunkBytes)
+                    throw new StorageError('Append exceeds chunk limits.', {
+                        code: 'LIMIT_EXCEEDED',
+                    });
+                // Snapshot before any await: callers may reuse or mutate their upload buffer.
+                const bytes = input.bytes.slice();
+                const sha256 = digest(bytes);
+                const prior = await transaction(signal, async (tx) => {
+                    const draft = await requireDraft(tx, input.draftId);
+                    requireMutation(draft.expectedEtag);
+                    return appendState(tx, draft, input.offset, bytes.byteLength, sha256);
+                });
+                if (prior.replay)
+                    return summary(prior.draft);
+                if (prior.draft.text) {
+                    try {
+                        new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+                    }
+                    catch {
+                        invalid('Text chunks must contain complete UTF-8 characters.');
+                    }
+                }
+                const body = await content.write(scope, storageBytesStream(bytes), {
+                    maxBytes: limits.maxChunkBytes,
+                    signal,
+                });
+                if (body.size !== bytes.byteLength || body.sha256 !== sha256)
+                    provider('Staged chunk receipt does not match input.');
+                return transaction(signal, async (tx) => {
+                    const current = await appendState(tx, await requireDraft(tx, input.draftId), input.offset, bytes.byteLength, sha256);
+                    requireMutation(current.draft.expectedEtag);
+                    if (current.replay)
+                        return summary(current.draft);
+                    const size = current.draft.size + bytes.byteLength;
+                    storageInteger(size, 'size');
+                    await tx.putPart(input.draftId, {
+                        offset: input.offset,
+                        size: body.size,
+                        sha256,
+                        body,
+                    });
+                    const draft = { ...current.draft, size };
+                    await tx.saveDraft(draft);
+                    return summary(draft);
+                });
+            },
+            parts: async (input) => {
+                const signal = operation('read', input);
+                const offset = input.offset ?? 0;
+                storageInteger(offset, 'offset');
+                return transaction(signal, async (tx) => {
+                    const draft = await requireDraft(tx, input.draftId);
+                    if (draft.status === 'cancelled')
+                        conflict('Draft is cancelled.');
+                    if (offset > draft.size)
+                        invalid('Offset exceeds draft size.');
+                    const parts = await tx.listParts(draft.id, offset, limits.maxPageSize);
+                    if (parts.length > limits.maxPageSize)
+                        provider('Persistence returned an oversized page.');
+                    const items = parts
+                        .filter((part) => part.offset + part.size > offset)
+                        .map(({ offset, size, sha256 }) => ({ offset, size, sha256 }));
+                    const last = items.at(-1);
+                    const next = last === undefined ? draft.size : last.offset + last.size;
+                    if (offset < draft.size && (last === undefined || next <= offset))
+                        provider('Draft contains missing chunks.');
+                    return { items, nextOffset: next < draft.size ? next : null };
+                });
+            },
+            cancel: async (input) => {
+                const signal = operation('write', input);
+                return transaction(signal, async (tx) => {
+                    const draft = await requireDraft(tx, input.draftId);
+                    requireMutation(draft.expectedEtag);
+                    if (draft.status === 'committed')
+                        conflict('Committed draft cannot be cancelled.');
+                    const cancelled = { ...draft, status: 'cancelled' };
+                    await tx.saveDraft(cancelled);
+                    return summary(cancelled);
+                });
+            },
+            commit: async (input) => {
+                const signal = operation('commit', input);
+                if (input.drafts.length < 1 ||
+                    input.drafts.length > limits.maxCommitFiles ||
+                    new Set(input.drafts.map((draft) => draft.draftId)).size !==
+                        input.drafts.length)
+                    invalid('Commit requires distinct draft IDs within the batch limit.');
+                const requests = input.drafts.map((draft) => ({ ...draft }));
+                for (const request of requests) {
+                    storageInteger(request.size, 'size');
+                    if (request.sha256 !== undefined &&
+                        !/^[0-9a-f]{64}$/u.test(request.sha256))
+                        invalid('Invalid SHA-256.');
+                }
+                const sealed = await transaction(signal, async (tx) => {
+                    const drafts = [];
+                    for (const request of requests) {
+                        const draft = await requireDraft(tx, request.draftId);
+                        requireMutation(draft.expectedEtag);
+                        if (draft.size !== request.size || draft.status === 'cancelled')
+                            conflict('Draft is cancelled or has a different byte count.');
+                        if (draft.status === 'committed' &&
+                            (draft.result === null ||
+                                draft.body === null ||
+                                (request.sha256 !== undefined &&
+                                    request.sha256 !== draft.body.sha256)))
+                            conflict('Committed draft does not match the requested digest.');
+                        drafts.push(draft);
+                    }
+                    if (new Set(drafts.map((draft) => draft.path)).size !== drafts.length)
+                        conflict('A path may appear only once per commit.');
+                    if (drafts.every((draft) => draft.status === 'committed'))
+                        return drafts;
+                    if (drafts.some((draft) => draft.status === 'committed'))
+                        conflict('Cannot mix committed and uncommitted drafts.');
+                    const result = drafts.map((draft) => ({
+                        ...draft,
+                        status: 'sealed',
+                    }));
+                    for (const draft of result)
+                        await tx.saveDraft(draft);
+                    return result;
+                });
+                if (sealed.every((draft) => draft.status === 'committed'))
+                    return sealed.map((draft) => draft.result);
+                const prepared = new Map();
+                for (const [index, draft] of sealed.entries()) {
+                    const body = await content.write(scope, this.#stream(scope, draft, limits, signal, 0, draft.size, 'commit'), { maxBytes: draft.size, signal });
+                    if (body.size !== draft.size ||
+                        (requests[index].sha256 !== undefined &&
+                            requests[index].sha256 !== body.sha256))
+                        conflict('Completed body does not match the expected byte count or SHA-256.');
+                    prepared.set(draft.id, body);
+                }
+                return transaction(signal, async (tx) => {
+                    const drafts = [];
+                    for (const request of requests) {
+                        const draft = await requireDraft(tx, request.draftId);
+                        requireMutation(draft.expectedEtag);
+                        drafts.push(draft);
+                    }
+                    // A competing identical commit may have completed while bodies streamed.
+                    if (drafts.every((draft) => draft.status === 'committed')) {
+                        for (const [index, draft] of drafts.entries())
+                            if (draft.result === null ||
+                                draft.body?.sha256 !== prepared.get(draft.id)?.sha256 ||
+                                draft.size !== requests[index].size)
+                                conflict('Concurrent commit differs from the prepared body.');
+                        return drafts.map((draft) => draft.result);
+                    }
+                    if (drafts.some((draft) => draft.status !== 'sealed'))
+                        conflict('Every draft must remain sealed until commit.');
+                    const ordered = [...drafts].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+                    const results = await tx.commitHeads(ordered.map((draft) => ({ draft, body: prepared.get(draft.id) })));
+                    if (results.length !== ordered.length ||
+                        results.some((receipt) => receipt === null || receipt === undefined))
+                        provider('Host must return one non-null receipt per head.');
+                    const byId = new Map();
+                    for (const [index, draft] of ordered.entries()) {
+                        const result = results[index];
+                        byId.set(draft.id, result);
+                        await tx.saveDraft({
+                            ...draft,
+                            status: 'committed',
+                            result,
+                            body: prepared.get(draft.id),
+                        });
+                    }
+                    return requests.map((request) => byId.get(request.draftId));
+                });
+            },
+        };
+        return Object.freeze(workflow);
+    }
+    #transaction(scope, signal, permission, work) {
+        signal.throwIfAborted();
+        return this.#options.persistence.transaction(scope, { signal, permission }, async (tx) => {
+            signal.throwIfAborted();
+            const result = await work(tx);
+            signal.throwIfAborted();
+            return result;
+        });
+    }
+    #stream(scope, draft, limits, parentSignal, start = 0, end = draft.size, permission = 'read') {
+        const controller = new AbortController();
+        const signal = AbortSignal.any([parentSignal, controller.signal]);
+        const content = this.#options.content;
+        const transaction = (work) => this.#transaction(scope, signal, permission, work);
+        const iterator = (async function* () {
+            let cursor = start;
+            while (cursor < end) {
+                const parts = await transaction(async (tx) => {
+                    const current = await requireDraft(tx, draft.id);
+                    if (current.status === 'cancelled')
+                        conflict('Draft was cancelled.');
+                    return tx.listParts(draft.id, cursor, limits.maxPageSize);
+                });
+                if (parts.length > limits.maxPageSize)
+                    provider('Persistence returned an oversized page.');
+                let advanced = false;
+                for (const part of parts) {
+                    if (cursor >= end)
+                        break;
+                    storageInteger(part.offset, 'part.offset');
+                    storageInteger(part.size, 'part.size', 1);
+                    if (part.size > limits.maxChunkBytes ||
+                        part.size !== part.body.size ||
+                        part.sha256 !== part.body.sha256)
+                        provider('Invalid chunk receipt.');
+                    if (part.offset + part.size <= cursor)
+                        continue;
+                    if (part.offset > cursor)
+                        provider('Draft contains a missing chunk.');
+                    const bytes = await collectStorageBytes(await content.read(scope, part.body, { signal }), part.size, signal);
+                    if (bytes.byteLength !== part.size || digest(bytes) !== part.sha256)
+                        conflict('Draft chunk failed integrity verification.');
+                    const next = Math.min(end, part.offset + part.size);
+                    yield bytes.subarray(cursor - part.offset, next - part.offset);
+                    cursor = next;
+                    advanced = true;
+                }
+                if (!advanced)
+                    provider('Draft is incomplete.');
+            }
+        })();
+        return new ReadableStream({
+            async pull(output) {
+                try {
+                    const next = await iterator.next();
+                    if (next.done)
+                        output.close();
+                    else
+                        output.enqueue(next.value);
+                }
+                catch (error) {
+                    output.error(error);
+                    await iterator.return(undefined);
+                }
+            },
+            async cancel(reason) {
+                controller.abort(reason);
+                await iterator.return(undefined);
+            },
+        }, { highWaterMark: 0 });
+    }
+}
+async function requireDraft(tx, id) {
+    validateIdentity(id);
+    const draft = await tx.getDraft(id);
+    if (draft === null)
+        throw new StorageError('Draft is unavailable.', { code: 'NOT_FOUND' });
+    return draft;
+}
+async function appendState(tx, draft, offset, size, sha256) {
+    if (draft.status !== 'open')
+        conflict('Draft is closed for writes.');
+    if (offset < draft.size) {
+        const previous = (await tx.listParts(draft.id, offset, 1))[0];
+        if (previous?.offset === offset &&
+            previous.size === size &&
+            previous.sha256 === sha256)
+            return { draft, replay: true };
+        conflict('Different bytes were already appended at this offset.');
+    }
+    if (offset !== draft.size)
+        conflict('Draft offset changed. Read the current size before appending.');
+    return { draft, replay: false };
+}
+function summary(draft) {
+    const { id, path, expectedEtag, text, status, size, result, createdAt } = draft;
+    return Object.freeze({
+        id,
+        path,
+        expectedEtag,
+        text,
+        status,
+        size,
+        result,
+        createdAt,
+    });
+}
+function validateIdentity(value) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > 256)
+        invalid('Invalid workflow identity.');
+}
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function invalid(message) {
+    throw new StorageError(message, { code: 'INVALID_ARGUMENT' });
+}
+function conflict(message) {
+    throw new StorageError(message, { code: 'CONFLICT' });
+}
+function provider(message) {
+    throw new StorageError(message, { code: 'PROVIDER' });
+}
+//# sourceMappingURL=storage-file-workflow.js.map