Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"baseline_version": "2.7.40",
"classification_rationale": "L3-FORGE-ACTION-FRONTIER-PRODUCER-V1-20261001",
"component": "product",
"event_lineage": "L3-FORGE-ACTION-FRONTIER-PRODUCER-V1-20261001",
"expected_head": "05b2a79eecfc162b8866c25ddd0dd66960626de3",
"operation_id": "l3-action-frontier-producer-20261001",
"policy_revision": "forge-bootstrap-release-cadence-v2",
"product": "forge",
"projection_paths": "product-version.json",
"release_class": "PATCH",
"requested_bump": "patch",
"requested_version": null,
"schema_version": "1",
"target_version": "2.7.41"
}
47 changes: 47 additions & 0 deletions docs/architecture/PARALLEL_ACTION_FRONTIER_PRODUCER_V1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Parallel Action graph/frontier producer V1

This is a bounded `PA-F0` producer and read-only `PA-F2` projection subset. It
does not qualify the `PA-F1/F2/F3/FQ` runtime nodes or change the serial
Mission-3 execution path. Forge remains responsible for graph interpretation;
EP owns host admission, capacity, execution and evidence production.

## Installed readback

The authenticated Forge Server `GET /v1/missions/{mission_id}` response adds
`mission.action_frontier` with contract version `parallel-action-frontier/v1`.
It reads the same installed, read-only Mission snapshot as the existing
lifecycle/evidence projection. At most 256 stored Actions are accepted. Action
IDs and orders must be unique; every dependency must name a stored Action; and
cycles, malformed statuses or invalid revisions fail closed with
`MISSION_ACTION_GRAPH_INVALID`. Output order is stable by stored order and ID.

`logical_frontier_action_ids` contains only stored `READY` Actions with no
hard predecessor. An Action with a completed predecessor still waits for
verified *edge-specific* evidence, which the current serial store cannot
prove. Failed or blocked predecessors block the dependent node. Every Action
reports `dispatchable: false` and `target_resolution: UNAVAILABLE` because the
current stored Action has no per-Action target binding. The response explicitly
reports `parallel_execution: NOT_QUALIFIED`. This is a planning/readback
classification, not authorization or proof of concurrent EP execution.

## Peer compatibility vector

The packaged
[`parallel-action-peer-graph-v1.json`](../../forge/api/parallel-action-peer-graph-v1.json)
is a synthetic `parallel-action-graph/v1` compatibility fixture: independent
Actions A/B target distinct repositories; Q names both predecessors and
repository-bound qualified-artifact digests. Forge's
`validate_peer_graph` checks the exact envelope, target fields, identifiers,
unique nodes/edges, predecessor existence, evidence digest format, evidence
repository match and cycles. It returns `dispatch_authorized: false` even for
a valid vector. An EP consumer can test parser/contract compatibility against
these bytes; the fixture is no credential, binding, grant, admission request,
execution receipt or proof that the current Forge runtime can materialize it.

Before any actual parallel Action dispatch, Forge still needs durable
per-Action target/baseline/correlation state, verified predecessor predicates,
scope policy and guarded fan-out; EP needs its separately qualified admission,
resource isolation and multi-run evidence. Those remain under their owning
`PA-F1..FQ` and `PA-E0..EQ` dependencies. Installed HTTP readback and exact
artifact qualification for this producer are separate from public release or
production installation.
6 changes: 6 additions & 0 deletions docs/roadmap/PARALLEL_ACTION_RUNTIME_V1.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ This is the implementation decomposition of the existing second Runtime mileston

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.

The [bounded graph/frontier producer](../architecture/PARALLEL_ACTION_FRONTIER_PRODUCER_V1.md)
supplies a versioned peer fixture and an installed logical readback subset.
Stored Actions still lack per-Action target and verified-edge evidence; the
readback marks dispatch and parallel execution unavailable. Its delivery does
not close full PA-F1/F2 or installed overlap qualification.

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.
100 changes: 100 additions & 0 deletions forge/action_frontier.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
"""Bounded, read-only logical Action frontier for an installed Mission.

This projection never decides host admission. A stored Action has no durable
per-Action target or predecessor evidence predicate in the serial schema, so
the result must not be interpreted as a dispatchable parallel workset.
"""
from __future__ import annotations

from collections.abc import Mapping, Sequence
from typing import Any


FRONTIER_CONTRACT_VERSION = "parallel-action-frontier/v1"
MAX_FRONTIER_ACTIONS = 256
_STATUSES = frozenset({"READY", "ACTIVE", "WAITING_FOR_RESULT", "COMPLETE", "BLOCKED", "FAILED"})


class ActionFrontierError(ValueError):
"""The installed Action graph cannot be safely represented as a DAG."""


def project_action_frontier(actions: Sequence[Mapping[str, Any]], *, mission_revision: int) -> dict[str, Any]:
"""Return a deterministic logical frontier without claiming execution eligibility."""
if len(actions) > MAX_FRONTIER_ACTIONS:
raise ActionFrontierError("Mission Action graph exceeds the bounded read limit")
if not isinstance(mission_revision, int) or isinstance(mission_revision, bool) or mission_revision < 1:
raise ActionFrontierError("Mission graph revision is invalid")
nodes: dict[str, dict[str, Any]] = {}
orders: set[int] = set()
for action in actions:
if not isinstance(action, Mapping):
raise ActionFrontierError("Mission Action record is invalid")
action_id = action.get("id")
order = action.get("order")
status = action.get("status")
edges = action.get("dependencies", ())
if (not isinstance(action_id, str) or not action_id or action_id in nodes
or not isinstance(order, int) or isinstance(order, bool) or order < 1 or order in orders
or not isinstance(status, str) or status not in _STATUSES
or not isinstance(edges, (list, tuple))
or any(not isinstance(edge, str) or not edge for edge in edges)
or len(edges) != len(set(edges))):
raise ActionFrontierError("Mission Action identity, order, status or edges are invalid")
orders.add(order)
nodes[action_id] = {"action_id": action_id, "order": order, "status": status,
"dependencies": tuple(edges)}
for node in nodes.values():
if node["action_id"] in node["dependencies"] or any(
edge not in nodes for edge in node["dependencies"]
):
raise ActionFrontierError("Mission Action graph has an unresolved edge")
active: set[str] = set()
complete: set[str] = set()

def visit(action_id: str) -> None:
if action_id in active:
raise ActionFrontierError("Mission Action graph has a cycle")
if action_id in complete:
return
active.add(action_id)
for predecessor in nodes[action_id]["dependencies"]:
visit(predecessor)
active.remove(action_id)
complete.add(action_id)

for action_id in nodes:
visit(action_id)
ordered = sorted(nodes.values(), key=lambda node: (node["order"], node["action_id"]))
frontier: list[str] = []
projected: list[dict[str, Any]] = []
for node in ordered:
dependencies = node["dependencies"]
if node["status"] != "READY":
logical_state = node["status"]
elif any(nodes[edge]["status"] in {"FAILED", "BLOCKED"} for edge in dependencies):
logical_state = "BLOCKED_BY_PREDECESSOR"
elif any(nodes[edge]["status"] != "COMPLETE" for edge in dependencies):
logical_state = "WAITING_FOR_PREDECESSOR"
elif dependencies:
# Serial storage does not bind a verified predicate to each edge.
logical_state = "WAITING_FOR_VERIFIED_EVIDENCE"
else:
logical_state = "LOGICALLY_ELIGIBLE"
frontier.append(node["action_id"])
projected.append({
"action_id": node["action_id"], "order": node["order"], "status": node["status"],
"dependencies": list(dependencies), "logical_state": logical_state,
"target_repository_id": None, "target_resolution": "UNAVAILABLE",
"dependency_evidence_resolution": "UNAVAILABLE" if dependencies else "NOT_REQUIRED",
"dispatchable": False,
})
return {
"contract_version": FRONTIER_CONTRACT_VERSION,
"source_mission_revision": mission_revision,
"graph_kind": "STORED_ACTION_LOGICAL_DAG",
"logical_frontier_action_ids": frontier,
"actions": projected,
"parallel_execution": "NOT_QUALIFIED",
"read_only": True,
}
54 changes: 54 additions & 0 deletions forge/api/parallel-action-peer-graph-v1.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
{
"contract_version": "parallel-action-graph/v1",
"mission_id": "MISSION-FIXTURE-1",
"mission_revision": 1,
"actions": [
{
"action_id": "ACTION-A",
"target": {
"ep_instance_id": "ep-fixture-1",
"project_id": "project-fixture-1",
"repository_id": "repository-a",
"baseline_revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"dependencies": []
},
{
"action_id": "ACTION-B",
"target": {
"ep_instance_id": "ep-fixture-1",
"project_id": "project-fixture-1",
"repository_id": "repository-b",
"baseline_revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
"dependencies": []
},
{
"action_id": "ACTION-Q",
"target": {
"ep_instance_id": "ep-fixture-1",
"project_id": "project-fixture-1",
"repository_id": "repository-a",
"baseline_revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"dependencies": [
{
"predecessor_action_id": "ACTION-A",
"required_evidence": {
"kind": "QUALIFIED_ARTIFACT",
"repository_id": "repository-a",
"content_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},
{
"predecessor_action_id": "ACTION-B",
"required_evidence": {
"kind": "QUALIFIED_ARTIFACT",
"repository_id": "repository-b",
"content_digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
}
]
}
]
}
2 changes: 1 addition & 1 deletion forge/api/server-openapi-v1.json
Original file line number Diff line number Diff line change
Expand Up @@ -289,7 +289,7 @@
},
"/v1/missions/{mission_id}": {
"get": {
"summary": "Read Mission lifecycle and evidence lineage",
"summary": "Read Mission lifecycle, evidence lineage and non-dispatchable Action frontier",
"responses": {
"200": {
"description": "Accepted JSON response"
Expand Down
2 changes: 1 addition & 1 deletion forge/api/server-postman-v1.json
Original file line number Diff line number Diff line change
Expand Up @@ -344,7 +344,7 @@
}
},
{
"name": "Read Mission lifecycle and evidence lineage",
"name": "Read Mission lifecycle, evidence lineage and non-dispatchable Action frontier",
"request": {
"method": "GET",
"header": [],
Expand Down
9 changes: 9 additions & 0 deletions forge/operations_read_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
from urllib.parse import unquote, urlsplit

from .__main__ import _status
from .action_frontier import ActionFrontierError, project_action_frontier
from .execution_host_configuration import PeerConfigurationError, read_peer_configuration
from .installed_health import InstalledHealthError, InstalledHealthSnapshotService
from .mission_cli import _status_projection as mission_status_projection
Expand Down Expand Up @@ -256,6 +257,14 @@ def mission_detail(self, mission_id: str) -> dict[str, Any]:
"criterion_assessment_history": [_project_assessment(item) for item in state.completion_history],
},
})
try:
projection["action_frontier"] = project_action_frontier(
state.actions, mission_revision=state.revision,
)
except ActionFrontierError:
raise OperationsProjectionError(
"MISSION_ACTION_GRAPH_INVALID", "Mission Action graph is inconsistent", status=409,
) from None
return _redact({
"api_version": API_VERSION,
"availability": "AVAILABLE",
Expand Down
103 changes: 103 additions & 0 deletions forge/parallel_action_contract.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
"""Versioned, authority-free compatibility contract for parallel Action graphs.

This validates a producer document for peer compatibility testing. It does not
resolve an EP binding, prove a grant, materialize Actions, or admit execution.
"""
from __future__ import annotations

from collections.abc import Mapping
import re
from typing import Any


PEER_GRAPH_CONTRACT_VERSION = "parallel-action-graph/v1"
_IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\Z")
_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
_EVIDENCE_KINDS = frozenset({"QUALIFIED_ARTIFACT", "REPOSITORY_REVISION"})


class ParallelActionContractError(ValueError):
"""A peer compatibility graph is malformed or self-contradictory."""


def _identifier(value: object) -> bool:
return isinstance(value, str) and _IDENTIFIER.fullmatch(value) is not None


def validate_peer_graph(document: Mapping[str, Any]) -> dict[str, Any]:
"""Validate and canonicalize an explicit-target test vector, never a grant."""
if (not isinstance(document, Mapping)
or set(document) != {"contract_version", "mission_id", "mission_revision", "actions"}
or document.get("contract_version") != PEER_GRAPH_CONTRACT_VERSION
or not _identifier(document.get("mission_id"))
or not isinstance(document.get("mission_revision"), int)
or isinstance(document["mission_revision"], bool) or document["mission_revision"] < 1
or not isinstance(document.get("actions"), list)
or not 1 <= len(document["actions"]) <= 256):
raise ParallelActionContractError("parallel Action graph envelope is invalid")
actions: dict[str, dict[str, Any]] = {}
for item in document["actions"]:
if (not isinstance(item, Mapping)
or set(item) != {"action_id", "target", "dependencies"}
or not _identifier(item.get("action_id"))
or item["action_id"] in actions
or not isinstance(item.get("target"), Mapping)
or set(item["target"]) != {
"ep_instance_id", "project_id", "repository_id", "baseline_revision",
}
or any(not _identifier(item["target"].get(key)) for key in item["target"])
or not isinstance(item.get("dependencies"), list)):
raise ParallelActionContractError("parallel Action or target is invalid")
dependencies: list[dict[str, Any]] = []
seen: set[str] = set()
for edge in item["dependencies"]:
if (not isinstance(edge, Mapping)
or set(edge) != {"predecessor_action_id", "required_evidence"}
or not _identifier(edge.get("predecessor_action_id"))
or edge["predecessor_action_id"] == item["action_id"]
or edge["predecessor_action_id"] in seen
or not isinstance(edge.get("required_evidence"), Mapping)
or set(edge["required_evidence"]) != {"kind", "repository_id", "content_digest"}
or not isinstance(edge["required_evidence"].get("kind"), str)
or edge["required_evidence"]["kind"] not in _EVIDENCE_KINDS
or not _identifier(edge["required_evidence"].get("repository_id"))
or not isinstance(edge["required_evidence"].get("content_digest"), str)
or _DIGEST.fullmatch(edge["required_evidence"]["content_digest"]) is None):
raise ParallelActionContractError("parallel Action predecessor evidence is invalid")
seen.add(edge["predecessor_action_id"])
dependencies.append({
"predecessor_action_id": edge["predecessor_action_id"],
"required_evidence": dict(edge["required_evidence"]),
})
actions[item["action_id"]] = {
"action_id": item["action_id"], "target": dict(item["target"]),
"dependencies": dependencies,
}
for action in actions.values():
for edge in action["dependencies"]:
predecessor = actions.get(edge["predecessor_action_id"])
if (predecessor is None or edge["required_evidence"]["repository_id"]
!= predecessor["target"]["repository_id"]):
raise ParallelActionContractError("parallel Action evidence target is inconsistent")
visiting: set[str] = set()
visited: set[str] = set()

def visit(action_id: str) -> None:
if action_id in visiting:
raise ParallelActionContractError("parallel Action graph has a cycle")
if action_id in visited:
return
visiting.add(action_id)
for edge in actions[action_id]["dependencies"]:
visit(edge["predecessor_action_id"])
visiting.remove(action_id)
visited.add(action_id)

for action_id in actions:
visit(action_id)
return {
"contract_version": PEER_GRAPH_CONTRACT_VERSION,
"mission_id": document["mission_id"], "mission_revision": document["mission_revision"],
"actions": [actions[key] for key in sorted(actions)],
"dispatch_authorized": False,
}
2 changes: 1 addition & 1 deletion product-version.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"product": "forge",
"schema_version": 1,
"version": "2.7.40"
"version": "2.7.41"
}
Loading
Loading