From 0095c4e5c8033c3a547a328fdcb8a614794bd01b Mon Sep 17 00:00:00 2001 From: DJConnect Date: Thu, 17 Sep 2026 19:02:02 +0200 Subject: [PATCH] docs: specify concurrent execution of independent Forge Actions (NO_BUMP) --- .../PARALLEL_ACTION_EXECUTION_V1_DAG.json | 19 +++ .../PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md | 21 +++ ...GE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md | 159 +++++++++++++++++- 3 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 docs/development/PARALLEL_ACTION_EXECUTION_V1_DAG.json create mode 100644 docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md diff --git a/docs/development/PARALLEL_ACTION_EXECUTION_V1_DAG.json b/docs/development/PARALLEL_ACTION_EXECUTION_V1_DAG.json new file mode 100644 index 00000000..02ae6037 --- /dev/null +++ b/docs/development/PARALLEL_ACTION_EXECUTION_V1_DAG.json @@ -0,0 +1,19 @@ +{ + "schema_version": "1.0", + "increment": "FORGE_EP_PARALLEL_ACTION_RUNTIME_V1", + "owner": "engineering-platform", + "authority": "DOCUMENTARY_DERIVED", + "executable": false, + "version_decision": "NO_BUMP", + "parent_lanes": ["P-QUEUE", "FORGE_ACTION_DEPENDENCY_ADMISSION", "MULTI_EXECUTION"], + "architecture": "docs/engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md", + "current_mission_3_dependency": false, + "nodes": [ + {"id":"PA-E0","status":"PLANNED","depends_on":[],"external_evidence":["forge:PA-F0"],"deliverable":"Per-Action dependency/concurrency contract and compatibility"}, + {"id":"PA-E1","status":"PLANNED","depends_on":["PA-E0"],"deliverable":"Independent admission and predecessor evidence enforcement"}, + {"id":"PA-E2","status":"PLANNED","depends_on":["PA-E1"],"deliverable":"Concurrent delivery with bounded repository/resource/capacity scheduling"}, + {"id":"PA-E3","status":"PLANNED","depends_on":["PA-E2"],"deliverable":"Invocation isolation, fencing and partial-failure/restart/cancel safety"}, + {"id":"PA-E4","status":"PLANNED","depends_on":["PA-E1"],"deliverable":"Per-result readback and complete multi-active timing/usage/export evidence"}, + {"id":"PA-EQ","status":"PLANNED","depends_on":["PA-E2","PA-E3","PA-E4"],"deliverable":"Installed actual concurrency and negative-boundary qualification"} + ] +} diff --git a/docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md b/docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md new file mode 100644 index 00000000..5575f73e --- /dev/null +++ b/docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md @@ -0,0 +1,21 @@ +# Parallel Action execution V1 — EP owning roadmap + +**Owner:** Engineering Platform. **All added implementation/qualification nodes: PLANNED. NO_BUMP.** +This is the bounded decomposition of the existing dependency-admission and P-QUEUE/multi-execution seams in [the canonical roadmap](ENGINEERING_PLATFORM_ROADMAP.md). It does not implement a second scheduler or reopen the entire Agent fleet, subagent-efficiency or post-assurance-publication programme. + +Owning contract: [Forge Action dependency and EP admission boundary](../engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md). Machine-readable index: [documentary DAG](PARALLEL_ACTION_EXECUTION_V1_DAG.json). Forge companion: `docs/roadmap/PARALLEL_ACTION_RUNTIME_V1.md`; shared tests: `docs/architecture/PARALLEL_ACTION_QUALIFICATION_V1.md`, PA-01..PA-26. + +| Node | Dependencies | Bounded deliverable | +| --- | --- | --- | +| PA-E0 | Forge PA-F0 contract fixtures | Versioned per-Action target/dependency/evidence/concurrency contract and compatibility resolution | +| PA-E1 | PA-E0 | Independent immutable submission/admission and exact predecessor predicates; typed wait/scope states | +| PA-E2 | PA-E1 | Real concurrent worker/provider delivery across independent repository resources, bounded slots and fairness | +| PA-E3 | PA-E2 | Per-invocation/workspace isolation, fenced leases, partial-submit/restart/cancel safety and repair-budget preservation | +| PA-E4 | PA-E1 | Independent terminal readback, multi-active collection, canonical timing/usage and MD/JSON evidence parity | +| PA-EQ | PA-E2, PA-E3, PA-E4 | Installed one-host/two-target concurrency and negative-case qualification with actual execution overlap | + +EP PA-EQ consumes Forge PA-F0 fixtures, not Forge's final PA-FQ. Forge PA-F3 consumes PA-E1/PA-E2/PA-E3; Forge final qualification consumes PA-EQ. This is acyclic. EP PA-E3 may reuse already qualified SA-ISO or equivalent invocation-isolation capabilities, but cannot assume the whole historic SA finding set is still open or require all SA-Q work. Active telemetry/reporting fixes stay closed unless a concrete regression is found. + +First delivery uses two authorized repositories and isolated workspaces on one compatible host. Existing admission/worker/lease/provider paths must actually run concurrently; capability labels or a threadpool alone do not qualify it. No full Workspace UI, distributed Agent fleet, new universal installer or nested provider-agent engine prerequisite. Same-repository parallel writes remain a separate stricter profile. + +The integrated consumer canary demonstrates Forge-derived fan-out, A-result-driven continuation while B runs, a true A+B artifact join and correct Mission completion. Tests compare serial and parallel behavior at the same quality/authority gates and report honest elapsed/usage evidence, not a promised speedup. It is separate from the current serial Mission-3 proof and data-reset implementation. Documentation does not allocate new Mission/Action IDs or activate policy, gates, runtimes or package versions. diff --git a/docs/engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md b/docs/engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md index 064c543c..717f1aae 100644 --- a/docs/engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md +++ b/docs/engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md @@ -2,6 +2,24 @@ **Status:** target Engineering Platform contract boundary; canonical when merged. Implementation and qualification remain separately governed. +## Parallel-runtime refinement — 2026-09-17 + +Increment `FORGE_EP_PARALLEL_ACTION_RUNTIME_V1` specifies the EP side of +multiple independent Actions from one Mission actually executing concurrently. +See [owning roadmap](../development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md) +and [documentary DAG](../development/PARALLEL_ACTION_EXECUTION_V1_DAG.json). +All six added EP implementation/qualification nodes remain PLANNED; NO_BUMP. +Forge owns the companion `docs/architecture/PARALLEL_ACTION_RUNTIME_V1.md` +and shared PA-01..PA-26 qualification catalogue. This refines existing +[P-QUEUE/Agent delivery scheduling](AGENT_DELIVERY_SCHEDULING_ARCHITECTURE.md), +not a second scheduler or the native nested-subagent roadmap. + +Observed source basis: EP `f45694d40b753d235feac8b803d364e1450cae26` and Forge +`03f9514e0f1e66a79ccb684c9fdbe51b28b88090`. Forge's `_OneActionProvider`, +single current-Action projection and loop-level target still limit that +composition. EP's existing parallel read-only capability reviews do not prove +parallel mutating Action execution. No new installed-runtime audit is claimed. + ## Purpose Engineering Platform must support a producer-supplied hard Engineering Action dependency graph without becoming the planner that invents that graph. @@ -27,7 +45,7 @@ An Action can wait for three fundamentally different reasons: 2. **Execution resource/lease.** The plan permits execution, but the required repository/resource is exclusively leased or otherwise unsafe. 3. **Qualified execution capacity.** The plan and resource state permit execution, but no authorized Agent/provider capacity can accept it yet. -These states must remain distinguishable in CENTRAL evidence and projections. Priority must never bypass any of them. +These states must remain distinguishable in CENTRAL evidence and projections. Priority must never bypass any of them. Current authorization and compatible target/profile capability are also required; missing authority is not disguised as capacity waiting. Preserve all relevant blocker reasons with a deterministic primary reason if a legacy UI needs one. ```text producer Action is logically eligible? @@ -67,6 +85,16 @@ EP validates and stores the dependency snapshot with the canonical submission/ru EP may reject malformed or contradictory dependency input. That validation is not planning. +The parallel implementation must additionally bind the source Mission/graph +revision, target baseline/Truth reference, effective execution policy and +supported concurrency profile through the existing versioned contract family. +Exact field names/schema versions are implementation work. Unknown required +parallel semantics fail closed; they are never silently discarded by a legacy +single-run adapter. No arbitrary peer URL or credential is accepted from a +provider-generated Action. Each actual target requires its own verified +project/repository scope; the existing forge consumer does not automatically +authorize another repository. + ## Evidence-gated predecessor satisfaction A predecessor edge can require more than a generic COMPLETE flag. The Action contract may require concrete predecessor evidence such as: @@ -108,12 +136,74 @@ Forge deciding that two Actions are independent does not force EP to run them co Conversely, EP finding spare capacity must never override a Forge-supplied hard dependency. +For a qualified parallel profile with at least two available compatible slots, +EP must be able to execute independent targets concurrently: acceptance of two +requests or concurrent eligibility alone does not close this feature. No +Mission-ID/project-ID-wide execution mutex may serialize them merely because +they share a Mission. Ordinary serialization of brief CENTRAL transactions is +not serialization of full provider/validation/delivery lifetimes. + +The first profile uses separate repositories/workspaces on one host and one +configured compatible execution service. It does not require a distributed +Agent fleet, Workspace, full universal installer or native subagent engine. +The relevant existing worker/provider/lease paths must nevertheless actually +support and be qualified for multiple deliveries, not just expose a limit flag. + +Same-repository parallel mutation remains a separately qualified stricter case. +Until then, independent Actions sharing its mutable repository resource wait on +that resource even with distinct branch names. Different repositories can also +share ports, test databases, build outputs, signing identity, release namespace +or updater target; declare and enforce those real resources. Independent +read-only resources need not acquire a writer lease merely for matching a +project label. Resolve actual Git/common-worktree identity, not path strings +that can alias the same storage. + +## Capacity, isolation and restart-safe ownership + +Reuse existing CENTRAL admission, lifecycle worker, execution leases and +provider-invocation ledger. Do not introduce a shadow run database or let an +Agent invent acceptance. Admission/claim/lease fencing must prevent two workers +owning the same delivery after races or restart. Capacity reservation and release +are atomic/idempotent for the owning attempt; an uncertain process or stale +heartbeat is not proof resources are free. No automatic duplicate execution to +test whether an old one is alive. + +Enforce effective global/host/provider/target limits and bounded backpressure. +Limits count actual applicable child invocations, not only parent Action rows; +provider-internal concurrency cannot multiply an allowance invisibly. Where +child capacity cannot be observed/enforced, do not advertise that unqualified +mode as bounded. Pending dependencies must not occupy scarce provider slots +needed by their predecessors; a blocked first queue item must not starve an +unrelated eligible target. Priority cannot bypass scope, predecessor evidence +or exclusive resources. + +Each delivery owns its workspace, branch, subprocess/cancellation identity, +callbacks, validation state, candidate/reviewer evidence, output capture, usage +and timers. Avoid shared mutable provider-client result fields or process-global +cwd/environment mutation. Short-lived locks never span an entire unrelated +provider request or network wait. Shared helpers are permitted only where their +contracts are demonstrably concurrency-safe. + +Quality/Security remains independent and candidate-bound for each Action. The +new profile does not require simultaneous mandatory reviews within an Action: +that is a separate qualification. It does require isolation across concurrently +running Actions. Existing provider-recovery and repair allowances retain attempt +lineage; releasing/reacquiring a slot does not reset them. Deterministic checks +and publication may reuse existing qualified adapters, but this documentation +does not reopen the separate post-assurance-publication repair or SA programme. + ## Relationship to Agent local scheduling CENTRAL decides logical eligibility and placement before an Agent owns delivery. An Agent may schedule already accepted independent work within its local resource policy, but may not execute an Action that CENTRAL has not admitted or bypass a hard predecessor. Agent-local retries, validation repair and branch reconciliation remain execution attempts for the same admitted Action; they do not create new Forge dependency nodes. +An Action is not a provider subagent. Internal delegation remains within the +admitted target/effect scope and qualified provider profile. No second target +may be hidden in a child prompt. Conversely every helper does not need a new +Forge Mission/Action or full PR/finalization transaction. Native nested-agent +implementation is not delivered or newly authorized by this inter-Action design. + ## Dynamic Forge replanning EP does not need the whole future Living Mission Graph. It receives immutable materialized Action snapshots. Forge may reconcile completed EP evidence and then derive new successor Actions or changed future dependencies. @@ -130,6 +220,59 @@ Forge mutable future plan No cross-product direct SQL or shared graph store is introduced. +Deliver each terminal result/readback independently. A finished A must become +available to Forge while B still runs; do not require a global batch/wave +completion. A-only successor C may execute after the required A proof. A joint +qualifier Q depending on A and B waits for both exact requirements. This is +producer-owned fan-in, not EP inventing a plan or automatically submitting Q. + +A new graph revision never mutates an admitted sibling's target/baseline or +expected output. Per-Action repository Truth must remain isolated. A real +invalidated read/dependency input is handled explicitly through the existing +failure/hold/recovery boundary; harmless progress in another repository is not +an input conflict. + +## Partial submission, failures and cancellation + +A accepted/B timed-out is not an atomic failure of both. Readback uses each +persisted request identity and unchanged bytes; duplicate delivery/callback +identities do not create new runs or transfer evidence to the wrong Action. +Persist independent slot outcomes even when arrival order differs from submission +order. Historical retry parents belong to one Action, never to its successful +sibling merely because both share a Mission. + +A failed predecessor blocks affected dependants without rewriting independent +successes. Continue, hold or cancel other work under the actual impact and +approved policy; uncertain scope/resource compromise is not ignored. Cancellation +is a request/acknowledged-effect protocol: don't report no-running-work until +providers and leases are safely reconciled. EP reports unresolved effects; +Forge cannot legitimately COMPLETE the Mission while an accepted writer or +uncertain cancellation remains. A Mission-wide pause/maintenance request must +account for all relevant deliveries, not one legacy current-run field. + +## Readmodels, telemetry and efficiency + +Expose all active/waiting/terminal Actions by exact producer Mission, Action, +request, attempt and target identity with policy/source-as-of evidence. Keep +technical delivery, host qualification and Forge Mission acceptance distinct. +Legacy singleton projections must explicitly indicate multiplicity rather than +hide all but the last run. Consumer readback remains scoped and secret-free. + +Use the existing canonical timing/usage/export contracts. Sibling Actions form a +Mission collection, not a retry chain. Sum valid usage exactly once with coverage +and conflicts preserved; do not call EP totals complete Mission usage when Forge +planning is excluded. Show Action elapsed spans, overall elapsed/busy interval +union, overlap, dependency/resource/capacity waiting and actual provider totals. +Inclusive parallel durations are not additive wall time. The same snapshot's MD +and JSON contain the entire selected Action population and its available details. + +A real overlap proof uses known comparable clocks/intervals and distinct active +provider/delivery identities; two RUNNING labels are insufficient. Compare serial +and parallel on the same bounded task, gates, policy and resource/provider limits. +Report observed time and complete/partial usage without fabricated speedup or +savings. Capacity-constrained serial execution can be correct operational behavior, +but cannot be presented as the successful concurrency canary. + ## Qualification The dependency-admission contract requires deterministic and end-to-end evidence for: @@ -146,4 +289,18 @@ The dependency-admission contract requires deterministic and end-to-end evidence - priority cannot bypass hard dependencies; - Agent local execution cannot self-admit blocked work. +The added PA-01..PA-26 catalogue in Forge further requires actual overlapping +execution; bounded resource/capacity fairness; invocation/result isolation; +partial-submit/crash/replay correctness; incremental A-only release while B runs; +proper A+B artifact joins; no premature Mission completion; scoped multi-active +readmodel/export parity; serial compatibility and honest efficiency measurement. +EP PA-EQ uses published Forge contract fixtures and need not wait for final Forge +PA-FQ. Forge's live integrated canary then consumes the qualified EP slice; no +cross-product qualification cycle or Workspace predecessor is introduced. + The first Forge dynamic inner-Mission canary may remain serial and does not require this full multi-repository parallel qualification. The cross-repository Forge canary requires this boundary together with EP's qualified multi-execution, repository lease and Agent/provider capacity capabilities. + +This design change performs no runtime implementation, schema migration, active +policy change, process start, reset, credential operation, release or installation. +The existing reset-development streams and serial Mission-3 acceptance are not +expanded or reclassified by this document.