Initial Commit

openspec/archive/2026-05-10-network-plugin-content-delivery-prefetch/proposal.md

@@ -0,0 +1,28 @@
+# OpenSpec Change: network-plugin-content-delivery-prefetch
+
+- **Change ID**: network-plugin-content-delivery-prefetch
+- **Package**: `@suaveplan/network-plugin-content-delivery` (extension)
+- **Status**: PROPOSED
+- **Type**: extension
+- **Date**: 2026-05-05
+
+## Why
+
+The core `network-plugin-content-delivery` change shipped the mesh-CDN primitives but deferred `PrefetchEngine` — the proactive fetch path that uses session context to predict which chunks a peer will need next. That deferral was per the parent proposal's `## Deferred to follow-up changes` block because the predictor needs `network-plugin-session` scope to limit prefetch to relevant peers and the heuristic itself warrants its own design + tuning.
+
+This change adds `PrefetchEngine` to the existing package without breaking the core surface.
+
+## What changes
+
+- **ADDED**: `PrefetchEngine` class with a pluggable `PredictionModel` (`(context) => readonly chunkHash[]`).
+- **ADDED**: Session-scoped prefetch — predictions only fan out to peers in the current `SessionScope`.
+- **ADDED**: `cd:prefetch-issued` event for observability of prefetch dispatches.
+- **ADDED**: `ContentDeliveryPlugin.prefetch` getter wires the new subsystem onto the plugin facade.
+
+## Verification approach
+
+- `src/prefetch/prefetch-engine.spec-conformance.test.ts` — pins prediction-model invocation, session-scope filtering, dedupe, observability event.
+
+## Migration impact
+
+None — additive only.

openspec/archive/2026-05-10-network-plugin-content-delivery-prefetch/tasks.md

@@ -0,0 +1,21 @@
+# Tasks — network-plugin-content-delivery-prefetch
+
+> Blocked on: `network-plugin-content-delivery` (core), `network-plugin-session`.
+
+## 1. Implementation
+
+- [x] 1.1 `src/prefetch/prefetch-engine.ts` — `PrefetchEngine` with pluggable `PredictionModel`.
+- [x] 1.2 Session-scoped fan-out via injected `SessionScope` provider.
+- [x] 1.3 Dedupe predictions against the local store + index to avoid redundant fetches.
+- [x] 1.4 Emit `cd:prefetch-issued` per dispatch.
+- [x] 1.5 Wire `ContentDeliveryPlugin.prefetch` getter.
+
+## 2. Tests
+
+- [x] 2.1 `src/prefetch/prefetch-engine.spec-conformance.test.ts` — model invocation, scope filtering, dedupe, event emission.
+
+## 3. Verify
+
+- [x] 3.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-content-delivery` green.
+- [x] 3.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-content-delivery` 100/100/100/100.
+- [x] 3.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-content-delivery` PASS (build green; CLAUDE-Rule-11 runner imports verified).