suaveplan/openspec/specs/drive/spec.md

Drive — Capability Spec

DRIVE-01 — Drive consumes AbstractStorage directly

Drive MUST accept any concrete AbstractStorage from @suaveplan/storage as its storage substrate. There MUST NOT be a separate StorageAdapter shim. Drive MUST narrow capabilities through a DriveStorage view that extends AbstractStorage with id: string and optional lifecycle hooks.

Verified by: src/drive/drive.spec-conformance.test.ts::"accepts MemoryStorage as DriveStorage"

DRIVE-02 — initialize() is idempotent and ownership-tracking

Drive.initialize() MUST be idempotent. For each registered storage, drive MUST call storage.connect?.() ONLY when storage.isConnected?.() !== true, and MUST record those storages in an internal connectedByMe: WeakSet<DriveStorage>. Connection failures MUST surface as DriveError(DRIVE.STORAGE_CONNECT_FAILED, { cause }).

Verified by: src/drive/drive.spec-conformance.test.ts::"calls connect only when not already connected" AND src/drive/drive.spec-conformance.test.ts::"surfaces connect failure as STORAGE_CONNECT_FAILED"

DRIVE-03 — dispose() is idempotent and ownership-respecting

Drive.dispose() MUST be idempotent. Drive MUST only close storages in connectedByMe; storages pre-connected by the caller MUST be left open. After dispose(), the drive transitions to a terminal disposed state.

Verified by: src/drive/drive.spec-conformance.test.ts::"closes only storages connected by drive" AND src/drive/drive.spec-conformance.test.ts::"does not close pre-connected storage"

DRIVE-04 — Operations after dispose() throw

Any file operation invoked on a disposed drive (read, write, delete, stat, list, createReadStream, createWriteStream) MUST throw DriveError(DRIVE.DISPOSED). Operations invoked before initialize() MUST throw DriveError(DRIVE.NOT_INITIALIZED).

Verified by: src/drive/drive.spec-conformance.test.ts::"read throws DISPOSED after dispose" AND src/drive/drive.spec-conformance.test.ts::"read throws NOT_INITIALIZED before initialize"

DRIVE-05 — Error-code registry is namespaced and frozen

DRIVE_CODES MUST be declared via defineCodes("DRIVE", [...]) from @suaveplan/error. Object.isFrozen(DRIVE_CODES) MUST be true. Every code value MUST start with DRIVE.. DriveError MUST extend SuaveplanError<DriveErrorCode>.

Verified by: src/error-codes.spec-conformance.test.ts::"Object.isFrozen(DRIVE_CODES) is true" AND src/error-codes.spec-conformance.test.ts::"every code value starts with DRIVE."

DRIVE-06 — Plugin middleware order

drive.use(plugin) and drive.useMiddleware(mw) MUST install in registration order. Middleware chains for read, write, delete, stat, list MUST execute outer-first on the request path and outer-last on the response path. plugin.dispose() MUST be called in reverse-registration order on Drive.dispose(). Plugin install/dispose throws MUST surface as DriveError(DRIVE.PLUGIN_FAILED, { cause }).

Verified by: src/plugins/registry.spec-conformance.test.ts::"middleware executes outer-first request, outer-last response" AND src/plugins/registry.spec-conformance.test.ts::"dispose calls plugins in reverse registration order" AND src/plugins/registry.spec-conformance.test.ts::"plugin install throw surfaces as PLUGIN_FAILED"

DRIVE-07 — Capability fallbacks for streams

drive.createReadStream(path) MUST use storage.createReadStream when storage.capabilities?.nativeStreams === true, otherwise MUST fall back to the inherited AbstractStorage.defaultCreateReadStream. Same rule for createWriteStream.

Verified by: src/file-operations/streams.spec-conformance.test.ts::"createReadStream uses native stream when nativeStreams=true" AND src/file-operations/streams.spec-conformance.test.ts::"createReadStream falls back when nativeStreams=false"

DRIVE-08 — Generic storage typing

Drive<TStorageMap> MUST narrow TStorageMap through drive.use<K, S>(id, storage) so that drive.getStorage(id) returns TStorageMap[K] exactly (no widening to the base DriveStorage). Calls with an unknown id MUST be a TypeScript error.

Verified by: src/drive/drive.spec-conformance.test.ts::"getStorage returns narrowed type" (type-level)

DRIVE-09 — Constructor overloads

new Drive(), new Drive(storage), new Drive(storage, options), and new Drive({ defaultStorage, plugins, ... }) MUST all be valid. The bare-storage form MUST be observably equivalent to passing { defaultStorage: storage } and MUST register the storage under id "default".

Verified by: src/drive/drive.spec-conformance.test.ts::"new Drive() is valid" AND src/drive/drive.spec-conformance.test.ts::"new Drive(storage) registers as default"