Skip to content

id: design: postcard wire schema v1 (from #5674) #5808

Open

Description

@dezren39

Summary

Follow-on design ticket from #5674 — its decomposition sketch names this as a separate design, and the parent's acceptance requires these tickets to be filed and linked. Filed in the 2026-11-04 gap pass (WS-F) so the design work exists and can be prioritised on its own merits; implementation timing is a separate decision, possibly months out.

What this design must settle

The envelope, discriminators, and golden vectors for the postcard wire schema — the byte-level contract every adapter shares.

Context from the parent

The parent design fixes the postcard wire-format family and the transport-adapter model that carries ID over non-UDP transports and relays. The parent issue carries the surrounding decisions this ticket must not re-decide; where this ticket's answer would change a parent decision, record that explicitly rather than silently forking it.

Decision record expected

Close this design with a recorded decision (on this issue or in a doc/ record linked from it): the chosen shape, the alternatives rejected and why, and the invariants implementation must hold. If the design splits further, file the splits and link them here rather than growing this issue.

Relations

Parent: #5674. Programme: epic #2056. Filed by WS-F (2026-11-04 ID design gap & expansion pass).

Activity

  1. added
    app/idPackage/app: id (pkgs/ or apps/ in this repo)
    on Nov 5, 2026
  2. developing-today commented on Nov 5, 2026

    @developing-today
    Contributor
  3. added
    queue/queuedHas a queued task in the Supabase agent queue
    task/triageQueue packet kind: verify, reproduce, and route this item
    on Nov 5, 2026
  4. dezren39 commented on Nov 5, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · done

    Triage findings (2026-11-05, verified against current main):

    • Parent state: issue id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674 is still OPEN and parked/assigned — its surrounding decisions (wire-format family, transport-adapter model) are not yet recorded. This ticket explicitly must not re-decide them, so its decision record comes after (or with) the parent's; that is the ordering blocker, recorded here per the ticket's own terms. The ticket also states implementation timing is a separate decision, possibly months out.
    • Existing practice the design must ratify (not invent): postcard is already the live wire encoding across pkgs/id — src/protocol.rs (MetaRequest/MetaResponse over QUIC, ALPN /iroh-meta/3), src/meta_client.rs, src/peer_announcement.rs (magic prefix separating authenticated v2 gossip frames from legacy postcard payloads), and src/match_audit.rs (field order/meaning changes require a new format version). The append-only enum-variant rule (postcard uses positional discriminants) is already documented in .opencode/plans/2026-03-21_peer-discovery.md.
    • Gap the design owns: there is no dedicated wire-schema v1 record and no golden-vector corpus for the meta-protocol envelope — golden vectors exist for chain checkpoints (src/chain.rs) but not for the wire envelope/discriminators this ticket names. The decision record expected by this ticket (envelope, discriminators, golden vectors, rejected alternatives, invariants) is therefore real, unstarted work.
    • Next action: when issue id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674's decision record lands, this ticket's design is unblocked and should be worked as a design task producing the doc/ decision record; no code task should be filed from it before that record exists.
  5. added
    status/triagedTriaged and routed (see agent note)
    and removed
    queue/queuedHas a queued task in the Supabase agent queue
    on Nov 5, 2026
  6. dezren39 commented on Nov 8, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · triaged — task 12309 (queue repo-health-code-pilot, lane code-y)

  7. developing-today commented on Nov 8, 2026

    @developing-today
    Contributor

    🤖 Agent note · triaged — task 12309 (queue repo-health-code-pilot, lane code-z)

  8. dezren39 commented on Nov 8, 2026

    @dezren39
    MemberAuthor

    🤖 Agent note · triaged — real and current, still parent-gated; blocked on #5674 rather than cycled again

    Verdict. Same as the two triages before it, re-verified fresh at 2026-11-08T09:1xZ: this is a real design ticket whose deliverable does not exist yet, and whose own terms forbid writing it before the parent's decisions land.

    Why this task is blocked and not re-enqueued. The acceptance for a re-triage says to convert a real issue into a fix packet — but this task already is the fix-class packet (repo-health:v1:fix:…:issue:5808), and a fresh one claimed today could only rediscover the same gate: the design cannot be written until #5674 records the wire-format family and transport-adapter decisions this ticket must not re-decide. Cycling the triage again is the loop this issue has already been through twice (tasks 10211, 12309). Blocking records the dependency honestly and keeps the real work queued for the moment the parent lands.

    Resume condition. #5674's decision record lands (task 12244 reaches a terminal state with the record merged), then write the postcard wire-schema v1 record here: envelope, discriminators, golden vectors, alternatives rejected, and the invariants implementation must hold — ratifying the existing pkgs/id postcard practice rather than inventing a new encoding.

  9. added
    queue/blockedQueue or user escalation state
    status/blockedQueue or user escalation state
    and removed
    status/triagedTriaged and routed (see agent note)
    on Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

app/idPackage/app: id (pkgs/ or apps/ in this repo)queue/blockedQueue or user escalation statestatus/blockedQueue or user escalation statetask/triageQueue packet kind: verify, reproduce, and route this item

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions