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

package/dist/workspace/storage-working-files.js

@@ -0,0 +1,326 @@
+import { createHash } from 'node:crypto';
+import { StorageError, isStorageError } from '../storage.error.js';
+import { storageBytesStream, storageInteger } from '../core/storage-streams.js';
+import { editStorageTextStream } from '../core/storage-text-stream-edit.js';
+/** A path-based editing view over durable checkpoints. Saved heads change only on commit. */
+export class StorageWorkingFiles {
+    files;
+    workflow;
+    catalog;
+    constructor(files, workflow) {
+        this.files = files;
+        this.workflow = workflow;
+        this.catalog = Object.freeze({
+            ...files,
+            list: (input) => this.page(input, 'list'),
+            search: (input) => this.page(input, 'search'),
+            stat: async (input) => {
+                const draft = await this.draft(input);
+                return draft && draft.status !== 'committed'
+                    ? this.receipt(draft)
+                    : files.stat(this.saved(input, draft));
+            },
+            readWindow: async (input) => {
+                const draft = await this.draft(input);
+                if (!draft || draft.status === 'committed')
+                    return files.readWindow(this.saved(input, draft));
+                const page = await workflow.read({
+                    draftId: draft.id,
+                    offset: input.offset,
+                    signal: input.signal,
+                });
+                if (page.size !== draft.size)
+                    this.conflict();
+                return {
+                    ...this.receipt(draft),
+                    content: page.content,
+                    offset: page.offset,
+                    nextOffset: page.nextOffset,
+                    totalBytes: page.size,
+                };
+            },
+            readStream: async (input) => {
+                const draft = await this.draft(input);
+                if (!draft || draft.status === 'committed')
+                    return files.readStream(this.saved(input, draft));
+                const stream = await workflow.readStream({
+                    draftId: draft.id,
+                    expectedSize: draft.size,
+                    start: input.start,
+                    end: input.end,
+                    signal: input.signal,
+                });
+                return { ...this.receipt(draft), body: stream.body };
+            },
+            searchContent: async (input) => {
+                const draft = await this.draft(input);
+                if (!draft || draft.status === 'committed')
+                    return files.searchContent(this.saved(input, draft));
+                return workflow.searchText({
+                    draftId: draft.id,
+                    expectedSize: draft.size,
+                    query: input.query,
+                    offset: input.offset,
+                    signal: input.signal,
+                });
+            },
+            write: (input) => this.write(input),
+            edit: async (input) => {
+                this.requireWrite();
+                const changes = input.change.kind === 'batch' ? input.change.changes : [input.change];
+                this.textLimit(changes
+                    .map((change) => change.kind === 'append'
+                    ? change.text
+                    : change.oldText + change.newText)
+                    .join(''));
+                const prior = await workflow.lookup({
+                    idempotencyKey: input.commandId,
+                    signal: input.signal,
+                });
+                const source = prior?.sourceDraftId
+                    ? await workflow.read({
+                        draftId: prior.sourceDraftId,
+                        signal: input.signal,
+                    })
+                    : await this.draft(input);
+                if (!source || (!prior && source.status === 'committed')) {
+                    const saved = this.saved(input, source);
+                    const result = await workflow.stageStream({
+                        path: input.path,
+                        expectedEtag: saved.expectedEtag,
+                        text: true,
+                        signal: input.signal,
+                        idempotencyKey: input.commandId,
+                        contentIdentity: createHash('sha256')
+                            .update(JSON.stringify([
+                            'catalog-edit',
+                            input.path,
+                            input.expectedEtag,
+                            changes,
+                        ]))
+                            .digest('hex'),
+                        body: async () => {
+                            const stream = await files.readStream(saved);
+                            return editStorageTextStream(stream.body, changes, {
+                                maxEditBytes: files.limits.maxWriteBytes,
+                                maxEdits: workflow.limits.maxEdits,
+                                ...(input.signal ? { signal: input.signal } : {}),
+                            });
+                        },
+                    });
+                    return this.result(result);
+                }
+                const result = await workflow.reviseText({
+                    draftId: source.id,
+                    expectedSize: source.size,
+                    changes,
+                    requestIdentity: JSON.stringify([input.path, input.expectedEtag]),
+                    idempotencyKey: input.commandId,
+                    signal: input.signal,
+                });
+                // The workflow fingerprint includes the source, but the host also fences its public path.
+                if (result.path !== input.path)
+                    this.conflict();
+                return this.result(result);
+            },
+        });
+    }
+    async write(input) {
+        this.requireWrite();
+        this.textLimit(input.content);
+        const prior = await this.workflow.lookup({
+            idempotencyKey: input.commandId,
+            signal: input.signal,
+        });
+        let source = prior?.sourceDraftId
+            ? await this.workflow.read({
+                draftId: prior.sourceDraftId,
+                signal: input.signal,
+            })
+            : null;
+        let originalEtag = prior?.expectedEtag ?? undefined;
+        if (!prior) {
+            source = await this.draft(input);
+            const saved = this.saved(input, source);
+            if (input.expectedEtag === undefined) {
+                if (source)
+                    this.conflict();
+                try {
+                    await this.files.stat(input);
+                    this.conflict();
+                }
+                catch (error) {
+                    if (!isStorageError(error) || error.code !== 'NOT_FOUND')
+                        throw error;
+                }
+            }
+            else if (!source || source.status === 'committed') {
+                const file = await this.files.stat(saved);
+                if (file.etag !== saved.expectedEtag)
+                    this.conflict();
+            }
+            if (source?.status === 'committed')
+                source = null;
+            originalEtag = source
+                ? (source.expectedEtag ?? undefined)
+                : saved.expectedEtag;
+        }
+        const bytes = new TextEncoder().encode(input.content);
+        const result = await this.workflow.stageStream({
+            path: input.path,
+            text: true,
+            idempotencyKey: input.commandId,
+            expectedEtag: originalEtag,
+            contentIdentity: createHash('sha256')
+                .update(JSON.stringify([input.expectedEtag ?? null, input.content]))
+                .digest('hex'),
+            body: () => storageBytesStream(bytes),
+            signal: input.signal,
+            ...(source
+                ? { sourceDraftId: source.id, expectedSize: source.size }
+                : {}),
+        });
+        return this.result(result);
+    }
+    /** Resolve an exact candidate (including committed replay) or the unique unfinished leaf. */
+    async draft(input) {
+        if (!this.files.allows('read'))
+            this.denied();
+        if (input.expectedEtag !== undefined) {
+            try {
+                const draft = await this.workflow.read({
+                    draftId: input.expectedEtag,
+                    signal: input.signal,
+                });
+                if (draft.path !== input.path || draft.status === 'cancelled')
+                    this.conflict();
+                return draft;
+            }
+            catch (error) {
+                if (!isStorageError(error) || error.code !== 'NOT_FOUND')
+                    throw error;
+                return null;
+            }
+        }
+        const matches = (await this.pending(input)).filter((draft) => draft.path === input.path);
+        if (matches.length > 1)
+            throw new StorageError('Several unfinished revisions exist. Read an exact listed ETag before editing.', { code: 'CONFLICT' });
+        return matches[0] ?? null;
+    }
+    /** Discovery derives from persisted lineage, so process restarts need no local registry. */
+    async pending(input) {
+        if (!this.files.allows('read'))
+            this.denied();
+        const drafts = [];
+        let offset = 0;
+        do {
+            const page = await this.workflow.list({ offset, signal: input.signal });
+            drafts.push(...page.items);
+            if (page.nextOffset !== null && page.nextOffset <= offset)
+                throw new StorageError('Invalid draft pagination.', {
+                    code: 'PROVIDER',
+                });
+            offset = page.nextOffset;
+        } while (offset !== null);
+        const predecessors = new Set(drafts.flatMap((draft) => draft.status !== 'cancelled' && draft.sourceDraftId
+            ? [draft.sourceDraftId]
+            : []));
+        return drafts.filter((draft) => ['open', 'sealed'].includes(draft.status) &&
+            !predecessors.has(draft.id));
+    }
+    async page(input, mode) {
+        const offset = input.offset ?? 0;
+        storageInteger(offset, 'offset', 0);
+        const pending = await this.pending(input);
+        const paths = new Set(pending.map((draft) => draft.path));
+        const items = [];
+        const savedByPath = new Map();
+        let cursor = 0;
+        do {
+            const page = mode === 'list'
+                ? await this.files.list({ ...input, offset: cursor })
+                : await this.files.search({
+                    ...input,
+                    query: input.query,
+                    offset: cursor,
+                });
+            for (const file of page.items)
+                savedByPath.set(file.path, file);
+            items.push(...page.items.filter((file) => !paths.has(file.path)));
+            if (page.nextOffset !== null && page.nextOffset <= cursor)
+                throw new StorageError('Invalid catalog pagination.', {
+                    code: 'PROVIDER',
+                });
+            cursor = page.nextOffset;
+        } while (cursor !== null);
+        const directory = input.directory?.replace(/\/$/u, '');
+        items.push(...pending
+            .filter((draft) => mode === 'search'
+            ? draft.path.toLowerCase().includes(input.query.toLowerCase())
+            : !directory ||
+                directory === '.' ||
+                draft.path.startsWith(`${directory}/`))
+            .map((draft) => ({
+            ...savedByPath.get(draft.path),
+            ...this.receipt(draft),
+        })));
+        items.sort((a, b) => a.path.localeCompare(b.path) || a.etag.localeCompare(b.etag));
+        const next = offset + this.files.limits.maxPageSize;
+        return {
+            items: items.slice(offset, next),
+            nextOffset: next < items.length ? next : null,
+        };
+    }
+    saved(input, draft) {
+        if (draft?.status !== 'committed')
+            return input;
+        if (!draft.result || draft.result.path !== input.path)
+            this.conflict();
+        return { ...input, expectedEtag: draft.result.etag };
+    }
+    result(draft) {
+        if (draft.status === 'cancelled')
+            this.conflict();
+        if (draft.status === 'committed') {
+            if (!draft.result)
+                this.conflict();
+            return draft.result;
+        }
+        return this.receipt(draft);
+    }
+    receipt(draft) {
+        return {
+            path: draft.path,
+            fileId: draft.id,
+            etag: draft.id,
+            size: draft.size,
+            contentType: draft.text ? 'text/plain' : 'application/octet-stream',
+            operation: draft.expectedEtag === null ? 'created' : 'updated',
+            pending: true,
+        };
+    }
+    textLimit(text) {
+        if (/[\uD800-\uDFFF]/u.test(text))
+            throw new StorageError('Text must be well-formed UTF-8.', {
+                code: 'INVALID_ARGUMENT',
+            });
+        if (new TextEncoder().encode(text).byteLength >
+            this.files.limits.maxWriteBytes)
+            throw new StorageError('Write exceeds the per-call text limit.', {
+                code: 'LIMIT_EXCEEDED',
+            });
+    }
+    requireWrite() {
+        if (!this.files.allows('write'))
+            this.denied();
+    }
+    denied() {
+        throw new StorageError('Working file operation is not permitted.', {
+            code: 'UNAUTHORIZED',
+        });
+    }
+    conflict() {
+        throw new StorageError('The working file revision changed. Read the current file before editing.', { code: 'CONFLICT' });
+    }
+}
+//# sourceMappingURL=storage-working-files.js.map

package/dist/workspace/storage-working-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-working-files.js","sourceRoot":"","sources":["../../src/workspace/storage-working-files.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport { StorageError, isStorageError } from '../storage.error.js';\nimport { storageBytesStream, storageInteger } from '../core/storage-streams.js';\nimport { editStorageTextStream } from '../core/storage-text-stream-edit.js';\nimport type {\n  StorageFileCatalogCapability,\n  StorageCatalogFile,\n  StorageCatalogPath,\n  StorageCatalogCommand,\n  StorageCatalogPage,\n} from './storage-file-catalog.types.js';\nimport type {\n  StorageFileDraft,\n  StorageFileWorkflowCapability,\n  StorageFileWorkflowOperation,\n  StorageFileWorkflowPage,\n} from './storage-file-workflow.types.js';\n\nexport interface StorageWorkingFile extends StorageCatalogFile {\n  readonly operation: 'created' | 'updated';\n  readonly pending: true;\n}\nexport interface StorageWorkingFileReceipt {\n  readonly path: string;\n  readonly etag: string;\n  readonly size: number;\n}\n\n/** A path-based editing view over durable checkpoints. Saved heads change only on commit. */\nexport class StorageWorkingFiles<Receipt extends StorageWorkingFileReceipt> {\n  readonly catalog: StorageFileCatalogCapability<Receipt | StorageWorkingFile>;\n  constructor(\n    readonly files: StorageFileCatalogCapability<Receipt>,\n    readonly workflow: StorageFileWorkflowCapability<Receipt>,\n  ) {\n    this.catalog = Object.freeze<\n      StorageFileCatalogCapability<Receipt | StorageWorkingFile>\n    >({\n      ...files,\n      list: (input) => this.page(input, 'list'),\n      search: (input) => this.page(input, 'search'),\n      stat: async (input) => {\n        const draft = await this.draft(input);\n        return draft && draft.status !== 'committed'\n          ? this.receipt(draft)\n          : files.stat(this.saved(input, draft));\n      },\n      readWindow: async (input) => {\n        const draft = await this.draft(input);\n        if (!draft || draft.status === 'committed')\n          return files.readWindow(this.saved(input, draft));\n        const page = await workflow.read({\n          draftId: draft.id,\n          offset: input.offset,\n          signal: input.signal,\n        });\n        if (page.size !== draft.size) this.conflict();\n        return {\n          ...this.receipt(draft),\n          content: page.content,\n          offset: page.offset,\n          nextOffset: page.nextOffset,\n          totalBytes: page.size,\n        };\n      },\n      readStream: async (input) => {\n        const draft = await this.draft(input);\n        if (!draft || draft.status === 'committed')\n          return files.readStream(this.saved(input, draft));\n        const stream = await workflow.readStream({\n          draftId: draft.id,\n          expectedSize: draft.size,\n          start: input.start,\n          end: input.end,\n          signal: input.signal,\n        });\n        return { ...this.receipt(draft), body: stream.body };\n      },\n      searchContent: async (input) => {\n        const draft = await this.draft(input);\n        if (!draft || draft.status === 'committed')\n          return files.searchContent(this.saved(input, draft));\n        return workflow.searchText({\n          draftId: draft.id,\n          expectedSize: draft.size,\n          query: input.query,\n          offset: input.offset,\n          signal: input.signal,\n        });\n      },\n      write: (input) => this.write(input),\n      edit: async (input) => {\n        this.requireWrite();\n        const changes =\n          input.change.kind === 'batch' ? input.change.changes : [input.change];\n        this.textLimit(\n          changes\n            .map((change) =>\n              change.kind === 'append'\n                ? change.text\n                : change.oldText + change.newText,\n            )\n            .join(''),\n        );\n        const prior = await workflow.lookup({\n          idempotencyKey: input.commandId,\n          signal: input.signal,\n        });\n        const source: StorageFileDraft<Receipt> | null = prior?.sourceDraftId\n          ? await workflow.read({\n              draftId: prior.sourceDraftId,\n              signal: input.signal,\n            })\n          : await this.draft(input);\n        if (!source || (!prior && source.status === 'committed')) {\n          const saved = this.saved(input, source);\n          const result = await workflow.stageStream({\n            path: input.path,\n            expectedEtag: saved.expectedEtag,\n            text: true,\n            signal: input.signal,\n            idempotencyKey: input.commandId,\n            contentIdentity: createHash('sha256')\n              .update(\n                JSON.stringify([\n                  'catalog-edit',\n                  input.path,\n                  input.expectedEtag,\n                  changes,\n                ]),\n              )\n              .digest('hex'),\n            body: async () => {\n              const stream = await files.readStream(saved);\n              return editStorageTextStream(stream.body, changes, {\n                maxEditBytes: files.limits.maxWriteBytes,\n                maxEdits: workflow.limits.maxEdits,\n                ...(input.signal ? { signal: input.signal } : {}),\n              });\n            },\n          });\n          return this.result(result);\n        }\n        const result = await workflow.reviseText({\n          draftId: source.id,\n          expectedSize: source.size,\n          changes,\n          requestIdentity: JSON.stringify([input.path, input.expectedEtag]),\n          idempotencyKey: input.commandId,\n          signal: input.signal,\n        });\n        // The workflow fingerprint includes the source, but the host also fences its public path.\n        if (result.path !== input.path) this.conflict();\n        return this.result(result);\n      },\n    });\n  }\n\n  async write(\n    input: StorageCatalogCommand & { readonly content: string },\n  ): Promise<Receipt | StorageWorkingFile> {\n    this.requireWrite();\n    this.textLimit(input.content);\n    const prior = await this.workflow.lookup({\n      idempotencyKey: input.commandId,\n      signal: input.signal,\n    });\n    let source: StorageFileDraft<Receipt> | null = prior?.sourceDraftId\n      ? await this.workflow.read({\n          draftId: prior.sourceDraftId,\n          signal: input.signal,\n        })\n      : null;\n    let originalEtag = prior?.expectedEtag ?? undefined;\n    if (!prior) {\n      source = await this.draft(input);\n      const saved = this.saved(input, source);\n      if (input.expectedEtag === undefined) {\n        if (source) this.conflict();\n        try {\n          await this.files.stat(input);\n          this.conflict();\n        } catch (error) {\n          if (!isStorageError(error) || error.code !== 'NOT_FOUND') throw error;\n        }\n      } else if (!source || source.status === 'committed') {\n        const file = await this.files.stat(saved);\n        if (file.etag !== saved.expectedEtag) this.conflict();\n      }\n      if (source?.status === 'committed') source = null;\n      originalEtag = source\n        ? (source.expectedEtag ?? undefined)\n        : saved.expectedEtag;\n    }\n    const bytes = new TextEncoder().encode(input.content);\n    const result = await this.workflow.stageStream({\n      path: input.path,\n      text: true,\n      idempotencyKey: input.commandId,\n      expectedEtag: originalEtag,\n      contentIdentity: createHash('sha256')\n        .update(JSON.stringify([input.expectedEtag ?? null, input.content]))\n        .digest('hex'),\n      body: () => storageBytesStream(bytes),\n      signal: input.signal,\n      ...(source\n        ? { sourceDraftId: source.id, expectedSize: source.size }\n        : {}),\n    });\n    return this.result(result);\n  }\n\n  /** Resolve an exact candidate (including committed replay) or the unique unfinished leaf. */\n  async draft(\n    input: StorageCatalogPath,\n  ): Promise<StorageFileDraft<Receipt> | null> {\n    if (!this.files.allows('read')) this.denied();\n    if (input.expectedEtag !== undefined) {\n      try {\n        const draft = await this.workflow.read({\n          draftId: input.expectedEtag,\n          signal: input.signal,\n        });\n        if (draft.path !== input.path || draft.status === 'cancelled')\n          this.conflict();\n        return draft;\n      } catch (error) {\n        if (!isStorageError(error) || error.code !== 'NOT_FOUND') throw error;\n        return null;\n      }\n    }\n    const matches = (await this.pending(input)).filter(\n      (draft) => draft.path === input.path,\n    );\n    if (matches.length > 1)\n      throw new StorageError(\n        'Several unfinished revisions exist. Read an exact listed ETag before editing.',\n        { code: 'CONFLICT' },\n      );\n    return matches[0] ?? null;\n  }\n\n  /** Discovery derives from persisted lineage, so process restarts need no local registry. */\n  async pending(\n    input: StorageFileWorkflowOperation,\n  ): Promise<StorageFileDraft<Receipt>[]> {\n    if (!this.files.allows('read')) this.denied();\n    const drafts: StorageFileDraft<Receipt>[] = [];\n    let offset: number | null = 0;\n    do {\n      const page = await this.workflow.list({ offset, signal: input.signal });\n      drafts.push(...page.items);\n      if (page.nextOffset !== null && page.nextOffset <= offset)\n        throw new StorageError('Invalid draft pagination.', {\n          code: 'PROVIDER',\n        });\n      offset = page.nextOffset;\n    } while (offset !== null);\n    const predecessors = new Set(\n      drafts.flatMap((draft) =>\n        draft.status !== 'cancelled' && draft.sourceDraftId\n          ? [draft.sourceDraftId]\n          : [],\n      ),\n    );\n    return drafts.filter(\n      (draft) =>\n        ['open', 'sealed'].includes(draft.status) &&\n        !predecessors.has(draft.id),\n    );\n  }\n\n  private async page(\n    input: StorageCatalogPage & {\n      directory?: string | undefined;\n      query?: string;\n    },\n    mode: 'list' | 'search',\n  ) {\n    const offset = input.offset ?? 0;\n    storageInteger(offset, 'offset', 0);\n    const pending = await this.pending(input);\n    const paths = new Set(pending.map((draft) => draft.path));\n    const items: StorageCatalogFile[] = [];\n    const savedByPath = new Map<string, StorageCatalogFile>();\n    let cursor: number | null = 0;\n    do {\n      const page: StorageFileWorkflowPage<StorageCatalogFile> =\n        mode === 'list'\n          ? await this.files.list({ ...input, offset: cursor })\n          : await this.files.search({\n              ...input,\n              query: input.query!,\n              offset: cursor,\n            });\n      for (const file of page.items) savedByPath.set(file.path, file);\n      items.push(...page.items.filter((file) => !paths.has(file.path)));\n      if (page.nextOffset !== null && page.nextOffset <= cursor)\n        throw new StorageError('Invalid catalog pagination.', {\n          code: 'PROVIDER',\n        });\n      cursor = page.nextOffset;\n    } while (cursor !== null);\n    const directory = input.directory?.replace(/\\/$/u, '');\n    items.push(\n      ...pending\n        .filter((draft) =>\n          mode === 'search'\n            ? draft.path.toLowerCase().includes(input.query!.toLowerCase())\n            : !directory ||\n              directory === '.' ||\n              draft.path.startsWith(`${directory}/`),\n        )\n        .map((draft) => ({\n          ...savedByPath.get(draft.path),\n          ...this.receipt(draft),\n        })),\n    );\n    items.sort(\n      (a, b) => a.path.localeCompare(b.path) || a.etag.localeCompare(b.etag),\n    );\n    const next = offset + this.files.limits.maxPageSize;\n    return {\n      items: items.slice(offset, next),\n      nextOffset: next < items.length ? next : null,\n    };\n  }\n  private saved<T extends StorageCatalogPath>(\n    input: T,\n    draft: StorageFileDraft<Receipt> | null,\n  ): T {\n    if (draft?.status !== 'committed') return input;\n    if (!draft.result || draft.result.path !== input.path) this.conflict();\n    return { ...input, expectedEtag: draft.result.etag };\n  }\n  private result(\n    draft: StorageFileDraft<Receipt>,\n  ): Receipt | StorageWorkingFile {\n    if (draft.status === 'cancelled') this.conflict();\n    if (draft.status === 'committed') {\n      if (!draft.result) this.conflict();\n      return draft.result;\n    }\n    return this.receipt(draft);\n  }\n  private receipt(draft: StorageFileDraft<Receipt>): StorageWorkingFile {\n    return {\n      path: draft.path,\n      fileId: draft.id,\n      etag: draft.id,\n      size: draft.size,\n      contentType: draft.text ? 'text/plain' : 'application/octet-stream',\n      operation: draft.expectedEtag === null ? 'created' : 'updated',\n      pending: true,\n    };\n  }\n  private textLimit(text: string) {\n    if (/[\\uD800-\\uDFFF]/u.test(text))\n      throw new StorageError('Text must be well-formed UTF-8.', {\n        code: 'INVALID_ARGUMENT',\n      });\n    if (\n      new TextEncoder().encode(text).byteLength >\n      this.files.limits.maxWriteBytes\n    )\n      throw new StorageError('Write exceeds the per-call text limit.', {\n        code: 'LIMIT_EXCEEDED',\n      });\n  }\n  private requireWrite() {\n    if (!this.files.allows('write')) this.denied();\n  }\n  private denied(): never {\n    throw new StorageError('Working file operation is not permitted.', {\n      code: 'UNAUTHORIZED',\n    });\n  }\n  private conflict(): never {\n    throw new StorageError(\n      'The working file revision changed. Read the current file before editing.',\n      { code: 'CONFLICT' },\n    );\n  }\n}\n"]}

package/dist/workspace/storage-workspace.cursor.d.ts

@@ -0,0 +1,71 @@
+import type { StorageWorkspaceLimits, StorageWorkspaceSearchMatch } from './storage-workspace.types.js';
+export declare const STORAGE_WORKSPACE_CURSOR_VERSION: 1;
+export declare const STORAGE_WORKSPACE_MAX_CURSOR_BYTES = 4096;
+export interface StorageWorkspaceCursorEncodeOptions {
+    /** Absolute Unix timestamp in milliseconds used by durable stores for TTL. */
+    readonly expiresAt: number;
+}
+/**
+ * Server-side opaque cursor contract. Implementations must either authenticate
+ * and encrypt payloads or keep them behind a shared durable random token.
+ * Tokens use only `[A-Za-z0-9._-]`, are at most 4,096 bytes, and `decode` must
+ * be non-destructive so the same token remains replayable until its authenticated
+ * expiry. Durable stores must expire records at `options.expiresAt` and read
+ * rather than consume them. Missing or expired records should fail with
+ * `StorageErrorCode.NOT_FOUND` or `StorageErrorCode.INVALID_ARGUMENT`;
+ * availability failures retain their operational storage error code.
+ */
+export interface StorageWorkspaceCursorCodec {
+    encode(payload: Uint8Array, options: StorageWorkspaceCursorEncodeOptions): Promise<string> | string;
+    decode(token: string): Promise<Uint8Array> | Uint8Array;
+}
+export interface StorageWorkspaceCursorConfiguration {
+    /** Codec shared by every replica that serves this logical mount. */
+    readonly codec: StorageWorkspaceCursorCodec;
+    /** Stable server-derived mount or binding identity. */
+    readonly mountId: string;
+    /** Stable trusted tenant/workspace scope. */
+    readonly scope: string;
+}
+export interface Aes256GcmStorageWorkspaceCursorCodecOptions {
+    /** Key used for newly issued cursors. */
+    readonly activeKeyId: string;
+    /** Decryption key ring. Retain rotated keys for at least one cursor TTL. */
+    readonly keys: Readonly<Record<string, Uint8Array>>;
+}
+/** Stateless AES-256-GCM cursor codec suitable for shared multi-replica use. */
+export declare class Aes256GcmStorageWorkspaceCursorCodec implements StorageWorkspaceCursorCodec {
+    #private;
+    constructor(options: Aes256GcmStorageWorkspaceCursorCodecOptions);
+    encode(payload: Uint8Array, options: StorageWorkspaceCursorEncodeOptions): string;
+    decode(token: string): Uint8Array;
+}
+interface StorageWorkspaceCursorBinding {
+    readonly limits: Readonly<StorageWorkspaceLimits>;
+    readonly prefix: string;
+    readonly store: string;
+}
+export interface StorageWorkspaceListCursorData {
+    readonly backendCursor: string;
+    readonly directory: string;
+    readonly limit: number;
+    readonly operation: 'list';
+    readonly recursive: boolean;
+}
+export interface StorageWorkspaceSearchCursorData {
+    readonly backendCursor: string;
+    readonly caseInsensitive: boolean;
+    readonly directory: string;
+    readonly limit: number;
+    readonly match: StorageWorkspaceSearchMatch;
+    readonly operation: 'search';
+    readonly query: string;
+    readonly scanned: number;
+}
+export type StorageWorkspaceCursorData = StorageWorkspaceListCursorData | StorageWorkspaceSearchCursorData;
+export declare function resolveStorageWorkspaceCursorConfiguration(configuration: StorageWorkspaceCursorConfiguration | undefined): Readonly<StorageWorkspaceCursorConfiguration> | undefined;
+export declare function issueStorageWorkspaceCursor(configuration: Readonly<StorageWorkspaceCursorConfiguration> | undefined, binding: StorageWorkspaceCursorBinding, cursor: StorageWorkspaceCursorData): Promise<string>;
+export declare function decodeStorageWorkspaceCursor(configuration: Readonly<StorageWorkspaceCursorConfiguration> | undefined, binding: StorageWorkspaceCursorBinding, operation: 'list', token: string): Promise<StorageWorkspaceListCursorData>;
+export declare function decodeStorageWorkspaceCursor(configuration: Readonly<StorageWorkspaceCursorConfiguration> | undefined, binding: StorageWorkspaceCursorBinding, operation: 'search', token: string): Promise<StorageWorkspaceSearchCursorData>;
+export {};
+//# sourceMappingURL=storage-workspace.cursor.d.ts.map

package/dist/workspace/storage-workspace.cursor.d.ts.map

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