first commit

docs/networking/drive/drive-uri/src/plugins/drive-mesh/drive-mesh.md

@@ -0,0 +1,91 @@
+# `@suaveplan/drive-uri/plugins/drive-mesh`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`driveMeshUriPlugin(options)` is a factory returning a `UriPlugin` registered
+against the `drive+mesh://` scheme. It parses `drive+mesh://<swarmId>/<path>`
+URIs, captures `swarmId` for instrumentation, and forwards `path` to the
+consumer-supplied mesh-configured `Drive`. The plugin does NOT use `swarmId`
+to choose a `Drive` or transport — peer routing remains entirely the
+responsibility of the `Drive`'s installed transports (`drive-transport-https`,
+`drive-webrtc`) and its `PeerRegistry`.
+
+The captured `swarmId` surfaces on every emitted span via the
+`drive.uri.swarm_id` attribute. When a span is active at the time of
+`parse(uri)`, the attribute is written there (alongside `drive.uri.scheme`
+and the redacted `drive.uri`); otherwise the parse step is silent.
+
+## Features
+
+- `parse(uri)` enforces `scheme === "drive+mesh"`, a non-empty authority, and
+  a non-empty path. All other URI hygiene (whitespace, NUL, scheme regex,
+  4096-char limit) is delegated to `parseUri` from `@suaveplan/storage-uri`.
+- `build(key, meta?)` round-trips the URI back to its source shape, defaulting
+  the swarmId to `options.defaultSwarmId` (or `"default"`) when no meta is
+  supplied.
+- Adapter inherits `InstrumentedDriveAdapter` so reads, writes, and errors
+  are recorded under the `drive+mesh` scheme attribute.
+
+## Usage: Basic
+
+```ts
+import { Drive } from "@suaveplan/drive";
+import { chunksPlugin } from "@suaveplan/drive-plugin-chunks";
+import { createStorageUriResolver } from "@suaveplan/storage-uri";
+import { driveMeshUriPlugin } from "@suaveplan/drive-uri/plugins/drive-mesh";
+
+const meshDrive = new Drive(localStorage);
+await meshDrive.initialize();
+await meshDrive.usePlugin(chunksPlugin({ /* ... */ }));
+
+const resolver = createStorageUriResolver([
+    driveMeshUriPlugin({ drive: meshDrive }),
+]);
+
+const bytes = await resolver.read("drive+mesh://swarmA/raw/clip.mov");
+```
+
+## Usage: Advanced
+
+Mixing mesh and template plugins on the same mesh-configured Drive so a
+single resolver dispatches both shapes through one drive instance:
+
+```ts
+import {
+    driveMeshUriPlugin,
+    driveTemplateUriPlugin,
+} from "@suaveplan/drive-uri";
+
+const resolver = createStorageUriResolver([
+    driveMeshUriPlugin({ drive: meshDrive, defaultSwarmId: "primary" }),
+    driveTemplateUriPlugin({ drive: meshDrive, templateProvider }),
+]);
+
+await resolver.read("drive+mesh://primary/folder/a.bin");
+await resolver.read("drive+template://templA/folder/a.bin");
+```
+
+The two plugins share the same `Drive`, so a hydration triggered by the
+template plugin populates the file-location index that the mesh plugin then
+uses to fetch chunks. This is the canonical composition.
+
+## API Reference
+
+- `driveMeshUriPlugin(options: DriveMeshUriPluginOptions): UriPlugin` —
+  `options.drive` is required; `options.defaultSwarmId` is optional and
+  defaults to `"default"` for `build` output.
+
+## Implementation Notes
+
+- The plugin's `parse(uri)` attaches the swarmId to the active span via
+  `trace.getActiveSpan()`. When no span is active (e.g. plugin used
+  outside the resolver, in unit tests parsing URIs directly), the
+  attribute write is silently skipped — never throws.
+- The `drive.uri` attribute is passed through `redactUri` so query strings
+  carrying peer hints or seeds are stripped before reaching span backends.
+- Like `driveUriPlugin`, writes are rejected with `DRIVE_URI.WRITE_UNSUPPORTED`
+  per the per-release scope.