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.
Files changed (177) hide show
  1. compiler/VERSION +1 -0
  2. compiler/__init__.py +1 -0
  3. compiler/atoms/__init__.py +54 -0
  4. compiler/atoms/error_codes.py +160 -0
  5. compiler/atoms/errors.py +125 -0
  6. compiler/atoms/fqdn.py +204 -0
  7. compiler/atoms/invariants.py +106 -0
  8. compiler/atoms/phase.py +99 -0
  9. compiler/atoms/pipeline.py +51 -0
  10. compiler/atoms/snapshot_gate.py +51 -0
  11. compiler/atoms/sorting.py +125 -0
  12. compiler/cli.py +637 -0
  13. compiler/diagnostics/__init__.py +6 -0
  14. compiler/diagnostics/determination.py +148 -0
  15. compiler/diagnostics/machine_block_health.py +199 -0
  16. compiler/governance/__init__.py +6 -0
  17. compiler/governance_engine/__init__.py +0 -0
  18. compiler/governance_engine/artifact_kinds.py +221 -0
  19. compiler/governance_engine/assertions/__init__.py +0 -0
  20. compiler/governance_engine/assertions/handlers/__init__.py +200 -0
  21. compiler/governance_engine/assertions/handlers/assert_ac_declaration_well_formed_v0.py +70 -0
  22. compiler/governance_engine/assertions/handlers/assert_actor_authority_separation_v0.py +17 -0
  23. compiler/governance_engine/assertions/handlers/assert_artifact_content_hash_declared_v0.py +60 -0
  24. compiler/governance_engine/assertions/handlers/assert_assert_not_runtime_referenced_v0.py +49 -0
  25. compiler/governance_engine/assertions/handlers/assert_assert_parity_v0.py +169 -0
  26. compiler/governance_engine/assertions/handlers/assert_atom_output_purity_v0.py +186 -0
  27. compiler/governance_engine/assertions/handlers/assert_authority_constituted_v0.py +56 -0
  28. compiler/governance_engine/assertions/handlers/assert_authority_required_for_execution_v0.py +16 -0
  29. compiler/governance_engine/assertions/handlers/assert_authority_state_well_formed_v0.py +17 -0
  30. compiler/governance_engine/assertions/handlers/assert_binding_integrity_v0.py +64 -0
  31. compiler/governance_engine/assertions/handlers/assert_binding_surface_closed_v0.py +92 -0
  32. compiler/governance_engine/assertions/handlers/assert_cc_capability_binding_valid_v0.py +85 -0
  33. compiler/governance_engine/assertions/handlers/assert_cc_inputs_satisfied_v0.py +89 -0
  34. compiler/governance_engine/assertions/handlers/assert_cc_no_implicit_chaining_v0.py +89 -0
  35. compiler/governance_engine/assertions/handlers/assert_cc_no_missing_dependencies_v0.py +89 -0
  36. compiler/governance_engine/assertions/handlers/assert_cc_no_unused_outputs_v0.py +81 -0
  37. compiler/governance_engine/assertions/handlers/assert_cc_storage_op_conformance_v0.py +74 -0
  38. compiler/governance_engine/assertions/handlers/assert_compiler_governance_declared_v0.py +65 -0
  39. compiler/governance_engine/assertions/handlers/assert_compiler_no_execution_v0.py +86 -0
  40. compiler/governance_engine/assertions/handlers/assert_concern_not_authority_v0.py +51 -0
  41. compiler/governance_engine/assertions/handlers/assert_conformance_assertion_mode_valid_v0.py +35 -0
  42. compiler/governance_engine/assertions/handlers/assert_cryptographic_trust_declared_v0.py +51 -0
  43. compiler/governance_engine/assertions/handlers/assert_cs_isolated_execution_v0.py +35 -0
  44. compiler/governance_engine/assertions/handlers/assert_cs_surface_closed_v0.py +241 -0
  45. compiler/governance_engine/assertions/handlers/assert_cs_traceable_v0.py +35 -0
  46. compiler/governance_engine/assertions/handlers/assert_ct_output_contract_match_v0.py +167 -0
  47. compiler/governance_engine/assertions/handlers/assert_ct_surface_closed_v0.py +173 -0
  48. compiler/governance_engine/assertions/handlers/assert_ct_surface_derived_closed_v0.py +108 -0
  49. compiler/governance_engine/assertions/handlers/assert_ct_test_data_outcome_declared_v0.py +112 -0
  50. compiler/governance_engine/assertions/handlers/assert_ev_append_only_v0.py +70 -0
  51. compiler/governance_engine/assertions/handlers/assert_ev_schema_required_v0.py +59 -0
  52. compiler/governance_engine/assertions/handlers/assert_execution_placement_declared_v0.py +51 -0
  53. compiler/governance_engine/assertions/handlers/assert_execution_scheduling_declared_v0.py +51 -0
  54. compiler/governance_engine/assertions/handlers/assert_fqdn_namespace_authorized_v0.py +38 -0
  55. compiler/governance_engine/assertions/handlers/assert_fqdn_only_references_v0.py +89 -0
  56. compiler/governance_engine/assertions/handlers/assert_governance_declaration_resolves_v0.py +126 -0
  57. compiler/governance_engine/assertions/handlers/assert_handler_registry_closed_v0.py +75 -0
  58. compiler/governance_engine/assertions/handlers/assert_identity_authority_separation_v0.py +19 -0
  59. compiler/governance_engine/assertions/handlers/assert_identity_fqdn_consistency.py +75 -0
  60. compiler/governance_engine/assertions/handlers/assert_implementation_admissible_v0.py +66 -0
  61. compiler/governance_engine/assertions/handlers/assert_in_no_execution_logic_v0.py +82 -0
  62. compiler/governance_engine/assertions/handlers/assert_in_schema_required_v0.py +74 -0
  63. compiler/governance_engine/assertions/handlers/assert_in_workflow_binding_v0.py +101 -0
  64. compiler/governance_engine/assertions/handlers/assert_inspection_capability_read_only_v0.py +114 -0
  65. compiler/governance_engine/assertions/handlers/assert_no_ambient_authority_v0.py +17 -0
  66. compiler/governance_engine/assertions/handlers/assert_no_runtime_authorization_v0.py +18 -0
  67. compiler/governance_engine/assertions/handlers/assert_no_runtime_topology_synthesis_v0.py +18 -0
  68. compiler/governance_engine/assertions/handlers/assert_no_smart_execution_v0.py +102 -0
  69. compiler/governance_engine/assertions/handlers/assert_no_undeclared_behavior_surface_v0.py +52 -0
  70. compiler/governance_engine/assertions/handlers/assert_no_workflow_authorization_logic_v0.py +18 -0
  71. compiler/governance_engine/assertions/handlers/assert_protocol_surface_closed_v0.py +119 -0
  72. compiler/governance_engine/assertions/handlers/assert_rb_binding_policy_conformance_v0.py +124 -0
  73. compiler/governance_engine/assertions/handlers/assert_rb_cs_only_v0.py +68 -0
  74. compiler/governance_engine/assertions/handlers/assert_rb_no_logic_v0.py +81 -0
  75. compiler/governance_engine/assertions/handlers/assert_rb_parameters_declared_v0.py +117 -0
  76. compiler/governance_engine/assertions/handlers/assert_rb_storage_subdomain_owned_v0.py +118 -0
  77. compiler/governance_engine/assertions/handlers/assert_runtime_invariant_wired_v0.py +163 -0
  78. compiler/governance_engine/assertions/handlers/assert_schema_conformance_v0.py +64 -0
  79. compiler/governance_engine/assertions/handlers/assert_schema_description_well_formed_v0.py +97 -0
  80. compiler/governance_engine/assertions/handlers/assert_security_domain_declared_v0.py +51 -0
  81. compiler/governance_engine/assertions/handlers/assert_structure_paths_well_formed_v0.py +118 -0
  82. compiler/governance_engine/assertions/handlers/assert_superseded_not_referenced_v0.py +134 -0
  83. compiler/governance_engine/assertions/handlers/assert_test_data_match_ct_output_v0.py +134 -0
  84. compiler/governance_engine/assertions/handlers/assert_topology_acyclic_v0.py +53 -0
  85. compiler/governance_engine/assertions/handlers/assert_topology_authority_orthogonal_v0.py +110 -0
  86. compiler/governance_engine/assertions/handlers/assert_topology_capability_reference_unique_v0.py +63 -0
  87. compiler/governance_engine/assertions/handlers/assert_topology_contract_closed_v0.py +113 -0
  88. compiler/governance_engine/assertions/handlers/assert_topology_immutable_after_compilation_v0.py +17 -0
  89. compiler/governance_engine/assertions/handlers/assert_topology_input_reference_declared_v0.py +112 -0
  90. compiler/governance_engine/assertions/handlers/assert_topology_routing_complete_v0.py +82 -0
  91. compiler/governance_engine/assertions/handlers/assert_topology_step_declared_v0.py +77 -0
  92. compiler/governance_engine/assertions/handlers/assert_topology_step_id_unique_v0.py +60 -0
  93. compiler/governance_engine/assertions/handlers/assert_topology_surface_canonical_v0.py +180 -0
  94. compiler/governance_engine/assertions/handlers/assert_topology_transport_orthogonal_v0.py +113 -0
  95. compiler/governance_engine/assertions/handlers/assert_trace_authority_binding_required_v0.py +18 -0
  96. compiler/governance_engine/assertions/handlers/assert_transport_canonical_normalization_v0.py +83 -0
  97. compiler/governance_engine/assertions/handlers/assert_transport_no_dynamic_routing_v0.py +93 -0
  98. compiler/governance_engine/assertions/handlers/assert_transport_no_workflow_semantics_v0.py +106 -0
  99. compiler/governance_engine/assertions/handlers/assert_transport_operation_identity_independence_v0.py +56 -0
  100. compiler/governance_engine/assertions/handlers/assert_transport_response_projection_external_v0.py +38 -0
  101. compiler/governance_engine/assertions/handlers/assert_transport_result_class_protocol_independence_v0.py +48 -0
  102. compiler/governance_engine/assertions/handlers/assert_transport_target_exists_v0.py +132 -0
  103. compiler/governance_engine/assertions/handlers/assert_unique_artifact_id_v0.py +58 -0
  104. compiler/governance_engine/assertions/handlers/assert_vocabulary_symbols_well_formed_v0.py +163 -0
  105. compiler/governance_engine/assertions/handlers/assert_wf_announcement_distinct_v0.py +85 -0
  106. compiler/governance_engine/assertions/handlers/assert_wf_cc_only_nodes_v0.py +60 -0
  107. compiler/governance_engine/assertions/handlers/assert_wf_entry_intent_v0.py +68 -0
  108. compiler/governance_engine/assertions/handlers/assert_wf_execution_path_valid_v0.py +89 -0
  109. compiler/governance_engine/assertions/handlers/assert_wf_node_key_binding_unique_v0.py +107 -0
  110. compiler/governance_engine/platform_root.py +102 -0
  111. compiler/governance_engine/structure/__init__.py +56 -0
  112. compiler/governance_engine/structure/discovery/__init__.py +28 -0
  113. compiler/governance_engine/structure/discovery/artifact_locator.py +210 -0
  114. compiler/governance_engine/structure/exceptions.py +113 -0
  115. compiler/governance_engine/structure/loading/__init__.py +88 -0
  116. compiler/governance_engine/structure/loading/fs_reader.py +225 -0
  117. compiler/governance_engine/structure/loading/markdown_parser.py +148 -0
  118. compiler/governance_engine/structure/loading/protocol_loader.py +587 -0
  119. compiler/governance_engine/structure/loading/test_case_provider.py +125 -0
  120. compiler/governance_engine/structure/loading/trace_reader.py +98 -0
  121. compiler/governance_engine/structure/loading/vocabulary_loader.py +174 -0
  122. compiler/governance_engine/structure/loading/yaml_parser.py +209 -0
  123. compiler/governance_engine/structure/resolution/__init__.py +22 -0
  124. compiler/governance_engine/structure/resolution/domain_resolver.py +124 -0
  125. compiler/governance_engine/structure/resolution/layer_resolver.py +572 -0
  126. compiler/governance_engine/structure/resolution/path_registry.py +1054 -0
  127. compiler/graph/__init__.py +38 -0
  128. compiler/graph/addressing.py +153 -0
  129. compiler/graph/edge.py +100 -0
  130. compiler/graph/evidence.py +637 -0
  131. compiler/graph/graph.py +269 -0
  132. compiler/graph/hashing.py +89 -0
  133. compiler/graph/node.py +134 -0
  134. compiler/graph/query.py +215 -0
  135. compiler/graph/state.py +237 -0
  136. compiler/graph/trace.py +97 -0
  137. compiler/graph/types.py +71 -0
  138. compiler/projections/__init__.py +207 -0
  139. compiler/projections/artifact_index.py +225 -0
  140. compiler/projections/canonical.py +173 -0
  141. compiler/projections/dispatch.py +532 -0
  142. compiler/projections/evidence.py +170 -0
  143. compiler/projections/handlers.py +224 -0
  144. compiler/projections/ipm.py +388 -0
  145. compiler/projections/reverse.py +165 -0
  146. compiler/projections/tokenized.py +135 -0
  147. compiler/projections/vocabulary.py +108 -0
  148. compiler/stages/__init__.py +28 -0
  149. compiler/stages/s1_extract.py +867 -0
  150. compiler/stages/s2_canonicalize.py +516 -0
  151. compiler/stages/s3_semantic_addressing.py +66 -0
  152. compiler/stages/s4_govern.py +754 -0
  153. compiler/stages/s5_construct.py +537 -0
  154. compiler/stages/s6_project.py +94 -0
  155. compiler/stages/s7_materialize.py +1170 -0
  156. compiler/stages/s8_verify.py +643 -0
  157. compiler/stages/s9_attest.py +184 -0
  158. compiler/structure_loader.py +132 -0
  159. compiler/visualization/__init__.py +12 -0
  160. compiler/visualization/consumers/__init__.py +28 -0
  161. compiler/visualization/consumers/evidence_projection.py +162 -0
  162. compiler/visualization/consumers/evidence_query.py +296 -0
  163. compiler/visualization/consumers/evidence_reader.py +127 -0
  164. compiler/visualization/views/__init__.py +70 -0
  165. compiler/visualization/views/_png_writer.py +45 -0
  166. compiler/visualization/views/artifact_lineage.py +180 -0
  167. compiler/visualization/views/family_view.py +164 -0
  168. compiler/visualization/views/materialization_view.py +150 -0
  169. compiler/visualization/views/structural_dag.py +158 -0
  170. compiler/visualization/wf_graph_generator.py +534 -0
  171. pgc_compiler-2.0.0.dist-info/METADATA +203 -0
  172. pgc_compiler-2.0.0.dist-info/RECORD +177 -0
  173. pgc_compiler-2.0.0.dist-info/WHEEL +5 -0
  174. pgc_compiler-2.0.0.dist-info/entry_points.txt +2 -0
  175. pgc_compiler-2.0.0.dist-info/licenses/LICENSE +67 -0
  176. pgc_compiler-2.0.0.dist-info/licenses/NOTICE +11 -0
  177. 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)