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

package/README.md

@@ -1,15 +1,15 @@
 # @nestm/storage
 
 Framework-neutral storage clients with NestJS 12 integration, named stores,
-explicit streaming I/O, cross-store workflows, and an optional guarded HTTP
-gateway.
+explicit streaming I/O, capability-scoped agent workspaces, cross-store
+workflows, and an optional guarded HTTP gateway.
 
 The package uses [`files-sdk`](https://github.com/haydenbleasel/files-sdk) as
 its provider engine, but owns the API injected into Nest applications. Provider
 SDK types, errors, and `files.raw` do not leak through the root package.
 
-> This package targets the NestJS 12 prerelease line and is itself published on
-> the `alpha` dist-tag.
+> This package targets stable NestJS 12 and is itself published on the `alpha`
+> dist-tag.
 
 ## Requirements
 
@@ -17,17 +17,32 @@ SDK types, errors, and `files.raw` do not leak through the root package.
 - ESM
 
 The framework-neutral `@nestm/storage/core` entry point does not require
-NestJS. The root entry point and HTTP gateway additionally require NestJS
-`12.0.0-alpha.5` or newer in the Nest 12 prerelease line, `reflect-metadata`,
-and RxJS. Those framework peers are optional at installation time so core-only
-consumers do not download NestJS.
+NestJS. The root entry point and HTTP gateway additionally require NestJS 12,
+`reflect-metadata`, and RxJS. Those framework peers are optional at installation
+time so core-only consumers do not download NestJS.
 
 ## Install
 
 ```sh
-pnpm add @nestm/storage@alpha files-sdk@2.2.2
+pnpm add @nestm/storage@alpha
 ```
 
+The package-owned S3 factory needs no direct `files-sdk` import. Install the
+pinned engine explicitly only when the application imports another adapter
+such as `files-sdk/gcs`:
+
+```sh
+pnpm add files-sdk@2.3.0
+```
+
+Pass AWS-SDK-backed S3 adapters through the package-owned `s3()` and
+`withS3Capabilities()` helpers (or use `createS3StorageDriver()`).
+`createFilesSdkDriver()` rejects a structurally S3-backed raw adapter that has
+not crossed this provenance boundary, even when a wrapper renames or proxies
+the adapter. This prevents callers from bypassing endpoint and provider-profile
+checks by omitting the capability decorator or replacing the public `raw`
+property while retaining methods closed over the original client.
+
 Install only the native SDKs required by the chosen provider. For example:
 
 ```sh
@@ -42,15 +57,15 @@ pnpm add @google-cloud/storage google-auth-library
 pnpm add @azure/storage-blob @azure/core-auth @azure/identity
 ```
 
+`@aws-sdk/client-s3` 3.1079.0 or newer is required, matching the Files SDK 2.3
+peer floor. The supported range includes destination `If-Match` and
+`If-None-Match` serialization for `CopyObject`; the package peer range and
+packed minimum-peer smoke test enforce this floor.
+
 `files-sdk` currently declares its optional Nest peer for Nest 10 and 11. This
 library does not import `files-sdk/nestjs`; the Nest 12 integration is entirely
 owned here. A package manager may nevertheless report that temporary optional
-peer mismatch while Nest 12 remains prerelease.
-
-NestJS 12 alpha also has prerelease peer declarations that npm may reject under
-its strict resolver. If npm reports an `ERESOLVE` error for Nest's own peers,
-install with `npm install --legacy-peer-deps`; pnpm works with the repository's
-checked-in peer-version policy.
+peer mismatch until Files SDK widens its declaration to include Nest 12.
 
 ## Framework-neutral core
 
@@ -80,16 +95,558 @@ storage errors and operation types, and `StorageUploadControl`. It has no NestJS
 runtime or declaration imports. Provider adapters remain available through
 `@nestm/storage/files-sdk`.
 
+## Mounted agent workspaces
+
+`@nestm/storage/workspace` turns a `StorageClient` into a narrow capability for
+one logical directory. The mount is virtual: the same API works over S3, a
+filesystem driver, or another storage backend without exposing the provider,
+bucket, filesystem root, raw cursor, or internal prefix to its caller.
+
+```mermaid
+flowchart LR
+  A["Trusted application context"] -->|"store + opaque prefix + policy"| W["StorageWorkspace"]
+  W --> C["StorageClient"]
+  C --> D["S3 / filesystem / other driver"]
+  W --> T["AI SDK workspace tools"]
+  T --> G["ToolLoopAgent"]
+```
+
+Only trusted application code chooses the mount prefix. Every path accepted by
+the workspace is a canonical, relative POSIX path. Absolute paths, backslashes,
+control characters, repeated separators, and `.` or `..` segments are rejected
+rather than normalized. Keys and provider cursors returned by a driver are also
+checked before they are converted back to logical paths.
+
+Pagination requires a server-owned cursor configuration. The built-in
+`Aes256GcmStorageWorkspaceCursorCodec` produces versioned, authenticated,
+encrypted tokens that can resume on another request, process, or replica when
+every replica constructs an equivalent codec from the same key ring and uses
+the same stable store identity, physical prefix, mount ID, trusted scope, and
+effective limits. Use one codec instance per process, use a dedicated 32-byte
+key, retain rotated decryption keys for at least one cursor TTL, and derive
+`mountId` and `scope` only from authenticated server context.
+
+The underlying driver must also implement the universal replayable list-cursor
+contract against the same logical backend namespace: its cursor cannot be
+consumed or tied to one driver instance. While the provider cursor remains
+valid and available, an outer cursor can be retried until its authenticated
+expiry. That expiry is only an authorization ceiling: it does not extend a
+provider token's lifetime or promise snapshot isolation, provider availability,
+network access, or valid credentials. Provider invalidation is an operational
+list failure, and concurrent object changes remain subject to provider
+continuation semantics. Without a codec, single-page operations still work but
+a continuation fails closed.
+
+```ts
+import {
+  Aes256GcmStorageWorkspaceCursorCodec,
+  mountStorageWorkspace,
+} from '@nestm/storage/workspace';
+
+// cursorKey is a separately validated 32-byte secret from deployment config.
+const cursorCodec = new Aes256GcmStorageWorkspaceCursorCodec({
+  activeKeyId: 'v1',
+  keys: { v1: cursorKey },
+});
+
+const workspace = mountStorageWorkspace(agentFiles, {
+  // Use an opaque server-derived run id, never a value selected by the model.
+  prefix: `workspaces/${runId}`,
+  cursor: {
+    codec: cursorCodec,
+    mountId: `agent-workspace:${runId}`,
+    scope: `organization:${organizationId}/workspace:${workspaceId}`,
+  },
+  permissions: [
+    'list',
+    'read',
+    'search',
+    'write',
+    'create',
+    'replace',
+    'copy',
+    'move',
+    'delete',
+  ],
+  limits: {
+    cursorTtlMs: 5 * 60 * 1000,
+    maxCursorBytes: 4096,
+    maxReadBytes: 1024 * 1024,
+    maxWriteBytes: 1024 * 1024,
+    maxPageSize: 100,
+    maxSearchResults: 100,
+    maxSearchScan: 1000,
+  },
+});
+
+const created = await workspace.writeFile(
+  'src/main.ts',
+  'export const ready = true;\n',
+  { mode: 'create', contentType: 'text/typescript' },
+);
+
+if (created.etag === undefined) {
+  throw new Error('This backend cannot safely replace the object.');
+}
+
+await workspace.writeFile('src/main.ts', 'export const ready = false;\n', {
+  mode: 'replace',
+  etag: created.etag,
+  contentType: 'text/typescript',
+});
+
+const image = await workspace.readBytes('assets/logo.png');
+console.log(image.bytes.byteLength);
+```
+
+`readBytes` is now a required member of the exported `StorageWorkspace`
+interface. Workspaces returned by `mountStorageWorkspace` provide it
+automatically; custom implementations and typed test doubles must add the
+method when adopting this alpha minor.
+
+Create, replace, and delete are conditional operations. A driver that cannot
+enforce the requested not-exists or ETag precondition fails with
+`NOT_SUPPORTED`; the workspace never substitutes an `exists()`/`head()` check
+followed by an unconditional mutation. Reads enforce their byte ceiling while
+consuming the stream, and list/search results are bounded. Search supports
+exact, substring, and workspace-coordinate glob matching, but no caller-supplied
+regular expressions.
+
+Move is implemented as create-only copy followed by ETag-conditional source
+delete. If source deletion cannot be confirmed, the destination is retained and
+the call returns `CONFLICT`; inspect both logical paths before retrying. This
+preserves at least one copy across provider timeouts and post-operation hook
+failures, but does not pretend a multi-object move is transactionally atomic.
+
+Callers that prefer the ordinary Files pipeline can opt into explicit
+last-write-wins variants. The `write` permission is separate from conditional
+`create` and `replace` authority:
+
+```ts
+await workspace.writeFile('notes.txt', 'latest contents', {
+  mode: 'overwrite',
+});
+await workspace.copyFile('notes.txt', 'backup.txt', { mode: 'overwrite' });
+await workspace.deleteFile('backup.txt', { mode: 'unconditional' });
+```
+
+Overwrite copy reads the latest source through the ordinary download pipeline,
+enforces `maxWriteBytes` while collecting it, and uploads it through the
+ordinary upload pipeline. It never substitutes the provider's server-side
+copy. These paths compose with Files SDK plugins, hooks, and receipts, including
+the built-in `encryption()` plugin. That plugin is useful compatibility
+evidence, not an Artifact-specific security policy: strict encrypted-only
+reads, tenant/path-bound AAD, key custody and rotation, and copy/move rules
+remain application-owned.
+
+Move remains conditional-only. A last-write-wins download/upload/delete
+sequence could copy one source generation and then delete a newer generation
+written during the transfer. Use the ETag-conditional `moveFile` variant when a
+move is required.
+
+A child mount may further restrict a directory, permissions, or limits, but it
+cannot widen any of them:
+
+```ts
+const readOnlySource = workspace.mount('src', {
+  permissions: ['list', 'read', 'search'],
+  limits: { maxReadBytes: 256 * 1024 },
+});
+```
+
+### AI SDK and NestJS composition
+
+Install AI SDK 7 and Zod only in applications that use the optional adapter:
+
+```sh
+pnpm add ai@^7 zod@^4
+```
+
+`files-sdk` 2.3.x still declares an optional `ai@^6` peer for its own adapter,
+so some package managers may print a peer warning when AI SDK 7 is installed.
+This package does not import that adapter; `@nestm/storage/ai-sdk` targets AI
+SDK 7 directly.
+
+`@nestm/storage/ai-sdk` converts an already-mounted workspace to an ordinary
+upstream `ToolSet`. It does not import NestJS or `@nestm/ai-sdk`; the application
+composes the tool set through the AI module's existing named-toolset factory.
+For a tenant or run selected per request, make both factories request-scoped and
+derive the mount coordinate from authenticated host context:
+
+```ts
+import { Module, Scope } from '@nestjs/common';
+import { AiSdkModule, AiSdkService, getAiToolsetToken } from '@nestm/ai-sdk';
+import { getStorageToken, type StorageClient } from '@nestm/storage';
+import { createAiSdkWorkspaceTools } from '@nestm/storage/ai-sdk';
+import { mountStorageWorkspace } from '@nestm/storage/workspace';
+import type { ToolSet } from 'ai';
+
+@Module({
+  imports: [
+    AppStorageModule,
+    WorkspaceContextModule,
+    AiSdkModule.forFeature({
+      imports: [AppStorageModule, WorkspaceContextModule],
+      toolsets: [
+        {
+          name: 'workspace',
+          scope: Scope.REQUEST,
+          inject: [getStorageToken('agent-files'), WorkspaceContext],
+          useFactory: (storage: StorageClient, context: WorkspaceContext) =>
+            createAiSdkWorkspaceTools({
+              workspace: mountStorageWorkspace(storage, {
+                // A validated, opaque coordinate from trusted auth/run state.
+                // It is never accepted from a prompt or tool input.
+                prefix: context.storagePrefix,
+                // Includes the singleton codec plus stable mountId and scope.
+                cursor: context.cursorConfiguration,
+                permissions: [
+                  'list',
+                  'read',
+                  'search',
+                  'write',
+                  'create',
+                  'replace',
+                  'copy',
+                  'move',
+                  'delete',
+                ],
+              }),
+            }),
+        },
+      ],
+      agents: [
+        {
+          name: 'workspace-agent',
+          scope: Scope.REQUEST,
+          inject: [AiSdkService, getAiToolsetToken('workspace')],
+          useFactory: (ai: AiSdkService, tools: ToolSet) => ({
+            model: ai.languageModel(),
+            instructions:
+              'Use only the mounted workspace tools for file operations.',
+            tools,
+          }),
+        },
+      ],
+    }),
+  ],
+})
+export class WorkspaceAgentModule {}
+```
+
+The generated set contains only tools allowed by the workspace permissions:
+bounded list, stat, UTF-8 read, and search tools plus conditional create,
+replace, copy, move, and delete tools when granted. Mutation tools require AI
+SDK user approval by default; approval can be configured per tool, but the
+workspace capability remains the authorization boundary even when approval is
+disabled. The module's `AiSdkService.files()` API is the model provider's file
+upload facility and is unrelated to storage workspaces.
+
+`mutationMode` defaults to `'conditional'`. A trusted composition can instead
+select `{ mutationMode: 'last-write-wins' }`; generated mutation schemas then
+omit ETags and modes, hardcode the explicit overwrite/unconditional workspace
+variants, and require `write` permission for destination mutations.
+Unconditional delete requires both `write` and `delete`. The move tool is
+omitted in last-write-wins mode because Workspace move remains conditional-only.
+
+Atomic create collisions remain sanitized tool errors by default. Applications
+that model an existing destination as a normal tool result can map that one
+case while preserving replace/ETag conflicts as failures:
+
+```ts
+const tools = createAiSdkWorkspaceTools({
+  workspace,
+  mapCreateConflict: ({ path }) => ({
+    kind: 'artifact-conflict' as const,
+    path,
+    status: 'already-exists' as const,
+  }),
+});
+```
+
+The mapper receives only the logical workspace path; provider errors, object
+keys, and mount coordinates are never exposed. `mapCreateConflict` is valid
+only in conditional mode and is rejected with last-write-wins mode.
+
+This logical confinement is sufficient for a `ToolLoopAgent` whose only file
+capabilities are these tools. It cannot constrain a coding harness that already
+has shell, `node:fs`, or subprocess access. For Codex/Claude-style harnesses,
+materialize the workspace into a per-session container or VM, mount only that
+directory, run the harness there, and synchronize reviewed changes back through
+`StorageWorkspace`. A working directory alone is not a sandbox.
+
+## Durable file workflows and catalog tools
+
+`@nestm/storage` owns byte mechanics and the draft state machine. The host owns
+logical file heads, authorization, persistence and transaction atomicity. No
+database, NestJS, tenant model or runtime lease is required by these contracts.
+
+| Entry point                | Exports                                                                                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nestm/storage/core`      | `StorageStagedContentStore`, `collectStorageBytes`, `storageBytesStream`, `readStorageTextWindow`, `searchStorageText`, `applyStorageTextEdit` and their types                              |
+| `@nestm/storage/workspace` | `StorageFileWorkflow`, draft/persistence/catalog contracts, `protectStorageFileWorkflowWorkspace`, `protectStorageFileWorkflowOperation`, `getStorageFileWorkflow`, `getStorageFileCatalog` |
+| `@nestm/storage/ai-sdk`    | `createAiSdkFileWorkflowTools`, `createAiSdkCatalogFileTools`, their options and tool-name constants; existing `createAiSdkWorkspaceTools` is unchanged                                     |
+| `@nestm/storage/bytes`     | Browser-safe `sha256StorageBytes`, `verifyStorageChunkReceipt`, `trimStorageUtf8Chunk`, `encodeStorageBase64`, `isStorageUtf8Blob`                                                          |
+
+```ts
+import { StorageStagedContentStore } from '@nestm/storage/core';
+import {
+  StorageFileWorkflow,
+  protectStorageFileWorkflowWorkspace,
+} from '@nestm/storage/workspace';
+import {
+  createAiSdkCatalogFileTools,
+  createAiSdkFileWorkflowTools,
+} from '@nestm/storage/ai-sdk';
+
+// These values are supplied by the host, never by the model.
+const content = new StorageStagedContentStore({
+  client,
+  key: (scope: HostScope, payloadId) => hostBodyKey(scope, payloadId),
+});
+const workflows = new StorageFileWorkflow({ content, persistence });
+const workspace = protectStorageFileWorkflowWorkspace({
+  workspace: hostCatalogWorkspace,
+  catalog: hostCatalog,
+  workflows: workflows.mount(trustedScope, {
+    permissions: ['read', 'write', 'commit'],
+    signal: executionSignal,
+  }),
+  signal: executionSignal,
+  authorize: ({ permission, signal }) =>
+    authorizeCurrentHostScope(trustedScope, permission, signal),
+});
+const tools = {
+  ...createAiSdkCatalogFileTools({
+    catalog: workspace.catalog!,
+    commandId: (toolCallId) => hostCommandId(toolCallId),
+  }),
+  ...createAiSdkFileWorkflowTools({
+    workflow: workspace.workflows,
+    idempotencyKey: (toolCallId) => hostCommandId(toolCallId),
+  }),
+};
+```
+
+The catalog delegate implements the existing `StorageWorkspace` against the
+host's logical catalog; do not pass a raw provider-prefix workspace alongside
+an unrelated file service. `StorageFileCatalogCapability` adds opaque file IDs,
+byte windows, literal content search and idempotent small write/edit commands.
+Its `commandId` is host-scoped, stable across retries, and compared against a
+canonical request fingerprint in host persistence. The host preserves its
+additional policy when a generic edit targets a specialized file.
+
+`createAiSdkCatalogFileEditSchemas(maxWriteBytes)` exposes typed append/edit
+Zod objects used by the generic factory itself. A host can `.extend()` these
+with an optional product-only metadata field while retaining the same UTF-8
+byte rules. Delegate ordinary input to the generic tool; dispatch specialized
+input through the same leased product capability and command identity. Do not
+cast an opaque tool schema or rebuild the generic schema locally.
+
+The protector retains the lease/caller signal and reauthorizes every call.
+Create-only base grants cannot replace or edit a catalog file. Workflow
+`restrict({ permissions, mutations, limits, signal })` intersects existing
+grants/ceilings and retains parent cancellation; it never changes scope. The
+protector restricts persisted draft mutations to the base create/replace grants,
+including resumed sealed drafts and replay, without requiring a public read
+grant to perform an otherwise authorized commit. Child mounts do
+not inherit broader catalog/workflow handles. Configure both delegates with the
+same scope and compatible limits; the host catalog must enforce scan budgets
+inside its implementation. Structured extensions on the returned workspace
+are supported: owning features can attach protected product closures while
+retaining the same `.catalog` and `.workflows` members. The structural getters
+are contract checks for trusted handles, not authentication of arbitrary objects.
+These static file operations acquire no lease themselves.
+
+### Host persistence transaction
+
+Implement `StorageFileWorkflowPersistence<Scope, Receipt>.transaction(scope,
+{ permission, signal }, work)`. On **every** call (including replay and body
+preparation reads), reauthorize that intent and serialize the scope's draft and
+idempotency records across replicas. `read` admits readers; `write` and `commit`
+must enforce the host's mutation authority. The callback receives detached
+records through `findDraftByKey`, `getDraft`, `saveDraft`, `listDrafts`,
+`listParts`, `putPart` and `commitHeads`.
+
+`commitHeads` receives sorted `{ draft, body }` changes. It must compare every
+create/expected-ETag predicate and change all logical heads **in the same host
+transaction** as the subsequent committed draft records and receipts. Return
+one non-null receipt per change in the supplied order. A rejection rolls back
+all callback effects. Serial object writes or independently committed database
+calls do not satisfy this port. The package does not claim to implement database
+atomicity. See the packed consumer fixture and filesystem e2e test for executable
+minimal hosts; production hosts need their own cross-replica transaction/locking
+implementation and rollback tests.
+
+Drafts transition `open → sealed → committed` or `open/sealed → cancelled`.
+Appends accept a bounded snapshot of bytes at the exact current byte offset.
+Identical offset/size/SHA-256 replay succeeds; changed bytes or gaps conflict.
+Text chunks must contain complete valid UTF-8. Public summaries and part receipts
+omit staged body IDs and provider keys. A commit seals all requested drafts,
+streams verified chunks into immutable bodies, then commits all heads and draft
+receipts in one host transaction. Failed preparation or stale heads leave sealed
+drafts retryable/cancellable. Mixed committed/uncommitted batches conflict;
+replaying an entirely committed batch returns its stored receipts after checking
+the requested size and optional digest. Cancellation cannot undo committed heads.
+
+Check the signal before durable transaction commit. After commit, return the
+receipt even if cancellation races the response. Do not automatically retry the
+transaction callback. A lost response requires replay/reconciliation, not an
+assumption of rollback. Provider writes happen before the metadata transaction;
+failures, losing concurrent preparations, cancellations and superseded files can
+leave unreferenced bodies. Retention eligibility, reference tracking and cleanup
+scheduling remain host-owned. `StorageStagedContentStore.remove` performs an
+ETag-conditional deletion only after the host proves eligibility; it is not a
+collector and is never called automatically by the workflow.
+
+### Text editing and checkpoints
+
+`applyStorageTextEdit` accepts one exact replacement/append or `{ kind: 'batch',
+changes }`. A batch applies in order to an intermediate buffer: later targets
+see earlier changes. Persist only its final return value. Each target must match
+exactly once, including overlapping matches; there is no fuzzy replacement.
+`StorageTextEditConflict.diagnostic` identifies the failing zero-based edit index,
+reason, and at most two source windows of 320 Unicode characters each. Window
+offsets count UTF-8 bytes; line/column are one-based UTF-16 coordinates. Contexts
+are untrusted source data from the intermediate buffer, not persisted changes.
+
+`workflow.readText({ draftId, expectedSize })` provides a bounded exact source
+buffer for host validation; concurrent size changes and cancellation conflict.
+`workflow.stageText` saves a bounded text buffer as a sealed checkpoint.
+`workflow.reviseText({ draftId, expectedSize, idempotencyKey, changes })` saves a
+new sealed checkpoint, retains the original path/head ETag, and records
+`sourceDraftId`. Its predecessor is sealed in the same host transaction; a
+failed edit leaves even an open predecessor unchanged. A competing append,
+cancellation or commit fails the revision check. Replays return the saved draft;
+a key reused for different edits conflicts. Persist the new nullable
+`sourceDraftId` field with every draft record. Keep it scoped like the draft.
+
+`checkoutStorageCatalogText(catalog, workflow, input)` streams an exact
+catalog revision into a sealed draft. Supplying the catalog to
+`createAiSdkFileWorkflowTools` enables `workspace_checkout_file`;
+`workspace_edit_file_draft` edits checkpoints without resending the source.
+For path-based authoring, wrap the protected catalog and workflow in
+`new StorageWorkingFiles(catalog, workflow)` and pass its `.catalog` to
+`createAiSdkWorkingFileTools`. Ordinary write, append and edit calls return an
+opaque working ETag. Reads and discovery include unfinished checkpoint leaves;
+listing remains paginated. A host can resolve `working.draft({ path,
+expectedEtag })`, perform domain admission, then commit the exact draft. Failed
+admission leaves that same path and ETag editable. This adapter never commits
+implicitly. Committed checkpoint ETags resolve to their receipt's saved ETag and
+still enforce the current head; concurrent changes cannot be silently adopted.
+
+`workflow.stageStream` stages a lazy source using bounded UTF-8-safe chunks and a
+host-provided stable content identity. `reviseText` applies exact ordered edits
+as a stream; file size is independent of the per-operation edit-text budget.
+`maxTextBytes` still bounds buffered `stageText` inputs and `readText` validation.
+Hosts must set their own admission and export resource limits. Stream failures
+leave no partial checkpoint; immutable unreferenced chunks follow normal staged
+content retention. `workflow.lookup` recovers host command receipts after
+response loss, with fresh scope authorization. Replaying the original mutation
+still verifies its full fingerprint and current mutation authority.
+
+The catalog factory also exposes `workspace_edit_file_batch`. Tool inputs bound
+all edit text together to the configured write/chunk budget. Exact-match failures
+return structured `{ applied: false, code: 'CONFLICT', diagnostic, guidance }`;
+provider failures retain the existing sanitized error contract.
+
+Text staging, checkout and draft editing explicitly buffer at most `maxTextBytes`
+(default 16 MiB); `maxEdits` defaults to 64 and restrictions only narrow limits.
+Chunked creation and commit remain streaming. Read and write authority are both
+required to revise a draft. The current file changes only when the host accepts
+`commitHeads`; content validation, authorization, preview, retention and repair
+budgets belong to that host. Earlier checkpoints remain readable until explicitly
+cancelled. They do not implement published version history or undo committed
+heads; restoring one after a commit requires the host's current-head precondition.
+
+### Byte and provider guarantees
+
+Staging requires native create-only writes that return an ETag and native exact
+ETag reads; byte ranges additionally require `rangeRead`. Missing primitives
+fail with `NOT_SUPPORTED`, without an existence-check/unconditional-write or
+full-download fallback. Files SDK remains the provider, streaming, range and
+conditional-policy engine. Its multipart upload controls remain distinct from
+the host-persisted draft protocol; it does not provide atomic catalog commits.
+The bundled filesystem and memory drivers and verified native S3 profiles
+support staging. Memory stores are process-local and volatile; their conditional
+comparison/publication is synchronous after asynchronous body consumption.
+Memory publications use canonical SHA-256 ETags. Direct raw-map mutation remains
+a trusted testing escape hatch, outside protected workspace authority.
+
+Windows count UTF-8 bytes, use inclusive provider range ends and preserve BOMs.
+Offsets splitting a character and malformed/truncated UTF-8 at EOF fail. Search
+budgets include the actual requested bytes; follow `nextOffset` even on an empty
+match page. `applyStorageTextEdit` works on an already buffered string, requires a
+result byte ceiling and rejects non-unique replacement targets; it is not a
+streaming document editor. Model text appends default to 8192 bytes per call,
+clamped to the capability. Mutation tools require approval by default; hosts may
+apply an existing approval policy explicitly.
+
+The browser bytes entrypoint imports no Node, provider, NestJS or AI modules.
+`verifyStorageChunkReceipt(blob, receipt, { offset, maxBytes, signal })` verifies
+ordering, bounds and the actual local SHA-256 before returning the next offset.
+Filename/size/mtime are insufficient proof of resumed content identity. Filename
+classification, browser session storage and HTTP transport remain host policy.
+
+### Azure Blob staged content
+
+Use the Azure entrypoint for native create-only uploads, ETag-conditional
+replacement/deletion, and exact ETag reads, including byte ranges. These operations
+run through the Files SDK conditional pipeline, so hooks, retries, prefix policy,
+readonly checks, and sanitized errors apply to them. The named `azure` provider
+also receives these primitives.
+
+```ts
+import { DefaultAzureCredential } from '@azure/identity';
+import { createAzureStorageDriver } from '@nestm/storage/files-sdk/azure';
+
+const driver = createAzureStorageDriver({
+  adapter: {
+    accountName: 'workspacestorage',
+    container: 'private-content',
+    credential: new DefaultAzureCredential(),
+    useUserDelegationSas: false,
+  },
+});
+```
+
+Install `@azure/storage-blob`, `@azure/core-auth`, and the credential provider used
+by the host. The Blob container must already exist. Grant the workload identity
+the required Blob data permissions; signed URLs are unnecessary for protected
+server-side content operations. Explicit token credentials cannot be combined
+with shared keys, SAS tokens, or connection strings, and cannot be overridden by
+ambient shared-key environment variables.
+
+Conditional uploads stream through bounded Azure SDK blocks and atomically apply
+their predicate when committing. They return the committed ETag and actual byte
+count without a separate metadata read. Failed uploads may leave uncommitted
+blocks for Azure's own expiration; they never fall back to unconditional writes.
+Exact reads verify the response ETag before exposing its body. The driver uses a
+conservative 1024-byte UTF-8 physical-key budget within Azure's name limit.
+Conditional server-side copy, version-ID predicates, and explicit conditional
+multipart completion are not advertised. Workspace safe copy/move can use the
+existing exact-read/create/delete workflow. The generic staged and encrypted
+content stores require no Azure-specific changes.
+
+Run `test/azure-content.e2e-spec.ts` with `STORAGE_AZURE_CONFORMANCE=true` and
+`STORAGE_AZURE_TEST_CONNECTION_STRING` against a dedicated account or Azurite.
+For live identity tests, supply `STORAGE_AZURE_TEST_ACCOUNT_NAME` instead; the
+suite uses `DefaultAzureCredential`. It creates and deletes its own uniquely
+named test container. The CI Azure job covers native predicates, competing
+writes, bounded streams, ranges, encrypted content, and the provider conformance
+suite on Azurite. Live Azure identity remains a separate deployment check.
+
 ## Configure named stores
 
-Create provider adapters with `files-sdk`, wrap them through the explicit
-bridge, and register the resulting drivers:
+Use the package-owned S3 factory when applicable. For other providers, create a
+`files-sdk` adapter, wrap it through the explicit bridge, and register the
+resulting driver:
 
 ```ts
 import { Module } from '@nestjs/common';
-import { s3 } from 'files-sdk/s3';
 import { gcs } from 'files-sdk/gcs';
 import { createFilesSdkDriver } from '@nestm/storage/files-sdk';
+import { createS3StorageDriver } from '@nestm/storage/files-sdk/s3';
 import { StorageModule } from '@nestm/storage';
 
 export const StorageKey = {
@@ -104,11 +661,11 @@ export const StorageKey = {
       stores: [
         {
           name: StorageKey.MEDIA,
-          driver: createFilesSdkDriver({
-            adapter: s3({
+          driver: createS3StorageDriver({
+            adapter: {
               bucket: 'media',
               region: 'us-east-1',
-            }),
+            },
           }),
         },
         {
@@ -194,11 +751,11 @@ StorageModule.forRootAsync({
       name: 'media',
       inject: [ConfigService],
       useFactory: (config: ConfigService) =>
-        createFilesSdkDriver({
-          adapter: s3({
+        createS3StorageDriver({
+          adapter: {
             bucket: config.getOrThrow('MEDIA_BUCKET'),
             region: config.getOrThrow('AWS_REGION'),
-          }),
+          },
         }),
     },
   ],
@@ -216,11 +773,136 @@ modules retain their own DI scope rather than mutating an application-wide
 registry. Names are case-sensitive and cannot contain leading or trailing
 whitespace.
 
+### Select the provider at runtime
+
+An application that ships to more than one environment usually cannot name its
+provider at build time. `createProviderStorageDriver` takes the slug as data and
+imports that provider's adapter — and only that one — on demand, so a deployment
+picks its store with an environment variable and installs one native SDK:
+
+```ts
+import { createProviderStorageDriver } from '@nestm/storage/files-sdk/provider';
+
+StorageModule.forRootAsync({
+  imports: [ConfigModule],
+  stores: [
+    {
+      name: 'media',
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) =>
+        createProviderStorageDriver({
+          provider: config.getOrThrow('STORAGE_PROVIDER'),
+          prefix: config.get('STORAGE_PREFIX'),
+          config: {
+            bucket: config.get('STORAGE_BUCKET'),
+            region: config.get('STORAGE_REGION'),
+            root: config.get('STORAGE_ROOT'),
+          },
+        }),
+    },
+  ],
+});
+```
+
+`config` is one flat bag of provider settings — `bucket` and `region` for an
+object store, `root` for the filesystem, `accountName` and `container` for
+Azure. Each provider reads what it needs and ignores the rest, so the same shape
+survives a provider change. Credentials may be omitted wherever the provider's
+SDK resolves its own chain (an IAM role, Application Default Credentials, a
+shared profile).
+
+An unknown slug fails closed with `INVALID_ARGUMENT` before anything is
+imported. Validate untrusted input up front with `isStorageProvider`, and drive
+config validation from the catalog rather than a hand-kept list:
+
+```ts
+import {
+  getStorageProvider,
+  isStorageProvider,
+  listStorageProviders,
+  listStorageProviderSecretEnvVars,
+} from '@nestm/storage/files-sdk/provider';
+
+listStorageProviders().map((provider) => provider.slug); // 'akamai', 'alibaba', …
+getStorageProvider('gcs')?.peerDeps; // ['@google-cloud/storage', …]
+listStorageProviderSecretEnvVars('s3').map((variable) => variable.key);
+```
+
+The catalog is pure data and pulls in no adapter, so it is safe in config UIs,
+health checks, and startup validation.
+
+The `s3` slug additionally carries the verified per-operation profile and
+signed-policy capabilities described under
+[Exact provider conditions and staged-object promotion](#exact-provider-conditions-and-staged-object-promotion);
+every provider not backed by the AWS S3 SDK exposes what its adapter declares.
+When the provider _is_ known at build time, import
+`@nestm/storage/files-sdk/s3` or `@nestm/storage/files-sdk/fs` directly and skip
+the indirection.
+
+S3 endpoint and public-URL provenance is resolved from the adapter that
+`files-sdk` actually constructs, including values merged from `configJson`.
+An unaudited endpoint forces the driver read-only, and a `publicBaseUrl` removes
+the signed-download TTL guarantee because the resulting public URL does not
+expire. AWS-SDK-backed noncanonical provider slugs (for example an S3-compatible
+provider wrapper) also default to unverified/read-only; only the canonical
+`s3` provider may infer the native AWS profile, and a custom endpoint becomes
+writable only with an explicit branded `S3ProviderProfile`.
+
+Before enabling conditional operations for a custom S3-compatible endpoint,
+run the reusable
+[provider conformance contract](https://github.com/nestm-dev/storage/blob/main/docs/provider-conformance.md)
+against dedicated test credentials. Unknown endpoints are forced read-only and
+receive no inferred conditional capabilities.
+
+## Files SDK responsibility boundary
+
+Files SDK is the upstream authority for the generic storage data plane:
+provider adapters, generic CRUD, bulk and list operations, retries, transfers
+and sync, its plugin pipeline, and framework-neutral gateway mechanics.
+`@nestm/storage` retains the guarantees that Files SDK does not currently
+provide: NestJS 12 named stores, exact native conditional/CAS capabilities,
+`StorageWorkspace` permissions and limits, bounded storage errors, and
+capability-scoped AI tools.
+
+Files SDK 2.3 provides native conditional operations through the same
+interception boundary as ordinary CRUD. NestM adapters expose their exact
+create, replace, ETag read, delete, and paired conditional-copy primitives to
+that boundary. These operations now pass through caller-configured Files
+plugins, hooks, retries, and receipts; a body transform, veto, retry observer,
+or audit policy therefore sees the conditional operation instead of being
+bypassed.
+
+NestM retains a narrow direct fallback only for conditional shapes Files SDK
+2.3 cannot represent: immutable version predicates, conditional
+multipart/resumable completion, and a copy with only its source or only its
+destination conditioned. Because those fallbacks cannot traverse the Files
+operation pipeline, they remain fail-closed when caller Files policy is active:
+
+| Operation shape                                             | Execution path        | With Files plugins, active hooks, or receipts |
+| ----------------------------------------------------------- | --------------------- | --------------------------------------------- |
+| Ordinary operations                                         | Files pipeline        | Available                                     |
+| Create/replace/ETag read/delete/paired conditional copy     | Files 2.3 pipeline    | Available                                     |
+| Version, conditional multipart/resumable, or one-sided copy | NestM direct fallback | Hidden; invocation returns `NOT_SUPPORTED`    |
+
+An empty plugin list, an empty hooks object, and `receipts: false` do not count
+as caller policy. When available, a direct fallback still applies prefixing,
+the physical-key budget, read-only restrictions, default retry/signal/timeout
+options, and bounded error mapping. `StoragePlugin` remains a separate
+veto/observation boundary; it is not a substitute for Files body or result
+transforms.
+
+`StorageWorkspace` uses the Files pipeline whenever its conditional operation
+has an upstream representation. Lower-level conditional client and driver APIs
+remain available for applications that intentionally use the policy-free
+NestM-only fallback shapes.
+
 ## Storage API
 
 `StorageClient` exposes:
 
 - `upload`, `downloadStream`, `head`, `exists`, `delete`, `copy`, and `move`;
+- exact `uploadConditional`, `downloadConditional`, `deleteConditional`, and
+  staged-object `promote` operations when the driver advertises each primitive;
 - `list`, cursor-aware `listAll`, and lazy `search`;
 - `signDownload` and discriminated PUT/POST `signUpload`;
 - `uploadMany`, `downloadMany`, `headMany`, `existsMany`, and `deleteMany`;
@@ -228,6 +910,24 @@ whitespace.
 - provider capability inspection; and
 - pause/resume/abort through `StorageUploadControl`.
 
+Provider list cursors are opaque, non-consuming continuation tokens. Replaying
+the same cursor and page limit against unchanged provider-visible state must
+return an equivalent page and continuation position, even after a descendant
+cursor has been used. A cursor is bound to the logical store, `prefix`, and
+`delimiter`, but not to `limit`, retries, timeout, or abort signal; callers may
+change those transport/page-size options while resuming the same position.
+
+The cursor must work through a newly constructed compatible driver targeting
+the same backend namespace while the provider token remains valid and
+available; it cannot depend on process-, client-, or session-local state. An
+adapter for a consuming or instance-bound provider token must materialize a
+stable continuation before it can provide conforming paginated
+`StorageDriver.list` results. This contract lets a caller safely retry, replay,
+or resume pagination on another replica. It does not promise a provider-token
+lifetime, snapshot isolation across concurrent mutations, or provider,
+network, credential, or authorization availability. Provider invalidation is
+an ordinary list-operation failure.
+
 Downloads are streaming by default:
 
 ```ts
@@ -250,6 +950,138 @@ Node `Readable` uploads are accepted and converted to Web streams without
 buffering. Provider capability gaps fail closed with `StorageError` rather than
 silently discarding a range, metadata, or cache-control request.
 
+### Exact provider conditions and staged-object promotion
+
+Capabilities distinguish conditional create, replace, delete, read, source
+copy, destination copy, atomic source-and-destination promotion, and multipart
+completion. They also declare the complete physical-key byte budget. Callers
+must check the exact primitive they need; a missing field is unsupported and is
+never widened from another operation.
+
+Some adapters expose conditional copy only as a paired source-and-destination
+operation. In that case,
+`capabilities.conditionalCopySource.requiresDestinationPredicate` and
+`capabilities.conditionalCopyDestination.requiresSourcePredicate` are `true`.
+`StorageClient.promote` rejects a request missing the required counterpart
+before provider I/O. A paired request must also satisfy the advertised
+create/replace bit and
+`capabilities.conditionalCopyDestination.atomicWithSource`.
+
+The physical-key budget applies to the exact key sent to the adapter. It
+therefore counts leading slashes for unprefixed drivers, the separator added to
+a configured driver prefix, and provider prefixes derived for `list` or
+`search`. Over-budget object keys and explicit list/search prefixes fail before
+provider dispatch rather than being normalized into a shorter key. A glob's
+provider prefix is the exact prefix inferred by files-sdk itself, and that
+derived list operation passes through the same final guard. A non-positive
+`maxResults` performs no provider walk and therefore dispatches no prefix.
+
+Adapters and plugins execute as trusted in-process code; this package does not
+attempt to sandbox a plugin that performs its own network or filesystem I/O.
+For supported plugin pipelines that forward operations through `next`, the
+physical-key guard is the innermost wrapper, after caller plugins and before
+the adapter call. A plugin therefore cannot widen an upload key or list/search
+prefix past the declared byte ceiling while still using the normal dispatch
+pipeline.
+
+Storage-facing ETags have one canonical representation: a bare, case-sensitive
+opaque token with no HTTP quotes. Canonical values contain 1–1024 visible
+ASCII bytes and exclude commas, backslashes, whitespace, control characters,
+`DEL`, non-ASCII text, the `*` wildcard, and case-insensitive `W/` weak-tag
+prefixes. Treat the value as opaque: preserve the exact string returned by
+`head`, reads, or writes and pass it back unchanged to a conditional operation.
+Do not add or remove quotes in application code. S3-compatible drivers remove
+exactly one valid provider-owned quote pair on ingress and add exactly one pair
+when serializing the HTTP header.
+
+This tightens the precondition boundary. Quoted or otherwise non-canonical
+ETags that older versions happened to accept now fail with `INVALID_ARGUMENT`,
+and an unsafe provider result fails with a sanitized `PROVIDER` error instead
+of being exposed as a usable validator. Applications that persisted quoted
+ETags must refresh them with `head` rather than trimming them heuristically.
+Strict normalization prevents a caller-controlled wildcard, entity-tag list,
+weak validator, or malformed header value from widening an operation that
+promises one exact strong match.
+
+The native AWS S3 profile advertises ETag- and version-conditioned server-side
+copy. This lets an application validate a staged object and copy that exact
+source to its final key instead of re-reading whichever bytes occupy the
+staging key later:
+
+```ts
+import { StorageError, StorageErrorCode } from '@nestm/storage';
+
+const staged = await media.head(stagingKey);
+if (staged.etag === undefined) {
+  throw new StorageError('Provider did not return a source ETag.', {
+    code: StorageErrorCode.NOT_SUPPORTED,
+  });
+}
+
+// Validate size, declared MIME, and magic bytes before this call.
+await media.file(stagingKey).promoteTo(finalKey, {
+  sourceEtag: staged.etag,
+});
+
+// Commit ready metadata first. Promotion deliberately retains the staged
+// object so a failed database commit remains recoverable.
+await media.delete(stagingKey);
+```
+
+`sourceVersion` can select an immutable S3 version and may be combined with
+`sourceEtag`. A destination condition can independently require create-only or
+replacement of an exact ETag. Combining source and destination predicates also
+requires `capabilities.conditionalCopyDestination.atomicWithSource`; otherwise
+the request fails with `NOT_SUPPORTED`. A promotion must contain at least one
+source or destination predicate.
+
+Cloudflare R2 has a separate stable profile: create, replace, ETag-conditioned
+read, and ETag-conditioned source copy are enabled, while conditional delete,
+destination copy, atomic promotion, version predicates, and conditional
+multipart completion remain absent. R2 proves content-type binding for
+presigned PUT requests but not POST-form size ranges, so its signed-upload
+policy is `{ contentType: true, sizeRange: false }` and the gateway refuses to
+mint its POST upload form. Cloudflare documents that presigned `POST` form
+uploads are not supported in its
+[presigned URL contract](https://developers.cloudflare.com/r2/api/s3/presigned-urls/).
+Direct R2 signed-upload calls that request a size bound likewise fail with
+`NOT_SUPPORTED` before signing.
+Custom S3-compatible endpoints start with no conditional operations and the
+entire driver is forced read-only until an explicit conformance-verified
+`S3ProviderProfile` is supplied. Omitting `signedUploadPolicy` while defining a
+custom profile normalizes both policy claims to `false`; providers may opt in
+only to constraints their conformance evidence proves.
+
+Successful S3 signed uploads enforce every requested constraint. A request
+with `contentType` and no `maxSize` uses a presigned PUT whose signature
+includes the `content-type` header. A request with `maxSize` uses a POST policy
+with `content-length-range` and, when present, an exact `Content-Type`
+condition. S3 cannot express a lower-only `minSize` through this contract, so
+that shape fails with `NOT_SUPPORTED`; an unclaimed profile constraint also
+fails before credentials are resolved or a URL is minted. Literal physical
+keys ending in AWS's `${filename}` POST template are rejected for bounded
+uploads because the SDK otherwise widens the exact key condition to a prefix.
+
+`withS3Capabilities()` decorates a raw S3 adapter in place and may be applied
+only once. Construct a fresh raw adapter when selecting a different profile;
+reapplying the helper is rejected so a previous broader profile cannot survive
+a later narrower declaration. The selected profile is bound to the exact
+reserved capability and operation members installed by that decoration;
+same-client aliases may change display metadata but cannot add or replace those
+members to widen the profile.
+
+An explicit profile applied to a native AWS SDK endpoint may only narrow the
+immutable `AWS_S3_PROVIDER_PROFILE`. It cannot raise the complete-key budget
+above 1,024 bytes or claim an operation/policy bit absent from the built-in
+profile. This containment follows actual SDK endpoint provenance even when an
+adapter alias changes its display name.
+
+The package-owned `s3()` factory also retains whether `publicBaseUrl` was
+configured even when the second `withS3Capabilities()` options object is
+omitted. In that case `signedDownloadPolicy.expiresIn` is false. Foreign S3
+adapters whose construction metadata is unavailable receive the same
+conservative false value instead of claiming an enforceable TTL.
+
 ### Resumable uploads
 
 ```ts
@@ -301,20 +1133,42 @@ The gateway lives at `@nestm/storage/gateway` and is never mounted by
 `StorageModule`.
 
 ```ts
-import { Module } from '@nestjs/common';
+import { Injectable, Module } from '@nestjs/common';
 import {
   StorageGatewayModule,
   StorageGatewayOperation,
+  type StorageGatewayKeyPolicy,
 } from '@nestm/storage/gateway';
 
+@Injectable()
+class TenantStorageKeyPolicy implements StorageGatewayKeyPolicy {
+  resolve({ input, request, target }) {
+    const tenantId = tenantIdFromAuthenticatedRequest(request);
+    const root = `tenants/${base64url(tenantId)}`;
+    if (target === 'pattern') {
+      // Search is already constrained by the separately resolved prefix.
+      return input?.value ?? '*';
+    }
+    return `${root}/${input?.value ?? ''}`;
+  }
+}
+
+@Module({
+  providers: [TenantStorageKeyPolicy],
+  exports: [TenantStorageKeyPolicy],
+})
+class StoragePolicyModule {}
+
 @Module({
   imports: [
     AppStorageModule,
     AuthModule,
+    StoragePolicyModule,
     StorageGatewayModule.register({
-      imports: [AppStorageModule, AuthModule],
+      imports: [AppStorageModule, AuthModule, StoragePolicyModule],
       store: 'media',
       guards: [JwtAuthGuard],
+      keyPolicy: TenantStorageKeyPolicy,
       mode: 'hybrid',
       operations: [
         StorageGatewayOperation.DOWNLOAD,
@@ -325,6 +1179,9 @@ import {
         StorageGatewayOperation.SIGN_UPLOAD,
       ],
       maxUploadBytes: 100 * 1024 * 1024,
+      maxSignedUploadBytes: 10 * 1024 * 1024,
+      signedUploadContentTypes: ['image/jpeg', 'image/png'],
+      maxSignedUrlExpiresIn: 900,
       maxListResults: 1000,
       maxSearchResults: 1000,
       proxyInlineContentTypes: ['image/jpeg', 'image/png'],
@@ -338,12 +1195,42 @@ Registration fails without at least one existing Nest guard. The only bypass is
 the explicit `allowUnauthenticated: true` development escape hatch. Operations
 are deny-by-default and must be allowlisted individually.
 
+Registration also fails without a `keyPolicy`. Guards answer whether a request
+may reach the gateway; the key policy independently resolves every parsed
+`key`, `prefix`, search `pattern`, `from`, and `to` value to the exact provider
+path. It runs even when a list/search prefix was omitted, so the policy can
+always impose a tenant root. Key-policy providers may be request scoped.
+Returned paths are parsed again and reject absolute paths, backslashes, control
+characters, empty segments, and dot/parent segments.
+
+Existing single-tenant applications can temporarily set
+`unsafeAllowUnscopedKeys: true` instead of `keyPolicy`. The name is intentional:
+it preserves caller-controlled provider keys and must not be used on an exposed
+or multi-tenant gateway. It cannot be combined with `keyPolicy`.
+
 Proxy downloads default to `Content-Disposition: attachment` and always send
 `X-Content-Type-Options: nosniff`. Add only trusted, non-active MIME types to
 `proxyInlineContentTypes` when browser rendering is required. Search responses
 are capped by `maxSearchResults`, and list pages by `maxListResults` (both
 1,000 by default).
 
+Every signed URL is capped by `maxSignedUrlExpiresIn` (3,600 seconds by
+default). Signed uploads always carry a provider-enforced maximum size, capped
+by `maxSignedUploadBytes`, and require an exact lowercase MIME type from
+`signedUploadContentTypes`. The default direct-upload allowlist contains only
+`application/octet-stream`. Gateway callers may request only the literal
+`attachment` or `inline` response disposition; arbitrary response-header text
+and filenames are rejected. A driver must also advertise
+`signedUploadPolicy.contentType` and `signedUploadPolicy.sizeRange`; otherwise
+the gateway refuses to mint the URL. Native AWS advertises both and uses S3
+POST policy conditions. R2 advertises content-type enforcement but not a POST
+size range, while omitted custom declarations normalize both claims to false;
+the gateway therefore fails closed for those profiles. Signed downloads
+similarly require
+`signedDownloadPolicy.expiresIn`. The S3 factory advertises it only when no
+permanent `publicBaseUrl` was configured, preventing a configured TTL from
+silently returning a non-expiring public link.
+
 The fixed gateway prefix is `/storage`:
 
 | Method   | Path                        | Operation                            |
@@ -394,9 +1281,26 @@ try {
 }
 ```
 
+`files-sdk` `NotFound` failures retain `StorageErrorCode.NOT_FOUND`, including
+when a provider adapter and this driver resolve separate copies of `files-sdk`.
+`isStorageError()` likewise recognizes branded and exact legacy structural
+errors produced by a duplicated `@nestm/storage` package copy.
+
+For a conditional mutation, `error.applied === true` means the provider commit
+succeeded but acknowledgement failed afterward, for example in an awaited
+post-operation plugin. Conditional uploads also expose `error.appliedEtag` when
+the committed generation is known. Do not blindly retry the original
+predicate: reconcile the logical destination first, using an exact ETag read
+when `appliedEtag` is present. This is a one-way signal: `applied === false`
+does not prove that a remote mutation did not commit. A timeout, connection
+loss, or exhausted retry can lose the provider's success response, so reconcile
+ambiguous transport/provider failures before repeating a conditional mutation.
+The sanitized workspace, AI-tool, and gateway error boundaries retain only
+this bounded reconciliation metadata.
+
 Capability flags cover range reads, native byte-level upload progress,
 delimiter listing, metadata, cache control, resumable uploads, server-side
-copy, and signed transfers.
+copy, conditional promotion, and signed transfers.
 Provider-specific native clients are intentionally not exposed from the root
 package.
 
@@ -412,9 +1316,51 @@ StorageModule.forRoot({
 });
 ```
 
-For local filesystem storage, import `fs` from `files-sdk/fs` and pass it to
-`createFilesSdkDriver` exactly like a cloud adapter.
+For local filesystem storage, use the package-owned factory. The adapter reaches
+only `node:fs`, so it needs no native SDK:
+
+```ts
+import { createFsStorageDriver } from '@nestm/storage/files-sdk/fs';
+
+StorageModule.forRoot({
+  stores: [
+    {
+      name: 'artifacts',
+      driver: createFsStorageDriver({ adapter: { root: './var/artifacts' } }),
+    },
+  ],
+});
+```
+
+Bodies are written verbatim at `<root>/<key>`. A `<key>.meta.json` sidecar beside
+each one carries the content type, ETag, and custom metadata a filesystem has
+nowhere else to put; sidecars never surface as keys, and uploading a key ending
+in `.meta.json` fails closed rather than colliding with one. Ordinary and
+conditional mutations made through the decorated adapter share one
+process-local lock domain. Conditional guarantees therefore require a
+dedicated root: do not mutate it through another process, an unwrapped adapter,
+or direct filesystem calls.
 
 ## License
 
 MIT
+
+## Encrypted staged content
+
+`@nestm/storage/crypto` exports `StorageEncryptedContentStore<Scope>`. Install the optional `@nestm/crypto` peer only for this entry point. The store uses a host-owned `FileCipherEngine`, object-address function, fresh AAD buffers, allowed key providers, and metadata callbacks. It prepares detached encryption metadata before uploading and completes metadata only after plaintext and ciphertext accounting agree. Reads pin physical ETags and authenticate full content or bounded frame ranges.
+
+The host authorizes reads, serializes metadata, enforces key policy and atomically proves reference eligibility before `metadata.discard` removes anything. A missing upload receipt means completion is uncertain: keep prepared cleanup inventory for a later sweep. A rejected prepare does not authorize cleanup of another writer's reservation. Engine shutdown stays with its owner. See [the standalone archive consumer](scripts/fixtures/encrypted-content-consumer.ts).
+
+`StorageStagedContentStore.writeReserved(scope, payloadId, stream, options)` accepts a fresh UUID from a trusted caller. It retains create-only semantics and returns that exact identity in the receipt; it never overwrites an existing payload. Ordinary writers continue to use `write`.
+
+### Revision-pinned host streams
+
+Catalog `readStream({ path, expectedEtag, start?, end?, signal? })` and workflow
+`readStream({ draftId, expectedSize, start?, end?, signal? })` return metadata and
+a byte stream. Ranges use an inclusive start and exclusive end. These host-only
+operations retain read authorization and linked cancellation; they are never
+projected as unbounded model tools. Catalog hosts must pin immutable content to
+the requested revision and reject stale heads. Saved-file working edits consume
+one stream directly into an atomic candidate without creating a checkout first.
+`stageStream.body` may asynchronously open its source after authorization and
+replay validation.