Propose agent execution plane v1
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"task_file": "dev/tasks/DEV-000103-epistemics-truth-v1-proposal.json",
|
||||
"task_id": "DEV-000103",
|
||||
"task_file": "dev/tasks/DEV-000104-agent-execution-plane-proposal.json",
|
||||
"task_id": "DEV-000104",
|
||||
"task_revision": 1
|
||||
}
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"task_id": "DEV-000104",
|
||||
"task_revision": 1,
|
||||
"architecture_revision": "ADR-0018",
|
||||
"base_repo_revision": "339f6a6",
|
||||
"risk_tier": "E",
|
||||
"intent": "Prepare the proposed ADR-0020 Agent Execution Plane boundary for review without implementing dispatcher, worker, schema, callback or deployment changes.",
|
||||
"requirement_ids": ["WP-300", "Durable dispatch lease heartbeat", "Independent verification and truthful UNKNOWN outcome"],
|
||||
"allowed_change_scope": {"modules": ["work-execution-governance"], "paths": ["docs/proposals/ADR-0020-agent-execution-plane-v1.md", "dev/ACTIVE_TASK.json", "dev/tasks/DEV-000104-agent-execution-plane-proposal.json"]},
|
||||
"forbidden_change_scope": {"paths": ["architecture/**", "contracts/**", "database/**", "migrations/**", "modules/**", "cmd/**", "runtime/**", "adapters/**", "deploy/**", ".gitea/**"]},
|
||||
"allowed_architecture_delta": {"new_cross_module_dependencies": 0, "new_canonical_owners": 0, "new_privileges": 0, "new_third_party_dependencies": 0, "new_database_owner_roles": 0},
|
||||
"contracts": {"consume": ["ADR-0017 General Agent Delegation and Codex Bridge V1", "Proposed ADR-0019 Epistemics Truth V1", "Core semantic model Work/Capability/Artifact/Continuity boundaries"], "may_change": ["Proposed ADR-0020 only; no accepted contract changes"]},
|
||||
"semantic_owner": "work-execution-plane-proposal-only",
|
||||
"canonical_state": [],
|
||||
"state_transitions": ["dispatch -> leased -> running -> result -> independently verified", "lease expiry/callback uncertainty -> UNKNOWN or RECOVERING", "cancel request -> acknowledged cancellation or typed unknown"],
|
||||
"side_effects_and_privileges": ["No runtime side effects, external mutation, connector access, credential access or authority expansion"],
|
||||
"persistence_and_migrations": ["No schema, migration, queue, worker or lease implementation changes"],
|
||||
"failure_retry_restart": ["Retry creates a new run and preserves history; late or duplicate callbacks cannot become authoritative"],
|
||||
"assumptions": ["Work remains canonical owner of durable delegation execution", "Artifact remains canonical owner of attestation metadata", "Production deployment remains outside this proposal"],
|
||||
"acceptance_scenarios": ["Worker identity and dispatch idempotency are explicit", "Lease fencing and heartbeat expiry are explicit", "Callback authentication/replay handling is explicit", "Cancellation/retry/UNKNOWN semantics preserve history", "Independent verification gates Work completion", "No implementation or registry delta is introduced"],
|
||||
"required_tests": ["go test ./...", "go vet ./...", "go run ./cmd/devctl preflight -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-diff -active dev/ACTIVE_TASK.json", "go run ./cmd/devctl check-architecture", "go run ./cmd/devctl/independent", "git diff --check", "proposal scope and required-section review"],
|
||||
"terminal_gap_states": ["BLOCKED_BY_ARCHITECTURE_GAP", "BLOCKED_BY_SPEC_GAP", "BLOCKED_BY_CONFLICT"]
|
||||
}
|
||||
@@ -0,0 +1,97 @@
|
||||
# Proposal ADR-0020 — Agent Execution Plane V1
|
||||
|
||||
Status: Proposed
|
||||
Task: DEV-000104
|
||||
|
||||
## Problem and evidence
|
||||
|
||||
ADR-0017 defines durable delegation semantics, but the audit found no
|
||||
automatic dispatcher/worker plane, lease/heartbeat lifecycle, callback
|
||||
authentication or independent verification boundary. A worker must be able
|
||||
to stop, restart and resume without turning a missing callback into success or
|
||||
silently duplicating external work.
|
||||
|
||||
## Decision proposed
|
||||
|
||||
1. Keep `work` as the canonical owner of `Delegation`, `AgentRun`,
|
||||
`AgentCheckpoint`, `AgentResult` and verification gating. `capability`
|
||||
owns executor-neutral agent implementations; adapters own transport and
|
||||
process details.
|
||||
2. Every dispatch has a stable `dispatch_id`, delegation id, run id,
|
||||
implementation id, exact source/worktree identity, bounded instruction
|
||||
artifact reference, requested capability set, authority/credential refs,
|
||||
deadline and idempotency key. The derived instruction must preserve
|
||||
OriginalHumanIntent, inferred goal, added context and verification plan as
|
||||
separate provenance fields.
|
||||
3. A worker must acquire a durable lease before execution. Lease ownership is
|
||||
a fencing token, not an in-memory mutex. Heartbeats extend the lease only
|
||||
for the same run and fencing token; an expired lease makes late callbacks
|
||||
non-authoritative.
|
||||
4. Dispatch and callback endpoints authenticate the worker identity and bind
|
||||
every message to delegation, run, dispatch, implementation and fencing
|
||||
token. Forged, replayed, out-of-order or duplicate callbacks are rejected
|
||||
or recorded as non-authoritative evidence. Idempotent acknowledgement is
|
||||
allowed only for the exact previously accepted event.
|
||||
5. Checkpoints and artifacts are content-addressed metadata owned by
|
||||
`artifact`, with typed refs from Work. Artifact attestation records source
|
||||
revision/worktree, producer, digest, test command/result and capture time;
|
||||
an un-attested path or log is not completion evidence.
|
||||
6. Cancellation is a durable Work decision. The dispatcher sends cancellation
|
||||
to the leased worker, records acknowledgement or timeout, and never erases
|
||||
history. A worker that cannot prove cancellation remains `UNKNOWN` or
|
||||
`RECOVERING` until reconciled.
|
||||
7. Retry is policy-driven and distinguishes retryable transport/worker loss,
|
||||
execution-window exhaustion, human blocker, invalid result and unknown
|
||||
external outcome. Retry creates a new run under the same delegation and
|
||||
preserves prior checkpoints/results; it never reuses an idempotency key for
|
||||
an unproven external mutation.
|
||||
8. A run result cannot complete Work directly. Independent verification must
|
||||
consume the declared artifacts and tests through a separate verifier
|
||||
identity and produce a typed verification result. Verification failure,
|
||||
missing evidence and verifier unavailability remain distinct states.
|
||||
9. Secrets are resolved only through approved `CredentialRef` boundaries and
|
||||
are not copied into instructions, callbacks, artifacts, logs or task
|
||||
packets. Worker startup has no ambient credential inheritance.
|
||||
10. The plane is durable and restartable: dispatch intent, lease, heartbeat,
|
||||
cancellation, checkpoint, result, verification and reconciliation events
|
||||
are persisted before their projections claim progress.
|
||||
|
||||
## Lifecycle proposal
|
||||
|
||||
Delegation remains the higher-level human/work intent. A run progresses through
|
||||
`DISPATCHED`, `LEASED`, `RUNNING`, `CHECKPOINTED`, `SUCCEEDED`, `FAILED`,
|
||||
`CANCEL_REQUESTED`, `CANCELLED`, `EXHAUSTED`, `WAITING_HUMAN`, `UNKNOWN` or
|
||||
`RECOVERING`, subject to explicit transition guards. `SUCCEEDED` means only
|
||||
that the worker returned an accepted result; Work completion additionally
|
||||
requires independent verification. Lease expiry and missing heartbeat never
|
||||
become success.
|
||||
|
||||
## Alternatives and rationale
|
||||
|
||||
- An in-memory queue or goroutine was rejected because it loses dispatch state
|
||||
on restart and violates durable timer/lease requirements.
|
||||
- A single generic `AgentManager` was rejected because it collapses Work,
|
||||
Capability, Artifact and Continuity ownership.
|
||||
- Trusting worker-reported success was rejected because the worker and
|
||||
verifier must remain separate authorities.
|
||||
- Reusing the same run on retry was rejected because it makes duplicate
|
||||
external effects and late callbacks indistinguishable.
|
||||
|
||||
## Boundaries, consequences and non-goals
|
||||
|
||||
No new canonical owner, provider, deployment authority, database migration,
|
||||
Codex-specific domain contract or automatic self-modification is proposed.
|
||||
The design enables restartable external work and truthful failure handling,
|
||||
but requires durable event ordering, fencing, artifact storage and verifier
|
||||
capacity before WP-301 can claim production readiness.
|
||||
|
||||
## Migration, rollback and revisit triggers
|
||||
|
||||
Implementation must begin behind an opt-in dispatch path with a dry-run
|
||||
verifier and deterministic fake worker. Existing delegation records remain
|
||||
readable; unknown legacy RUNNING records are classified by WP-302 rather than
|
||||
silently resumed. Rollback disables new dispatch and drains/recovers leases;
|
||||
history and artifacts remain. Revisit if a worker needs authority beyond its
|
||||
declared capability, if a second transport changes callback guarantees, or if
|
||||
artifact attestation cannot be made independent of the worker.
|
||||
|
||||
Reference in New Issue
Block a user