spec: message envelope payload schema (pull coordination)

[vybe]

Summary

Write the one-page pre-experiment artifact required by the actor-model transition roadmap before Phase 2 scheduling. Two sections only — message envelope fields and journal entry format. If both fit cleanly on a postcard, the model is sound and Phase 2 (#TBD) proceeds. If either sprawls, the planned Sprint D/D′ path remains the best one available.

Context

The orchestration reliability plan (docs/planning/ORCHESTRATION_RELIABILITY_2026-04.md §"Target architecture: actor model" → "Pre-experiment artifact") names this as the gate between Sprint D′ and any actor-model experimentation. The target architecture (docs/planning/TARGET_ARCHITECTURE.md §"Coordination Model" and §"Key Open Questions" #1) names the envelope but leaves the per-kind payload schema and the journal format unspecified.

Until this exists, Phase 2 cannot be scheduled and #927 (replica groups) lacks a serialization contract for journal-projection.

Acceptance Criteria

• Document committed under docs/planning/ (proposed name: ACTOR_MODEL_POSTCARD.md)
• Message envelope section: full field list with types, semantics, and which fields are required vs optional. Cover id, kind (chat|task|event|reply), from, to, correlation_id, causation_id, idempotency_key, deadline, payload. Define the payload schema for each kind.
• Journal entry section: file location (journal.ndjson in agent repo), one entry per processed message, fields per entry, retention/rotation behavior. Decide whether workflow checkpoints are inline entries or separate state.yaml per workflow.
• Each section fits on roughly one page (no sprawl)
• Cross-references from TARGET_ARCHITECTURE.md §"Key Open Questions" Fix: Add missing Docker labels to system agent container #1 and ORCHESTRATION_RELIABILITY_2026-04.md updated

Technical Notes

• Envelope must be usable by the existing BacklogService enqueue path without schema migration (the experiment in Phase 2 reuses backlog).
• Journal format must not require backend writes from the container — projection path is platform-owned (see Replica groups: horizontal scaling for single agents #927 shared-state discipline notes).
• Pure spec work — no code changes in this issue.

🤖 Generated with Claude Code

[Keesan12]

This looks like a coordination or scheduling contract issue. I’d make the envelope or schedule semantics visible in one place before layering on more behavior. I’d pin a canonical formatter and keep the copy or render path aligned with it so the output stays predictable. The main win here is making the failure mode observable early, before it turns into a harder-to-debug downstream symptom. If this is useful, I can help turn it into a compact repro checklist or PR shape.