diff --git a/docs/architecture/FORGE_V1_IMPLEMENTATION_DAG.md b/docs/architecture/FORGE_V1_IMPLEMENTATION_DAG.md index 0f845bf..498e74f 100644 --- a/docs/architecture/FORGE_V1_IMPLEMENTATION_DAG.md +++ b/docs/architecture/FORGE_V1_IMPLEMENTATION_DAG.md @@ -8,6 +8,15 @@ > **Runtime planning reconciliation:** the canonical inner-Mission target is the > [Living Mission Graph and cross-repository Engineering Action DAG](LIVING_MISSION_GRAPH_AND_CROSS_REPOSITORY_ACTION_DAG.md). +> **Parallel-runtime refinement — 2026-09-17:** the +> [detailed multi-Action runtime design](PARALLEL_ACTION_RUNTIME_V1.md), +> [seven-node owning roadmap](../roadmap/PARALLEL_ACTION_RUNTIME_V1.md), +> [documentary JSON DAG](../roadmap/parallel-action-runtime-v1.json) and +> [PA-01..PA-26 qualification](PARALLEL_ACTION_QUALIFICATION_V1.md) +> concretize the second milestone below. Actual execution overlap and incremental +> result-driven release are required, not just simultaneous eligibility. All added +> PA nodes remain PLANNED; current serial Mission 3/reset work is unchanged. + **AUTHORITY = DERIVED.** Source authority is the canonical Forge roadmap and product-owned EP/Workspace/Forge Platform contracts. This document never allocates peer implementation work. ## Current bootstrap reconciliation — 2026-09-07 @@ -52,10 +61,11 @@ This is the first real Forge -> EP -> Forge autonomy proof. It is deliberately s | Installed Forge Server / peer binding | IMPLEMENTATION/QUALIFICATION LANE | Required before live inner-loop canary. | | Forge exact receipt reconciliation | IMPLEMENTATION LANE | Required before replanning from live evidence. | | Dynamic same-Mission `reconcile -> replan -> derive successor` | TARGET RUNTIME GAP | First autonomy canary. | -| Per-Action repository target | TARGET RUNTIME GAP | Required before cross-repository Mission graph. | -| Forge-owned hard `depends_on` snapshot | BOOTSTRAP SEED EXISTS | Generalize from current Action dependencies. | -| Multiple independently eligible Actions in flight | TARGET RUNTIME GAP | Second cross-repository canary. | -| EP dependency enforcement/resource/capacity separation | EP-OWNED TARGET | Consume producer contract; Forge does not schedule resources. | +| Per-Action repository target | TARGET RUNTIME GAP | PA-F0/PA-F1; required before cross-repository Mission graph. | +| Forge-owned hard `depends_on` snapshot | BOOTSTRAP SEED EXISTS | PA-F0/PA-F2 generalize current Action dependencies. | +| Multiple independently eligible Actions in flight | TARGET RUNTIME GAP | PA-F1/PA-F2/PA-F3; actual overlap in PA-FQ, not just two eligible rows. | +| Incremental fan-in/replan without a wave barrier | TARGET RUNTIME GAP | PA-F4; A-only successor need not wait for unrelated B. | +| EP dependency enforcement/resource/capacity separation | EP-OWNED TARGET | Consume PA-E evidence; Forge does not schedule resources. | | Evidence-gated cross-repository artifact unlock | CROSS-PRODUCT TARGET | Second canary; Forge Platform manifest is reference scenario. | | Project Intelligence / outer Mission loop | FOLLOW-ON CORE PRODUCT | Consumes completed Mission evidence. | | Workspace Roadmap/DAG Governance | FOLLOW-ON CORE PRODUCT | Not required for first machine loop. | @@ -127,6 +137,14 @@ FP-A4 installer qualification The graph expresses logical dependencies only. EP separately decides whether an eligible Action may actually run based on leases, Agent capabilities and capacity. +For the qualified parallel profile, closure must also show two compatible +independent targets actually executing in overlapping intervals. The first +bounded scenario may use already-authorized repositories on one host rather +than waiting for the complete installer/Agent-fleet example. Per-result +reconciliation can release an A-only successor while B still runs; only real +multi-parent joins wait for both. The exact PA-F/PA-E dependencies are in the +linked owning documentary DAGs and do not add a first-canary edge. + ## Dependency semantics A hard Action edge means the successor is not eligible until the required predecessor terminal-success evidence exists. The edge may also name required predecessor evidence, for example published artifact identity, artifact SHA-256, source revision and qualification/provenance references. @@ -222,13 +240,20 @@ Required proof: ```text FORGE_DERIVES_CROSS_REPO_DEPENDENCIES = TRUE INDEPENDENT_REPOSITORIES_BECOME_CONCURRENTLY_ELIGIBLE = TRUE +INDEPENDENT_ACTION_EXECUTION_INTERVALS_OVERLAP = TRUE +PER_ACTION_TARGET_STATE_AND_EVIDENCE_ISOLATED = TRUE DEPENDENT_ACTION_NEVER_EXECUTES_EARLY = TRUE ARTIFACT_EVIDENCE_UNLOCKS_SUCCESSOR = TRUE +INCREMENTAL_REPLAN_WITHOUT_UNRELATED_SIBLING_BARRIER = TRUE EP_RESOURCE_POLICY_REMAINS_SEPARATE_FROM_FORGE_PLAN = TRUE MISSION_REPLANS_AFTER_PARALLEL_RESULTS = TRUE ``` -The Execution Agent + Forge Platform installer-role Mission is a preferred real dogfood candidate after the corresponding EP multi-execution/lease/capacity capability is qualified. +The Execution Agent + Forge Platform installer-role Mission remains a preferred +larger dogfood candidate after its corresponding EP capability is qualified. +The bounded PA-FQ canary does not require the full fleet/UI first. Actual +concurrency, isolated state/evidence, safe recovery, complete required assurance +and efficiency measurements are distinct proof obligations. ## Authority boundaries @@ -285,9 +310,9 @@ per-Action repository target + multiple Action persistence/in-flight state + EP multi-execution/lease/capacity qualification -> Forge cross-repo depends_on graph - -> independent Actions concurrently eligible - -> evidence-gated successor unlock - -> replan after parallel results + -> independent Actions concurrently eligible and actually overlapping + -> per-result incremental reconciliation and evidence-gated successor unlock + -> Mission completion with all required evidence and effects accounted for ``` Project Intelligence/Workspace governance and universal installer productization are not inserted into the first inner-loop readiness chain. @@ -299,6 +324,9 @@ Project Intelligence/Workspace governance and universal installer productization - Different repositories may become concurrently eligible when Forge declares no dependency. - EP can still delay either Action for repository/resource/Agent/provider reasons. - Same-repository parallel mutation is a separate, stricter qualification and is not implied. +- A bounded eligible frontier replaces the serial singleton only through the PA implementation and qualification; no unbounded fan-out. +- No global wave barrier: an A-only successor can advance without unrelated B, but an A+B join waits for both. +- An Action is not one native subagent; provider-internal delegation has separate scope/capacity/qualification boundaries. ## Roadmap-to-action rule diff --git a/docs/architecture/LIVING_MISSION_GRAPH_AND_CROSS_REPOSITORY_ACTION_DAG.md b/docs/architecture/LIVING_MISSION_GRAPH_AND_CROSS_REPOSITORY_ACTION_DAG.md index 4cd45e0..56549de 100644 --- a/docs/architecture/LIVING_MISSION_GRAPH_AND_CROSS_REPOSITORY_ACTION_DAG.md +++ b/docs/architecture/LIVING_MISSION_GRAPH_AND_CROSS_REPOSITORY_ACTION_DAG.md @@ -5,6 +5,18 @@ and evidence-derived completion slice is source-delivered and deterministically qualified; live Forge→EP and cross-repository qualifications remain separately governed and unexecuted. +## Parallel-runtime refinement — 2026-09-17 + +The [Parallel Action runtime V1 design](PARALLEL_ACTION_RUNTIME_V1.md), +[owning roadmap](../roadmap/PARALLEL_ACTION_RUNTIME_V1.md), +[documentary DAG](../roadmap/parallel-action-runtime-v1.json) and +[shared qualification catalogue](PARALLEL_ACTION_QUALIFICATION_V1.md) +make the existing second Runtime milestone implementable: bounded planner +fan-out, durable per-Action targets/state, asynchronous dispatch, incremental +fan-in and actual EP execution overlap. All added PA implementation nodes remain +PLANNED. This NO_BUMP design does not change the current serial Mission-3 proof, +reset-maintenance work, active policy, credentials or installed runtime. + ## Purpose An approved Mission is the stable human-governed boundary. Forge owns the dynamic engineering plan inside that boundary. It must be able to derive the first Engineering Action, reconcile real execution evidence, change the remaining plan, derive additional Actions, and stop only when Mission completion is proven by evidence. @@ -147,9 +159,16 @@ Forge Living Mission Graph ## Parallel release from one Mission -The target Runtime may release more than one eligible Action from the same Mission. It should select the maximal safe set allowed by the Living Mission Graph and submit them independently. EP remains free to serialize or delay them for execution-resource reasons. +The target Runtime releases a **bounded eligible frontier** from the same Mission, +not an enforced singleton or the entire backlog. Approved release/concurrency +policy and peer capability limits constrain how many independent immutable Actions +are offered. EP separately decides actual resource/capacity admission. Waiting due +to a limit does not create a false logical dependency. -The current Bootstrap Mission Scheduler's single in-flight Action rule is a bootstrap implementation limit, not a target invariant. The current runner-wide repository target is likewise a bootstrap limit; target architecture requires repository identity at the Action/submission boundary. +The current Bootstrap Mission Scheduler's single in-flight Action rule and +`_OneActionProvider` are bootstrap implementation limits, not target invariants. +The loop-wide repository binding must become a verified per-Action mapping before +cross-target release; two repositories require real scope, not a broader prompt. The delivered serial source slice retains that bootstrap limit. For an approved provider-derived scope with no Action definitions, it derives and validates an @@ -157,6 +176,21 @@ initial Action, reconciles canonical terminal evidence, refreshes current planning evidence, and may append a validated successor. Derivation lineage and completed materialized Actions survive a normal durable runtime reopen. +The parallel refinement requires durable per-Action execution/correlation slots, +per-repository Truth, graph revision guards and in-flight contribution reservations. +Locks protect short state transitions, not full provider or HTTP waits. Process +each result independently: after A succeeds, C depending only on A may start while +B still runs. Only a real multi-parent dependency waits for both A and B. Do not +invent a global wave barrier. Materialized siblings remain immutable during replan; +duplicate/lost/late results cannot produce new submissions or overwrite another +slot. See [the detailed model and recovery contract](PARALLEL_ACTION_RUNTIME_V1.md). + +An Engineering Action is not one subagent. Provider-internal delegation stays +under the owning Action's scope; it neither replaces cross-repository Action +admission nor requires a new full delivery cycle for every helper. Native nested +implementation agents and same-repository parallel writers remain separately +qualified, not implied by this target. + ## Mission completion Mission completion is not defined as “all Actions from the initial plan are COMPLETE”. The initial plan is provisional. @@ -173,6 +207,12 @@ exact current Repository Truth snapshot plus canonical correlated terminal Host evidence. Unknown or absent evidence remains unsatisfied; neither provider prose nor an Execution Host completion assertion has planning or completion authority. +For multi-in-flight operation, success evaluation also requires that all admitted +side effects are accounted for. No Mission COMPLETE while a sibling can still +write, cancellation is unacknowledged or an accepted request is uncertain. +A failed predecessor blocks its dependants without rewriting unrelated successes; +continuation/cancellation of independent siblings follows actual impact and policy. + ## Qualification sequence Two separate real-world qualifications are required. @@ -204,10 +244,20 @@ A later Mission spans at least two repositories and proves: ```text FORGE_DERIVES_CROSS_REPO_DEPENDENCIES = TRUE INDEPENDENT_REPOSITORIES_BECOME_CONCURRENTLY_ELIGIBLE = TRUE +INDEPENDENT_ACTION_EXECUTION_INTERVALS_OVERLAP = TRUE +PER_ACTION_TARGET_STATE_AND_EVIDENCE_ISOLATED = TRUE DEPENDENT_ACTION_NEVER_EXECUTES_EARLY = TRUE ARTIFACT_EVIDENCE_UNLOCKS_SUCCESSOR = TRUE +INCREMENTAL_REPLAN_WITHOUT_UNRELATED_SIBLING_BARRIER = TRUE EP_RESOURCE_POLICY_REMAINS_SEPARATE_FROM_FORGE_PLAN = TRUE MISSION_REPLANS_AFTER_PARALLEL_RESULTS = TRUE ``` -The Execution Agent + Forge Platform installer role is a suitable real dogfood Mission for this second qualification once the required EP multi-execution/lease/capacity capabilities are qualified. +The Execution Agent + Forge Platform installer role remains a suitable larger +dogfood Mission once its own prerequisites exist. The first bounded qualification +may instead use two already-authorized repositories on one host; no Agent-fleet +or UI dependency is added merely to prove concurrency. It must prove actual EP +execution overlap, independent per-Action recovery, incremental fan-in, complete +required assurance and honest time/usage accounting. See PA-01..PA-26 in the +[qualification catalogue](PARALLEL_ACTION_QUALIFICATION_V1.md). Eligibility alone +is no longer sufficient closure evidence for the parallel-runtime milestone. diff --git a/docs/architecture/PARALLEL_ACTION_QUALIFICATION_V1.md b/docs/architecture/PARALLEL_ACTION_QUALIFICATION_V1.md new file mode 100644 index 0000000..a55b924 --- /dev/null +++ b/docs/architecture/PARALLEL_ACTION_QUALIFICATION_V1.md @@ -0,0 +1,37 @@ +# Parallel Action runtime — shared qualification cases + +**Status:** PLANNED tests, not executed qualification. **Increment:** `FORGE_EP_PARALLEL_ACTION_RUNTIME_V1`. **NO_BUMP.** +The [Forge runtime design](PARALLEL_ACTION_RUNTIME_V1.md) owns graph semantics; EP's owning dependency/admission design owns execution proof. Implement tests against actual product services and isolated stores. Name exact source/artifact, policy, target and invocation scope in every receipt. + +| ID | Case | Required proof | +| --- | --- | --- | +| PA-01 | Serial compatibility and migration | Existing singleton Action maps losslessly to one slot; no replay or authority/usage reset | +| PA-02 | Actual planner fan-out | One approved Mission produces distinct justified per-target Actions without owner Action script | +| PA-03 | Invalid graph delta | Cycles, missing targets/edges, duplicate identity and out-of-scope nodes rejected before partial materialization | +| PA-04 | Independent targets execute concurrently | Two real EP execution intervals overlap with independent resources; queue/eligible flags alone insufficient | +| PA-05 | True cross-repository dependency | Free resources/capacity never allow execution before required predecessor evidence | +| PA-06 | Evidence predicate integrity | Wrong run, target, candidate, revision or artifact rejected; source merge does not prove published qualified bytes | +| PA-07 | Incremental fan-in | A completes while B runs; C needing only A can advance without waiting for B | +| PA-08 | Multi-parent join | Q requiring A and B remains blocked until both exact result/artifact predicates hold | +| PA-09 | Per-repository Truth | A progress does not overwrite B baseline; real shared-input invalidation handled explicitly | +| PA-10 | Concurrent result updates | Out-of-order/duplicate callbacks reconcile correct slots once; no lost graph updates or double usage | +| PA-11 | Stale planner/completion CAS | Old snapshot cannot overwrite new evidence/reservations or claim premature completion | +| PA-12 | Partial submission and lost acknowledgement | A accepted/B uncertain remain distinct; exact B readback, no duplicate Action/request | +| PA-13 | Runtime restart | All pending/running/uncertain slots reopen; no second writer or silent singleton truncation | +| PA-14 | Same-repository contention | Logical independence preserved, first profile serializes shared mutable target; no fake dependency edge | +| PA-15 | Cross-repo shared test resources | Shared ports, data-root, signing/build/release resources still exclude correctly | +| PA-16 | Capacity and fairness | Bounded global/provider/per-target limits, no multiplication by subagents, no head-of-line starvation | +| PA-17 | Scope and peer routing | A grant cannot authorize B target; no global rebind, new broad credential or arbitrary endpoint | +| PA-18 | Child failure and cancellation | Unaffected success retained; dependants blocked; no unacknowledged cancellation or hidden running work | +| PA-19 | Required reviews and delivery | Independent candidate-bound assurance for each Action; joint proof binds exact combination | +| PA-20 | Completion with pending effects | Mission cannot COMPLETE while required work, accepted writes or uncertain cancellations remain | +| PA-21 | No authority or budget laundering | Materialized identities immutable; retries don't become new Actions or reset allowance; no next Mission | +| PA-22 | Readmodel/MD/JSON parity | All active Actions and wait causes represented in one scoped snapshot, no singleton/last-result disguise | +| PA-23 | Usage/time accounting | Siblings not retry lineage; all child usage once, unknown explicit; union/elapsed versus sums labelled | +| PA-24 | Controlled efficiency comparison | Same work and quality gates; actual overlap and measured elapsed/usage, no invented speedup | +| PA-25 | Unsupported/disabled capability | Explicit serial-only disposition or blocker; never claim parallel qualification from fallback | +| PA-26 | Installed real boundary | Qualified artifacts outside source checkout, real Forge→HTTP→EP and returned per-Action evidence | + +Qualification levels remain separate: documentary JSON/DAG checks; deterministic graph/store/HTTP fixtures; real local concurrent EP execution with a controlled provider; explicitly authorized live provider/cross-repository dogfood. A controlled provider test proves scheduling/identity, not actual model reasoning or provider efficiency. The final live canary must prove Forge-generated fan-out and incremental successor derivation as well as overlapping execution. No production CENTRAL reset, credential change or paid canary follows from this document. + +Prototype the scenario with two authorized repositories on one host. Distributed fleet and Workspace UI are not required. Same-repository parallel writers and native nested-agent implementation are not implied. Existing serial Mission-3 criteria remain unchanged. diff --git a/docs/architecture/PARALLEL_ACTION_RUNTIME_V1.md b/docs/architecture/PARALLEL_ACTION_RUNTIME_V1.md new file mode 100644 index 0000000..ad3d28e --- /dev/null +++ b/docs/architecture/PARALLEL_ACTION_RUNTIME_V1.md @@ -0,0 +1,111 @@ +# Parallel Actions inside one Mission — runtime design V1 + +**Increment:** `FORGE_EP_PARALLEL_ACTION_RUNTIME_V1`. **Owner:** Forge. +**Status:** target-design refinement; canonical after protected merge. All new implementation and qualification nodes remain **PLANNED**. **Version decision: NO_BUMP.** + +This concretizes the existing [Living Mission Graph](LIVING_MISSION_GRAPH_AND_CROSS_REPOSITORY_ACTION_DAG.md) and its second cross-repository Runtime milestone. It is not a new planner, EP scheduler, Mission programme or replacement roadmap. See [owning delivery roadmap](../roadmap/PARALLEL_ACTION_RUNTIME_V1.md), [documentary DAG](../roadmap/parallel-action-runtime-v1.json) and [shared qualification cases](PARALLEL_ACTION_QUALIFICATION_V1.md). EP owns the companion `docs/engineering/FORGE_ACTION_DEPENDENCY_ADMISSION_BOUNDARY.md` and `docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md`. + +## 1. Observed limitation and requested outcome + +Source reviewed on 2026-09-17: Forge `03f9514e0f1e66a79ccb684c9fdbe51b28b88090`; EP `f45694d40b753d235feac8b803d364e1450cae26`. These identify inspected source, not a new audit of running services or the in-progress reset implementation. + +At that Forge source, `forge/runtime/dynamic_mission.py` composes `_OneActionProvider`, requires exactly one derived Action per provider result and carries a single current Action/result correlation. `_loop()` binds the selected host configuration's project/repository at loop level. These are deliberate serial-canary limits, not permanent architecture invariants. Removing only the one-result check would leave persistence, target authorization, dispatch and reconciliation unsafe. + +Required target: within one governed Mission, Forge derives multiple distinct, bounded Actions, proves their logical eligibility and durably submits a bounded eligible frontier. EP can actually execute independent repository Actions concurrently when its resource/capacity policy permits. A declaration that two nodes are eligible, two queued receipts, or two UI spinners is not proof of concurrent execution. + +The current Mission-3 serial dynamic-replanning test and reset work remain unchanged. This design grants no permission to run a Mission, modify policy, install a release, rotate credentials or reset data. The first parallel delivery is two authorized repositories on one compatible EP host with separate workspaces. A distributed Agent fleet, Workspace UI, native nested-agent engine and the complete future Server/Console programme are not artificial predecessors; the exact installed runtime/transport/concurrency seams still require qualification. + +## 2. Separate planning from execution and from subagents + +Forge owns objective/criterion containment, graph reasoning, per-Action target/write scope, hard dependency evidence, planning policy and Mission reconciliation. EP owns accepted execution state, leases, physical placement, provider capacity, validation, assurance, delivery and terminal evidence. Communication uses the existing authenticated versioned HTTP boundary; neither product queries the other's database. + +An Action is a bounded engineering delivery, not one AI worker. A provider may internally delegate work under its existing qualified scope; that does not create another Forge Action or permit writing another repository. Native subagents and parallel mandatory reviewers are separately governed capabilities, not prerequisites or proof for inter-Action concurrency. One Action retains its own candidate-bound assurance and delivery requirements regardless of the number of internal workers. + +One Mission may cover several explicitly approved repository targets. A project label, same owner or filesystem adjacency is not authorization. One Action normally has one target repository. Per-Action routing resolves the exact EP instance/project/repository attachment and credential scope from an approved registry/binding, not a loop-global target or provider-supplied arbitrary URL. The current consumer for repository `forge` does not automatically authorize `engineering-platform`. Missing target grants are explicit blockers; no broad consumer, secret copying or repeated global peer reconfiguration to switch targets. + +## 3. Model and immutable execution boundary + +Extend the existing Mission state/store, planner, derivation journal and submission services; do not create a second graph database, scheduler or queue. Exact schema versions and migrations belong to implementation. + +| Record | Required meaning | +| --- | --- | +| Mission graph revision | Stable Mission/revision, approved scope/policy references, current criteria and a revisioned set of nodes/edges | +| Planning snapshot | Per-repository Truth vector, accepted predecessor evidence set, unsatisfied criteria, unresolved findings, and reservations for materialized/in-flight contributions | +| Unmaterialized node | Proposed objective, target, criterion contribution, expected output/evidence, dependencies and independence/conflict analysis | +| Materialized Action | Immutable Action/revision, Mission/Intent provenance, target and write scope, actual target baseline, acceptance, dependency snapshot/evidence predicates, request digest and idempotency/correlation identity | +| Per-Action execution slot | Owning submission intent, selected binding revision, admission/readback identity, EP attempt lineage, observed lifecycle state and verified evidence references | +| Mission aggregation | Reconciled contributions, pending/blocked/uncertain work, graph revision and completion decision; never just the latest callback | + +A materialized Action remains immutable even if not yet dispatched. To withdraw it, use an explicit pre-dispatch cancellation disposition proving no accepted effect, or owning EP cancellation/readback when acceptance is possible. Do not recycle its identity for changed bytes. Future unmaterialized work may be revised, split or retired. Already running siblings and historical evidence are never rewritten by replanning. + +Legacy singleton fields are compatible projections only when exactly one Action exists in flight. With multiple Actions they must expose an explicit collection/count or unsupported legacy view, not an arbitrary first/latest child. Migration maps an existing serial Action/correlation losslessly into one slot. Ambiguous legacy records fail closed; migration cannot replay submissions, invent graph edges or reset grants/usage. + +## 4. Derive an eligible frontier, not a forced A→B chain + +The planner may return one or several justified nodes from one immutable planning snapshot. Validate the complete proposed graph delta for scope, criterion causality, unique identities, valid targets, resolvable references and acyclicity before accepting/materializing it. An invalid delta does not silently materialize its convenient valid subset; use an explicitly versioned partial-result contract only if separately qualified. + +Independence is reasoned from required inputs/outputs, approved artifact/interfaces and causal evidence, not merely absence of an edge in malformed data. Different repositories can depend on each other. Conversely membership of one Mission/project is not a hard dependency. Shared resource exclusion remains EP-owned and must not be encoded as a fake `depends_on` edge. + +Reserve intended criterion contributions for materialized/in-flight Actions. Reservation is not success evidence, but prevents two planners from duplicating the same missing work while a sibling is progressing. Overlapping contributions are allowed only with an explicit reason, such as independent verification or distinct parts of one criterion. Do not split a coherent Action solely to increase agent count or create unnecessary review/publication transactions. + +Compute the currently eligible frontier from the validated graph and verified evidence. Release a bounded subset according to the approved Mission policy, fair selection and negotiated peer limits; do not fan out the whole backlog. Remaining eligible nodes are visibly waiting for release/capacity policy, not given invented logical predecessors. A finite numeric limit, not the number three from an example, is resolved and recorded before execution. `SERIAL` remains compatible; `PARALLEL_ELIGIBLE` is a design profile whose activation requires real capability/authorization. Unknown capability cannot be reported as parallel success. + +## 5. Dependencies and Truth are per Action + +A hard edge names the predecessor Action/revision and the required canonical result/evidence. Predicates can require exact project/repository, source revision, immutable receipt, qualified artifact digest, publication provenance and contract version. A generic COMPLETE or source merge cannot satisfy a published-qualified-wheel requirement. Wrong attempt, different candidate or stale incompatible artifact cannot satisfy the edge. + +Use a repository Truth vector, not one Mission-wide commit SHA. A change to repository A does not overwrite B's baseline or invalidate an unrelated B Action. Each admitted Action retains its own pinned target baseline and declared read/evidence dependencies. A newly derived successor pins the actual current baseline required by its inputs; it cannot retrofit a new allowed-baseline to an existing request. + +If an in-flight consumer's declared inputs are materially invalidated, record the actual conflict and use guarded hold/cancellation/replanning. An unrelated sibling's successful commit is not automatically such a conflict. Qualification must distinguish causal input invalidation from harmless graph revision, unrelated repository progress, pending CI or read-only observations. + +## 6. Bounded asynchronous dispatch and concurrency-safe persistence + +Persist intended materialization/submission identities before HTTP effects. Use short owning database transactions plus graph/slot revision compare-and-swap. Do not hold a Mission/database mutation lock across provider reasoning, network waits or the whole EP execution. SQLite serializing brief writes does not justify serializing independent engineering work. + +Planning uses a captured revision; publication of its result rechecks relevant Truth, accepted evidence, policy and in-flight reservations. A stale plan is recorded as stale, not applied over newer sibling results. Deduplicate/batch independent events where semantically safe to avoid redundant planning; completion/cancellation events still cannot be lost. Planner concurrency need not equal execution concurrency: a single short planning coordinator may manage several concurrent EP runs. + +Submission outcomes are independent. Persist A's acceptance even if B's POST is rejected or times out. A lost acknowledgement triggers exact readback/reconciliation of B's existing identity and bytes, never a new Action/submission or a resend with a different key. On restart rebuild all slots and reconcile each accepted/uncertain request before retrying any effect. Product policy owns retry/recovery allowances; parallelism does not replenish them or convert same-Action attempts into new graph nodes. + +EP may accept several independently and report dependency/resource/capacity/authority waits separately. A blocked queue head must not prevent eligible unrelated work from being considered. Forge does not allocate CPU/provider slots or bypass EP admission. Bounded dispatch and backpressure prevent request storms; one unavailable target must not silently retarget to another host/project. + +## 7. Incremental fan-in and replan without a global wave barrier + +Process results by Action identity and immutable receipt, not arrival order. Verify and reconcile each result once; update only the owning slot and affected criterion/Truth references. Duplicate, late, reordered or contradictory events retain their own classification and cannot overwrite another Action's outcome or double-count usage. + +If A completes while B is still running, Forge may immediately derive/release C when C depends only on verified A evidence and is otherwise eligible. Do not wait for all Actions launched in the same planning round merely because they share a wave label. D depending on both A and B waits for both required evidence sets. A coordinator preparing integration tests can work earlier, but cannot claim joint qualification before both artifacts exist. + +Example, not an allocated programme or prescribed Action script: + +```text + approved shared contract / Mission criteria + / \ + A: Forge reset implementation B: EP reset implementation + | | + C: A-only follow-up B still running + \ / + Q: combined qualification of exact required artifacts +``` + +A and B become independent only once their required shared interface inputs are sufficiently fixed. The planner chooses actual nodes/sizing; a named coordination agent is not automatically another mutating Action. Q may be a provider-free validation operation under the existing contract or a real separately scoped Action if it delivers independent engineering work. None of these examples authorizes the live reset or changes the current reset task. + +## 8. Failure, cancellation, maintenance and Mission completion + +Use causal impact and explicit policy. A failed required predecessor blocks its dependants; a proven success in another slot stays successful. Permitted independent siblings can finish, or be safely cancelled when the applicable Mission/authority policy requires it. Revoked authority, unknown scope impact or compromised shared resources stop affected new admission and require owning reconciliation. Do not globally mark every sibling failed, silently ignore a required failure, or automatically launch scope-expanding repair work. + +Cancellation/pause is a per-Action protocol with an aggregate Mission disposition. A request is not proof execution stopped or a lease was released. Uncertain effects remain visible and block unsafe completion/reuse. Existing product maintenance/reset must enumerate all active/uncertain slots; this document neither implements that maintenance change nor permits a reset during execution. + +Mission completion requires current evidence for all approved required criteria AND no unaccounted accepted/pending/uncertain effects or required unresolved work. If work becomes unnecessary, retire unmaterialized forecasts and explicitly settle any materialized/admitted cancellations. Do not declare the Mission complete while a sibling may still mutate a repository. A stale completion check must fail its revision guard when another result or authorized graph change intervenes. + +Each Action retains its own independent Quality/Security, validation and protected delivery. Joint qualification binds the actual pair/set of source/artifact digests, not two unrelated green reports. No new human approval is introduced merely for each eligible Action inside already-approved scope; existing genuine gates and scope/publication authority remain mandatory. Starting the next Mission remains the separately governed project loop. + +## 9. Readback and efficiency evidence + +Expose one Mission graph with a set of active Actions, independent target/attempt/receipt identities, dependency reasons, all applicable wait reasons, policy limits and source/as-of revisions. Legacy single-current-Action views must not hide other work. Workspace/Console are consumers of these readmodels, not prerequisites or lifecycle authorities; UI implementation is out of scope here. + +Use existing canonical telemetry/evidence stores. Separate Mission planning, Action attempts, provider invocations and any observable internal subagents. Sibling Actions are not an EP retry chain. Include all observed child usage once; unknown subagent accounting remains explicitly incomplete, not zero. Concurrent duration is not the sum of Action wall times; distinguish Mission elapsed time, busy interval union, overlapping work, provider totals and dependency/resource/capacity waits. + +Qualify actual execution overlap on a common observable clock and correct result isolation. Compare parallel and serial execution on the same bounded workload, provider/policy/quality gates and resource limits. Report elapsed time, accepted outcome, required-review quality, total/cached/uncached usage with coverage and orchestration overhead. No universal speedup or token reduction is guaranteed; constrained capacity may legitimately serialize. The acceptance claim must distinguish eligible concurrency, observed parallel execution and measured efficiency. + +## 10. Delivery boundary + +The seven Forge nodes in the owning roadmap generalize the existing runtime rather than deleting its serial guard in isolation. EP's six-node counterpart supplies dependency admission, independent resource execution, isolation/recovery and multi-run evidence. Both source and installed qualification are required. The first serial canary, active reset work, policy defaults, existing credentials and historical telemetry outcomes are unchanged by this documentation merge. diff --git a/docs/roadmap/PARALLEL_ACTION_RUNTIME_V1.md b/docs/roadmap/PARALLEL_ACTION_RUNTIME_V1.md new file mode 100644 index 0000000..8919519 --- /dev/null +++ b/docs/roadmap/PARALLEL_ACTION_RUNTIME_V1.md @@ -0,0 +1,20 @@ +# Parallel Action runtime V1 — Forge owning roadmap + +**Owner:** Forge. **All implementation/qualification nodes: PLANNED. NO_BUMP.** +This is the implementation decomposition of the existing second Runtime milestone in [the canonical roadmap](../../knowledge/bootstrap/10_ROADMAP.md) and [implementation DAG](../architecture/FORGE_V1_IMPLEMENTATION_DAG.md), not a competing programme. Read [the detailed design](../architecture/PARALLEL_ACTION_RUNTIME_V1.md) and [26 shared qualification families](../architecture/PARALLEL_ACTION_QUALIFICATION_V1.md). The [JSON](parallel-action-runtime-v1.json) is documentary, not scheduler input. + +| Node | Dependencies | Bounded deliverable | +| --- | --- | --- | +| PA-F0 | none | Versioned graph/frontier/target/evidence contract and published peer compatibility fixtures | +| PA-F1 | PA-F0 | Multi-slot durable Mission state, serial migration, per-Action target/baseline/correlation and revision guards | +| PA-F2 | PA-F1 | Validated bounded planner fan-out, criterion reservations, DAG/containment validation and eligible frontier | +| PA-F3 | PA-F1; EP PA-E1/PA-E2/PA-E3 | Existing HTTP adapter's bounded asynchronous multi-submit/readback, backpressure and exact replay/restart | +| PA-F4 | PA-F2, PA-F3 | Per-result reconciliation, incremental successor derivation, multi-parent joins, failure/cancel and completion barrier | +| PA-F5 | PA-F4; EP PA-E4 | Multi-active readmodels, complete per-Action evidence and scope-correct telemetry/export projections | +| PA-FQ | PA-F5; EP PA-EQ | Installed one-host/two-repository dynamic fan-out/overlap/fan-in canary and serial/parallel efficiency evidence | + +PA-F0 consumes the existing Living Mission Graph/Producer contract; no complete future policy/UI programme is required. PA-F1/F2 can progress using peer fixtures while EP qualifies execution. PA-F3 requires the exact used EP admission/resource/isolation slice, not merely a threadpool or two accepted rows. EP PA-EQ consumes PA-F0 contract fixtures, never PA-FQ, so there is no cross-product qualification cycle. + +EP owns `docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md` and its JSON DAG. Same-Mission membership must not add an EP global mutex; real shared resources may legitimately serialize. First canary uses separate repositories/workspaces on one host, no full Agent fleet, Workspace or native subagent implementation dependency. Same-repository concurrent mutation remains separate stricter qualification. + +The serial Mission-3 loop and current reset maintenance task are not expanded. Implementation can be prepared in parallel with other roadmap lanes in isolated work; acceptance of this capability is separate from serial autonomy, not inferred from it. Any later prioritization/actual Mission allocation follows existing governance. No new Mission IDs, live grants, policy activation, CI gate activation, installed change or release is made by this documentation. diff --git a/docs/roadmap/parallel-action-runtime-v1.json b/docs/roadmap/parallel-action-runtime-v1.json new file mode 100644 index 0000000..0d51144 --- /dev/null +++ b/docs/roadmap/parallel-action-runtime-v1.json @@ -0,0 +1,21 @@ +{ + "schema_version": "1.0", + "increment": "FORGE_EP_PARALLEL_ACTION_RUNTIME_V1", + "owner": "forge", + "authority": "DOCUMENTARY_DERIVED", + "executable": false, + "version_decision": "NO_BUMP", + "parent_milestone": "Cross-repository Action DAG — second Runtime autonomy milestone", + "architecture": "docs/architecture/PARALLEL_ACTION_RUNTIME_V1.md", + "qualification": "docs/architecture/PARALLEL_ACTION_QUALIFICATION_V1.md", + "current_mission_3_dependency": false, + "nodes": [ + {"id":"PA-F0","status":"PLANNED","depends_on":[],"deliverable":"Graph/frontier/target/evidence contract and compatibility fixtures"}, + {"id":"PA-F1","status":"PLANNED","depends_on":["PA-F0"],"deliverable":"Durable multi-Action slots, migration and per-target Truth"}, + {"id":"PA-F2","status":"PLANNED","depends_on":["PA-F1"],"deliverable":"Contained planner fan-out, reservations and eligible frontier"}, + {"id":"PA-F3","status":"PLANNED","depends_on":["PA-F1"],"external_evidence":["engineering-platform:PA-E1","engineering-platform:PA-E2","engineering-platform:PA-E3"],"deliverable":"Bounded asynchronous HTTP submission/readback and recovery"}, + {"id":"PA-F4","status":"PLANNED","depends_on":["PA-F2","PA-F3"],"deliverable":"Incremental reconcile/replan, joins and completion/cancellation"}, + {"id":"PA-F5","status":"PLANNED","depends_on":["PA-F4"],"external_evidence":["engineering-platform:PA-E4"],"deliverable":"Multi-active readmodels and complete scope-correct evidence"}, + {"id":"PA-FQ","status":"PLANNED","depends_on":["PA-F5"],"external_evidence":["engineering-platform:PA-EQ"],"deliverable":"Installed two-repository parallel canary and measured efficiency"} + ] +} diff --git a/knowledge/bootstrap/10_ROADMAP.md b/knowledge/bootstrap/10_ROADMAP.md index 610f1f5..edbc862 100644 --- a/knowledge/bootstrap/10_ROADMAP.md +++ b/knowledge/bootstrap/10_ROADMAP.md @@ -209,14 +209,56 @@ Qualification must prove: ```text FORGE_DERIVES_CROSS_REPO_DEPENDENCIES = TRUE INDEPENDENT_REPOSITORIES_BECOME_CONCURRENTLY_ELIGIBLE = TRUE +INDEPENDENT_ACTION_EXECUTION_INTERVALS_OVERLAP = TRUE +PER_ACTION_TARGET_STATE_AND_EVIDENCE_ISOLATED = TRUE DEPENDENT_ACTION_NEVER_EXECUTES_EARLY = TRUE ARTIFACT_EVIDENCE_UNLOCKS_SUCCESSOR = TRUE +INCREMENTAL_REPLAN_WITHOUT_UNRELATED_SIBLING_BARRIER = TRUE EP_RESOURCE_POLICY_REMAINS_SEPARATE_FROM_FORGE_PLAN = TRUE MISSION_REPLANS_AFTER_PARALLEL_RESULTS = TRUE ``` A suitable dogfood Mission is: make Engineering Platform Execution Agents production-ready and installable through Forge Platform. EP implementation/package Actions and Forge Platform installer-role work may advance in parallel, while the final platform component-manifest Action must depend on actual publication of qualified EP Server/Agent artifacts and their artifact digests/source revisions. +### Concrete parallel-runtime delivery slice — 2026-09-17 + +`FORGE_EP_PARALLEL_ACTION_RUNTIME_V1` refines this existing milestone through +[the runtime design](../../docs/architecture/PARALLEL_ACTION_RUNTIME_V1.md), +[seven-node Forge roadmap](../../docs/roadmap/PARALLEL_ACTION_RUNTIME_V1.md), +[documentary DAG](../../docs/roadmap/parallel-action-runtime-v1.json) and +[PA-01..PA-26 qualification](../../docs/architecture/PARALLEL_ACTION_QUALIFICATION_V1.md). +All added implementation/qualification nodes remain PLANNED; NO_BUMP. + +```text +PA-F0 contract -> PA-F1 multi-Action state/targets +PA-F1 -> PA-F2 bounded planner fan-out +PA-F1 + qualified EP admission/resources/isolation -> PA-F3 async dispatch +PA-F2 + PA-F3 -> PA-F4 incremental reconcile/replan/joins/completion +PA-F4 + EP evidence -> PA-F5 multi-active readmodels +PA-F5 + EP PA-EQ -> PA-FQ installed actual-parallel qualification +``` + +EP owns its matching six-node roadmap at +`docs/development/PARALLEL_ACTION_EXECUTION_V1_ROADMAP.md` and DAG. Forge +PA-F0 supplies contracts to EP PA-E0; EP PA-EQ does not depend on Forge PA-FQ, +so the integration is acyclic. The current singleton provider guard, current +Action/correlation projection and loop-level target must be generalized together, +not bypassed by a prompt or by removing one length check. + +The first qualified profile may use two already-authorized repositories on one +host. It must demonstrate actual overlapping EP execution, not just eligibility. +A-only successors can proceed while unrelated B runs; only true multi-parent +joins wait for both. Materialized Actions, per-target baselines and authority +remain immutable. Count full child usage and compare elapsed time at equal +quality gates; native subagents are a distinct layer, not one Action per helper. + +This narrows an existing core Runtime gap without changing the current serial +Mission-3 acceptance, its reset preparation, next-Mission governance or active +policy. Full Agent-fleet/Workspace/native-subagent/Console productization is not +an artificial predecessor. Same-repository parallel writes remain a separate +stricter qualification. No actual Mission IDs or executable programme edges are +allocated by this documentary plan. + ## Governance-minimal execution Within an approved Mission boundary, ordinary implementation, validation, quality/security review, bounded repair, exact-head requalification, evidence reconciliation and Action replanning are engineering iterations rather than new owner decisions. Manual owner input remains reserved for actual authority expansion, destructive operation, wider write scope, weakened security invariants or materially ambiguous product decisions. @@ -328,10 +370,10 @@ SECOND CROSS-REPOSITORY DAG QUALIFICATION: one Mission spanning >= 2 repositories -> Forge derives per-Action repository targets + depends_on -> independent Actions concurrently eligible - -> EP enforces resource/capacity separately + -> EP enforces resource/capacity separately and executes independent targets concurrently -> predecessor artifact/evidence unlocks dependent Action - -> Forge reconciles parallel results + replans - -> Mission completion + -> Forge reconciles each result + replans without unrelated sibling barrier + -> Mission completion after all required evidence and effects are accounted for OUTER LOOP: completed Mission evidence