Initial Commit

openspec/archive/2026-05-16-fix-storage-uri-error-passthrough/tasks.md

@@ -0,0 +1,62 @@
+# Tasks — fix-storage-uri-error-passthrough
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 1. Spec authoring
+
+- [ ] 1.1 Read `openspec/changes/add-storage-uri/specs/storage-uri/spec.md` requirements "Adapter error re-wrapping" and "Streaming writes with buffered fallback"
+- [ ] 1.2 Read `openspec/changes/add-drive-uri/specs/drive-uri/spec.md` — confirm the wrap-aware scenarios to tighten
+- [ ] 1.3 Read `openspec/AGENTS.md` §0c, §2c, §13, §13a, §14
+- [ ] 1.4 Read `packages/core/error/src/error.ts` (or equivalent) — confirm `SuaveplanError` is the right `instanceof` target
+- [ ] 1.5 Draft `proposal.md`, `specs/storage-uri/spec.md` (MODIFIED form), `specs/drive-uri/spec.md` (MODIFIED form), `tasks.md`
+- [ ] 1.6 Build numbered Requirement/Scenario implementation checklist (§0c step 6) — 2 MODIFIED storage-uri requirements, 3 MODIFIED drive-uri requirements
+
+## 2. Storage-uri implementation
+
+- [ ] 2.1 Locate the resolver's error-handling branch — `packages/storage/storage-uri/src/resolver/resolver.ts` (`#wrapAdapterError` or equivalent)
+- [ ] 2.2 Change the discriminator from `err instanceof StorageUriError` to `err instanceof SuaveplanError`
+- [ ] 2.3 Same change in the write path — `packages/storage/storage-uri/src/resolver/resolver.writes.ts` (`WRITE_UNSUPPORTED` wrap branch)
+- [ ] 2.4 Verify the `import` is from `@suaveplan/error` (it already is for `StorageUriError`'s base — `SuaveplanError` ships from there)
+- [ ] 2.5 Update sibling `.md` docs — `resolver.md`, `resolver.writes.md` — to describe the new pass-through behaviour (§4a doc-drift gate)
+- [ ] 2.6 Update README "Features" section if it claims errors are uniformly wrapped
+
+## 3. Storage-uri tests
+
+- [ ] 3.1 `src/resolver/resolver.test.ts` — rename existing `"wraps adapter errors as ADAPTER_ERROR"` to `"wraps non-SuaveplanError throwables as ADAPTER_ERROR"`; assertion stays (plain `Error` thrown → `STORAGE_URI.ADAPTER_ERROR` wrap)
+- [ ] 3.2 `src/resolver/resolver.test.ts` — add `it("passes through thrown SuaveplanError subclasses unchanged", ...)` — instantiate a `SuaveplanError("FOO.BAR", ...)` directly (no need to import `DriveUriError`), throw from a fake adapter, assert resolver re-throws same instance with `err.code === "FOO.BAR"`
+- [ ] 3.3 `src/resolver/resolver.writes.test.ts` — rename existing `"wraps read-only adapter error as WRITE_UNSUPPORTED"` to `"wraps non-Suaveplan throw on set as WRITE_UNSUPPORTED"` and switch the fixture to throw a plain `new Error(...)` (not a `StorageHttpError`); assertion stays
+- [ ] 3.4 `src/resolver/resolver.writes.test.ts` — add `it("passes through thrown SuaveplanError subclasses on write", ...)` — fake adapter throws `new SuaveplanError("FOO.BAR", ...)` from `set`, assert resolver re-throws same instance
+- [ ] 3.5 Every `it(...)` carries `{ timeout: 5000 }`
+- [ ] 3.6 No `vi.mock`; tests construct real fake adapters per CLAUDE.md rule 2
+- [ ] 3.7 All test imports remain via `@suaveplan/testing/runner` (rule 11)
+
+## 4. Drive-uri test tightening (no production code change)
+
+- [ ] 4.1 `packages/drive/drive-uri/src/plugins/drive/drive.test.ts` — switch the `DRIVE_ID_MISMATCH` test from asserting `err.cause.code === "DRIVE_URI.DRIVE_ID_MISMATCH"` to asserting `err.code === "DRIVE_URI.DRIVE_ID_MISMATCH"` (and `err instanceof DriveUriError`)
+- [ ] 4.2 `packages/drive/drive-uri/src/plugins/drive/drive.test.ts` — switch the `WRITE_UNSUPPORTED` test to direct-code assertion
+- [ ] 4.3 `packages/drive/drive-uri/src/plugins/drive-template/drive-template.test.ts` — switch `TEMPLATE_NOT_AVAILABLE` and `TEMPLATE_INVALID` tests to direct-code assertion
+- [ ] 4.4 `packages/drive/drive-uri/src/plugins/drive-mesh/drive-mesh.test.ts` — same treatment if a `.cause`-based assertion exists
+- [ ] 4.5 Coverage stays at 100/100/100/100 (no production code changed; some branches in the test helpers may become unreachable — remove unused helpers if so per §7a — write the test against real behaviour, don't preserve dead code)
+
+## 5. Spec annotation cleanup (drive-uri)
+
+- [ ] 5.1 In `openspec/changes/add-drive-uri/specs/drive-uri/spec.md`, remove the top-of-file `> **Note — error-wrap behaviour is revisited in fix-storage-uri-error-passthrough.**` paragraph (the behaviour it described is now retired by this change)
+- [ ] 5.2 Keep the second top-of-file `> **Note — buffered-read signal threading is revisited in add-signal-to-storage-like.**` paragraph as-is (separate concern, not retired yet)
+- [ ] 5.3 Confirm no remaining scenarios in `add-drive-uri/specs/drive-uri/spec.md` reference `STORAGE_URI.ADAPTER_ERROR` or "cause.code" indirection for drive-uri throws — if any remain, tighten them in this delta
+
+## 6. Gates
+
+- [ ] 6.1 `bunx turbo lint typecheck test --filter=@suaveplan/storage-uri`
+- [ ] 6.2 `bunx turbo test:coverage --filter=@suaveplan/storage-uri --force` — 100/100/100/100 Istanbul
+- [ ] 6.3 `bunx turbo lint typecheck test --filter=@suaveplan/drive-uri`
+- [ ] 6.4 `bunx turbo test:coverage --filter=@suaveplan/drive-uri --force` — 100/100/100/100 Istanbul
+- [ ] 6.5 `bunx turbo build --filter=@suaveplan/storage-uri @suaveplan/drive-uri`
+- [ ] 6.6 Dependent sweep — `bunx turbo test --filter=...@suaveplan/storage-uri` (catches any consumer that asserted on `err.code === "STORAGE_URI.ADAPTER_ERROR"` for what is now a passed-through `SuaveplanError`)
+- [ ] 6.7 `bun scripts/lint/check-test-runner-imports.ts`
+- [ ] 6.8 Banned-pattern scan empty for both packages' `src/`
+- [ ] 6.9 Spec-reconciliation gate — every modified scenario's `**Verified by:**` test name exists verbatim
+
+## 7. Manifest & archival (defer)
+
+- [ ] 7.1 This change folder remains in `openspec/changes/` until `add-storage-uri` and `add-drive-uri` are archived together. The fold step for all three changes happens as a single archival wave so the canonical `openspec/specs/storage-uri/spec.md` and `openspec/specs/drive-uri/spec.md` reflect the final, pass-through behaviour from day one.
+- [ ] 7.2 At archive time, the modified scenarios from this delta supersede the originals in the `add-storage-uri` / `add-drive-uri` deltas during the fold.