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

Tasks — network-plugin-content-delivery

Blocked on: network-core, network-plugin-webrtc, network-plugin-transport-manager.

1. Scaffold

• 1.1 packages/network/network-plugin-content-delivery/ with package.json, tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/packer, @suaveplan/drive, @suaveplan/rate-limiter, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/chunk.types.ts — ChunkManifest, ChunkIndexEntry, ChunkRequest.
• 2.2 src/types/redundancy.types.ts — RedundancyConfig, ReplicationTask.
• 2.3 src/types/prefetch.types.ts — PrefetchConfig, PredictionModel.
• 2.4 src/error-codes.ts — defineCodes("NET_CD", [...]).

3. Chunk index

• 3.1 src/index/chunk-index.ts — ChunkIndex.
• 3.2 Gossip protocol for index propagation.
• 3.3 Entries: { chunkHash, fileId, chunkIndex, holders[], redundancyTarget }.

4. Chunk request router

• 4.1 src/router/chunk-request-router.ts — ChunkRequestRouter.
• 4.2 Routes to nearest holder using latency data.
• 4.3 Falls back to server if no mesh peer has chunk.

5. Chunk store

• 5.1 src/store/chunk-store.ts — ChunkStore over @suaveplan/drive.
• 5.2 Browser: OPFS/IndexedDB. Node: filesystem.
• 5.3 TTL-based eviction with LRU.

6. Redundancy manager

• 6.1 src/redundancy/redundancy-manager.ts — RedundancyManager.
• 6.2 Ensures ≥ N copies per chunk.
• 6.3 Triggers re-replication on peer departure.

7. Packer integration

• 7.1 src/packer/packer-integration.ts — PackerIntegration.
• 7.2 Consumes @suaveplan/packer manifest.
• 7.3 Broadcasts manifest on bus.

8. Prefetch engine

• 8.1 src/prefetch/prefetch-engine.ts — PrefetchEngine.
• 8.2 Predictive fetching based on session context.
• 8.3 Session-scoped to avoid irrelevant fetches.

9. Integrity verifier

• 9.1 src/integrity/integrity-verifier.ts — IntegrityVerifier.
• 9.2 BLAKE3 hash verification.
• 9.3 Blacklists sender on corruption.

10. Bandwidth throttler

• 10.1 src/throttle/bandwidth-throttler.ts — BandwidthThrottler.
• 10.2 Uses @suaveplan/rate-limiter.
• 10.3 BULK priority via transport manager.

11. Plugin wrapper

• 11.1 src/plugin/content-delivery-plugin.ts — ContentDeliveryPlugin implements NetworkPlugin.

12. Spec

• 12.1 Update openspec/specs/network/spec.md with NET-CD requirements.

13. Conformance tests

• 13.1 src/index/chunk-index.spec-conformance.test.ts — gossip, holder lookup.
• 13.2 src/router/chunk-request-router.spec-conformance.test.ts — latency routing, fallback.
• 13.3 src/redundancy/redundancy-manager.spec-conformance.test.ts — N-copy, re-replication.
• 13.4 src/integrity/integrity-verifier.spec-conformance.test.ts — hash verify, blacklist.
• 13.5 src/throttle/bandwidth-throttler.spec-conformance.test.ts — rate limit, priority.
• 13.6 src/prefetch/prefetch-engine.spec-conformance.test.ts — prediction, session scope.
• 13.7 src/error-codes.spec-conformance.test.ts — frozen registry.

14. Verify

• 14.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-content-delivery green.
• 14.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-content-delivery 100/100/100/100.
• 14.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-content-delivery PASS.

Audit (2026-05-05)

Shipped the core mesh-CDN primitives at 100/100/100/100 statement/branch/function/line coverage across 7 spec-conformance test files (77 tests). Documentation coverage: 8/8 files (100%). OpenSpec conformance: PASS. All seven NETWORK_CD_CODES are wired (CHUNK_NOT_FOUND, NO_HOLDER_AVAILABLE, INTEGRITY_HASH_MISMATCH, SENDER_BLACKLISTED, REDUNDANCY_TARGET_INVALID, INDEX_ENTRY_MISSING, ROUTER_NO_FALLBACK).

Subsystems wired: ChunkIndex, ChunkRequestRouter, RedundancyManager, IntegrityVerifier, plus the ContentDeliveryPlugin facade.

Per the proposal's ## Deferred to follow-up changes block (and openspec/AGENTS.md §2c), four integration-heavy subsystems are deferred to dedicated follow-up changes that ship at the same package version:

• network-plugin-content-delivery-store — ChunkStore over @suaveplan/drive.
• network-plugin-content-delivery-packer — PackerIntegration over @suaveplan/packer.
• network-plugin-content-delivery-prefetch — PrefetchEngine over network-plugin-session.
• network-plugin-content-delivery-throttle — BandwidthThrottler over @suaveplan/rate-limiter + transport-manager BULK priority.

The deferred verification entries (bandwidth-throttler.spec-conformance.test.ts, prefetch-engine.spec-conformance.test.ts, plus the tests/dep-graph.test.ts line that asserts @suaveplan/packer / @suaveplan/drive imports) move to the relevant follow-up.