Align @nestm/storage with Files SDK ownership and conditional-operation policy

[kauandotnet]

Context

Artifact Studio's Workspace Storage v1 milestone should use this layering:

Artifact Studio tenant/binding/crypto policy
  -> @nestm/storage capability workspace and CAS
    -> Files SDK generic data plane
      -> FS / S3

Files SDK already owns generic adapters, file operations, capabilities, retries, transfer/sync, plugins, and a framework-neutral gateway. @nestm/storage should remain the hardened NestJS 12 and workspace-capability layer, not a second generic storage SDK.

Official references: Files SDK, plugins, gateway, and capabilities.

Current alpha.8 correctness gap

Normal operations pass through the configured Files instance, but conditional operations call adapter extensions directly:

• conditional upload
• conditional read
• conditional delete
• promotion

Workspace mutations use those conditional paths (workspace writes). Consequently, Files SDK transforming, veto, and observation plugins do not consistently see workspace operations. Enabling encryption, validation, audit, versioning, or soft-delete plugins could produce split behavior between ordinary and conditional calls.

Alpha.8 already enforces prefix, read-only mode, key budgets, and default operation controls for these extensions. This issue is about the missing common policy/plugin boundary; it must not weaken CAS by emulating conditional writes with head-then-write.

Scope

• Define one documented transformation/veto/observation boundary covering ordinary and conditional read/write/delete/promotion operations.
• Make plugin compatibility explicit. Unsupported combinations must fail closed at construction or invocation, never silently bypass protection.
• Preserve native create-only, compare-and-replace, exact-read, compare-and-delete, and promotion guarantees.
• Delegate generic transfer/sync, provider loading, and gateway mechanics to Files SDK where its contract is equivalent; keep only NestM policy or compatibility code.
• Retain NestJS 12 named-store DI, StorageWorkspace permissions/limits/CAS, safe AI tools, and bounded public errors.
• Treat Files SDK conditional capabilities as an upstream contribution target; retain local FS/S3 extensions until upstream offers equivalent guarantees.

Acceptance criteria

• A transforming write plugin cannot yield plaintext or unvalidated conditional workspace writes.
• Veto and observation hooks cover create, replace, exact read, conditional delete, and promotion with documented failure semantics.
• No conditional operation is weakened into a check-then-mutate sequence.
• Prefix, read-only, timeout, retry, signal, and physical-key-budget conformance remains green for FS and S3.
• The responsibility boundary and plugin compatibility matrix are documented.
• Duplicate generic operations have an explicit delegate/keep decision and follow-up coverage.

[kauandotnet]

Decision update: use last-write-wins for Workspace Files

While Files SDK #138 and draft PR #139 are under upstream review, Workspace Files compositions will use an explicit StorageWorkspace last-write-wins capability backed by the ordinary Files operation path. This lets encryption, validation, audit, hooks, and receipts share the existing Files plugin pipeline instead of growing a second conditional middleware stack in NestM.

CAS was a concurrency guarantee, not an encryption requirement. The temporary contract is therefore:

• Workspace Files writes overwrite the current destination; there is no create-only or ETag-checked replace on that surface;
• reads return the latest object, not an exact ETag snapshot;
• deletes can be unconditional only when the composition grants both the new write authority and delete;
• copy reads the latest source through the protected pipeline and overwrites its destination;
• move remains conditional-only and therefore unavailable with Files policy until conditional protection can preserve the source predicate; an unsafe read/overwrite/delete sequence is not exposed;
• security policy still fails closed: this decision does not permit plaintext pass-through or bypass protected-content plugins.

Conditional workspace modes and lower-level native extensions remain available for separate immutable/internal lifecycles, stay guarded by #30 when Files policy would be bypassed, and are not used by Workspace Files. R2 remains out of scope.

Implementation is tracked in draft PR #32.

Revisit / acceptance criteria

• Files SDK ships provider-neutral conditional operations through its existing plugin, hook, receipt, prefix, retry, timeout, and abort pipeline.
• Every conditional capability is explicit and unsupported adapters fail before provider I/O.
• CAS is provider-native; no head/exists-then-mutate emulation.
• Required filesystem and S3 behavior is honest and documented, including any unsupported filesystem capability.
• @nestm/storage can delegate conditional paths and delete its interim direct-extension/policy gate instead of adding another middleware layer.
• Workspace and Artifact CAS is reintroduced only as an explicit capability and migration, with protected-content plugin coverage and concurrency tests.

[kauandotnet]

Landing update: LWW policy released in alpha.9

The scoped Workspace Files policy described above has landed:

• feat: add last-write-wins workspace policy #32 added the explicit write/overwrite capability, bounded ordinary-pipeline copy, guarded unconditional delete, bounded readBytes, and the opt-in AI LWW mutation policy.
• chore: release @nestm/storage (alpha) #31 released those changes together with fix: fail conditional operations closed with Files policy #30's fail-closed conditional-policy guard as @nestm/storage@0.1.0-alpha.9 under the npm alpha tag.

This does not remove or weaken native conditional operations. Conditional create, replace, exact read, copy/move, and delete remain reserved for immutable/CAS workloads. When Files plugins, hooks, or receipts would be bypassed, #30 continues to hide and reject those conditional capabilities before provider I/O.

The issue remains open for the upstream native-conditional pipeline criteria below. Workspace Files can proceed independently with last-write-wins through ordinary Files operations; CAS can be reconsidered only after equivalent upstream plugin, hook, and receipt coverage exists. R2 remains out of scope.