@nestm/storage 0.1.0-alpha.6 → 0.1.0-alpha.8

package/CHANGELOG.md

@@ -1,5 +1,133 @@
 # @nestm/storage
 
+## 0.1.0-alpha.8
+
+### Minor Changes
+
+- d81c6f4: Add a typed `mapCreateConflict` hook to the AI SDK workspace adapter so
+  applications can represent atomic create collisions as domain results without
+  mutating generated tools. Keep replace/ETag conflicts fail-closed and sanitize
+  mapper failures at the tool boundary.
+
+  Mark workspace tools with optional inputs or a combined create/replace union as
+  non-strict for provider schema generation while retaining strict Zod runtime
+  validation.
+
+- a0ea392: Add injectable, replica-safe workspace pagination cursors. The workspace now
+  binds versioned cursor payloads to stable store, mount, tenant/workspace, prefix,
+  operation, query, limit, and expiry context; authorizes non-consuming replay
+  before that expiry; and rejects altered or cross-context continuations.
+  Successful continuation still depends on the embedded provider cursor remaining
+  valid and available.
+
+  Export an AES-256-GCM key-ring codec for stateless multi-replica deployments and
+  an asynchronous byte-payload codec contract for shared durable opaque-token
+  stores. Cursor payloads and tokens are bounded, provider continuations remain
+  opaque, and pagination fails closed when no cursor mechanism is configured.
+  Compatible replicas rely on the universal driver contract for non-consuming,
+  instance-portable provider cursors whose position is independent of page size
+  while the provider token remains valid. Cursor expiry is not a provider-token
+  retention, snapshot-isolation, or uptime promise; provider invalidation remains
+  an operational list failure.
+
+- d996b92: Split the aggregate S3 conditional-mutation and copy declarations into exact
+  create, replace, delete, read, source-copy, destination-copy, atomic-promotion,
+  and multipart-completion capabilities. Add independent AWS S3, Cloudflare R2,
+  and fail-closed custom-endpoint profiles that force unverified drivers
+  read-only; enforce complete physical-key byte budgets; normalize provider
+  errors without retaining raw provider payloads or causes; and publish a reusable
+  provider conformance contract with gated filesystem, AWS, R2, and custom suites.
+
+  Normalize every provider ETag to a canonical bare 1–1024-byte visible ASCII
+  token and serialize exactly one HTTP quote pair at S3 request boundaries.
+  Quoted, weak, wildcard, list-shaped, control-bearing, non-ASCII, and otherwise
+  unsafe values now fail closed instead of being accepted as arbitrary non-empty
+  strings. Applications that persisted quoted ETags must refresh them from
+  provider metadata before conditional mutation; this prevents wildcard/list and
+  header-ambiguity inputs from widening an exact-match precondition.
+
+  Specify and test provider list cursors as non-consuming replayable tokens for
+  unchanged provider state, so higher-level replayable pagination can fail closed
+  when a provider cannot meet that contract.
+
+  Exercise the complete advertised source-condition by destination-condition
+  promotion matrix, including stale-state preservation and competing stale/valid
+  requests. Provider documentation or audited implementation evidence remains
+  required for the internal one-linearization-point claim.
+
+  Ordinary and conditional provider failures now expose stable public messages
+  and preserve only normalized codes and retry flags; raw provider bodies,
+  request metadata, and nested causes are not retained in loggable error shapes.
+
+  Raise the `@aws-sdk/client-s3` peer floor to 3.919.0, the first release that
+  serializes destination conditions for `CopyObject`, and verify the real wire
+  headers in the packed minimum-peer consumer. Native AWS construction now
+  disables environment and shared-config endpoint URL overrides, while the public
+  capability helper derives custom-endpoint provenance from the actual SDK client
+  instead of a duplicated caller hint. Capability decoration is now single-use
+  per raw S3 adapter, preventing broader operations from surviving a later
+  narrower profile application.
+
+  Bind S3 provider authority to package-private raw-client and adapter-method
+  identity plus the exact surface snapshot installed by capability decoration.
+  Structurally S3-backed raw adapters are rejected until they pass through the
+  package helper, regardless of adapter name, proxying, or forged global symbols;
+  same-client aliases cannot replace their raw client, ordinary methods, policies,
+  or conditional operations. Unverified custom endpoints and noncanonical
+  S3-backed provider slugs are forced read-only, while an explicit branded profile
+  unlocks only its declared conditional operations. Endpoint and public-URL
+  provenance now follows the adapter actually produced by the provider loader,
+  including `configJson`.
+
+  Retain `publicBaseUrl` construction policy in the package-owned `s3()` helper
+  so omitted decorator hints cannot re-enable an expiring-download claim. Unknown
+  foreign S3 construction conservatively disables that claim. Validate the exact
+  physical adapter key without stripping leading slashes, and include configured
+  separators plus list/search-derived prefixes in the provider byte budget before
+  dispatch. Search uses files-sdk's own inferred glob-prefix and zero-result
+  semantics instead of duplicating its matcher logic. The innermost dispatch guard
+  repeats these checks after supported in-process plugins have transformed an
+  operation; adapters and plugins remain trusted code rather than a sandbox
+  boundary.
+
+  Derive signed-upload policy claims from the branded provider profile instead
+  of granting them to every S3-compatible endpoint. Native AWS proves content
+  type and POST size-range enforcement; Cloudflare R2 proves content type but not
+  POST form size ranges; omitted custom declarations normalize to false/false so
+  the gateway fails closed. Profile authority is backed by a package-private
+  WeakSet after deep freezing, so reflecting and copying the nominal brand symbol
+  cannot forge conformance evidence.
+
+  Treat the built-in AWS profile as an immutable ceiling for every SDK client
+  with native endpoint provenance, independent of mutable adapter display names.
+  Explicit profiles may narrow its operations, policy bits, and key limit but
+  cannot raise the 1,024-byte physical-key budget or add unsupported claims.
+
+  Enforce every requested signed-upload constraint at URL creation time.
+  Content-type-constrained PUT URLs now sign the `content-type` header; bounded
+  AWS uploads use exact POST MIME and byte-range conditions; unsupported profile
+  constraints and lower-only S3 ranges fail before signing. Bounded POST uploads
+  also reject physical keys ending in AWS's `${filename}` template so an exact
+  authorized key cannot be widened into a prefix policy.
+
+## 0.1.0-alpha.7
+
+### Minor Changes
+
+- 842ff34: Add a backend-neutral `StorageWorkspace` capability and optional AI SDK 7 tool
+  adapter. Workspaces expose only canonical mount-relative paths, enforce
+  permissions and resource limits, hide provider coordinates and cursors, and use
+  atomic create/ETag mutation preconditions. S3 now advertises and implements the
+  conditional mutation primitives used by writable workspaces.
+
+  Harden local filesystem workspace reads and conditional mutations against
+  symlink aliases. Moves retain their create-only destination whenever source
+  deletion cannot be confirmed, avoiding data loss after provider or
+  post-operation hook ambiguity.
+
+  Fix cross-store sync so `destinationPrefix` is applied to uploaded keys as well
+  as pruning, keeping every mutation inside the selected destination scope.
+
 ## 0.1.0-alpha.6
 
 ### Minor Changes

package/README.md

@@ -1,8 +1,8 @@
 # @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
@@ -36,6 +36,14 @@ such as `files-sdk/gcs`:
 pnpm add files-sdk@2.2.3
 ```
 
+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
@@ -50,6 +58,11 @@ pnpm add @google-cloud/storage google-auth-library
 pnpm add @azure/storage-blob @azure/core-auth @azure/identity
 ```
 
+`@aws-sdk/client-s3` 3.919.0 or newer is required. Earlier releases omit
+destination `If-Match` and `If-None-Match` from the serialized `CopyObject`
+request even when those fields appear in a newer compile-time command shape;
+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
@@ -88,6 +101,242 @@ 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',
+    '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',
+});
+```
+
+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.
+
+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.2.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',
+                  '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.
+
+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.
+
+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.
+
 ## Configure named stores
 
 Use the package-owned S3 factory when applicable. For other providers, create a
@@ -283,19 +532,36 @@ 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 conditional-promotion and signed-policy
-capabilities described under
-[Race-free staged-object promotion](#race-free-staged-object-promotion); every
-other provider exposes exactly 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.
+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.
 
 ## Storage API
 
 `StorageClient` exposes:
 
 - `upload`, `downloadStream`, `head`, `exists`, `delete`, `copy`, and `move`;
-- conditional staged-object `promote` when the driver advertises it;
+- 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`;
@@ -303,6 +569,24 @@ known at build time, import `@nestm/storage/files-sdk/s3` or
 - 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
@@ -325,11 +609,54 @@ 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.
 
-### Race-free staged-object promotion
-
-The S3 bridge advertises ETag- and version-conditional 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:
+### 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.
+
+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';
@@ -352,9 +679,58 @@ await media.delete(stagingKey);
 ```
 
 `sourceVersion` can select an immutable S3 version and may be combined with
-`sourceEtag`. A promotion without either identity is rejected. Drivers that do
-not publish `capabilities.conditionalCopy` fail with `NOT_SUPPORTED` rather
-than falling back to an unsafe ordinary copy.
+`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
 
@@ -496,8 +872,11 @@ by `maxSignedUploadBytes`, and require an exact lowercase MIME type from
 `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. `createS3StorageDriver()` advertises both
-and uses S3 POST policy conditions. Signed downloads similarly require
+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.