@flowscripter/pluggable-io-framework-api 1.0.0 → 1.0.1

package/README.md

@@ -5,63 +5,47 @@
 [![docs](https://img.shields.io/badge/docs-API-blue)](https://flowscripter.github.io/pluggable-io-framework-api/index.html)
 [![license: MIT](https://img.shields.io/github/license/flowscripter/pluggable-io-framework-api)](https://github.com/flowscripter/pluggable-io-framework-api/blob/main/LICENSE)
 
-> API contracts for [pluggable-io-framework](https://github.com/flowscripter/pluggable-io-framework)
-> source/sink provider plugins
+> API for the https://github.com/flowscripter/pluggable-io-framework
 
 ## Key Features
 
 - Defines the `IOProviderFactory`/`IOProvider` contract that source/sink
-  plugins (e.g. local filesystem, object storage) implement, discovered and
+  plugins (e.g. local filesystem, object storage) implement which are then discovered and
   loaded via
   [dynamic-plugin-framework](https://github.com/flowscripter/dynamic-plugin-framework).
-- Config and per-item property schemas are defined with
-  [Zod](https://zod.dev) (source of truth), portable to JSON Schema via
-  `zod-to-json-schema` for hand-edited config files or non-TS validation.
-- `ChunkRef`: a tagged-union stream payload (`js` vs `native`) that carries
-  memory ownership/origin with it, enabling zero-copy handoff to/from
+- `IOProvider`, `StreamHandle` and `Part` are tagged with the single
+  `ChunkKind` ("js" or "native") a provider natively produces/consumes -
+  streams are homogeneous, so consumers never test each chunk's kind. A
+  mismatch between two linked streams is decided once per link via
+  `adaptReadableStream`, not once per chunk.
+- `JsChunk`/`NativeChunk`: a tagged-union stream payload that carries memory
+  ownership/origin with it, enabling zero-copy handoff to/from
   Rust-FFI-backed providers and decorators, with a small adapter to the
   standard Web Streams `ReadableStream<Uint8Array>`/`WritableStream<Uint8Array>`
   for interop (`fetch`, `pipeTo`, etc.).
+- Capabilities beyond plain streaming (e.g. `seekable`) are modeled as
+  small interfaces (`Seekable`, `RangeReadable`) with co-located type guards
+  (`isSeekable`, `isRangeReadable`).
 - Well-known item properties (`size`, `lastModified`, `isFolder`,
-  `contentType`) guaranteed by every provider, plus a provider-specific
-  `properties` extension bag for anything else (etag, storage class, custom
-  tags).
-- Multipart transfer modeled as a stream of independently readable/writable
-  `Part` handles, so parts can be processed concurrently.
-- Telemetry as a global `TelemetryHooks` object supplied once at
-  initialisation; every operation reports through it tagged with a
-  correlation id.
-- Pure TypeScript, minimal dependencies, no concrete provider
-  implementations - see
+  `contentType`) are default for every provider.
+- A provider-specific
+  `properties` extension bag supports other properties (e.g. etag, storage class, custom tags).
+- Provider config and per-item property schemas are defined with
+  [Zod](https://zod.dev).
+- Multipart transfers are modeled as a stream of independently readable/writable
+  `Part` handles allowing parts to be processed concurrently.
+- A global `TelemetryHooks` object is supplied once at
+  initialisation and every operation reports through it tagged with a
+  correlation ID.
+- Disposal is `Symbol.asyncDispose` (TC39 explicit resource management) -
+  `await using provider = await factory.createProvider(config)` disposes
+  deterministically, including on thrown errors.
+- See
   [pluggable-io-framework](https://github.com/flowscripter/pluggable-io-framework)
   for orchestration and
   [pluggable-io-framework-plugin-filesystem](https://github.com/flowscripter/pluggable-io-framework-plugin-filesystem)
   for a reference implementation.
 
-## Bun Module Usage
-
-Add the module:
-
-`bun add @flowscripter/pluggable-io-framework-api`
-
-Implement a provider factory:
-
-```typescript
-import { z } from "zod";
-import type { IOProviderFactory } from "@flowscripter/pluggable-io-framework-api";
-
-const configSchema = z.object({ rootPath: z.string() });
-const propertySchema = z.object({ etag: z.string().optional() });
-
-const factory: IOProviderFactory<z.infer<typeof configSchema>> = {
-  configSchema,
-  propertySchema,
-  async createProvider(config) {
-    // return an IOProvider implementation
-  },
-};
-```
-
 ## Development
 
 Install dependencies:
@@ -95,10 +79,10 @@ Generate HTML API Documentation:
 ```mermaid
 classDiagram
     IOProviderFactory --> IOProvider : creates
-    IOProvider --> StreamHandle : returns
-    IOProvider --> Part : returns (multipart)
-    StreamHandle --> ChunkRef : streams
-    Part --> ChunkRef : streams
+    IOProvider --> StreamHandle : returns (kind K)
+    IOProvider --> Part : returns (multipart, kind K)
+    StreamHandle --> JsChunk : streams (kind "js")
+    StreamHandle --> NativeChunk : streams (kind "native")
     IOProvider --> ItemProperties : returns
 
     class IOProviderFactory {
@@ -107,7 +91,8 @@ classDiagram
       +createProvider(config)
     }
     class IOProvider {
-      +dispose()
+      +kind: K
+      +[Symbol.asyncDispose]()
       +list(path, options)
       +getProperties(path)
       +setProperties(path, properties)

package/dist/src/ChunkRef.d.ts

@@ -1,40 +1,58 @@
 /**
- * A chunk of stream payload, tagged with its memory origin/ownership.
- *
- * This is the actual unit flowing through {@link StreamHandle} and
- * {@link Part} streams - not a TS-vs-Rust-specific type. A pure-TS pipeline
- * is simply a stream of `kind: "js"` chunks end to end.
- *
- * Tagging origin lets a consumer choose a zero-copy pointer handoff when
- * compatible (js -> rust always; rust -> rust always) or fall back to an
- * explicit copy when required (rust -> js, since JS code cannot safely
- * retain a raw pointer past the call that produced it).
- *
- * `attributes` is deliberately shaped close to the future Flowscripter
- * runtime's Item (attributes + payload) so this type is a natural fit if/when
- * an `adapt` operator wraps these streams later. It is unused today.
+ * The two possible chunk memory origins.
  */
-export type ChunkRef = {
-    readonly kind: "js";
+export declare enum ChunkKind {
+    Js = "js",
+    Native = "native"
+}
+/** A chunk whose payload lives in a normal JS-managed Uint8Array. */
+export interface JsChunk {
+    readonly kind: ChunkKind.Js;
     readonly data: Uint8Array;
     readonly attributes?: Readonly<Record<string, unknown>>;
-} | {
-    readonly kind: "native";
+}
+/**
+ * A chunk whose payload lives in memory owned outside the JS heap (e.g. a
+ * Rust-allocated buffer). `release()` must be called once nothing needs the
+ * buffer - ownership/lifetime is explicit rather than GC'd, since JS code
+ * cannot safely retain a raw pointer past the point its owner frees it.
+ */
+export interface NativeChunk {
+    readonly kind: ChunkKind.Native;
     readonly ptr: number;
     readonly length: number;
     release(): void;
     readonly attributes?: Readonly<Record<string, unknown>>;
-};
+}
+/**
+ * A chunk of stream payload, tagged with its memory origin/ownership.
+ */
+export type ChunkRef = JsChunk | NativeChunk;
+/** The concrete chunk type produced by a stream tagged with a given kind. */
+export type ChunkOfKind<K extends ChunkKind> = Extract<ChunkRef, {
+    kind: K;
+}>;
+/**
+ * Converts a single chunk to the target kind. Pure-TS code can only ever
+ * implement the identity case (same kind in, same kind out) - a real
+ * js<->native conversion needs FFI-capable pointer access and must be
+ * supplied by a runtime-specific package (e.g. via `bun:ffi`).
+ */
+export type ChunkConverter = (chunk: ChunkRef, toKind: ChunkKind) => ChunkRef;
+/** Identity converter - only handles chunks already of the requested kind. */
+export declare const identityChunkConverter: ChunkConverter;
 /**
- * Copy a chunk's bytes into a plain Uint8Array, regardless of origin.
- * The only copy incurred is for `kind: "native"` chunks.
+ * Adapts a homogeneous stream of one kind to another, using `convert`. When
+ * `fromKind === toKind` the stream is passed straight through untouched (no
+ * per-chunk work at all). This is the ONE place a kind mismatch is decided -
+ * once per stream link, not once per chunk.
  */
-export declare function toUint8Array(chunk: ChunkRef): Uint8Array;
+export declare function adaptReadableStream<From extends ChunkKind, To extends ChunkKind>(stream: ReadableStream<ChunkOfKind<From>>, fromKind: From, toKind: To, convert?: ChunkConverter): ReadableStream<ChunkOfKind<To>>;
 /**
  * Adapter to the standard Web Streams interop surface (fetch, pipeTo
  * external consumers). This is the one clearly-marked copy boundary -
  * internal source/sink/decorator code speaks {@link ChunkRef} directly.
  */
-export declare function toWebReadableStream(source: ReadableStream<ChunkRef>): ReadableStream<Uint8Array>;
-export declare function fromWebReadableStream(source: ReadableStream<Uint8Array>): ReadableStream<ChunkRef>;
+export declare function toWebReadableStream(source: ReadableStream<JsChunk>): ReadableStream<Uint8Array>;
+export declare function fromWebReadableStream(source: ReadableStream<Uint8Array>): ReadableStream<JsChunk>;
 //# sourceMappingURL=ChunkRef.d.ts.map

package/dist/src/ChunkRef.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChunkRef.d.ts","sourceRoot":"","sources":["../../src/ChunkRef.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,QAAQ,GAChB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD,CAAC;AAEN;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAehG;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GACjC,cAAc,CAAC,QAAQ,CAAC,CAe1B"}
+{"version":3,"file":"ChunkRef.d.ts","sourceRoot":"","sources":["../../src/ChunkRef.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,SAAS;IACnB,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,KAAK,QAAQ,CAAC;AAE9E,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,EAAE,cAOpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,SAAS,EAAE,EAAE,SAAS,SAAS,EAC9E,MAAM,EAAE,cAAc,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,EACzC,QAAQ,EAAE,IAAI,EACd,MAAM,EAAE,EAAE,EACV,OAAO,GAAE,cAAuC,GAC/C,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAkBjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAgB/F;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAejG"}

package/dist/src/ChunkRef.js

@@ -1,12 +1,42 @@
 /**
- * Copy a chunk's bytes into a plain Uint8Array, regardless of origin.
- * The only copy incurred is for `kind: "native"` chunks.
+ * The two possible chunk memory origins.
  */
-export function toUint8Array(chunk) {
-    if (chunk.kind === "js") {
-        return chunk.data;
+export var ChunkKind;
+(function (ChunkKind) {
+    ChunkKind["Js"] = "js";
+    ChunkKind["Native"] = "native";
+})(ChunkKind || (ChunkKind = {}));
+/** Identity converter - only handles chunks already of the requested kind. */
+export const identityChunkConverter = (chunk, toKind) => {
+    if (chunk.kind === toKind) {
+        return chunk;
     }
-    throw new Error("Copying a native ChunkRef to Uint8Array requires an FFI-capable runtime helper - not implemented in pluggable-io-framework-api");
+    throw new Error(`Cannot convert a "${chunk.kind}" chunk to "${toKind}" without an FFI-capable ChunkConverter`);
+};
+/**
+ * Adapts a homogeneous stream of one kind to another, using `convert`. When
+ * `fromKind === toKind` the stream is passed straight through untouched (no
+ * per-chunk work at all). This is the ONE place a kind mismatch is decided -
+ * once per stream link, not once per chunk.
+ */
+export function adaptReadableStream(stream, fromKind, toKind, convert = identityChunkConverter) {
+    if (fromKind === toKind) {
+        return stream;
+    }
+    const reader = stream.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            const { done, value } = await reader.read();
+            if (done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue(convert(value, toKind));
+        },
+        cancel(reason) {
+            return reader.cancel(reason);
+        },
+    });
 }
 /**
  * Adapter to the standard Web Streams interop surface (fetch, pipeTo
@@ -22,7 +52,8 @@ export function toWebReadableStream(source) {
                 controller.close();
                 return;
             }
-            controller.enqueue(toUint8Array(value));
+            // value is statically a JsChunk here - no per-chunk kind check needed.
+            controller.enqueue(value.data);
         },
         cancel(reason) {
             return reader.cancel(reason);
@@ -38,7 +69,7 @@ export function fromWebReadableStream(source) {
                 controller.close();
                 return;
             }
-            controller.enqueue({ kind: "js", data: value });
+            controller.enqueue({ kind: ChunkKind.Js, data: value });
         },
         cancel(reason) {
             return reader.cancel(reason);

package/dist/src/IOProvider.d.ts

@@ -1,16 +1,22 @@
+import type { ChunkKind } from "./ChunkRef.ts";
 import type { ItemProperties } from "./ItemProperties.ts";
 import type { Part } from "./Part.ts";
 import type { StreamHandle } from "./StreamHandle.ts";
 /**
  * A configured source/sink instance, as returned by
- * {@link IOProviderFactory.createProvider}.
+ * {@link IOProviderFactory.createProvider}. `K` is the single
+ * {@link ChunkKind} this provider natively produces/consumes - e.g. a
+ * pure-TS filesystem plugin is `IOProvider<"js">`, a Rust-FFI-backed plugin
+ * is `IOProvider<"native">`.
  *
- * Disposal is the explicit {@link IOProvider.dispose} method - not a reliance
- * on `Symbol.asyncDispose` - so plugins have an unambiguous, discoverable
- * contract for releasing connections/handles.
+ * Disposal is `Symbol.asyncDispose` (TC39 explicit resource management) -
+ * host code disposes deterministically via `await using provider = ...`,
+ * including on thrown errors, without needing a bespoke method name.
  */
-export interface IOProvider {
-    dispose(): Promise<void>;
+export interface IOProvider<K extends ChunkKind = ChunkKind> {
+    /** The single chunk kind this provider natively produces/consumes. */
+    readonly kind: K;
+    [Symbol.asyncDispose](): Promise<void>;
     list(path: string, options?: {
         recursive?: boolean;
         regex?: RegExp;
@@ -21,11 +27,11 @@ export interface IOProvider {
     getProperties(path: string): Promise<ItemProperties>;
     setProperties(path: string, properties: Partial<Record<string, unknown>>): Promise<void>;
     delete(path: string): Promise<void>;
-    getReadableStream(path: string): Promise<StreamHandle>;
-    getWritableStream(path: string): Promise<StreamHandle>;
-    getMultipartReader(path: string): AsyncIterable<Part>;
+    getReadableStream(path: string): Promise<StreamHandle<K>>;
+    getWritableStream(path: string): Promise<StreamHandle<K>>;
+    getMultipartReader(path: string): AsyncIterable<Part<K>>;
     getMultipartWriter(path: string): {
-        write(parts: AsyncIterable<Part>): Promise<void>;
+        write(parts: AsyncIterable<Part<K>>): Promise<void>;
     };
     /**
      * Self-reported direct-transfer eligibility - the provider owns what

package/dist/src/IOProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IOProvider.d.ts","sourceRoot":"","sources":["../../src/IOProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC/D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACrD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACtD,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAEvF;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/C,UAAU,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,UAAU,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}
+{"version":3,"file":"IOProvider.d.ts","sourceRoot":"","sources":["../../src/IOProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IACzD,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC/D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACrD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IAE1F;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/C,UAAU,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,UAAU,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}

package/dist/src/IOProviderFactory.d.ts

@@ -1,4 +1,5 @@
 import type { ZodType } from "zod";
+import type { ChunkKind } from "./ChunkRef.ts";
 import type { IOProvider } from "./IOProvider.ts";
 /**
  * Extension point constant that a `dynamic-plugin-framework` `Plugin`'s
@@ -10,14 +11,10 @@ export declare const PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT = "
  * Returned (as `unknown`, cast at the extension point boundary) from
  * `ExtensionFactory.create()` in a `dynamic-plugin-framework`
  * `ExtensionDescriptor`.
- *
- * Config/property schema: Zod is the source of truth; JSON Schema can be
- * derived via `zod-to-json-schema` for portability (hand-edited config
- * files, non-TS validation).
  */
-export interface IOProviderFactory<TConfig = unknown> {
+export interface IOProviderFactory<TConfig = unknown, K extends ChunkKind = ChunkKind> {
     readonly configSchema: ZodType<TConfig>;
     readonly propertySchema: ZodType<Record<string, unknown>>;
-    createProvider(config: TConfig): Promise<IOProvider>;
+    createProvider(config: TConfig): Promise<IOProvider<K>>;
 }
 //# sourceMappingURL=IOProviderFactory.d.ts.map

package/dist/src/IOProviderFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IOProviderFactory.d.ts","sourceRoot":"","sources":["../../src/IOProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,uDAAuD,0DACX,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,GAAG,OAAO;IAClD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACtD"}
+{"version":3,"file":"IOProviderFactory.d.ts","sourceRoot":"","sources":["../../src/IOProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,uDAAuD,0DACX,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,GAAG,OAAO,EAAE,CAAC,SAAS,SAAS,GAAG,SAAS;IACnF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;CACzD"}

package/dist/src/ItemProperties.d.ts

@@ -1,8 +1,7 @@
 /**
  * Properties of a file/folder item. `size`, `lastModified`, `isFolder` and
  * `contentType` are well-known, framework-guaranteed fields every provider
- * must populate so generic consumers (CLI, copy/move orchestration) can rely
- * on them without knowing the provider. Anything provider-specific (etag,
+ * must populate. Anything provider-specific (etag,
  * storage class, custom tags) goes in `properties`, validated against that
  * provider's `propertySchema`.
  */

package/dist/src/ItemProperties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ItemProperties.d.ts","sourceRoot":"","sources":["../../src/ItemProperties.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,IAAI,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD"}
+{"version":3,"file":"ItemProperties.d.ts","sourceRoot":"","sources":["../../src/ItemProperties.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,IAAI,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD"}

package/dist/src/Part.d.ts

@@ -1,13 +1,15 @@
-import type { ChunkRef } from "./ChunkRef.ts";
+import type { ChunkKind, ChunkOfKind } from "./ChunkRef.ts";
 /**
- * One independently readable/writable part of a multipart transfer.
- * Parts may be processed concurrently (e.g. `Promise.all` over N parts);
- * the provider assembles/commits them once all parts finish.
+ * One independently readable/writable part of a multipart transfer, carrying
+ * a homogeneous stream of a single declared {@link ChunkKind}. Parts may be
+ * processed concurrently (e.g. `Promise.all` over N parts); the provider
+ * assembles/commits them once all parts finish.
  */
-export interface Part {
+export interface Part<K extends ChunkKind = ChunkKind> {
     readonly index: number;
     readonly offset: number;
-    readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
+    readonly kind: K;
+    readonly stream: ReadableStream<ChunkOfKind<K>> | WritableStream<ChunkOfKind<K>>;
     complete(): Promise<void>;
 }
 //# sourceMappingURL=Part.d.ts.map

package/dist/src/Part.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Part.d.ts","sourceRoot":"","sources":["../../src/Part.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACrE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}
+{"version":3,"file":"Part.d.ts","sourceRoot":"","sources":["../../src/Part.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/src/StreamDecorator.d.ts

@@ -1,9 +1,22 @@
+import type { ChunkKind, ChunkOfKind } from "./ChunkRef.ts";
 import type { StreamHandle } from "./StreamHandle.ts";
+/** Capability added by the `seekable` decorator: jump to an absolute offset. */
+export interface Seekable {
+    seek(offset: number): Promise<void>;
+}
+export declare function isSeekable<K extends ChunkKind>(handle: StreamHandle<K>): handle is StreamHandle<K> & Seekable;
+/** Capability added by decorators that can serve an arbitrary byte range directly. */
+export interface RangeReadable<K extends ChunkKind = ChunkKind> {
+    readRange(start: number, end: number): Promise<ReadableStream<ChunkOfKind<K>>>;
+}
+export declare function isRangeReadable<K extends ChunkKind>(handle: StreamHandle<K>): handle is StreamHandle<K> & RangeReadable<K>;
 /**
  * A decorator wraps a {@link StreamHandle} and returns an enhanced handle
- * with additional capability methods (e.g. `seekable` adds `seek`/
- * `readRange`; `locally-cached` transparently serves repeated reads from a
- * local cache).
+ * with additional capabilities `C` (e.g. {@link Seekable}). When `C` is
+ * known at the call site (the common case - a specific decorator is applied
+ * directly), consumers get static typing with no runtime capability check
+ * needed. Where a handle arrives already decorated by unknown/dynamic
+ * decorators, use the `is*` type guards above instead.
  */
-export type StreamDecorator = (handle: StreamHandle) => StreamHandle;
+export type StreamDecorator<K extends ChunkKind = ChunkKind, C extends object = object> = (handle: StreamHandle<K>) => StreamHandle<K> & C;
 //# sourceMappingURL=StreamDecorator.d.ts.map

package/dist/src/StreamDecorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StreamDecorator.d.ts","sourceRoot":"","sources":["../../src/StreamDecorator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,YAAY,CAAC"}
+{"version":3,"file":"StreamDecorator.d.ts","sourceRoot":"","sources":["../../src/StreamDecorator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAC5C,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,MAAM,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAEtC;AAED,sFAAsF;AACtF,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC5D,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChF;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EACjD,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,MAAM,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAE9C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,CACxF,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,KACpB,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC"}

package/dist/src/StreamDecorator.js

@@ -1 +1,6 @@
-export {};
+export function isSeekable(handle) {
+    return typeof handle.seek === "function";
+}
+export function isRangeReadable(handle) {
+    return typeof handle.readRange === "function";
+}

package/dist/src/StreamHandle.d.ts

@@ -1,15 +1,13 @@
-import type { ChunkRef } from "./ChunkRef.ts";
+import type { ChunkKind, ChunkOfKind } from "./ChunkRef.ts";
 /**
- * A handle to a readable or writable stream of {@link ChunkRef}s, plus
- * optional capability methods for providers/decorators that support
- * random-access beyond plain sequential read (e.g. `seekable`).
- *
- * Capability methods are present only when supported - consumers
- * feature-detect via `typeof handle.seek === "function"` etc.
+ * A handle to a readable or writable stream of a single, declared
+ * {@link ChunkKind} - homogeneous, so consumers never need to test each
+ * chunk's kind. Plus optional capability methods for providers/decorators
+ * that support random-access beyond plain sequential read (e.g. `seekable`)
+ * - see {@link Seekable}/{@link isSeekable} in `StreamDecorator.ts`.
  */
-export interface StreamHandle {
-    readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
-    seek?(offset: number): Promise<void>;
-    readRange?(start: number, end: number): Promise<ReadableStream<ChunkRef>>;
+export interface StreamHandle<K extends ChunkKind = ChunkKind> {
+    readonly kind: K;
+    readonly stream: ReadableStream<ChunkOfKind<K>> | WritableStream<ChunkOfKind<K>>;
 }
 //# sourceMappingURL=StreamHandle.d.ts.map

package/dist/src/StreamHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StreamHandle.d.ts","sourceRoot":"","sources":["../../src/StreamHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACrE,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC3E"}
+{"version":3,"file":"StreamHandle.d.ts","sourceRoot":"","sources":["../../src/StreamHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC3D,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;CAClF"}

package/dist/src/TelemetryHooks.d.ts

@@ -1,9 +1,9 @@
 /**
  * Global telemetry hooks supplied once at framework initialisation. Every
- * operation is given a correlation id and reports through the same hooks,
- * tagged with that id/operation-type - callers don't need to thread a
+ * operation is given a correlation ID and reports through the same hooks,
+ * tagged with that ID/operation-type. Callers don't need to thread a
  * callback through every call, but can still track individual operations
- * via the id in emitted events.
+ * via the ID in emitted events.
  */
 export interface TelemetryHooks {
     onProgress?(event: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowscripter/pluggable-io-framework-api",
-  "version": "1.0.0",
-  "description": "API contracts for pluggable-io-framework source/sink provider plugins",
+  "version": "1.0.1",
+  "description": "API for the https://github.com/flowscripter/pluggable-io-framework",
   "keywords": [
     "api",
     "bun",

package/src/ChunkRef.ts

@@ -1,44 +1,87 @@
+/**
+ * The two possible chunk memory origins.
+ */
+export enum ChunkKind {
+  Js = "js",
+  Native = "native",
+}
+
+/** A chunk whose payload lives in a normal JS-managed Uint8Array. */
+export interface JsChunk {
+  readonly kind: ChunkKind.Js;
+  readonly data: Uint8Array;
+  readonly attributes?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A chunk whose payload lives in memory owned outside the JS heap (e.g. a
+ * Rust-allocated buffer). `release()` must be called once nothing needs the
+ * buffer - ownership/lifetime is explicit rather than GC'd, since JS code
+ * cannot safely retain a raw pointer past the point its owner frees it.
+ */
+export interface NativeChunk {
+  readonly kind: ChunkKind.Native;
+  readonly ptr: number;
+  readonly length: number;
+  release(): void;
+  readonly attributes?: Readonly<Record<string, unknown>>;
+}
+
 /**
  * A chunk of stream payload, tagged with its memory origin/ownership.
- *
- * This is the actual unit flowing through {@link StreamHandle} and
- * {@link Part} streams - not a TS-vs-Rust-specific type. A pure-TS pipeline
- * is simply a stream of `kind: "js"` chunks end to end.
- *
- * Tagging origin lets a consumer choose a zero-copy pointer handoff when
- * compatible (js -> rust always; rust -> rust always) or fall back to an
- * explicit copy when required (rust -> js, since JS code cannot safely
- * retain a raw pointer past the call that produced it).
- *
- * `attributes` is deliberately shaped close to the future Flowscripter
- * runtime's Item (attributes + payload) so this type is a natural fit if/when
- * an `adapt` operator wraps these streams later. It is unused today.
  */
-export type ChunkRef =
-  | {
-      readonly kind: "js";
-      readonly data: Uint8Array;
-      readonly attributes?: Readonly<Record<string, unknown>>;
-    }
-  | {
-      readonly kind: "native";
-      readonly ptr: number;
-      readonly length: number;
-      release(): void;
-      readonly attributes?: Readonly<Record<string, unknown>>;
-    };
+export type ChunkRef = JsChunk | NativeChunk;
+
+/** The concrete chunk type produced by a stream tagged with a given kind. */
+export type ChunkOfKind<K extends ChunkKind> = Extract<ChunkRef, { kind: K }>;
 
 /**
- * Copy a chunk's bytes into a plain Uint8Array, regardless of origin.
- * The only copy incurred is for `kind: "native"` chunks.
+ * Converts a single chunk to the target kind. Pure-TS code can only ever
+ * implement the identity case (same kind in, same kind out) - a real
+ * js<->native conversion needs FFI-capable pointer access and must be
+ * supplied by a runtime-specific package (e.g. via `bun:ffi`).
  */
-export function toUint8Array(chunk: ChunkRef): Uint8Array {
-  if (chunk.kind === "js") {
-    return chunk.data;
+export type ChunkConverter = (chunk: ChunkRef, toKind: ChunkKind) => ChunkRef;
+
+/** Identity converter - only handles chunks already of the requested kind. */
+export const identityChunkConverter: ChunkConverter = (chunk, toKind) => {
+  if (chunk.kind === toKind) {
+    return chunk;
   }
   throw new Error(
-    "Copying a native ChunkRef to Uint8Array requires an FFI-capable runtime helper - not implemented in pluggable-io-framework-api",
+    `Cannot convert a "${chunk.kind}" chunk to "${toKind}" without an FFI-capable ChunkConverter`,
   );
+};
+
+/**
+ * Adapts a homogeneous stream of one kind to another, using `convert`. When
+ * `fromKind === toKind` the stream is passed straight through untouched (no
+ * per-chunk work at all). This is the ONE place a kind mismatch is decided -
+ * once per stream link, not once per chunk.
+ */
+export function adaptReadableStream<From extends ChunkKind, To extends ChunkKind>(
+  stream: ReadableStream<ChunkOfKind<From>>,
+  fromKind: From,
+  toKind: To,
+  convert: ChunkConverter = identityChunkConverter,
+): ReadableStream<ChunkOfKind<To>> {
+  if ((fromKind as ChunkKind) === (toKind as ChunkKind)) {
+    return stream as unknown as ReadableStream<ChunkOfKind<To>>;
+  }
+  const reader = stream.getReader();
+  return new ReadableStream<ChunkOfKind<To>>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(convert(value, toKind) as ChunkOfKind<To>);
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
 }
 
 /**
@@ -46,7 +89,7 @@ export function toUint8Array(chunk: ChunkRef): Uint8Array {
  * external consumers). This is the one clearly-marked copy boundary -
  * internal source/sink/decorator code speaks {@link ChunkRef} directly.
  */
-export function toWebReadableStream(source: ReadableStream<ChunkRef>): ReadableStream<Uint8Array> {
+export function toWebReadableStream(source: ReadableStream<JsChunk>): ReadableStream<Uint8Array> {
   const reader = source.getReader();
   return new ReadableStream<Uint8Array>({
     async pull(controller) {
@@ -55,7 +98,8 @@ export function toWebReadableStream(source: ReadableStream<ChunkRef>): ReadableS
         controller.close();
         return;
       }
-      controller.enqueue(toUint8Array(value));
+      // value is statically a JsChunk here - no per-chunk kind check needed.
+      controller.enqueue(value.data);
     },
     cancel(reason) {
       return reader.cancel(reason);
@@ -63,18 +107,16 @@ export function toWebReadableStream(source: ReadableStream<ChunkRef>): ReadableS
   });
 }
 
-export function fromWebReadableStream(
-  source: ReadableStream<Uint8Array>,
-): ReadableStream<ChunkRef> {
+export function fromWebReadableStream(source: ReadableStream<Uint8Array>): ReadableStream<JsChunk> {
   const reader = source.getReader();
-  return new ReadableStream<ChunkRef>({
+  return new ReadableStream<JsChunk>({
     async pull(controller) {
       const { done, value } = await reader.read();
       if (done) {
         controller.close();
         return;
       }
-      controller.enqueue({ kind: "js", data: value });
+      controller.enqueue({ kind: ChunkKind.Js, data: value });
     },
     cancel(reason) {
       return reader.cancel(reason);

package/src/IOProvider.ts

@@ -1,17 +1,24 @@
+import type { ChunkKind } from "./ChunkRef.ts";
 import type { ItemProperties } from "./ItemProperties.ts";
 import type { Part } from "./Part.ts";
 import type { StreamHandle } from "./StreamHandle.ts";
 
 /**
  * A configured source/sink instance, as returned by
- * {@link IOProviderFactory.createProvider}.
+ * {@link IOProviderFactory.createProvider}. `K` is the single
+ * {@link ChunkKind} this provider natively produces/consumes - e.g. a
+ * pure-TS filesystem plugin is `IOProvider<"js">`, a Rust-FFI-backed plugin
+ * is `IOProvider<"native">`.
  *
- * Disposal is the explicit {@link IOProvider.dispose} method - not a reliance
- * on `Symbol.asyncDispose` - so plugins have an unambiguous, discoverable
- * contract for releasing connections/handles.
+ * Disposal is `Symbol.asyncDispose` (TC39 explicit resource management) -
+ * host code disposes deterministically via `await using provider = ...`,
+ * including on thrown errors, without needing a bespoke method name.
  */
-export interface IOProvider {
-  dispose(): Promise<void>;
+export interface IOProvider<K extends ChunkKind = ChunkKind> {
+  /** The single chunk kind this provider natively produces/consumes. */
+  readonly kind: K;
+
+  [Symbol.asyncDispose](): Promise<void>;
 
   list(
     path: string,
@@ -21,10 +28,10 @@ export interface IOProvider {
   setProperties(path: string, properties: Partial<Record<string, unknown>>): Promise<void>;
   delete(path: string): Promise<void>;
 
-  getReadableStream(path: string): Promise<StreamHandle>;
-  getWritableStream(path: string): Promise<StreamHandle>;
-  getMultipartReader(path: string): AsyncIterable<Part>;
-  getMultipartWriter(path: string): { write(parts: AsyncIterable<Part>): Promise<void> };
+  getReadableStream(path: string): Promise<StreamHandle<K>>;
+  getWritableStream(path: string): Promise<StreamHandle<K>>;
+  getMultipartReader(path: string): AsyncIterable<Part<K>>;
+  getMultipartWriter(path: string): { write(parts: AsyncIterable<Part<K>>): Promise<void> };
 
   /**
    * Self-reported direct-transfer eligibility - the provider owns what

package/src/IOProviderFactory.ts

@@ -1,4 +1,5 @@
 import type { ZodType } from "zod";
+import type { ChunkKind } from "./ChunkRef.ts";
 import type { IOProvider } from "./IOProvider.ts";
 
 /**
@@ -13,13 +14,9 @@ export const PLUGGABLE_IO_FRAMEWORK_PROVIDER_FACTORY_EXTENSION_POINT =
  * Returned (as `unknown`, cast at the extension point boundary) from
  * `ExtensionFactory.create()` in a `dynamic-plugin-framework`
  * `ExtensionDescriptor`.
- *
- * Config/property schema: Zod is the source of truth; JSON Schema can be
- * derived via `zod-to-json-schema` for portability (hand-edited config
- * files, non-TS validation).
  */
-export interface IOProviderFactory<TConfig = unknown> {
+export interface IOProviderFactory<TConfig = unknown, K extends ChunkKind = ChunkKind> {
   readonly configSchema: ZodType<TConfig>;
   readonly propertySchema: ZodType<Record<string, unknown>>;
-  createProvider(config: TConfig): Promise<IOProvider>;
+  createProvider(config: TConfig): Promise<IOProvider<K>>;
 }

package/src/ItemProperties.ts

@@ -1,8 +1,7 @@
 /**
  * Properties of a file/folder item. `size`, `lastModified`, `isFolder` and
  * `contentType` are well-known, framework-guaranteed fields every provider
- * must populate so generic consumers (CLI, copy/move orchestration) can rely
- * on them without knowing the provider. Anything provider-specific (etag,
+ * must populate. Anything provider-specific (etag,
  * storage class, custom tags) goes in `properties`, validated against that
  * provider's `propertySchema`.
  */

package/src/Part.ts

@@ -1,13 +1,15 @@
-import type { ChunkRef } from "./ChunkRef.ts";
+import type { ChunkKind, ChunkOfKind } from "./ChunkRef.ts";
 
 /**
- * One independently readable/writable part of a multipart transfer.
- * Parts may be processed concurrently (e.g. `Promise.all` over N parts);
- * the provider assembles/commits them once all parts finish.
+ * One independently readable/writable part of a multipart transfer, carrying
+ * a homogeneous stream of a single declared {@link ChunkKind}. Parts may be
+ * processed concurrently (e.g. `Promise.all` over N parts); the provider
+ * assembles/commits them once all parts finish.
  */
-export interface Part {
+export interface Part<K extends ChunkKind = ChunkKind> {
   readonly index: number;
   readonly offset: number;
-  readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
+  readonly kind: K;
+  readonly stream: ReadableStream<ChunkOfKind<K>> | WritableStream<ChunkOfKind<K>>;
   complete(): Promise<void>;
 }

package/src/StreamDecorator.ts

@@ -1,9 +1,36 @@
+import type { ChunkKind, ChunkOfKind } from "./ChunkRef.ts";
 import type { StreamHandle } from "./StreamHandle.ts";
 
+/** Capability added by the `seekable` decorator: jump to an absolute offset. */
+export interface Seekable {
+  seek(offset: number): Promise<void>;
+}
+
+export function isSeekable<K extends ChunkKind>(
+  handle: StreamHandle<K>,
+): handle is StreamHandle<K> & Seekable {
+  return typeof (handle as Partial<Seekable>).seek === "function";
+}
+
+/** Capability added by decorators that can serve an arbitrary byte range directly. */
+export interface RangeReadable<K extends ChunkKind = ChunkKind> {
+  readRange(start: number, end: number): Promise<ReadableStream<ChunkOfKind<K>>>;
+}
+
+export function isRangeReadable<K extends ChunkKind>(
+  handle: StreamHandle<K>,
+): handle is StreamHandle<K> & RangeReadable<K> {
+  return typeof (handle as Partial<RangeReadable<K>>).readRange === "function";
+}
+
 /**
  * A decorator wraps a {@link StreamHandle} and returns an enhanced handle
- * with additional capability methods (e.g. `seekable` adds `seek`/
- * `readRange`; `locally-cached` transparently serves repeated reads from a
- * local cache).
+ * with additional capabilities `C` (e.g. {@link Seekable}). When `C` is
+ * known at the call site (the common case - a specific decorator is applied
+ * directly), consumers get static typing with no runtime capability check
+ * needed. Where a handle arrives already decorated by unknown/dynamic
+ * decorators, use the `is*` type guards above instead.
  */
-export type StreamDecorator = (handle: StreamHandle) => StreamHandle;
+export type StreamDecorator<K extends ChunkKind = ChunkKind, C extends object = object> = (
+  handle: StreamHandle<K>,
+) => StreamHandle<K> & C;

package/src/StreamHandle.ts

@@ -1,15 +1,13 @@
-import type { ChunkRef } from "./ChunkRef.ts";
+import type { ChunkKind, ChunkOfKind } from "./ChunkRef.ts";
 
 /**
- * A handle to a readable or writable stream of {@link ChunkRef}s, plus
- * optional capability methods for providers/decorators that support
- * random-access beyond plain sequential read (e.g. `seekable`).
- *
- * Capability methods are present only when supported - consumers
- * feature-detect via `typeof handle.seek === "function"` etc.
+ * A handle to a readable or writable stream of a single, declared
+ * {@link ChunkKind} - homogeneous, so consumers never need to test each
+ * chunk's kind. Plus optional capability methods for providers/decorators
+ * that support random-access beyond plain sequential read (e.g. `seekable`)
+ * - see {@link Seekable}/{@link isSeekable} in `StreamDecorator.ts`.
  */
-export interface StreamHandle {
-  readonly stream: ReadableStream<ChunkRef> | WritableStream<ChunkRef>;
-  seek?(offset: number): Promise<void>;
-  readRange?(start: number, end: number): Promise<ReadableStream<ChunkRef>>;
+export interface StreamHandle<K extends ChunkKind = ChunkKind> {
+  readonly kind: K;
+  readonly stream: ReadableStream<ChunkOfKind<K>> | WritableStream<ChunkOfKind<K>>;
 }

package/src/TelemetryHooks.ts

@@ -1,9 +1,9 @@
 /**
  * Global telemetry hooks supplied once at framework initialisation. Every
- * operation is given a correlation id and reports through the same hooks,
- * tagged with that id/operation-type - callers don't need to thread a
+ * operation is given a correlation ID and reports through the same hooks,
+ * tagged with that ID/operation-type. Callers don't need to thread a
  * callback through every call, but can still track individual operations
- * via the id in emitted events.
+ * via the ID in emitted events.
  */
 export interface TelemetryHooks {
   onProgress?(event: {