@nestm/storage 0.1.0-alpha.2 → 0.1.0-alpha.20

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

@@ -0,0 +1,184 @@
+import type { StorageStagedBody, StorageStagedContent } from '../core/storage-staged-content.js';
+import type { StorageTextChange } from '../core/storage-text-edit.js';
+import type { StorageTextSearchResult } from '../core/storage-text.js';
+import type { StorageTextWindow } from '../core/storage-streams.js';
+export type StorageFileWorkflowPermission = 'read' | 'write' | 'commit';
+export type StorageFileWorkflowMutation = 'create' | 'replace';
+export interface StorageFileWorkflowLimits {
+    maxChunkBytes: number;
+    maxReadBytes: number;
+    maxPageSize: number;
+    maxCommitFiles: number;
+    maxPathBytes: number;
+    /** Buffered input and host read ceiling; streamed file edits are not limited by total file size. */
+    maxTextBytes: number;
+    maxEdits: number;
+}
+export declare const DEFAULT_STORAGE_FILE_WORKFLOW_LIMITS: Readonly<StorageFileWorkflowLimits>;
+export interface StorageFileWorkflowOperation {
+    readonly signal?: AbortSignal | undefined;
+}
+export interface StorageFileDraftBegin extends StorageFileWorkflowOperation {
+    readonly path: string;
+    readonly idempotencyKey: string;
+    readonly text: boolean;
+    readonly expectedEtag?: string | undefined;
+}
+export interface StorageFileDraftStageText extends Omit<StorageFileDraftBegin, 'text'> {
+    readonly content: string;
+}
+export interface StorageFileDraftStageStream extends StorageFileDraftBegin {
+    /** Stable trusted source identity used to detect conflicting command replay. */
+    readonly contentIdentity: string;
+    /** Open only after authorization and replay lookup; bytes are never exposed to the model. */
+    readonly body: () => ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>;
+    readonly sourceDraftId?: string | undefined;
+    readonly expectedSize?: number | undefined;
+}
+export interface StorageFileDraftReviseText extends StorageFileDraftRequest {
+    /** Optional host request identity, included in replay validation. */
+    readonly requestIdentity?: string | undefined;
+    readonly expectedSize: number;
+    readonly idempotencyKey: string;
+    readonly changes: readonly StorageTextChange[];
+}
+export interface StorageFileDraftRequest extends StorageFileWorkflowOperation {
+    readonly draftId: string;
+}
+export interface StorageFileDraftPageRequest extends StorageFileWorkflowOperation {
+    readonly offset?: number | undefined;
+}
+export interface StorageFileDraftAppend extends StorageFileDraftRequest {
+    readonly offset: number;
+    readonly bytes: Uint8Array;
+}
+export interface StorageFileDraftCommit {
+    readonly draftId: string;
+    readonly size: number;
+    readonly sha256?: string | undefined;
+}
+export interface StorageFileWorkflowCommit extends StorageFileWorkflowOperation {
+    readonly drafts: readonly StorageFileDraftCommit[];
+}
+export interface StorageFileDraft<Receipt> {
+    readonly id: string;
+    readonly path: string;
+    readonly expectedEtag: string | null;
+    /** Predecessor checkpoint; null for a new draft or catalog checkout. */
+    readonly sourceDraftId: string | null;
+    readonly text: boolean;
+    readonly status: 'open' | 'sealed' | 'committed' | 'cancelled';
+    readonly size: number;
+    readonly result: Receipt | null;
+    readonly createdAt: string;
+}
+export interface StorageFileDraftRecord<Receipt> extends StorageFileDraft<Receipt> {
+    readonly idempotencyKey: string;
+    readonly requestFingerprint: string;
+    /** Whole-file verified body; persisted only with successful head commit. */
+    readonly body: StorageStagedBody | null;
+}
+export interface StorageFilePartReceipt {
+    readonly offset: number;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface StorageFilePartRecord extends StorageFilePartReceipt {
+    readonly body: StorageStagedBody;
+}
+export interface StorageFileWorkflowPage<Item> {
+    readonly items: readonly Item[];
+    readonly nextOffset: number | null;
+}
+export interface StorageFileHeadChange<Receipt> {
+    readonly draft: StorageFileDraftRecord<Receipt>;
+    readonly body: StorageStagedBody;
+}
+/** All methods execute in the SAME host transaction. Records are detached values. */
+export interface StorageFileWorkflowTransaction<Receipt> {
+    findDraftByKey(key: string): Promise<StorageFileDraftRecord<Receipt> | null>;
+    getDraft(id: string): Promise<StorageFileDraftRecord<Receipt> | null>;
+    saveDraft(draft: StorageFileDraftRecord<Receipt>): Promise<void>;
+    /** Stable order, at most limit entries; scoped to the authorized principal. */
+    listDrafts(offset: number, limit: number): Promise<readonly StorageFileDraftRecord<Receipt>[]>;
+    /** Ordered by offset; include the part containing offset, then later parts. */
+    listParts(draftId: string, offset: number, limit: number): Promise<readonly StorageFilePartRecord[]>;
+    putPart(draftId: string, part: StorageFilePartRecord): Promise<void>;
+    /**
+     * Compare every expected head/create predicate and update all heads atomically.
+     * Return one receipt per change, in the supplied order. Must join this transaction;
+     * never implement this as serial provider writes or independent transactions.
+     * Paths arrive sorted to permit consistent lock ordering.
+     */
+    commitHeads(changes: readonly StorageFileHeadChange<Receipt>[]): Promise<readonly Receipt[]>;
+}
+export interface StorageFileWorkflowPersistence<Scope, Receipt> {
+    /**
+     * Reauthorize scope on EVERY call; lock/serialize its draft/idempotency state
+     * before work begins, including across replicas. Roll back ALL callback effects
+     * on rejection. Resolve only after durable commit. Do not retry the callback.
+     * Check signal before committing; once committed, return its result even if
+     * signal subsequently aborts. Lost responses are reconciled by replay.
+     */
+    transaction<Result>(scope: Scope, options: StorageFileWorkflowOperation & {
+        readonly permission: StorageFileWorkflowPermission;
+    }, work: (transaction: StorageFileWorkflowTransaction<Receipt>) => Promise<Result>): Promise<Result>;
+}
+export interface StorageFileWorkflowOptions<Scope, Receipt> {
+    readonly persistence: StorageFileWorkflowPersistence<Scope, Receipt>;
+    readonly content: StorageStagedContent<Scope>;
+}
+export interface MountStorageFileWorkflowOptions extends StorageFileWorkflowOperation {
+    readonly permissions?: Iterable<StorageFileWorkflowPermission>;
+    /** Checked against each persisted draft on append/cancel/commit, including replay. */
+    readonly mutations?: Iterable<StorageFileWorkflowMutation>;
+    readonly limits?: Partial<StorageFileWorkflowLimits>;
+}
+/** A host-scope-bound capability. Scope, provider keys and staged bodies stay private. */
+export interface StorageFileWorkflowCapability<Receipt = unknown> {
+    readonly kind: 'storage-file-workflow';
+    readonly version: 1;
+    readonly limits: Readonly<StorageFileWorkflowLimits>;
+    allows(permission: StorageFileWorkflowPermission): boolean;
+    /** Narrow only; cannot change scope, widen grants/limits, or detach parent abort. */
+    restrict(options: MountStorageFileWorkflowOptions): StorageFileWorkflowCapability<Receipt>;
+    /** Atomically save a bounded text buffer as a sealed, resumable checkpoint. */
+    stageText(input: StorageFileDraftStageText): Promise<StorageFileDraft<Receipt>>;
+    /** Stage arbitrary-size text or binary source in bounded, integrity-checked chunks. */
+    stageStream(input: StorageFileDraftStageStream): Promise<StorageFileDraft<Receipt>>;
+    /** Save a new sealed checkpoint; preserve the source and original head precondition. */
+    reviseText(input: StorageFileDraftReviseText): Promise<StorageFileDraft<Receipt>>;
+    /** Recover a host command receipt without reopening its source. */
+    lookup(input: StorageFileWorkflowOperation & {
+        readonly idempotencyKey: string;
+    }): Promise<StorageFileDraft<Receipt> | null>;
+    begin(input: StorageFileDraftBegin): Promise<StorageFileDraft<Receipt>>;
+    list(input?: StorageFileDraftPageRequest): Promise<StorageFileWorkflowPage<StorageFileDraft<Receipt>>>;
+    read(input: StorageFileDraftRequest & StorageFileDraftPageRequest): Promise<StorageFileDraft<Receipt> & StorageTextWindow>;
+    /** Host-only stream of an exact checkpoint; end is exclusive. */
+    readStream(input: StorageFileDraftRequest & {
+        readonly expectedSize: number;
+        readonly start?: number | undefined;
+        readonly end?: number | undefined;
+    }): Promise<StorageFileDraft<Receipt> & {
+        readonly body: ReadableStream<Uint8Array>;
+    }>;
+    searchText(input: StorageFileDraftRequest & StorageFileDraftPageRequest & {
+        readonly expectedSize: number;
+        readonly query: string;
+    }): Promise<StorageTextSearchResult & {
+        readonly path: string;
+        readonly etag: string;
+    }>;
+    /** Buffer one exact text revision within maxTextBytes for host validation. */
+    readText(input: StorageFileDraftRequest & {
+        readonly expectedSize: number;
+    }): Promise<StorageFileDraft<Receipt> & {
+        readonly content: string;
+    }>;
+    append(input: StorageFileDraftAppend): Promise<StorageFileDraft<Receipt>>;
+    parts(input: StorageFileDraftRequest & StorageFileDraftPageRequest): Promise<StorageFileWorkflowPage<StorageFilePartReceipt>>;
+    cancel(input: StorageFileDraftRequest): Promise<StorageFileDraft<Receipt>>;
+    commit(input: StorageFileWorkflowCommit): Promise<readonly Receipt[]>;
+}
+//# sourceMappingURL=storage-file-workflow.types.d.ts.map

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

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

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

@@ -0,0 +1,10 @@
+export const DEFAULT_STORAGE_FILE_WORKFLOW_LIMITS = Object.freeze({
+    maxChunkBytes: 262_144,
+    maxReadBytes: 4096,
+    maxPageSize: 64,
+    maxCommitFiles: 20,
+    maxPathBytes: 1024,
+    maxTextBytes: 16 * 1024 * 1024,
+    maxEdits: 64,
+});
+//# sourceMappingURL=storage-file-workflow.types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage-file-workflow.types.js","sourceRoot":"","sources":["../../src/workspace/storage-file-workflow.types.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,oCAAoC,GAC/C,MAAM,CAAC,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO;IACtB,YAAY,EAAE,IAAI;IAClB,WAAW,EAAE,EAAE;IACf,cAAc,EAAE,EAAE;IAClB,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IAC9B,QAAQ,EAAE,EAAE;CACb,CAAC,CAAC","sourcesContent":["import type {\n  StorageStagedBody,\n  StorageStagedContent,\n} from '../core/storage-staged-content.js';\nimport type { StorageTextChange } from '../core/storage-text-edit.js';\nimport type { StorageTextSearchResult } from '../core/storage-text.js';\nimport type { StorageTextWindow } from '../core/storage-streams.js';\n\nexport type StorageFileWorkflowPermission = 'read' | 'write' | 'commit';\nexport type StorageFileWorkflowMutation = 'create' | 'replace';\nexport interface StorageFileWorkflowLimits {\n  maxChunkBytes: number;\n  maxReadBytes: number;\n  maxPageSize: number;\n  maxCommitFiles: number;\n  maxPathBytes: number;\n  /** Buffered input and host read ceiling; streamed file edits are not limited by total file size. */\n  maxTextBytes: number;\n  maxEdits: number;\n}\nexport const DEFAULT_STORAGE_FILE_WORKFLOW_LIMITS: Readonly<StorageFileWorkflowLimits> =\n  Object.freeze({\n    maxChunkBytes: 262_144,\n    maxReadBytes: 4096,\n    maxPageSize: 64,\n    maxCommitFiles: 20,\n    maxPathBytes: 1024,\n    maxTextBytes: 16 * 1024 * 1024,\n    maxEdits: 64,\n  });\nexport interface StorageFileWorkflowOperation {\n  readonly signal?: AbortSignal | undefined;\n}\nexport interface StorageFileDraftBegin extends StorageFileWorkflowOperation {\n  readonly path: string;\n  readonly idempotencyKey: string;\n  readonly text: boolean;\n  readonly expectedEtag?: string | undefined;\n}\nexport interface StorageFileDraftStageText extends Omit<\n  StorageFileDraftBegin,\n  'text'\n> {\n  readonly content: string;\n}\nexport interface StorageFileDraftStageStream extends StorageFileDraftBegin {\n  /** Stable trusted source identity used to detect conflicting command replay. */\n  readonly contentIdentity: string;\n  /** Open only after authorization and replay lookup; bytes are never exposed to the model. */\n  readonly body: () =>\n    ReadableStream<Uint8Array> | Promise<ReadableStream<Uint8Array>>;\n  readonly sourceDraftId?: string | undefined;\n  readonly expectedSize?: number | undefined;\n}\nexport interface StorageFileDraftReviseText extends StorageFileDraftRequest {\n  /** Optional host request identity, included in replay validation. */\n  readonly requestIdentity?: string | undefined;\n  readonly expectedSize: number;\n  readonly idempotencyKey: string;\n  readonly changes: readonly StorageTextChange[];\n}\nexport interface StorageFileDraftRequest extends StorageFileWorkflowOperation {\n  readonly draftId: string;\n}\nexport interface StorageFileDraftPageRequest extends StorageFileWorkflowOperation {\n  readonly offset?: number | undefined;\n}\nexport interface StorageFileDraftAppend extends StorageFileDraftRequest {\n  readonly offset: number;\n  readonly bytes: Uint8Array;\n}\nexport interface StorageFileDraftCommit {\n  readonly draftId: string;\n  readonly size: number;\n  readonly sha256?: string | undefined;\n}\nexport interface StorageFileWorkflowCommit extends StorageFileWorkflowOperation {\n  readonly drafts: readonly StorageFileDraftCommit[];\n}\nexport interface StorageFileDraft<Receipt> {\n  readonly id: string;\n  readonly path: string;\n  readonly expectedEtag: string | null;\n  /** Predecessor checkpoint; null for a new draft or catalog checkout. */\n  readonly sourceDraftId: string | null;\n  readonly text: boolean;\n  readonly status: 'open' | 'sealed' | 'committed' | 'cancelled';\n  readonly size: number;\n  readonly result: Receipt | null;\n  readonly createdAt: string;\n}\nexport interface StorageFileDraftRecord<\n  Receipt,\n> extends StorageFileDraft<Receipt> {\n  readonly idempotencyKey: string;\n  readonly requestFingerprint: string;\n  /** Whole-file verified body; persisted only with successful head commit. */\n  readonly body: StorageStagedBody | null;\n}\nexport interface StorageFilePartReceipt {\n  readonly offset: number;\n  readonly size: number;\n  readonly sha256: string;\n}\nexport interface StorageFilePartRecord extends StorageFilePartReceipt {\n  readonly body: StorageStagedBody;\n}\nexport interface StorageFileWorkflowPage<Item> {\n  readonly items: readonly Item[];\n  readonly nextOffset: number | null;\n}\nexport interface StorageFileHeadChange<Receipt> {\n  readonly draft: StorageFileDraftRecord<Receipt>;\n  readonly body: StorageStagedBody;\n}\n\n/** All methods execute in the SAME host transaction. Records are detached values. */\nexport interface StorageFileWorkflowTransaction<Receipt> {\n  findDraftByKey(key: string): Promise<StorageFileDraftRecord<Receipt> | null>;\n  getDraft(id: string): Promise<StorageFileDraftRecord<Receipt> | null>;\n  saveDraft(draft: StorageFileDraftRecord<Receipt>): Promise<void>;\n  /** Stable order, at most limit entries; scoped to the authorized principal. */\n  listDrafts(\n    offset: number,\n    limit: number,\n  ): Promise<readonly StorageFileDraftRecord<Receipt>[]>;\n  /** Ordered by offset; include the part containing offset, then later parts. */\n  listParts(\n    draftId: string,\n    offset: number,\n    limit: number,\n  ): Promise<readonly StorageFilePartRecord[]>;\n  putPart(draftId: string, part: StorageFilePartRecord): Promise<void>;\n  /**\n   * Compare every expected head/create predicate and update all heads atomically.\n   * Return one receipt per change, in the supplied order. Must join this transaction;\n   * never implement this as serial provider writes or independent transactions.\n   * Paths arrive sorted to permit consistent lock ordering.\n   */\n  commitHeads(\n    changes: readonly StorageFileHeadChange<Receipt>[],\n  ): Promise<readonly Receipt[]>;\n}\nexport interface StorageFileWorkflowPersistence<Scope, Receipt> {\n  /**\n   * Reauthorize scope on EVERY call; lock/serialize its draft/idempotency state\n   * before work begins, including across replicas. Roll back ALL callback effects\n   * on rejection. Resolve only after durable commit. Do not retry the callback.\n   * Check signal before committing; once committed, return its result even if\n   * signal subsequently aborts. Lost responses are reconciled by replay.\n   */\n  transaction<Result>(\n    scope: Scope,\n    options: StorageFileWorkflowOperation & {\n      readonly permission: StorageFileWorkflowPermission;\n    },\n    work: (\n      transaction: StorageFileWorkflowTransaction<Receipt>,\n    ) => Promise<Result>,\n  ): Promise<Result>;\n}\nexport interface StorageFileWorkflowOptions<Scope, Receipt> {\n  readonly persistence: StorageFileWorkflowPersistence<Scope, Receipt>;\n  readonly content: StorageStagedContent<Scope>;\n}\nexport interface MountStorageFileWorkflowOptions extends StorageFileWorkflowOperation {\n  readonly permissions?: Iterable<StorageFileWorkflowPermission>;\n  /** Checked against each persisted draft on append/cancel/commit, including replay. */\n  readonly mutations?: Iterable<StorageFileWorkflowMutation>;\n  readonly limits?: Partial<StorageFileWorkflowLimits>;\n}\n/** A host-scope-bound capability. Scope, provider keys and staged bodies stay private. */\nexport interface StorageFileWorkflowCapability<Receipt = unknown> {\n  readonly kind: 'storage-file-workflow';\n  readonly version: 1;\n  readonly limits: Readonly<StorageFileWorkflowLimits>;\n  allows(permission: StorageFileWorkflowPermission): boolean;\n  /** Narrow only; cannot change scope, widen grants/limits, or detach parent abort. */\n  restrict(\n    options: MountStorageFileWorkflowOptions,\n  ): StorageFileWorkflowCapability<Receipt>;\n  /** Atomically save a bounded text buffer as a sealed, resumable checkpoint. */\n  stageText(\n    input: StorageFileDraftStageText,\n  ): Promise<StorageFileDraft<Receipt>>;\n  /** Stage arbitrary-size text or binary source in bounded, integrity-checked chunks. */\n  stageStream(\n    input: StorageFileDraftStageStream,\n  ): Promise<StorageFileDraft<Receipt>>;\n  /** Save a new sealed checkpoint; preserve the source and original head precondition. */\n  reviseText(\n    input: StorageFileDraftReviseText,\n  ): Promise<StorageFileDraft<Receipt>>;\n  /** Recover a host command receipt without reopening its source. */\n  lookup(\n    input: StorageFileWorkflowOperation & { readonly idempotencyKey: string },\n  ): Promise<StorageFileDraft<Receipt> | null>;\n  begin(input: StorageFileDraftBegin): Promise<StorageFileDraft<Receipt>>;\n  list(\n    input?: StorageFileDraftPageRequest,\n  ): Promise<StorageFileWorkflowPage<StorageFileDraft<Receipt>>>;\n  read(\n    input: StorageFileDraftRequest & StorageFileDraftPageRequest,\n  ): Promise<StorageFileDraft<Receipt> & StorageTextWindow>;\n  /** Host-only stream of an exact checkpoint; end is exclusive. */\n  readStream(\n    input: StorageFileDraftRequest & {\n      readonly expectedSize: number;\n      readonly start?: number | undefined;\n      readonly end?: number | undefined;\n    },\n  ): Promise<\n    StorageFileDraft<Receipt> & { readonly body: ReadableStream<Uint8Array> }\n  >;\n  searchText(\n    input: StorageFileDraftRequest &\n      StorageFileDraftPageRequest & {\n        readonly expectedSize: number;\n        readonly query: string;\n      },\n  ): Promise<\n    StorageTextSearchResult & { readonly path: string; readonly etag: string }\n  >;\n  /** Buffer one exact text revision within maxTextBytes for host validation. */\n  readText(\n    input: StorageFileDraftRequest & { readonly expectedSize: number },\n  ): Promise<StorageFileDraft<Receipt> & { readonly content: string }>;\n  append(input: StorageFileDraftAppend): Promise<StorageFileDraft<Receipt>>;\n  parts(\n    input: StorageFileDraftRequest & StorageFileDraftPageRequest,\n  ): Promise<StorageFileWorkflowPage<StorageFilePartReceipt>>;\n  cancel(input: StorageFileDraftRequest): Promise<StorageFileDraft<Receipt>>;\n  commit(input: StorageFileWorkflowCommit): Promise<readonly Receipt[]>;\n}\n"]}

package/dist/workspace/storage-text-draft.d.ts

@@ -0,0 +1,21 @@
+import type { StorageStagedContent } from '../core/storage-staged-content.js';
+import type { StorageFileDraftRecord, StorageFileWorkflowLimits, StorageFileWorkflowTransaction } from './storage-file-workflow.types.js';
+/** Stage bytes outside the host transaction, then atomically publish all part references. */
+export declare function stageStorageTextDraft<Scope, Receipt>(options: {
+    readonly scope: Scope;
+    readonly signal: AbortSignal;
+    readonly limits: Readonly<StorageFileWorkflowLimits>;
+    readonly content: StorageStagedContent<Scope>;
+    readonly idempotencyKey: string;
+    readonly fingerprint: string;
+    readonly requireMutation: (expectedEtag: string | null) => void;
+    readonly transaction: <T>(work: (tx: StorageFileWorkflowTransaction<Receipt>) => Promise<T>) => Promise<T>;
+    readonly load: () => Promise<{
+        content: string | ReadableStream<Uint8Array>;
+        text?: boolean;
+        path: string;
+        expectedEtag: string | null;
+        source: StorageFileDraftRecord<Receipt> | null;
+    }>;
+}): Promise<StorageFileDraftRecord<Receipt>>;
+//# sourceMappingURL=storage-text-draft.d.ts.map

package/dist/workspace/storage-text-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-text-draft.d.ts","sourceRoot":"","sources":["../../src/workspace/storage-text-draft.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EACV,sBAAsB,EAEtB,yBAAyB,EACzB,8BAA8B,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,6FAA6F;AAC7F,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EACtB,IAAI,EAAE,CAAC,EAAE,EAAE,8BAA8B,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAC9D,OAAO,CAAC,CAAC,CAAC,CAAC;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;QAC3B,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;KAChD,CAAC,CAAC;CACJ,GAAG,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CA4F3C"}

package/dist/workspace/storage-text-draft.js

@@ -0,0 +1,77 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chunkStorageDraftStream } from './storage-draft-stream.js';
+import { StorageError } from '../storage.error.js';
+import { storageBytesStream } from '../core/storage-streams.js';
+/** Stage bytes outside the host transaction, then atomically publish all part references. */
+export async function stageStorageTextDraft(options) {
+    const { transaction, signal, limits } = options;
+    const replay = async (tx) => {
+        const prior = await tx.findDraftByKey(options.idempotencyKey);
+        if (prior !== null) {
+            options.requireMutation(prior.expectedEtag);
+            if (prior.requestFingerprint !== options.fingerprint)
+                throw new StorageError('Draft key was already used for different input.', { code: 'CONFLICT' });
+        }
+        return prior;
+    };
+    const prior = await transaction(replay);
+    if (prior !== null)
+        return prior;
+    const loaded = await options.load();
+    options.requireMutation(loaded.expectedEtag);
+    if (typeof loaded.content === 'string' &&
+        /[\uD800-\uDFFF]/u.test(loaded.content))
+        throw new StorageError('Text must be well-formed UTF-8.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    const source = typeof loaded.content === 'string'
+        ? storageBytesStream(new TextEncoder().encode(loaded.content))
+        : loaded.content;
+    const parts = [];
+    let size = 0;
+    for await (const chunk of chunkStorageDraftStream(source, limits.maxChunkBytes, loaded.text ?? true, signal)) {
+        signal.throwIfAborted();
+        const body = await options.content.write(options.scope, storageBytesStream(chunk), { maxBytes: limits.maxChunkBytes, signal });
+        if (body.size !== chunk.length ||
+            body.sha256 !== createHash('sha256').update(chunk).digest('hex'))
+            throw new StorageError('Invalid draft chunk receipt.', {
+                code: 'PROVIDER',
+            });
+        parts.push({ offset: size, size: body.size, sha256: body.sha256, body });
+        size += chunk.length;
+        if (!Number.isSafeInteger(size))
+            throw new StorageError('Draft size exceeds supported integer precision.', { code: 'LIMIT_EXCEEDED' });
+    }
+    return transaction(async (tx) => {
+        const concurrent = await replay(tx);
+        if (concurrent !== null)
+            return concurrent;
+        if (loaded.source !== null) {
+            const current = await tx.getDraft(loaded.source.id);
+            if (current === null ||
+                current.size !== loaded.source.size ||
+                !['open', 'sealed'].includes(current.status))
+                throw new StorageError('The source draft changed while editing. Read its latest size.', { code: 'CONFLICT' });
+            await tx.saveDraft({ ...current, status: 'sealed' });
+        }
+        const draft = {
+            id: randomUUID(),
+            path: loaded.path,
+            expectedEtag: loaded.expectedEtag,
+            sourceDraftId: loaded.source?.id ?? null,
+            text: loaded.text ?? true,
+            status: 'sealed',
+            size,
+            result: null,
+            createdAt: new Date().toISOString(),
+            idempotencyKey: options.idempotencyKey,
+            requestFingerprint: options.fingerprint,
+            body: null,
+        };
+        await tx.saveDraft(draft);
+        for (const part of parts)
+            await tx.putPart(draft.id, part);
+        return draft;
+    });
+}
+//# sourceMappingURL=storage-text-draft.js.map

package/dist/workspace/storage-text-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-text-draft.js","sourceRoot":"","sources":["../../src/workspace/storage-text-draft.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport { chunkStorageDraftStream } from './storage-draft-stream.js';\nimport { StorageError } from '../storage.error.js';\nimport { storageBytesStream } from '../core/storage-streams.js';\nimport type { StorageStagedContent } from '../core/storage-staged-content.js';\nimport type {\n  StorageFileDraftRecord,\n  StorageFilePartRecord,\n  StorageFileWorkflowLimits,\n  StorageFileWorkflowTransaction,\n} from './storage-file-workflow.types.js';\n\n/** Stage bytes outside the host transaction, then atomically publish all part references. */\nexport async function stageStorageTextDraft<Scope, Receipt>(options: {\n  readonly scope: Scope;\n  readonly signal: AbortSignal;\n  readonly limits: Readonly<StorageFileWorkflowLimits>;\n  readonly content: StorageStagedContent<Scope>;\n  readonly idempotencyKey: string;\n  readonly fingerprint: string;\n  readonly requireMutation: (expectedEtag: string | null) => void;\n  readonly transaction: <T>(\n    work: (tx: StorageFileWorkflowTransaction<Receipt>) => Promise<T>,\n  ) => Promise<T>;\n  readonly load: () => Promise<{\n    content: string | ReadableStream<Uint8Array>;\n    text?: boolean;\n    path: string;\n    expectedEtag: string | null;\n    source: StorageFileDraftRecord<Receipt> | null;\n  }>;\n}): Promise<StorageFileDraftRecord<Receipt>> {\n  const { transaction, signal, limits } = options;\n  const replay = async (tx: StorageFileWorkflowTransaction<Receipt>) => {\n    const prior = await tx.findDraftByKey(options.idempotencyKey);\n    if (prior !== null) {\n      options.requireMutation(prior.expectedEtag);\n      if (prior.requestFingerprint !== options.fingerprint)\n        throw new StorageError(\n          'Draft key was already used for different input.',\n          { code: 'CONFLICT' },\n        );\n    }\n    return prior;\n  };\n  const prior = await transaction(replay);\n  if (prior !== null) return prior;\n  const loaded = await options.load();\n  options.requireMutation(loaded.expectedEtag);\n  if (\n    typeof loaded.content === 'string' &&\n    /[\\uD800-\\uDFFF]/u.test(loaded.content)\n  )\n    throw new StorageError('Text must be well-formed UTF-8.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  const source =\n    typeof loaded.content === 'string'\n      ? storageBytesStream(new TextEncoder().encode(loaded.content))\n      : loaded.content;\n  const parts: StorageFilePartRecord[] = [];\n  let size = 0;\n  for await (const chunk of chunkStorageDraftStream(\n    source,\n    limits.maxChunkBytes,\n    loaded.text ?? true,\n    signal,\n  )) {\n    signal.throwIfAborted();\n    const body = await options.content.write(\n      options.scope,\n      storageBytesStream(chunk),\n      { maxBytes: limits.maxChunkBytes, signal },\n    );\n    if (\n      body.size !== chunk.length ||\n      body.sha256 !== createHash('sha256').update(chunk).digest('hex')\n    )\n      throw new StorageError('Invalid draft chunk receipt.', {\n        code: 'PROVIDER',\n      });\n    parts.push({ offset: size, size: body.size, sha256: body.sha256, body });\n    size += chunk.length;\n    if (!Number.isSafeInteger(size))\n      throw new StorageError(\n        'Draft size exceeds supported integer precision.',\n        { code: 'LIMIT_EXCEEDED' },\n      );\n  }\n  return transaction(async (tx) => {\n    const concurrent = await replay(tx);\n    if (concurrent !== null) return concurrent;\n    if (loaded.source !== null) {\n      const current = await tx.getDraft(loaded.source.id);\n      if (\n        current === null ||\n        current.size !== loaded.source.size ||\n        !['open', 'sealed'].includes(current.status)\n      )\n        throw new StorageError(\n          'The source draft changed while editing. Read its latest size.',\n          { code: 'CONFLICT' },\n        );\n      await tx.saveDraft({ ...current, status: 'sealed' });\n    }\n    const draft: StorageFileDraftRecord<Receipt> = {\n      id: randomUUID(),\n      path: loaded.path,\n      expectedEtag: loaded.expectedEtag,\n      sourceDraftId: loaded.source?.id ?? null,\n      text: loaded.text ?? true,\n      status: 'sealed',\n      size,\n      result: null,\n      createdAt: new Date().toISOString(),\n      idempotencyKey: options.idempotencyKey,\n      requestFingerprint: options.fingerprint,\n      body: null,\n    };\n    await tx.saveDraft(draft);\n    for (const part of parts) await tx.putPart(draft.id, part);\n    return draft;\n  });\n}\n"]}

package/dist/workspace/storage-working-files.d.ts

@@ -0,0 +1,34 @@
+import type { StorageFileCatalogCapability, StorageCatalogFile, StorageCatalogPath, StorageCatalogCommand } from './storage-file-catalog.types.js';
+import type { StorageFileDraft, StorageFileWorkflowCapability, StorageFileWorkflowOperation } from './storage-file-workflow.types.js';
+export interface StorageWorkingFile extends StorageCatalogFile {
+    readonly operation: 'created' | 'updated';
+    readonly pending: true;
+}
+export interface StorageWorkingFileReceipt {
+    readonly path: string;
+    readonly etag: string;
+    readonly size: number;
+}
+/** A path-based editing view over durable checkpoints. Saved heads change only on commit. */
+export declare class StorageWorkingFiles<Receipt extends StorageWorkingFileReceipt> {
+    readonly files: StorageFileCatalogCapability<Receipt>;
+    readonly workflow: StorageFileWorkflowCapability<Receipt>;
+    readonly catalog: StorageFileCatalogCapability<Receipt | StorageWorkingFile>;
+    constructor(files: StorageFileCatalogCapability<Receipt>, workflow: StorageFileWorkflowCapability<Receipt>);
+    write(input: StorageCatalogCommand & {
+        readonly content: string;
+    }): Promise<Receipt | StorageWorkingFile>;
+    /** Resolve an exact candidate (including committed replay) or the unique unfinished leaf. */
+    draft(input: StorageCatalogPath): Promise<StorageFileDraft<Receipt> | null>;
+    /** Discovery derives from persisted lineage, so process restarts need no local registry. */
+    pending(input: StorageFileWorkflowOperation): Promise<StorageFileDraft<Receipt>[]>;
+    private page;
+    private saved;
+    private result;
+    private receipt;
+    private textLimit;
+    private requireWrite;
+    private denied;
+    private conflict;
+}
+//# sourceMappingURL=storage-working-files.d.ts.map

package/dist/workspace/storage-working-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-working-files.d.ts","sourceRoot":"","sources":["../../src/workspace/storage-working-files.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EAEtB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,gBAAgB,EAChB,6BAA6B,EAC7B,4BAA4B,EAE7B,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB;AACD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,6FAA6F;AAC7F,qBAAa,mBAAmB,CAAC,OAAO,SAAS,yBAAyB;IAGtE,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,6BAA6B,CAAC,OAAO,CAAC;IAH3D,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC,OAAO,GAAG,kBAAkB,CAAC,CAAC;IAC7E,YACW,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,EAC5C,QAAQ,EAAE,6BAA6B,CAAC,OAAO,CAAC,EA2H1D;IAEK,KAAK,CACT,KAAK,EAAE,qBAAqB,GAAG;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,OAAO,GAAG,kBAAkB,CAAC,CAkDvC;IAED,6FAA6F;IACvF,KAAK,CACT,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAyB3C;IAED,4FAA4F;IACtF,OAAO,CACX,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC,CAyBtC;YAEa,IAAI;IAuDlB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,YAAY;IAGpB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,QAAQ;CAMjB"}