# Capability Spec: storage

- **Capability**: `storage`
- **Package**: `@suaveplan/storage`
- **Change**: storage-set-partial
- **Date**: 2026-04-28

---

## Requirements

### STORAGE-01 — `setPartial` is part of the abstract surface

`AbstractStorage` MUST declare `abstract setPartial(key: string, offset: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>`. Every concrete subclass MUST provide an implementation. A protected `defaultSetPartial` helper MUST exist as the read-modify-write reference fallback. `defaultSetPartial` MUST reject non-integer or negative `offset` values.

**Verified by:** `src/abstract/abstract.spec-conformance.test.ts` (`STORAGE-01`).

### STORAGE-02 — sparse extension semantics

When `setPartial(key, offset, bytes)` is called on a non-existent key or on an existing object shorter than `offset + bytes.byteLength`, the storage object MUST be created/extended to length `max(currentLength, offset + bytes.byteLength)`. Bytes in the gap `[currentLength, offset)` MUST be zero (`0x00`) on subsequent reads.

**Verified by:** `src/abstract/abstract.spec-conformance.test.ts` (`STORAGE-02`).

### STORAGE-03 — overlap is in-place overwrite

When `setPartial(key, offset, bytes)` is called on a key whose existing object overlaps the written range, bytes within `[offset, offset + bytes.byteLength)` MUST be overwritten with `bytes`. Bytes outside that range MUST be preserved exactly. Zero-length writes MUST be a no-op.

**Verified by:** `src/abstract/abstract.spec-conformance.test.ts` (`STORAGE-03`).

### STORAGE-04 — capabilities are explicit

`AbstractStorage` MUST expose a readonly `capabilities` property of shape `{ partialReads: boolean; partialWrites: boolean; nativeStreams: boolean; atomicWrites: boolean; contentAddressable: boolean }`. Defaults MUST be all `false` (`DEFAULT_STORAGE_CAPABILITIES`). Subclasses MUST override per native support. `MemoryStorage.capabilities.partialWrites` MUST be `true`. `NamespacedStorage.capabilities` MUST mirror its inner storage. `S3.capabilities.partialWrites` MUST be `false` (multipart-upload native impl deferred).

**Verified by:** `src/abstract/abstract.spec-conformance.test.ts` (`STORAGE-04`); `packages/storage/storage-s3/src/s3/s3.test.ts` (`setPartial` describe block).