posta/spec
0
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity

Spec refactor: fold posta.room.broadcast/v1 into posta.room/v1 with action discriminator #2

New issue
Closed
opened 2026-05-13 18:43:44 +02:00 by arne · 0 comments
arne commented 2026-05-13 18:43:44 +02:00
Owner
Copy link

What to build

Refactor the room-broadcast wrapper kind so that all room-related payloads live under a single content kind, distinguished by an `action` field. Folds the existing wrapper into a more general taxonomy that can host future control actions (`leave`, `join`, `kick`, …) without bloating the namespace.

The wire shape becomes:

```json
{ "kind": "posta.room/v1", "action": "broadcast", "envelopeBytes": "...", "signature": "..." }
```

A receiver matches on `payload.kind == "posta.room/v1"`, then dispatches on `payload.action`. Unknown actions are tolerated per §13.1 (additive evolution).

Includes:

  • §14 rewrite: describe `posta.room/v1` as the room-payload kind, with `action: "broadcast"` as the wrapper shape (existing prose adapts almost verbatim). The 64KB cap + base64 inflation discussion stays.
  • §13.1.1 update: list `posta.room/v1` as the third well-known kind (no more `posta.room.broadcast/v1`).
  • Conformance vectors under `testdata/vectors/` updated to the new kind/action shape.
  • `pkg/posta` wrapper helpers and tests updated to match.

Since nothing has shipped externally, this is a normative revision of proposal 1, not a wire-format-version bump.

Acceptance criteria

  • SPEC.md §14 renamed/refactored to describe `posta.room/v1` with `action: "broadcast"`
  • §13.1.1 namespacing summary lists three well-known kinds: `posta.text/v1`, `posta.link/v1`, `posta.room/v1`
  • All references to `posta.room.broadcast/v1` in spec prose, examples, and vectors are updated
  • Conformance vectors verify against the new shape; old fixtures removed
  • `pkg/posta` wrapper tests pass against the new shape
  • Per-category versioning consequence noted in §13.1.2 or §14 (a backwards-incompatible change to any action bumps the whole `posta.room/v1` kind)

Blocked by

None - can start immediately.

## What to build Refactor the room-broadcast wrapper kind so that all room-related payloads live under a single content kind, distinguished by an \`action\` field. Folds the existing wrapper into a more general taxonomy that can host future control actions (\`leave\`, \`join\`, \`kick\`, …) without bloating the namespace. The wire shape becomes: \`\`\`json { \"kind\": \"posta.room/v1\", \"action\": \"broadcast\", \"envelopeBytes\": \"...\", \"signature\": \"...\" } \`\`\` A receiver matches on \`payload.kind == \"posta.room/v1\"\`, then dispatches on \`payload.action\`. Unknown actions are tolerated per §13.1 (additive evolution). Includes: - §14 rewrite: describe \`posta.room/v1\` as the room-payload kind, with \`action: \"broadcast\"\` as the wrapper shape (existing prose adapts almost verbatim). The 64KB cap + base64 inflation discussion stays. - §13.1.1 update: list \`posta.room/v1\` as the third well-known kind (no more \`posta.room.broadcast/v1\`). - Conformance vectors under \`testdata/vectors/\` updated to the new kind/action shape. - \`pkg/posta\` wrapper helpers and tests updated to match. Since nothing has shipped externally, this is a normative revision of proposal 1, not a wire-format-version bump. ## Acceptance criteria - [ ] SPEC.md §14 renamed/refactored to describe \`posta.room/v1\` with \`action: \"broadcast\"\` - [ ] §13.1.1 namespacing summary lists three well-known kinds: \`posta.text/v1\`, \`posta.link/v1\`, \`posta.room/v1\` - [ ] All references to \`posta.room.broadcast/v1\` in spec prose, examples, and vectors are updated - [ ] Conformance vectors verify against the new shape; old fixtures removed - [ ] \`pkg/posta\` wrapper tests pass against the new shape - [ ] Per-category versioning consequence noted in §13.1.2 or §14 (a backwards-incompatible change to any action bumps the whole \`posta.room/v1\` kind) ## Blocked by None - can start immediately.
arne closed this issue 2026-05-13 21:32:21 +02:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
spec-review-fixes
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
posta/spec#2
No description provided.