pgc-compiler 2.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- compiler/VERSION +1 -0
- compiler/__init__.py +1 -0
- compiler/atoms/__init__.py +54 -0
- compiler/atoms/error_codes.py +160 -0
- compiler/atoms/errors.py +125 -0
- compiler/atoms/fqdn.py +204 -0
- compiler/atoms/invariants.py +106 -0
- compiler/atoms/phase.py +99 -0
- compiler/atoms/pipeline.py +51 -0
- compiler/atoms/snapshot_gate.py +51 -0
- compiler/atoms/sorting.py +125 -0
- compiler/cli.py +637 -0
- compiler/diagnostics/__init__.py +6 -0
- compiler/diagnostics/determination.py +148 -0
- compiler/diagnostics/machine_block_health.py +199 -0
- compiler/governance/__init__.py +6 -0
- compiler/governance_engine/__init__.py +0 -0
- compiler/governance_engine/artifact_kinds.py +221 -0
- compiler/governance_engine/assertions/__init__.py +0 -0
- compiler/governance_engine/assertions/handlers/__init__.py +200 -0
- compiler/governance_engine/assertions/handlers/assert_ac_declaration_well_formed_v0.py +70 -0
- compiler/governance_engine/assertions/handlers/assert_actor_authority_separation_v0.py +17 -0
- compiler/governance_engine/assertions/handlers/assert_artifact_content_hash_declared_v0.py +60 -0
- compiler/governance_engine/assertions/handlers/assert_assert_not_runtime_referenced_v0.py +49 -0
- compiler/governance_engine/assertions/handlers/assert_assert_parity_v0.py +169 -0
- compiler/governance_engine/assertions/handlers/assert_atom_output_purity_v0.py +186 -0
- compiler/governance_engine/assertions/handlers/assert_authority_constituted_v0.py +56 -0
- compiler/governance_engine/assertions/handlers/assert_authority_required_for_execution_v0.py +16 -0
- compiler/governance_engine/assertions/handlers/assert_authority_state_well_formed_v0.py +17 -0
- compiler/governance_engine/assertions/handlers/assert_binding_integrity_v0.py +64 -0
- compiler/governance_engine/assertions/handlers/assert_binding_surface_closed_v0.py +92 -0
- compiler/governance_engine/assertions/handlers/assert_cc_capability_binding_valid_v0.py +85 -0
- compiler/governance_engine/assertions/handlers/assert_cc_inputs_satisfied_v0.py +89 -0
- compiler/governance_engine/assertions/handlers/assert_cc_no_implicit_chaining_v0.py +89 -0
- compiler/governance_engine/assertions/handlers/assert_cc_no_missing_dependencies_v0.py +89 -0
- compiler/governance_engine/assertions/handlers/assert_cc_no_unused_outputs_v0.py +81 -0
- compiler/governance_engine/assertions/handlers/assert_cc_storage_op_conformance_v0.py +74 -0
- compiler/governance_engine/assertions/handlers/assert_compiler_governance_declared_v0.py +65 -0
- compiler/governance_engine/assertions/handlers/assert_compiler_no_execution_v0.py +86 -0
- compiler/governance_engine/assertions/handlers/assert_concern_not_authority_v0.py +51 -0
- compiler/governance_engine/assertions/handlers/assert_conformance_assertion_mode_valid_v0.py +35 -0
- compiler/governance_engine/assertions/handlers/assert_cryptographic_trust_declared_v0.py +51 -0
- compiler/governance_engine/assertions/handlers/assert_cs_isolated_execution_v0.py +35 -0
- compiler/governance_engine/assertions/handlers/assert_cs_surface_closed_v0.py +241 -0
- compiler/governance_engine/assertions/handlers/assert_cs_traceable_v0.py +35 -0
- compiler/governance_engine/assertions/handlers/assert_ct_output_contract_match_v0.py +167 -0
- compiler/governance_engine/assertions/handlers/assert_ct_surface_closed_v0.py +173 -0
- compiler/governance_engine/assertions/handlers/assert_ct_surface_derived_closed_v0.py +108 -0
- compiler/governance_engine/assertions/handlers/assert_ct_test_data_outcome_declared_v0.py +112 -0
- compiler/governance_engine/assertions/handlers/assert_ev_append_only_v0.py +70 -0
- compiler/governance_engine/assertions/handlers/assert_ev_schema_required_v0.py +59 -0
- compiler/governance_engine/assertions/handlers/assert_execution_placement_declared_v0.py +51 -0
- compiler/governance_engine/assertions/handlers/assert_execution_scheduling_declared_v0.py +51 -0
- compiler/governance_engine/assertions/handlers/assert_fqdn_namespace_authorized_v0.py +38 -0
- compiler/governance_engine/assertions/handlers/assert_fqdn_only_references_v0.py +89 -0
- compiler/governance_engine/assertions/handlers/assert_governance_declaration_resolves_v0.py +126 -0
- compiler/governance_engine/assertions/handlers/assert_handler_registry_closed_v0.py +75 -0
- compiler/governance_engine/assertions/handlers/assert_identity_authority_separation_v0.py +19 -0
- compiler/governance_engine/assertions/handlers/assert_identity_fqdn_consistency.py +75 -0
- compiler/governance_engine/assertions/handlers/assert_implementation_admissible_v0.py +66 -0
- compiler/governance_engine/assertions/handlers/assert_in_no_execution_logic_v0.py +82 -0
- compiler/governance_engine/assertions/handlers/assert_in_schema_required_v0.py +74 -0
- compiler/governance_engine/assertions/handlers/assert_in_workflow_binding_v0.py +101 -0
- compiler/governance_engine/assertions/handlers/assert_inspection_capability_read_only_v0.py +114 -0
- compiler/governance_engine/assertions/handlers/assert_no_ambient_authority_v0.py +17 -0
- compiler/governance_engine/assertions/handlers/assert_no_runtime_authorization_v0.py +18 -0
- compiler/governance_engine/assertions/handlers/assert_no_runtime_topology_synthesis_v0.py +18 -0
- compiler/governance_engine/assertions/handlers/assert_no_smart_execution_v0.py +102 -0
- compiler/governance_engine/assertions/handlers/assert_no_undeclared_behavior_surface_v0.py +52 -0
- compiler/governance_engine/assertions/handlers/assert_no_workflow_authorization_logic_v0.py +18 -0
- compiler/governance_engine/assertions/handlers/assert_protocol_surface_closed_v0.py +119 -0
- compiler/governance_engine/assertions/handlers/assert_rb_binding_policy_conformance_v0.py +124 -0
- compiler/governance_engine/assertions/handlers/assert_rb_cs_only_v0.py +68 -0
- compiler/governance_engine/assertions/handlers/assert_rb_no_logic_v0.py +81 -0
- compiler/governance_engine/assertions/handlers/assert_rb_parameters_declared_v0.py +117 -0
- compiler/governance_engine/assertions/handlers/assert_rb_storage_subdomain_owned_v0.py +118 -0
- compiler/governance_engine/assertions/handlers/assert_runtime_invariant_wired_v0.py +163 -0
- compiler/governance_engine/assertions/handlers/assert_schema_conformance_v0.py +64 -0
- compiler/governance_engine/assertions/handlers/assert_schema_description_well_formed_v0.py +97 -0
- compiler/governance_engine/assertions/handlers/assert_security_domain_declared_v0.py +51 -0
- compiler/governance_engine/assertions/handlers/assert_structure_paths_well_formed_v0.py +118 -0
- compiler/governance_engine/assertions/handlers/assert_superseded_not_referenced_v0.py +134 -0
- compiler/governance_engine/assertions/handlers/assert_test_data_match_ct_output_v0.py +134 -0
- compiler/governance_engine/assertions/handlers/assert_topology_acyclic_v0.py +53 -0
- compiler/governance_engine/assertions/handlers/assert_topology_authority_orthogonal_v0.py +110 -0
- compiler/governance_engine/assertions/handlers/assert_topology_capability_reference_unique_v0.py +63 -0
- compiler/governance_engine/assertions/handlers/assert_topology_contract_closed_v0.py +113 -0
- compiler/governance_engine/assertions/handlers/assert_topology_immutable_after_compilation_v0.py +17 -0
- compiler/governance_engine/assertions/handlers/assert_topology_input_reference_declared_v0.py +112 -0
- compiler/governance_engine/assertions/handlers/assert_topology_routing_complete_v0.py +82 -0
- compiler/governance_engine/assertions/handlers/assert_topology_step_declared_v0.py +77 -0
- compiler/governance_engine/assertions/handlers/assert_topology_step_id_unique_v0.py +60 -0
- compiler/governance_engine/assertions/handlers/assert_topology_surface_canonical_v0.py +180 -0
- compiler/governance_engine/assertions/handlers/assert_topology_transport_orthogonal_v0.py +113 -0
- compiler/governance_engine/assertions/handlers/assert_trace_authority_binding_required_v0.py +18 -0
- compiler/governance_engine/assertions/handlers/assert_transport_canonical_normalization_v0.py +83 -0
- compiler/governance_engine/assertions/handlers/assert_transport_no_dynamic_routing_v0.py +93 -0
- compiler/governance_engine/assertions/handlers/assert_transport_no_workflow_semantics_v0.py +106 -0
- compiler/governance_engine/assertions/handlers/assert_transport_operation_identity_independence_v0.py +56 -0
- compiler/governance_engine/assertions/handlers/assert_transport_response_projection_external_v0.py +38 -0
- compiler/governance_engine/assertions/handlers/assert_transport_result_class_protocol_independence_v0.py +48 -0
- compiler/governance_engine/assertions/handlers/assert_transport_target_exists_v0.py +132 -0
- compiler/governance_engine/assertions/handlers/assert_unique_artifact_id_v0.py +58 -0
- compiler/governance_engine/assertions/handlers/assert_vocabulary_symbols_well_formed_v0.py +163 -0
- compiler/governance_engine/assertions/handlers/assert_wf_announcement_distinct_v0.py +85 -0
- compiler/governance_engine/assertions/handlers/assert_wf_cc_only_nodes_v0.py +60 -0
- compiler/governance_engine/assertions/handlers/assert_wf_entry_intent_v0.py +68 -0
- compiler/governance_engine/assertions/handlers/assert_wf_execution_path_valid_v0.py +89 -0
- compiler/governance_engine/assertions/handlers/assert_wf_node_key_binding_unique_v0.py +107 -0
- compiler/governance_engine/platform_root.py +102 -0
- compiler/governance_engine/structure/__init__.py +56 -0
- compiler/governance_engine/structure/discovery/__init__.py +28 -0
- compiler/governance_engine/structure/discovery/artifact_locator.py +210 -0
- compiler/governance_engine/structure/exceptions.py +113 -0
- compiler/governance_engine/structure/loading/__init__.py +88 -0
- compiler/governance_engine/structure/loading/fs_reader.py +225 -0
- compiler/governance_engine/structure/loading/markdown_parser.py +148 -0
- compiler/governance_engine/structure/loading/protocol_loader.py +587 -0
- compiler/governance_engine/structure/loading/test_case_provider.py +125 -0
- compiler/governance_engine/structure/loading/trace_reader.py +98 -0
- compiler/governance_engine/structure/loading/vocabulary_loader.py +174 -0
- compiler/governance_engine/structure/loading/yaml_parser.py +209 -0
- compiler/governance_engine/structure/resolution/__init__.py +22 -0
- compiler/governance_engine/structure/resolution/domain_resolver.py +124 -0
- compiler/governance_engine/structure/resolution/layer_resolver.py +572 -0
- compiler/governance_engine/structure/resolution/path_registry.py +1054 -0
- compiler/graph/__init__.py +38 -0
- compiler/graph/addressing.py +153 -0
- compiler/graph/edge.py +100 -0
- compiler/graph/evidence.py +637 -0
- compiler/graph/graph.py +269 -0
- compiler/graph/hashing.py +89 -0
- compiler/graph/node.py +134 -0
- compiler/graph/query.py +215 -0
- compiler/graph/state.py +237 -0
- compiler/graph/trace.py +97 -0
- compiler/graph/types.py +71 -0
- compiler/projections/__init__.py +207 -0
- compiler/projections/artifact_index.py +225 -0
- compiler/projections/canonical.py +173 -0
- compiler/projections/dispatch.py +532 -0
- compiler/projections/evidence.py +170 -0
- compiler/projections/handlers.py +224 -0
- compiler/projections/ipm.py +388 -0
- compiler/projections/reverse.py +165 -0
- compiler/projections/tokenized.py +135 -0
- compiler/projections/vocabulary.py +108 -0
- compiler/stages/__init__.py +28 -0
- compiler/stages/s1_extract.py +867 -0
- compiler/stages/s2_canonicalize.py +516 -0
- compiler/stages/s3_semantic_addressing.py +66 -0
- compiler/stages/s4_govern.py +754 -0
- compiler/stages/s5_construct.py +537 -0
- compiler/stages/s6_project.py +94 -0
- compiler/stages/s7_materialize.py +1170 -0
- compiler/stages/s8_verify.py +643 -0
- compiler/stages/s9_attest.py +184 -0
- compiler/structure_loader.py +132 -0
- compiler/visualization/__init__.py +12 -0
- compiler/visualization/consumers/__init__.py +28 -0
- compiler/visualization/consumers/evidence_projection.py +162 -0
- compiler/visualization/consumers/evidence_query.py +296 -0
- compiler/visualization/consumers/evidence_reader.py +127 -0
- compiler/visualization/views/__init__.py +70 -0
- compiler/visualization/views/_png_writer.py +45 -0
- compiler/visualization/views/artifact_lineage.py +180 -0
- compiler/visualization/views/family_view.py +164 -0
- compiler/visualization/views/materialization_view.py +150 -0
- compiler/visualization/views/structural_dag.py +158 -0
- compiler/visualization/wf_graph_generator.py +534 -0
- pgc_compiler-2.0.0.dist-info/METADATA +203 -0
- pgc_compiler-2.0.0.dist-info/RECORD +177 -0
- pgc_compiler-2.0.0.dist-info/WHEEL +5 -0
- pgc_compiler-2.0.0.dist-info/entry_points.txt +2 -0
- pgc_compiler-2.0.0.dist-info/licenses/LICENSE +67 -0
- pgc_compiler-2.0.0.dist-info/licenses/NOTICE +11 -0
- pgc_compiler-2.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,534 @@
|
|
|
1
|
+
"""
|
|
2
|
+
wf_graph_generator.py — Workflow Graph Generation
|
|
3
|
+
|
|
4
|
+
Generates first-class graph artifacts from compiled workflows:
|
|
5
|
+
- JSON: Machine-readable execution graph
|
|
6
|
+
- PNG: Visual diagram (if graphviz available)
|
|
7
|
+
- Markdown: Human-readable summary
|
|
8
|
+
|
|
9
|
+
Governed by: STRUCTURE_BUILD_PLATFORM_CONFIG_V0
|
|
10
|
+
|
|
11
|
+
This is NOT debug-only output - graphs are first-class compiled artifacts
|
|
12
|
+
used for:
|
|
13
|
+
- Runtime trace correlation
|
|
14
|
+
- Workflow debugging
|
|
15
|
+
- Documentation generation
|
|
16
|
+
- IDE integration
|
|
17
|
+
|
|
18
|
+
**COMPILER-OWNED**: Self-sufficient graph construction, no external dependencies.
|
|
19
|
+
This is COMPILE-TIME graph generation (static WF structure).
|
|
20
|
+
Runtime trace visualization is separate (lives in pgs_tooling/visualization).
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
import json
|
|
24
|
+
import subprocess
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any, Dict, List, Optional
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class WorkflowGraphGenerator:
|
|
30
|
+
"""
|
|
31
|
+
Generates execution graph artifacts from compiled workflows.
|
|
32
|
+
|
|
33
|
+
Responsibilities:
|
|
34
|
+
- Extract execution graph from WF node structure
|
|
35
|
+
- Generate JSON graph artifact
|
|
36
|
+
- Generate PNG visualization (if graphviz available)
|
|
37
|
+
- Generate Markdown summary
|
|
38
|
+
- Store in compiled/artifacts/workflow_graphs/
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
def __init__(self, output_root: Path):
|
|
42
|
+
"""
|
|
43
|
+
Initialize graph generator.
|
|
44
|
+
|
|
45
|
+
Args:
|
|
46
|
+
output_root: Root directory for graph artifacts
|
|
47
|
+
(e.g., .../compiled/artifacts/workflow_graphs/)
|
|
48
|
+
"""
|
|
49
|
+
self.output_root = output_root
|
|
50
|
+
|
|
51
|
+
def generate(self, wf_artifact: Dict[str, Any], cc_artifacts: Dict[str, Any]) -> Dict[str, Any]:
|
|
52
|
+
"""
|
|
53
|
+
Generate compile-time graph artifacts for a workflow.
|
|
54
|
+
|
|
55
|
+
Persisted artifacts (two only):
|
|
56
|
+
- {wf_code}.graph.json — machine-readable DAG, CC nodes carry projection data
|
|
57
|
+
- {wf_code}.projection.png — visual DAG with CT/CS leaf nodes (best-effort)
|
|
58
|
+
|
|
59
|
+
All other views (wf_only PNG, markdown) are derivable on demand from the JSON.
|
|
60
|
+
|
|
61
|
+
Args:
|
|
62
|
+
wf_artifact: Compiled workflow artifact
|
|
63
|
+
cc_artifacts: Map of CC code → compiled CC artifact (for capability lookup)
|
|
64
|
+
|
|
65
|
+
Returns:
|
|
66
|
+
{
|
|
67
|
+
"wf_code": str,
|
|
68
|
+
"json_path": Path | None,
|
|
69
|
+
"projection_png_path": Path | None,
|
|
70
|
+
"status": "SUCCESS" | "PARTIAL" | "FAILED",
|
|
71
|
+
"errors": list[str]
|
|
72
|
+
}
|
|
73
|
+
"""
|
|
74
|
+
errors = []
|
|
75
|
+
|
|
76
|
+
# Extract WF code
|
|
77
|
+
wf_code = wf_artifact.get("artifact_code")
|
|
78
|
+
if not wf_code:
|
|
79
|
+
return {
|
|
80
|
+
"wf_code": "UNKNOWN",
|
|
81
|
+
"status": "FAILED",
|
|
82
|
+
"errors": ["Missing artifact_code on WF artifact"]
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
# Build graph model (CC nodes carry projection data)
|
|
86
|
+
try:
|
|
87
|
+
graph = self._build_graph_model(wf_artifact, cc_artifacts)
|
|
88
|
+
except Exception as e:
|
|
89
|
+
return {
|
|
90
|
+
"wf_code": wf_code,
|
|
91
|
+
"status": "FAILED",
|
|
92
|
+
"errors": [f"Failed to build graph model: {e}"]
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
# Create output directory
|
|
96
|
+
wf_dir = self.output_root / wf_code
|
|
97
|
+
wf_dir.mkdir(parents=True, exist_ok=True)
|
|
98
|
+
|
|
99
|
+
# Artifact 1: JSON with projection data embedded in CC nodes
|
|
100
|
+
json_path = wf_dir / f"{wf_code}.graph.json"
|
|
101
|
+
try:
|
|
102
|
+
self._generate_json(graph, json_path)
|
|
103
|
+
except Exception as e:
|
|
104
|
+
errors.append(f"Failed to generate JSON: {e}")
|
|
105
|
+
|
|
106
|
+
# Artifact 2: projection PNG (best-effort)
|
|
107
|
+
projection_png_path = None
|
|
108
|
+
try:
|
|
109
|
+
projection_png_path = self._generate_png(
|
|
110
|
+
graph, wf_dir / f"{wf_code}.projection.png", dag_view="wf_cc_projection"
|
|
111
|
+
)
|
|
112
|
+
except Exception as e:
|
|
113
|
+
errors.append(f"Projection PNG generation skipped: {e}")
|
|
114
|
+
|
|
115
|
+
# Determine status
|
|
116
|
+
if errors:
|
|
117
|
+
status = "PARTIAL" if json_path.exists() else "FAILED"
|
|
118
|
+
else:
|
|
119
|
+
status = "SUCCESS"
|
|
120
|
+
|
|
121
|
+
return {
|
|
122
|
+
"wf_code": wf_code,
|
|
123
|
+
"json_path": json_path if json_path.exists() else None,
|
|
124
|
+
"projection_png_path": projection_png_path,
|
|
125
|
+
"status": status,
|
|
126
|
+
"errors": errors
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
def _build_graph_model(self, wf_artifact: Dict[str, Any], cc_artifacts: Dict[str, Any]) -> Dict[str, Any]:
|
|
130
|
+
"""
|
|
131
|
+
Build graph model from WF node structure.
|
|
132
|
+
|
|
133
|
+
COMPILER-OWNED: Direct graph construction from WF nodes specification.
|
|
134
|
+
|
|
135
|
+
Args:
|
|
136
|
+
wf_artifact: Compiled workflow artifact
|
|
137
|
+
cc_artifacts: Map of CC code → CC artifact
|
|
138
|
+
|
|
139
|
+
Returns:
|
|
140
|
+
{
|
|
141
|
+
"wf_id": str,
|
|
142
|
+
"entry": str,
|
|
143
|
+
"nodes": list[dict],
|
|
144
|
+
"edges": list[dict],
|
|
145
|
+
"execution_paths": list[list[str]]
|
|
146
|
+
}
|
|
147
|
+
"""
|
|
148
|
+
wf_code = wf_artifact.get("artifact_code")
|
|
149
|
+
|
|
150
|
+
return self._build_graph(wf_artifact, cc_artifacts, wf_code)
|
|
151
|
+
|
|
152
|
+
def _build_graph(self, wf_artifact: Dict[str, Any],
|
|
153
|
+
cc_artifacts: Dict[str, Any],
|
|
154
|
+
wf_code: str) -> Dict[str, Any]:
|
|
155
|
+
"""
|
|
156
|
+
Build execution graph from WF node structure.
|
|
157
|
+
|
|
158
|
+
Extracts nodes, edges, and execution paths from WF specification.
|
|
159
|
+
Enriches CC nodes with capability binding information.
|
|
160
|
+
|
|
161
|
+
Args:
|
|
162
|
+
wf_artifact: Compiled workflow artifact
|
|
163
|
+
cc_artifacts: Map of CC code → CC artifact
|
|
164
|
+
wf_code: Workflow code
|
|
165
|
+
|
|
166
|
+
Returns:
|
|
167
|
+
Graph model dict
|
|
168
|
+
"""
|
|
169
|
+
frontmatter = wf_artifact.get("frontmatter", {})
|
|
170
|
+
core = frontmatter.get("core", {})
|
|
171
|
+
|
|
172
|
+
start_node = core.get("start_node")
|
|
173
|
+
nodes_spec = core.get("nodes", {})
|
|
174
|
+
|
|
175
|
+
# Build node list with capability bindings
|
|
176
|
+
nodes = []
|
|
177
|
+
for node_id, node_spec in nodes_spec.items():
|
|
178
|
+
node_type = node_spec.get("type")
|
|
179
|
+
|
|
180
|
+
node = {
|
|
181
|
+
"id": node_id,
|
|
182
|
+
"type": node_type
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
# For CC nodes, resolve capability binding and projection
|
|
186
|
+
if node_type == "CC":
|
|
187
|
+
cc_code = node_spec.get("code")
|
|
188
|
+
if cc_code:
|
|
189
|
+
node["cc_code"] = cc_code
|
|
190
|
+
|
|
191
|
+
# Look up CC artifact to find capability binding
|
|
192
|
+
cc_artifact = cc_artifacts.get(cc_code, {})
|
|
193
|
+
cc_frontmatter = cc_artifact.get("frontmatter", {})
|
|
194
|
+
cc_core = cc_frontmatter.get("core", {})
|
|
195
|
+
pipeline = cc_core.get("pipeline", [])
|
|
196
|
+
|
|
197
|
+
# Extract first capability binding (for node label)
|
|
198
|
+
if pipeline and len(pipeline) > 0:
|
|
199
|
+
first_step = pipeline[0]
|
|
200
|
+
capability_fqdn = first_step.get("transform") or first_step.get("side_effect")
|
|
201
|
+
if capability_fqdn:
|
|
202
|
+
node["capability"] = capability_fqdn
|
|
203
|
+
# Determine type
|
|
204
|
+
if "::CT_" in capability_fqdn or capability_fqdn.startswith("CT_"):
|
|
205
|
+
node["capability_type"] = "CT"
|
|
206
|
+
elif "::CS_" in capability_fqdn or capability_fqdn.startswith("CS_"):
|
|
207
|
+
node["capability_type"] = "CS"
|
|
208
|
+
|
|
209
|
+
# Attach full CT/CS projection (compile-time extracted in materialize phase)
|
|
210
|
+
cc_projection = cc_artifact.get("cc_projection")
|
|
211
|
+
if cc_projection:
|
|
212
|
+
node["projection"] = cc_projection
|
|
213
|
+
|
|
214
|
+
# Attach WF-level input bindings — surfaces data-flow into this node
|
|
215
|
+
# alongside routing edges, making binding bugs visible without opening CC artifacts.
|
|
216
|
+
# Bindings are normalized to structural references (IN.*, NODE.*) — raw DSL
|
|
217
|
+
# syntax ($.payload, $.results) is authoring-layer detail, not graph-layer truth.
|
|
218
|
+
wf_inputs = node_spec.get("inputs")
|
|
219
|
+
if wf_inputs:
|
|
220
|
+
node["input_bindings"] = {
|
|
221
|
+
"type": "wf_boundary",
|
|
222
|
+
"bindings": {k: self._normalize_binding(v) for k, v in wf_inputs.items()},
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
nodes.append(node)
|
|
226
|
+
|
|
227
|
+
# Build edge list from node transitions
|
|
228
|
+
edges = []
|
|
229
|
+
for node_id, node_spec in nodes_spec.items():
|
|
230
|
+
next_transitions = node_spec.get("next", {})
|
|
231
|
+
for condition, target_id in next_transitions.items():
|
|
232
|
+
edges.append({
|
|
233
|
+
"from": node_id,
|
|
234
|
+
"to": target_id,
|
|
235
|
+
"condition": condition
|
|
236
|
+
})
|
|
237
|
+
|
|
238
|
+
# Extract all execution paths (DFS from start_node)
|
|
239
|
+
paths = self._extract_paths(start_node, nodes_spec)
|
|
240
|
+
|
|
241
|
+
return {
|
|
242
|
+
"wf_id": wf_code,
|
|
243
|
+
"entry": start_node,
|
|
244
|
+
"nodes": nodes,
|
|
245
|
+
"edges": edges,
|
|
246
|
+
"execution_paths": paths
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
@staticmethod
|
|
250
|
+
def _normalize_binding(value: Any) -> str:
|
|
251
|
+
"""
|
|
252
|
+
Normalize a raw WF DSL binding expression to a structural reference.
|
|
253
|
+
|
|
254
|
+
Rules (authoring DSL → graph layer):
|
|
255
|
+
$.payload.<field> → IN.<field>
|
|
256
|
+
$.results.<NODE>.<field> → <NODE>.<field>
|
|
257
|
+
<literal> (no $ prefix) → unchanged (constant)
|
|
258
|
+
|
|
259
|
+
The graph layer must not expose DSL syntax — only structural lineage.
|
|
260
|
+
"""
|
|
261
|
+
if not isinstance(value, str):
|
|
262
|
+
return value # Non-string constants (booleans, ints) pass through
|
|
263
|
+
if value.startswith("$.payload."):
|
|
264
|
+
return "IN." + value[len("$.payload."):]
|
|
265
|
+
if value.startswith("$.results."):
|
|
266
|
+
return value[len("$.results."):]
|
|
267
|
+
# Literal constant (e.g. "UNAUTHORIZED_TOOL", "AREQ") — no transformation
|
|
268
|
+
return value
|
|
269
|
+
|
|
270
|
+
def _extract_paths(self, start_node: str, nodes_spec: Dict[str, Any]) -> List[List[str]]:
|
|
271
|
+
"""
|
|
272
|
+
Extract all execution paths from start_node to EXIT nodes.
|
|
273
|
+
|
|
274
|
+
Args:
|
|
275
|
+
start_node: Entry node ID
|
|
276
|
+
nodes_spec: WF nodes specification
|
|
277
|
+
|
|
278
|
+
Returns:
|
|
279
|
+
List of paths (each path is list of node IDs)
|
|
280
|
+
"""
|
|
281
|
+
paths = []
|
|
282
|
+
visited = set()
|
|
283
|
+
|
|
284
|
+
def dfs(node_id: str, path: List[str]):
|
|
285
|
+
# Detect cycles
|
|
286
|
+
if node_id in visited:
|
|
287
|
+
return
|
|
288
|
+
|
|
289
|
+
visited.add(node_id)
|
|
290
|
+
path = path + [node_id]
|
|
291
|
+
|
|
292
|
+
node_spec = nodes_spec.get(node_id, {})
|
|
293
|
+
node_type = node_spec.get("type")
|
|
294
|
+
|
|
295
|
+
# Terminal node
|
|
296
|
+
if node_type == "EXIT" or not node_spec.get("next"):
|
|
297
|
+
paths.append(path)
|
|
298
|
+
visited.remove(node_id)
|
|
299
|
+
return
|
|
300
|
+
|
|
301
|
+
# Traverse next nodes
|
|
302
|
+
next_transitions = node_spec.get("next", {})
|
|
303
|
+
for condition, target_id in next_transitions.items():
|
|
304
|
+
dfs(target_id, path)
|
|
305
|
+
|
|
306
|
+
visited.remove(node_id)
|
|
307
|
+
|
|
308
|
+
dfs(start_node, [])
|
|
309
|
+
return paths
|
|
310
|
+
|
|
311
|
+
def _generate_json(self, graph: Dict[str, Any], output_path: Path):
|
|
312
|
+
"""
|
|
313
|
+
Generate JSON graph artifact.
|
|
314
|
+
|
|
315
|
+
Args:
|
|
316
|
+
graph: Graph model
|
|
317
|
+
output_path: Output file path
|
|
318
|
+
"""
|
|
319
|
+
with open(output_path, "w") as f:
|
|
320
|
+
json.dump(graph, f, indent=2)
|
|
321
|
+
|
|
322
|
+
def _generate_png(self, graph: Dict[str, Any], output_path: Path, dag_view: str = "wf_only") -> Optional[Path]:
|
|
323
|
+
"""
|
|
324
|
+
Generate PNG visualization using graphviz.
|
|
325
|
+
|
|
326
|
+
Args:
|
|
327
|
+
graph: Graph model
|
|
328
|
+
output_path: Output file path
|
|
329
|
+
dag_view: "wf_only" or "wf_cc_projection"
|
|
330
|
+
|
|
331
|
+
Returns:
|
|
332
|
+
Path to PNG file if successful, None otherwise
|
|
333
|
+
"""
|
|
334
|
+
# Check if graphviz is available
|
|
335
|
+
try:
|
|
336
|
+
subprocess.run(["dot", "-V"], capture_output=True, check=True)
|
|
337
|
+
except (subprocess.CalledProcessError, FileNotFoundError):
|
|
338
|
+
raise RuntimeError("Graphviz not available (PNG generation skipped)")
|
|
339
|
+
|
|
340
|
+
# Generate DOT file
|
|
341
|
+
dot_content = self._generate_dot(graph, dag_view=dag_view)
|
|
342
|
+
dot_path = output_path.with_suffix(".dot")
|
|
343
|
+
|
|
344
|
+
with open(dot_path, "w") as f:
|
|
345
|
+
f.write(dot_content)
|
|
346
|
+
|
|
347
|
+
# Render to PNG
|
|
348
|
+
try:
|
|
349
|
+
subprocess.run(
|
|
350
|
+
["dot", "-Tpng", str(dot_path), "-o", str(output_path)],
|
|
351
|
+
check=True,
|
|
352
|
+
capture_output=True
|
|
353
|
+
)
|
|
354
|
+
dot_path.unlink() # Clean up DOT file
|
|
355
|
+
return output_path
|
|
356
|
+
except subprocess.CalledProcessError as e:
|
|
357
|
+
raise RuntimeError(f"Graphviz rendering failed: {e.stderr.decode()}")
|
|
358
|
+
|
|
359
|
+
def _generate_dot(self, graph: Dict[str, Any], dag_view: str = "wf_only") -> str:
|
|
360
|
+
"""
|
|
361
|
+
Generate Graphviz DOT format from graph model.
|
|
362
|
+
|
|
363
|
+
Args:
|
|
364
|
+
graph: Graph model
|
|
365
|
+
dag_view: "wf_only" or "wf_cc_projection"
|
|
366
|
+
|
|
367
|
+
Returns:
|
|
368
|
+
DOT format string
|
|
369
|
+
"""
|
|
370
|
+
lines = [
|
|
371
|
+
f'digraph "{graph["wf_id"]}" {{',
|
|
372
|
+
' rankdir=LR;',
|
|
373
|
+
' node [fontname="Arial"];',
|
|
374
|
+
''
|
|
375
|
+
]
|
|
376
|
+
|
|
377
|
+
# Define WF nodes
|
|
378
|
+
for node in graph["nodes"]:
|
|
379
|
+
node_id = node["id"]
|
|
380
|
+
node_type = node["type"]
|
|
381
|
+
|
|
382
|
+
# Style by type
|
|
383
|
+
if node_type == "IN":
|
|
384
|
+
shape = "ellipse"
|
|
385
|
+
color = "lightblue"
|
|
386
|
+
elif node_type == "CC":
|
|
387
|
+
shape = "box"
|
|
388
|
+
color = "lightgreen"
|
|
389
|
+
elif node_type == "EXIT":
|
|
390
|
+
shape = "ellipse"
|
|
391
|
+
color = "lightcoral"
|
|
392
|
+
else:
|
|
393
|
+
shape = "box"
|
|
394
|
+
color = "white"
|
|
395
|
+
|
|
396
|
+
# Add capability label for CC nodes
|
|
397
|
+
label = node_id
|
|
398
|
+
if node_type == "CC" and "capability" in node:
|
|
399
|
+
cap_type = node.get("capability_type", "?")
|
|
400
|
+
label = f"{node_id}\\n({cap_type})"
|
|
401
|
+
|
|
402
|
+
lines.append(f' "{node_id}" [label="{label}", shape={shape}, style=filled, fillcolor={color}];')
|
|
403
|
+
|
|
404
|
+
lines.append('')
|
|
405
|
+
|
|
406
|
+
# In projection mode: add CT/CS leaf nodes under each CC
|
|
407
|
+
# Each node shows: declared inputs/outputs (signatures) + binding overlay
|
|
408
|
+
# Granularity = CT/CS artifact boundary, never internal atom steps
|
|
409
|
+
if dag_view == "wf_cc_projection":
|
|
410
|
+
for node in graph["nodes"]:
|
|
411
|
+
if node["type"] != "CC":
|
|
412
|
+
continue
|
|
413
|
+
projection = node.get("projection", {})
|
|
414
|
+
cc_id = node["id"]
|
|
415
|
+
|
|
416
|
+
for step in projection.get("steps", []):
|
|
417
|
+
kind = step["kind"]
|
|
418
|
+
code = step["id"]
|
|
419
|
+
# Unique DOT node id (collision-safe across multiple CCs)
|
|
420
|
+
dot_id = f"{cc_id}__{kind}__{code}"
|
|
421
|
+
|
|
422
|
+
# PNG = minimal cognition: name + kind tag only
|
|
423
|
+
# Full signatures and bindings live in graph.json
|
|
424
|
+
color = "lightyellow" if kind == "CT" else "lightcyan"
|
|
425
|
+
label = f"{code}\\n({kind})"
|
|
426
|
+
|
|
427
|
+
lines.append(
|
|
428
|
+
f' "{dot_id}" [label="{label}", shape=box, style="filled,dashed",'
|
|
429
|
+
f' fillcolor={color}, fontsize=8];'
|
|
430
|
+
)
|
|
431
|
+
lines.append(f' "{cc_id}" -> "{dot_id}" [style=dotted, arrowhead=open];')
|
|
432
|
+
|
|
433
|
+
lines.append('')
|
|
434
|
+
|
|
435
|
+
# Define WF edges
|
|
436
|
+
for edge in graph["edges"]:
|
|
437
|
+
from_id = edge["from"]
|
|
438
|
+
to_id = edge["to"]
|
|
439
|
+
condition = edge["condition"]
|
|
440
|
+
|
|
441
|
+
lines.append(f' "{from_id}" -> "{to_id}" [label="{condition}"];')
|
|
442
|
+
|
|
443
|
+
lines.append('}')
|
|
444
|
+
|
|
445
|
+
return '\n'.join(lines)
|
|
446
|
+
|
|
447
|
+
def _generate_markdown(self, graph: Dict[str, Any], output_path: Path, dag_view: str = "wf_only"):
|
|
448
|
+
"""
|
|
449
|
+
Generate Markdown summary of execution graph.
|
|
450
|
+
|
|
451
|
+
Args:
|
|
452
|
+
graph: Graph model
|
|
453
|
+
output_path: Output file path
|
|
454
|
+
dag_view: "wf_only" or "wf_cc_projection"
|
|
455
|
+
"""
|
|
456
|
+
view_label = "CC Projection View" if dag_view == "wf_cc_projection" else "Execution Graph"
|
|
457
|
+
lines = [
|
|
458
|
+
f"# {graph['wf_id']} {view_label}",
|
|
459
|
+
"",
|
|
460
|
+
f"**Entry**: {graph['entry']}",
|
|
461
|
+
"",
|
|
462
|
+
"## Nodes",
|
|
463
|
+
""
|
|
464
|
+
]
|
|
465
|
+
|
|
466
|
+
# List nodes
|
|
467
|
+
for node in graph["nodes"]:
|
|
468
|
+
node_id = node["id"]
|
|
469
|
+
node_type = node["type"]
|
|
470
|
+
|
|
471
|
+
line = f"- `{node_id}` ({node_type})"
|
|
472
|
+
|
|
473
|
+
if node_type == "CC" and "capability" in node:
|
|
474
|
+
capability = node["capability"]
|
|
475
|
+
cap_type = node.get("capability_type", "?")
|
|
476
|
+
line += f" → {capability} ({cap_type})"
|
|
477
|
+
|
|
478
|
+
lines.append(line)
|
|
479
|
+
|
|
480
|
+
# In projection mode: show CT/CS with signatures and bindings under each CC
|
|
481
|
+
if dag_view == "wf_cc_projection" and node_type == "CC":
|
|
482
|
+
projection = node.get("projection", {})
|
|
483
|
+
for step in projection.get("steps", []):
|
|
484
|
+
kind = step["kind"]
|
|
485
|
+
code = step["id"]
|
|
486
|
+
if kind == "CT":
|
|
487
|
+
inputs = step.get("inputs", [])
|
|
488
|
+
outputs = step.get("outputs", [])
|
|
489
|
+
bindings = step.get("bindings", {})
|
|
490
|
+
in_str = ", ".join(inputs) + (" ..." if step.get("inputs_truncated") else "")
|
|
491
|
+
out_str = ", ".join(outputs) + (" ..." if step.get("outputs_truncated") else "")
|
|
492
|
+
lines.append(f" - `{code}` (CT)")
|
|
493
|
+
if in_str:
|
|
494
|
+
lines.append(f" - in: {in_str}")
|
|
495
|
+
if out_str:
|
|
496
|
+
lines.append(f" - out: {out_str}")
|
|
497
|
+
for k, v in bindings.items():
|
|
498
|
+
lines.append(f" - {k} <- {v}")
|
|
499
|
+
else: # CS
|
|
500
|
+
ops = step.get("ops", [])
|
|
501
|
+
ops_str = ", ".join(ops) + (" ..." if step.get("ops_truncated") else "")
|
|
502
|
+
lines.append(f" - `{code}` (CS)")
|
|
503
|
+
if ops_str:
|
|
504
|
+
lines.append(f" - ops: {ops_str}")
|
|
505
|
+
|
|
506
|
+
lines.extend(["", "## Execution Paths", ""])
|
|
507
|
+
|
|
508
|
+
# List paths
|
|
509
|
+
for idx, path in enumerate(graph["execution_paths"], 1):
|
|
510
|
+
path_str = " → ".join(path)
|
|
511
|
+
lines.append(f"{idx}. {path_str}")
|
|
512
|
+
|
|
513
|
+
lines.append("")
|
|
514
|
+
|
|
515
|
+
with open(output_path, "w") as f:
|
|
516
|
+
f.write('\n'.join(lines))
|
|
517
|
+
|
|
518
|
+
|
|
519
|
+
def generate_workflow_graph(wf_artifact: Dict[str, Any],
|
|
520
|
+
cc_artifacts: Dict[str, Any],
|
|
521
|
+
output_root: Path) -> Dict[str, Any]:
|
|
522
|
+
"""
|
|
523
|
+
Generate workflow graph artifacts.
|
|
524
|
+
|
|
525
|
+
Args:
|
|
526
|
+
wf_artifact: Compiled workflow artifact
|
|
527
|
+
cc_artifacts: Map of CC code → CC artifact
|
|
528
|
+
output_root: Root directory for graph artifacts
|
|
529
|
+
|
|
530
|
+
Returns:
|
|
531
|
+
Generation result dict
|
|
532
|
+
"""
|
|
533
|
+
generator = WorkflowGraphGenerator(output_root)
|
|
534
|
+
return generator.generate(wf_artifact, cc_artifacts)
|