Skip to content

Swarm Phase 3a: src/services/wire-types.ts — TypeScript types + JCS canonicalize helper #85

@Dewinator

Description

@Dewinator

Why

Phase 0/1/2 are landed (SWARM_SPEC, node identity, Ed25519 signature service). Phase 3 starts implementing the wire format defined in docs/SWARM_SPEC.md. This issue is the type-and-canonicalization foundation that every later wire-touching piece reuses.

Background — read this BEFORE starting

  • mcp__vector-memory__prime_context with task_description "implement TypeScript wire types and JCS canonicalization for mycelium swarm"
  • Read docs/SWARM_SPEC.md §2 (JCS) and §3 (Wire types) carefully — the field tables are the source of truth
  • Look at src/services/signature.ts (PR feat(swarm): signature service — Ed25519 sign/verify over JCS (#77) #82) — it already imports a JCS canonicalizer; reuse the same library

What this issue delivers

A new file src/services/wire-types.ts containing:

  1. TypeScript interfaces for the four wire record kinds defined in §3:
    • Lesson (§3.1)
    • HubAnchor (§3.2)
    • NodeAdvertisement (§3.3)
    • TrustEdge (§3.4) — local-only, but the type still belongs here
  2. A const WIRE_SPEC_VERSION = "1.0" (matches §1)
  3. A typed helper canonicalizeForSigning<T extends { signature?: string }>(record: T): Uint8Array that:
    • Strips signature if present
    • Returns the JCS bytes via the same canonicalizer signature.ts uses
  4. A typed helper kindOf(record: unknown): "lesson" | "hub_anchor" | "node_advertisement" | "trust_edge" | null — best-effort discriminator using required-field presence

Plus tests in tests/services/wire-types.test.ts:

  • One example record per kind that satisfies the interface (compile-time check via satisfies)
  • canonicalizeForSigning is deterministic (call twice, byte-equal)
  • canonicalizeForSigning strips signature (record with vs. without signature produces same bytes)
  • kindOf correctly classifies each example and returns null on garbage

Acceptance criteria

  • src/services/wire-types.ts exists and exports the four interfaces, WIRE_SPEC_VERSION, canonicalizeForSigning, kindOf
  • tests/services/wire-types.test.ts runs green (at least 6 assertions)
  • No new runtime dependency unless signature.ts already pulled it in
  • No DB, no HTTP, no file I/O — pure module

Hard constraints

  • DO NOT touch the SWARM_SPEC. If the spec is ambiguous, leave a TODO referencing the section and pick the most conservative interpretation.
  • DO NOT add a runtime validator here — that's Phase 3b (separate issue).
  • DO NOT add HTTP handlers — that's Phase 3c.

Out of scope

  • Rejection rules from §5 → Phase 3b
  • Endpoints from §4 → Phase 3c+
  • Storage schema → Phase 3d

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-eligibleAutonomous agent loop is allowed to pick thisfoundationPhase-0/1 Fundament für ein größeres FeatureswarmSchwarm-Foundation: dezentrale P2P-Architektur

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions