Tasks: drive-mesh-protocol-v1

Change ID: drive-mesh-protocol-v1 Capability: drive-mesh-protocol (new) New package: @suaveplan/drive-mesh-protocol (types + codecs + validators only; zero runtime side effects) Target path: packages/drive/drive-mesh-protocol/ Prerequisite packages on Verdaccio: @suaveplan/types, @suaveplan/error, @suaveplan/bitpacker, @suaveplan/bitpacker-compressed, @suaveplan/bitpacker-network, @suaveplan/bitpacker-schema, @suaveplan/crypto

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Do not tick a box for a test that doesn't exist or doesn't pin the requirement it claims to verify.

1. Spec authoring

1.1 Read openspec/AGENTS.md Sections 0, 11, 13, and 14
1.2 Draft proposal.md
1.3 Draft specs/drive-mesh-protocol/spec.md with 22 ADDED requirements
1.4 Every requirement carries a **Verified by:** line
1.5 Source mapping section completed (genesis-original; antecedents listed)
1.6 Parity Checklist completed (genesis-original — no upstream)
1.7 Impact section enumerates affected dependents

2. Implementation — `@suaveplan/drive-mesh-protocol` package

2.1 Create package skeleton at packages/drive/drive-mesh-protocol/
2.2 package.json — workspace, type:module, sideEffects:false, catalog deps
2.3 src/types/request.ts — ChunkRequest, ChunkRequestEnvelope, ChunkRequestPayload
2.4 src/types/advertise.ts — ChunkAdvertiseEnvelope, ChunkAdvertisePayload
2.5 src/types/response.ts — ChunkResponseEnvelope, ChunkResponsePayload, ChunkBytes
2.6 src/types/error.ts — ChunkErrorEnvelope, ChunkErrorCode enum
2.7 src/codec/request.ts — encode/decode via @suaveplan/bitpacker-network
2.8 src/codec/advertise.ts — bitset payload via @suaveplan/bitpacker-compressed
2.9 src/codec/response.ts — multi-chunk payload + presence piggyback
2.10 src/codec/error.ts
2.11 src/select/form.ts — auto-selection logic (>64 chunks → bitset)
2.12 src/trust/score.ts — per-(peerId, fileId) trust map
2.13 src/trust/decay.ts — probabilistic skip logic
2.14 src/trust/sample.ts — adaptive sample-verification rate
2.15 src/error-codes.ts — defineCodes("DMP", [...]) registry
2.16 src/index.ts — barrel
2.17 Subpath exports: ./types, ./codec, ./select, ./trust, ./errors
2.18 Sibling .md for every .ts (≥200 words, basic + advanced examples)
2.19 Root README.md with Quick start + Modules

3. Tests (`tests/`)

3.1 three-form-roundtrip.test.ts — every ChunkRequest form roundtrips
3.2 bitset-rle.test.ts — fast-check property over random bit densities
3.3 generation-monotonic.test.ts — out-of-order drop logic
3.4 piggyback-presence.test.ts — cd:response updates peer-index
3.5 trust-decay.test.ts — repeated lying demotes; bad sig terminates
3.6 cap-respected.test.ts — maxChunks enforcement
3.7 empty-specific-rejected.test.ts — kind:'specific' with [] rejected
3.8 bitset-length-invariant.test.ts — presence.length !== totalChunks rejected
3.9 error-envelope-shape.test.ts — every ChunkErrorCode round-trips
3.10 codec-mandate.test.ts — non-bitpacker-encoded payloads rejected
3.11 spec-conformance.test.ts — every **Verified by:** line resolves to a real test
3.12 error-codes.spec-conformance.test.ts — registry frozen, codes namespaced

4. Documentation

4.1 Sibling .md for every implementation .ts (excludes barrels, .types.ts, tests)
4.2 Root README.md with package description, Modules section linking to each .md
4.3 Update docs/drive/mesh-protocol.md to reference the new package's actual exports

5. Pre-archive verification (the 5-gate triple)

5.1 bun run check — Biome 0 errors / 0 warnings / 0 info
5.2 bunx turbo lint typecheck test --filter=@suaveplan/drive-mesh-protocol — green
5.3 bunx turbo test:coverage --filter=@suaveplan/drive-mesh-protocol — 100/100/100/100
5.4 bun scripts/openspec-conformance.ts @suaveplan/drive-mesh-protocol — exit 0
5.5 bunx turbo build --filter=@suaveplan/drive-mesh-protocol — green

6. Pre-archive 7-row checklist (AGENTS.md §13)

6.1 Generics threaded; expectTypeOf assertions on type-shape claims
6.2 Zod schemas for every public type (sibling *.schemas.ts — but bitpacker-schema is the wire validator)
6.3 Frozen DMP_CODES registry; every thrown error extends SuaveplanError
6.4 Strict-mode behaviors tested (rejection paths each have an explicit test)
6.5 OTel instruments: dmp.envelope.encoded (counter), dmp.envelope.bytes (histogram), dmp.trust.score (gauge)
6.6 Lifecycle dedup: trust map respects (peerId, fileId) tuple; cleanup on peer disconnect
6.7 No retroactive tick — every box reflects work done in this change

7. Dependents update

7.1 openspec/changes/drive-mesh-port/proposal.md — MESH-GOSSIP-01 references DMP-08..09; cd:request references DMP-01..05
7.2 openspec/changes/network-plugin-content-delivery/proposal.md — references this protocol for forwarding semantics
7.3 openspec/changes/network-plugin-relay/proposal.md — references the envelopes it carries cross-mesh

8. Behavior-change propagation (AGENTS §13a)

8.1 Update docs/drive/mesh-protocol.md if any spec wording shifts during implementation
8.2 Migration note in proposal.md already lists the search command for old cd:request references
8.3 Run grep -rln "cd:request\|cd:advertise\|cd:response" openspec/changes/ --include="*.md" and update every hit (or document why not)

9. Archive

9.1 Fold spec delta into openspec/specs/drive-mesh-protocol/spec.md (new top-level capability spec)
9.2 Move openspec/changes/drive-mesh-protocol-v1/ → openspec/archive/<yyyy-mm-dd>-drive-mesh-protocol-v1/
9.3 Refresh MANIFEST.md (new package adds a row)
9.4 Update STATUS.md migration note if the package displaces or duplicates anything in upstream

6.3 KiB Raw Permalink Blame History