Initial Commit

openspec/archive/2026-05-16-fix-storage-uri-error-passthrough/specs/drive-uri/spec.md

@@ -0,0 +1,75 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: drive-uri (fix-storage-uri-error-passthrough)
+
+**Package**: `@suaveplan/drive-uri`
+**Status**: PROPOSED
+
+> Every requirement carries a `**Verified by:**` line at authoring time. This delta MODIFIES five scenarios across three requirements from `add-drive-uri` (still in `openspec/changes/`, not yet archived). The `**Note —** revisited in `fix-storage-uri-error-passthrough`...` annotation at the top of the drive-uri `add-drive-uri` delta is also retired by this change. (The companion `**Note —** buffered-read signal threading` annotation stays, since `add-signal-to-storage-like` has not landed.)
+
+## MODIFIED Requirements
+
+### Requirement: `drive://` plugin parses authority as driveId and delegates to `Drive.read`
+
+The `driveUriPlugin(options)` factory SHALL return a `UriPlugin` with `scheme === "drive"`. Its `parse` SHALL extract the URI authority as `driveId` and the remainder as a slash-prefix-trimmed `key`. The returned plugin SHALL forward `key` to the consumer-supplied `Drive` via `Drive.read(key, { signal })` (or `Drive.createReadStream` on `open()`). The plugin SHALL throw `DRIVE_URI.DRIVE_ID_MISMATCH` when the URI's driveId does not equal the `driveId` declared in `options`.
+
+The `StorageUriResolver` SHALL surface this throw directly per the pass-through rule (see `fix-storage-uri-error-passthrough` spec delta for storage-uri).
+
+#### Scenario: URI dispatches to Drive.read
+
+- **WHEN** `resolver.read("drive://primary/folder/file.bin")` is called and the resolver holds `driveUriPlugin({ drive, driveId: "primary" })`
+- **THEN** `drive.read("folder/file.bin", { signal })` is invoked exactly once and its return value is the resolver's result
+
+#### Scenario: driveId mismatch surfaces DRIVE_URI.DRIVE_ID_MISMATCH directly
+
+- **WHEN** `resolver.read("drive://other/x")` is called and the plugin is configured with `driveId: "primary"`
+- **THEN** the call rejects with `DriveUriError` having `code === "DRIVE_URI.DRIVE_ID_MISMATCH"`, `uri === "drive://other/x"`, `expected === "primary"`, `actual === "other"` (the resolver passes the `DriveUriError` through unchanged per the storage-uri pass-through rule; no `STORAGE_URI.*` envelope is added)
+
+#### Scenario: build round-trips driveId and key
+
+- **WHEN** `plugin.build("folder/file.bin", { driveId: "primary" })` is called
+- **THEN** the returned string equals `"drive://primary/folder/file.bin"`
+
+**Verified by:** `src/plugins/drive/drive.test.ts::"dispatches a drive:// URI to Drive.read"` AND `src/plugins/drive/drive.test.ts::"throws DRIVE_ID_MISMATCH when URI driveId differs from configured driveId"` AND `src/plugins/drive/drive.test.ts::"build round-trips driveId and key into a drive:// URI"`
+
+---
+
+### Requirement: Template fetch and hydration failures map to distinct DRIVE_URI codes
+
+When `options.templateProvider.fetchTemplate` rejects, the plugin SHALL re-wrap the rejection as `DRIVE_URI.TEMPLATE_NOT_AVAILABLE` with the original error preserved on `cause`. When `Drive.hydrateFrom` rejects (any `DTP_*` code), the plugin SHALL re-wrap the rejection as `DRIVE_URI.TEMPLATE_INVALID` with the original on `cause`. The two failures MUST NOT be conflated — operator response differs (network/availability vs. integrity).
+
+The `StorageUriResolver` SHALL surface both `DriveUriError`s directly per the pass-through rule.
+
+#### Scenario: fetchTemplate rejection becomes TEMPLATE_NOT_AVAILABLE
+
+- **WHEN** `resolver.read("drive+template://templA/x")` is called and `templateProvider.fetchTemplate` rejects with `new Error("404")`
+- **THEN** the call rejects with `DriveUriError` having `code === "DRIVE_URI.TEMPLATE_NOT_AVAILABLE"` AND `cause.message === "404"`
+
+#### Scenario: hydrateFrom rejection becomes TEMPLATE_INVALID
+
+- **WHEN** `resolver.read("drive+template://templA/x")` is called and `drive.hydrateFrom` rejects with a `SuaveplanError` carrying `code === "DTP.TEMPLATE_EXPIRED"`
+- **THEN** the call rejects with `DriveUriError` having `code === "DRIVE_URI.TEMPLATE_INVALID"` AND `cause.code === "DTP.TEMPLATE_EXPIRED"`
+
+**Verified by:** `src/plugins/drive-template/drive-template.test.ts::"wraps fetchTemplate rejection as TEMPLATE_NOT_AVAILABLE"` AND `src/plugins/drive-template/drive-template.test.ts::"wraps hydrateFrom rejection as TEMPLATE_INVALID"`
+
+---
+
+### Requirement: Writes via drive:// schemes are rejected
+
+The three plugins SHALL reject `set` (write) calls with `DRIVE_URI.WRITE_UNSUPPORTED`. The rejection SHALL carry the original URI and scheme on the error so operators can see misuse rate via `drive_uri.writes_total{scheme, outcome: "error"}`.
+
+The `StorageUriResolver` SHALL surface this throw directly per the pass-through rule — `err.code === "DRIVE_URI.WRITE_UNSUPPORTED"` reaches the caller without a `STORAGE_URI.WRITE_UNSUPPORTED` envelope.
+
+#### Scenario: write against drive:// rejects with DRIVE_URI.WRITE_UNSUPPORTED
+
+- **WHEN** `resolver.write("drive://primary/x", new Uint8Array([1, 2, 3]))` is called
+- **THEN** the call rejects with `DriveUriError` having `code === "DRIVE_URI.WRITE_UNSUPPORTED"`, `uri === "drive://primary/x"`, `scheme === "drive"`
+
+#### Scenario: writes_total counter increments on the rejection
+
+- **WHEN** `resolver.write("drive+mesh://swarmA/x", bytes)` is called
+- **THEN** `drive_uri.writes_total{scheme: "drive+mesh", outcome: "error"}` is incremented by 1
+
+**Verified by:** `src/plugins/drive/drive.test.ts::"rejects writes with DRIVE_URI.WRITE_UNSUPPORTED"` AND `src/otel/otel.test.ts::"increments writes_total on rejected writes"`
+
+<!-- markdownlint-enable MD024 -->