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.

[vybe]

Reframed under the 2026-06-05 pull-coordination revision (docs/planning/TARGET_ARCHITECTURE.md §Coordination Model, umbrella #1081). The pull model retires the journal-as-source-of-truth question — execution state is the backend schedule_executions row, not an agent-owned journal.ndjson. What remains in scope here is the message-envelope payload schema per kind, which is still the unit of enqueue / re-delivery / dedup and gates the pilot #946. Bumped to p1 because #946 is blocked on it.

[vybe]

Add: typed terminal-reason on the reply payload (acceptance criterion). Surfaced by the execution-bug meta-analysis (PR #1087 · docs/planning/ORCHESTRATION_BUG_META_ANALYSIS_2026-06.md).

The meta-analysis's #2 recurrence hotspot is the failure classifier — an auth-substring heuristic re-patched 5+ times (#285→#361→#517→#909→#904) across three hand-synced container copies (subscription_auto_switch.py, scheduler/service.py, agent-server error_classifier.py/headless_executor.py; the backend docstring claiming "the scheduler imports this list" is already false).

The structural cure is to make the agent emit a typed terminal outcome rather than have the backend guess from exit codes/stderr. The reply envelope payload should pin:

{ "status": "success | failed",
  "error_code": "AUTH | TIMEOUT | OOM | MAX_TURNS | AGENT_ERROR | NETWORK | ...",
  "cost": 0, "tokens": 0, "session_id": "..." }

This is now reflected in TARGET_ARCHITECTURE.md §Message Envelope and Open Question #1. Treat the typed taxonomy as a coordination-contract requirement of this spec, not an agent implementation detail.