suaveplan/openspec/archive/2026-05-12-enterprise-browser-network-discovery-crdt/tasks.md

Tasks: enterprise-browser-network-discovery-crdt

Change ID: enterprise-browser-network-discovery-crdt Package: @suaveplan/network-discovery-crdt Target path: browser/network/network-discovery-crdt Prerequisite packages on Verdaccio: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/crypto

---

1. Scaffold

• Create directory tree per layout in proposal.md.
• Write package.json at version 0.1.0 — "sideEffects": false, strict: true default.
  • dependencies: @suaveplan/network workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/crypto workspace:^, yjs, y-webrtc, all @automerge/* packages (Bun catalog), zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @suaveplan/testing workspace:^, react catalog:browser, @types/react catalog:browser
• Write tsconfig.json and vitest.config.ts (pool: forks).

---

2. Error codes

• Define CRDTErrorCode: CRDT_PROVIDER_UNAVAILABLE, CRDT_SIGNALING_FAILED, AWARENESS_REJECTED.
• Export registerCRDTErrorCodes() and call eagerly.

---

3. CRDTProviderAdapter interface (src/provider/provider.ts)

• Define CRDTProviderAdapter interface with init, destroy, getAwareness, setLocalAwareness, onAwarenessChange.
• Export AwarenessChange type.

---

4. Yjs provider (src/provider/yjs/)

• Implement YjsProvider implements CRDTProviderAdapter:
  • Strict-mode: reject if signalingUrls empty or contains known public URLs without strict: false.
  • yjs-awareness.ts: awareness state helpers.
  • yjs-sync.ts: Y.Doc sync utilities.
• Write yjs-provider.test.ts using in-process signalling harness (no public URLs), yjs-provider.md.

---

5. Automerge provider (src/provider/automerge/)

• Implement AutomergeProvider implements CRDTProviderAdapter using @automerge/automerge-repo with broadcast-channel + websocket adapters.
• Write automerge-provider.test.ts, automerge-provider.md.

---

6. Awareness schema (src/schema/awareness/)

• Define CRDTPeerMetadataSchema (Zod): { peerId: string, addresses: string[], protocols: string[], capabilities: string[], timestamp: number }.
• Register in @suaveplan/schema-registry.
• Write awareness.md.

---

7. Manager modules

For each manager (crdt-peer-manager, crdt-state-manager, crdt-initializer, crdt-intervals):

• Implement the manager.
• Write *.test.ts and *.md.

---

8. CRDTDiscovery orchestrator (src/crdt-discovery/)

• Implement CRDTDiscovery using CRDTProviderAdapter (no provider-string branching).
• Optional encryption: if config.encrypt, wrap awareness payloads with @suaveplan/crypto AES-GCM.
• Wire OTel metrics.
• Write crdt-discovery.test.ts (Yjs + Automerge paths via their respective providers; in-process harness), crdt-discovery.md, crdt-discovery.types.ts.

---

9. Storybook story

• Write src/crdt-discovery/crdt-discovery.stories.tsx with react in devDependencies — no missing dep.
• Story demonstrates peer discovery with both providers.

---

10. Integration test (tests/integration.test.ts)

• Two CRDTDiscovery instances with Yjs provider via in-process signalling; assert peer discovery event fires.
• Automerge provider round-trip.
• Awareness payload with malformed data rejected with AWARENESS_REJECTED.
• Encryption: encrypted awareness payload cannot be read without the key.

---

11. Docs

• Write .md per module (≥200 words, API reference, examples).
• Write README.md with provider-adapter table, signalling self-hosting guidance, encryption opt-in.

---

12. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-crdt — green.
• bunx turbo test:coverage --filter=@suaveplan/network-discovery-crdt — 100%.
• bun run docs:check --filter=@suaveplan/network-discovery-crdt — zero errors.
• No vi.mock, any, ts-ignore, .skip in src/.
• Story builds cleanly; React dep declared.
• Awareness payload Zod schema registered.
• bun scripts/publish.ts --package @suaveplan/network-discovery-crdt.
• Archive to openspec/archive/2026-04-24-enterprise-browser-network-discovery-crdt/.