docs(target-arch): revise coordination model to pull/work-stealing (#1081)#1086
Merged
Conversation
…1081) Replace the push actor-model with pull / work-stealing in TARGET_ARCHITECTURE.md, per the 2026-06-05 design review. The backend owns one durable per-agent queue (schedule_executions); agents pull when they have free capacity; capacity is physical (worker count); recovery is lease-expiry re-delivery of the same execution_id. - Governing principle #5, data layer (queue→Postgres, Redis loses the mailbox/slot-ZSET), agent runtime, and observability updated to match. - Adds the side-effect idempotency contract (the hardest open problem, #1084) and the Postgres-before-the-queue sequencing constraint (#300). - Reconciles the tracking table + open questions with the new issues: #1081 umbrella, #1082 status-as-projection, #1083 fire-and-forget, #1084 effect-idempotency, #1085 herd controls (all under Epic #1045); #946 reframed as the pilot, #307/#526 as gate→alert. - Includes the team announcement record. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Revises
docs/planning/TARGET_ARCHITECTURE.md§Coordination Model from a push actor model (backend dispatches into a per-agent Redis mailbox) to pull / work-stealing, per the 2026-06-05 design review. The backend owns one durable per-agent queue (schedule_executions); each agent pulls the next task only when it has a free worker; capacity is physical (worker count); the sole recovery primitive is lease-expiry re-delivery of the sameexecution_id.Chosen over the push model for simplicity, single-source-of-truth, and ~80% reuse of existing primitives (
claim_next_queued, the RELIABILITY-005 CAS, idempotency #525, the agentauto_sync.pyloop).What changed in the doc
mailbox_depthdropped from/health; journal demoted from source-of-truth; queue-depth metrics.Tracking (Epic #1045)
Also includes the team announcement record under
docs/user-docs/dev-announcements/.Docs-only; no code changes.
🤖 Generated with Claude Code