Initial Commit

openspec/archive/2026-04-28-storage-set-partial/proposal.md

@@ -0,0 +1,89 @@
+# OpenSpec Change: storage-set-partial
+
+- **Change ID**: storage-set-partial
+- **Package**: `@suaveplan/storage` (modify)
+- **Status**: PROPOSED
+- **Date**: 2026-04-28
+
+## Summary
+
+Add `setPartial(key, offset, bytes, signal?)` to `AbstractStorage` with a `partialWrites` capability flag and a `defaultSetPartial` read-modify-write fallback. This unblocks `drive-plugin-chunks-port`'s sparse-file layout (pre-allocate a file at full size, drop chunks at deterministic offsets as they arrive) and matches the existing `getPartial` symmetry.
+
+## Current state
+
+- `packages/storage/storage/src/abstract/abstract.ts:56` declares `getPartial`, `getItemSize`, `createReadStream`, `createWriteStream` as abstract — there is no `setPartial` counterpart.
+- `defaultGetPartial` exists as a protected helper (`abstract.ts:178`); the symmetric `defaultSetPartial` does not.
+- `MemoryStorage` overrides streams with zero-copy variants but has no random-access write API.
+- `StorageCapabilities` is informal; this change pins it as a required readonly property on every storage instance.
+
+## What changes
+
+### 1. Abstract method addition
+
+```ts
+abstract setPartial(
+    key: string,
+    offset: number,
+    bytes: Uint8Array,
+    signal?: AbortSignal,
+): Promise<void>;
+```
+
+Semantics:
+
+- Writes `bytes` at `offset` within the storage object at `key`.
+- If the object does not exist, MUST create one large enough to hold `[offset, offset + bytes.byteLength)`. Bytes outside the written range are zero-valued (`0x00`) on read.
+- If the object exists and is shorter than `offset + bytes.byteLength`, MUST extend it; intermediate bytes are zero-valued.
+- Concurrent `setPartial` calls on the same key are NOT required to be atomic; callers MUST serialise per-key.
+- AbortSignal honoured on a best-effort basis.
+
+### 2. Default fallback
+
+```ts
+protected async defaultSetPartial(key, offset, bytes, signal?) {
+    const current = (await this.get(key, signal)) ?? new Uint8Array(0);
+    const end = offset + bytes.byteLength;
+    const out = new Uint8Array(Math.max(current.byteLength, end));
+    out.set(current, 0);
+    out.set(bytes, offset);
+    await this.set(key, out, undefined, signal);
+}
+```
+
+O(N) memory per call; sparse-file consumers prefer native-capable backends.
+
+### 3. Capability flag
+
+```ts
+readonly capabilities: Readonly<{
+    partialReads: boolean;
+    partialWrites: boolean;
+    nativeStreams: boolean;
+    atomicWrites: boolean;
+    contentAddressable: boolean;
+}>;
+```
+
+Default all `false`. Subclasses override per backend.
+
+### 4. Backend wiring (this change)
+
+| Backend | `setPartial` | `partialWrites` |
+| --- | --- | --- |
+| `MemoryStorage` | Native: resize `Uint8Array`, `set(bytes, offset)` | `true` |
+| `storage-s3` | `defaultSetPartial` (multipart wrapper deferred) | `false` |
+| Future ports (`storage-file`, `storage-browser-opfs`) | Native | `true` |
+| Future ports (`storage-browser` IndexedDB) | `defaultSetPartial` | `false` |
+
+## Impact
+
+- New abstract method; every concrete subclass MUST provide an impl.
+- `capabilities` becomes required readonly property; constructors set it.
+- `storage-s3` gains the fallback wiring (no behaviour change for non-`setPartial` callers).
+- New conformance tests pinning the contract.
+
+## Out of scope
+
+- `storage-s3` multipart-upload native impl — follow-up.
+- IndexedDB streaming chunked write — follow-up.
+- Atomicity guarantees — covered by `atomicWrites` flag.