rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/workflows/README.md

@@ -0,0 +1,18 @@
+# workflows — process inventories and completion gates
+
+`workflows/` holds the digital, analog, photonic, and mixed-domain verification stages as data. It plans checks and reports whether the requested flow has enough available operations and passing evidence. It never launches a solver.
+
+## Current behavior
+
+- `stages.py` contains the D/A/P/M inventories and their stage-to-operation mappings.
+- `capability_plan.py` marks stages ready or blocked based on available operations.
+- `completion.py` combines the plan with the latest check records. Missing operations, checks that have not run, and non-PASS verdicts remain blockers; only a blocker-free flow can report fully verified.
+- The stage `when` expressions are descriptive today. The planner currently treats planned stages as required instead of evaluating those expressions to narrow applicability.
+
+The same plan and completion reports are served by `plan_checks` and `get_design_completion`, so clients can show the engine's reasons and blockers directly.
+
+## Boundaries and routing
+
+This module owns stage order, applicability metadata, and completion rules. `composition.Engine` supplies registered operations and check results. Solver inputs and evidence belong to [`adapters/`](../adapters/README.md) and [`execution/`](../execution/README.md); command and result shapes belong to [`interfaces/`](../interfaces/README.md).
+
+For the product process source, see the [PRD verification process](../../../PRD/tools-research/verification-process.md) and [workflow catalog](../../../PRD/tools-research/verification-workflows.yaml). For current engine gaps, see the [sprint board](../../docs/sprint-board.md).

rocket_engine/workflows/__init__.py

@@ -0,0 +1,53 @@
+"""D/A/P/M step order and check plans as data. Never calls solvers directly."""
+
+from .capability_plan import plan_from_capabilities
+from .completion import design_completion_report, plan_checks_report
+from .connectgraph import (
+    RULE_DANGLING_NET,
+    RULE_ORPHAN_LABEL,
+    RULE_SHORT,
+    RULE_UNCONNECTED_PIN,
+    Connectivity,
+    ConnectGraphError,
+    Net,
+    NetlistStructs,
+    ResolvedInstance,
+    erc_findings,
+    prepare_netlist_structs,
+)
+from .connectgraph_emit import (
+    LANGUAGES,
+    emit_netlists,
+    emit_spice,
+    emit_verilog,
+    emit_vhdl,
+    resolve_format,
+    to_raw_ir,
+)
+from .stages import STAGES, applicable_stages
+
+__all__ = [
+    "STAGES",
+    "applicable_stages",
+    "plan_from_capabilities",
+    "design_completion_report",
+    "plan_checks_report",
+    "Connectivity",
+    "ConnectGraphError",
+    "Net",
+    "NetlistStructs",
+    "ResolvedInstance",
+    "erc_findings",
+    "prepare_netlist_structs",
+    "RULE_SHORT",
+    "RULE_UNCONNECTED_PIN",
+    "RULE_DANGLING_NET",
+    "RULE_ORPHAN_LABEL",
+    "LANGUAGES",
+    "emit_netlists",
+    "emit_spice",
+    "emit_verilog",
+    "emit_vhdl",
+    "resolve_format",
+    "to_raw_ir",
+]

rocket_engine/workflows/capability_plan.py

@@ -0,0 +1,102 @@
+"""Capability-aware stage planning: readiness from tool truth, not wiring.
+
+`applicable_stages` plans against a caller-supplied backend set,
+which reads ready whenever an operation is merely wired — M11
+(`run_timing`) planned ready while `sta` was absent. This module
+plans against a `report_capabilities` operations mapping instead:
+a stage is ready only when every tool entrypoint it needs reports
+ready, and a blocked stage carries which entrypoints block it plus
+their reason, missing items, and remedy.
+"""
+
+from .stages import _SCRIPTED, STAGES, covering_decks
+
+_FALLBACK_REMEDY = "Provision the missing tooling (see docs/provision-plan.md)."
+
+
+def _stage_decks(stage, operations, solvers):
+    """Covering deck cites for one stage's tool entrypoints.
+
+    Args:
+        stage: Stage inventory entry with entrypoints.
+        operations: Per-operation readiness mapping.
+        solvers: Operation -> deck-tool cites; None means the
+            curated DECKS table.
+
+    Returns:
+        Deck cites across the stage's tool entrypoints.
+    """
+    cites = []
+    for entrypoint in stage["entrypoints"]:
+        cites.extend(covering_decks(entrypoint, solvers, operations))
+    return cites
+
+
+def plan_from_capabilities(flow, operations, solvers=None):
+    """Plan a flow against a capabilities report's operations mapping.
+
+    Scripted entrypoints need no backend. A stage whose tool
+    entrypoints all read ready in the report is ready; otherwise it
+    stays required-but-blocked (never silently dropped) and names
+    the blocking entrypoints with their report reason, missing
+    items, and remedy. Entrypoints with no report row block loudly
+    with a no-report reason instead of a tool-blind ready. Every
+    stage also cites its covering decks (WORKFLOW-COVERAGE, ADR-007)
+    so blockers resolve to a deck, a probe-gated deck, or a named
+    gap — the completion report reads the same cites per blocker.
+
+    Args:
+        flow: Flow inventory to plan (digital/analog/photonic/mixed).
+        operations: Per-operation readiness mapping as reported by
+            `report_capabilities` (operation -> readiness plus
+            reason/missing/remedy detail).
+        solvers: Operation -> deck-tool cites (tool plus needs).
+            Defaults to the curated DECKS table.
+
+    Returns:
+        Stage list with per-stage readiness (ready/blocked) plus
+            deck cites; blocked stages also carry blocked_by,
+            reason, missing, and remedy keys.
+
+    Raises:
+        ValueError: Unknown flow name.
+    """
+    try:
+        stages = STAGES[flow]
+    except KeyError:
+        raise ValueError(f"Unknown flow: {flow}.") from None
+    planned = []
+    for stage in stages:
+        needed = [e for e in stage["entrypoints"] if e not in _SCRIPTED]
+        decks = _stage_decks(stage, operations, solvers)
+        blocking = [
+            e for e in needed
+            if operations.get(e, {}).get("readiness") != "ready"
+        ]
+        if not blocking:
+            planned.append({**stage, "readiness": "ready", "decks": decks})
+            continue
+        reasons, missing, remedies = [], [], []
+        for entry in blocking:
+            row = operations.get(entry, {})
+            if entry not in operations:
+                reasons.append(
+                    f"{entry}: no capability report on this machine."
+                )
+                missing.append(entry)
+                continue
+            reasons.append(f"{entry}: {row.get('reason', 'not ready.')}")
+            missing.extend(row.get("missing") or [])
+            remedy = row.get("remedy")
+            if remedy and remedy not in remedies:
+                remedies.append(remedy)
+        planned.append({
+            **stage,
+            "readiness": "blocked",
+            "blocked_by": blocking,
+            "reason": "; ".join(reasons),
+            "missing": sorted(set(missing)),
+            "remedy": " ".join(remedies) if remedies else _FALLBACK_REMEDY,
+            "decks": decks,
+        })
+    return planned

rocket_engine/workflows/completion.py

@@ -0,0 +1,228 @@
+"""Design-completion gate: stage plans plus fully-verified claims (I27).
+
+`plan_checks_report` wires the stage inventory to caller backends so
+required-but-blocked stages surface instead of vanishing; every
+planned stage stays required and reports ready or blocked with its
+missing operations. `design_completion_report` layers the latest
+check verdicts over that plan: any blocked, unverified, or failing
+stage becomes a named blocker (mixed M14 cites run_thermal, and the
+vocab-only run_thermal operation appears as its own blocker), the
+report refuses the fully-verified claim while any stand, and only
+an all-satisfied plan claims with per-operation evidence run ids.
+"""
+
+from .gates import gate_plan_for_target
+from .stages import applicable_stages
+
+# Scripted entrypoints need no backend (mirrors stages._SCRIPTED).
+_SCRIPTED = frozenset({"project scripting", "get_capabilities", "ip_instantiate"})
+
+
+def _tool_ops(stage):
+    """Tool entrypoints one stage needs (scripted entries excluded)."""
+    return [e for e in stage["entrypoints"] if e not in _SCRIPTED]
+
+
+def _missing_ops(stage, available):
+    """Tool entrypoints one stage needs but no backend serves."""
+    return [e for e in _tool_ops(stage) if e not in available]
+
+
+def _check_status(record):
+    """Verdict status for one check record (None when never ran)."""
+    if record is None:
+        return None
+    if not isinstance(record, dict):
+        return "unknown"
+    status = record.get("status")
+    if status is None:
+        verdict = record.get("verdict")
+        if isinstance(verdict, dict):
+            status = verdict.get("status")
+    return status if status is not None else "unknown"
+
+
+def _run_id(record):
+    """String run id for one check record (None when absent)."""
+    if isinstance(record, dict) and isinstance(record.get("run_id"), str):
+        return record["run_id"]
+    return None
+
+
+def plan_checks_report(flow, available_backends, target=None, canvas=None):
+    """Plan one flow against installed backends with named blockers.
+
+    Thin report over `applicable_stages`: every planned stage keeps
+    its required flag and gains its readiness plus the exact missing
+    operations, so a caller can name required-but-blocked stages
+    (mixed M14 cites run_thermal) instead of silently dropping them.
+    With a target (plus an optional canvas) the plan is additionally
+    gated per `gates.gate_plan_for_target`, joining deck tools,
+    canvas settings, and metric budgets to every stage.
+
+    Args:
+        flow: Flow inventory to plan (digital/analog/photonic/mixed).
+        available_backends: Installed backend entrypoint names.
+        target: v1 target the plan serves (kind required); None
+            skips gating and returns the backend-only plan.
+        canvas: Canvas mapping with targets/tools; None means an
+            empty canvas (a canvas without a target refuses).
+
+    Returns:
+        Mapping with the flow, per-stage plans (each carrying
+            readiness plus missing_operations), blocked_stages and
+            ready_stages id lists in stage order, the sorted
+            unique missing_operations across blocked stages, and —
+            when gated — the target/canvas join.
+
+    Raises:
+        ValueError: Unknown flow name, a canvas without a target,
+            or a bad target/canvas shape.
+    """
+    available = set() if available_backends is None else set(available_backends)
+    planned = applicable_stages(flow, available)
+    stages = []
+    for stage in planned:
+        stages.append({**stage, "missing_operations": _missing_ops(stage, available)})
+    blocked = [s["id"] for s in stages if s["readiness"] == "blocked"]
+    ready = [s["id"] for s in stages if s["readiness"] == "ready"]
+    missing = sorted({op for stage in stages for op in stage["missing_operations"]})
+    plan = {
+        "flow": flow,
+        "stages": stages,
+        "blocked_stages": blocked,
+        "ready_stages": ready,
+        "missing_operations": missing,
+    }
+    if target is None and canvas is None:
+        return plan
+    if target is None:
+        raise ValueError("plan_checks canvas needs a target.")
+    return gate_plan_for_target(plan, target, canvas)
+
+
+def design_completion_report(flow, available_backends, checks, current_revision=None):
+    """Judge one flow's completion: blockers stand or evidence claims.
+
+    Combines the stage plan with the latest check verdicts. A stage
+    whose backends are missing blocks as blocked_stage; a ready tool
+    stage whose operation never ran blocks as unverified_stage; a
+    ready stage whose latest verdict is not PASS blocks as
+    failing_check with its run id. Missing operations additionally
+    appear as missing_operation blockers so vocab-only names such as
+    run_thermal never vanish silently. Scripted-only stages need no
+    solver evidence and never block. While any blocker stands the
+    report refuses the claim (fully_verified False, claim None);
+    only a blocker-free plan claims fully verified with evidence.
+
+    Args:
+        flow: Flow inventory to judge (digital/analog/photonic/mixed).
+        available_backends: Installed backend entrypoint names.
+        checks: Mapping of operation to its latest check record
+            (the checks value from Engine.check_results: each with
+            status plus run_id); absent operations read never_run.
+        current_revision: Project revision to echo; None when unknown.
+
+    Returns:
+        Mapping with the flow, fully_verified flag, claim (fully
+            verified) or refusal text, blockers in stage order with
+            missing-operation entries after, sorted unique
+            missing_operations, evidence mapping each PASS operation
+            to its run id, per-stage plans carrying stage_status plus
+            run_ids, and the echoed current_revision.
+
+    Raises:
+        ValueError: Unknown flow name.
+    """
+    available = set() if available_backends is None else set(available_backends)
+    seen = dict(checks) if checks is not None else {}
+    plan = plan_checks_report(flow, available)
+    blockers = []
+    stages_out = []
+    for stage in plan["stages"]:
+        tool_ops = _tool_ops(stage)
+        missing = stage["missing_operations"]
+        if missing:
+            blockers.append(
+                {
+                    "kind": "blocked_stage",
+                    "stage": stage["id"],
+                    "step": stage["step"],
+                    "missing_operations": list(missing),
+                    "required": stage["required"],
+                }
+            )
+            stages_out.append({**stage, "stage_status": "blocked", "run_ids": {}})
+            continue
+        if not tool_ops:
+            stages_out.append({**stage, "stage_status": "verified", "run_ids": {}})
+            continue
+        run_ids = {}
+        failing = []
+        unverified = []
+        for op in tool_ops:
+            record = seen.get(op)
+            if op not in seen:
+                unverified.append(
+                    {
+                        "kind": "unverified_stage",
+                        "stage": stage["id"],
+                        "step": stage["step"],
+                        "operation": op,
+                        "status": "never_run",
+                    }
+                )
+                continue
+            status = _check_status(record)
+            rid = _run_id(record)
+            if rid is not None:
+                run_ids[op] = rid
+            if status == "PASS":
+                continue
+            failing.append(
+                {
+                    "kind": "failing_check",
+                    "stage": stage["id"],
+                    "step": stage["step"],
+                    "operation": op,
+                    "status": status,
+                    "run_id": rid,
+                }
+            )
+        blockers.extend(failing)
+        blockers.extend(unverified)
+        if failing:
+            stage_status = "failing"
+        elif unverified:
+            stage_status = "unverified"
+        else:
+            stage_status = "verified"
+        stages_out.append({**stage, "stage_status": stage_status, "run_ids": run_ids})
+    for op in plan["missing_operations"]:
+        stages_needing = sorted(
+            s["id"] for s in plan["stages"] if op in s["missing_operations"]
+        )
+        blockers.append(
+            {"kind": "missing_operation", "operation": op, "stages": stages_needing}
+        )
+    evidence = {}
+    for op in sorted(available):
+        record = seen.get(op)
+        if _check_status(record) == "PASS":
+            rid = _run_id(record)
+            if rid is not None:
+                evidence[op] = rid
+    fully_verified = not blockers
+    return {
+        "flow": flow,
+        "fully_verified": fully_verified,
+        "claim": "fully verified" if fully_verified else None,
+        "refusal": None
+        if fully_verified
+        else f"{len(blockers)} blocker(s) stand; not fully verified.",
+        "blockers": blockers,
+        "missing_operations": plan["missing_operations"],
+        "evidence": evidence,
+        "stages": stages_out,
+        "current_revision": current_revision,
+    }