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

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.