"""The Reference's own subject, cloud solution architecture, as a Workflow. The engine's tests run this, to show that what the engine takes from a Workflow is enough for the agent it was built from (ADR-0001). The graph, the data checks and the samples are the Reference's, from its `app/workflows/deliverables.py` and `app/adk/fake_runtime.py`; only their arrangement into one value is new. """ from __future__ import annotations import dataclasses import functools import json from collections.abc import Mapping from execution_engine.adk import fake_runtime from execution_engine.workflows.deliverables import DataCheck, DeliverableSpec from execution_engine.workflows.workflow import ValidationPolicy, Workflow from tests.reference_workflow.assessment import assess from tests.reference_workflow.chain import ( COMPONENTS_FILE, IMPLEMENTATION_FILE, PRODUCTS_FILE, RECOMMENDATIONS_FILE, REQUIREMENTS_FILE, SCOPE_DATA_FILE, SCOPE_FILE, VERDICTS_FILE, check_components, check_implementation, check_products, check_recommendations, check_requirements, check_scope, check_target_architecture, check_verdicts, graph_structure, validation_outcome, ) from tests.reference_workflow.changes import check_requirement_changes from tests.reference_workflow.hooks import ( CARD, CHANGES, COVERAGE_REVIEWER, GRAPH_SHAPE, GUIDE_FILENAME, MODULES_OPTION, PILLAR_ADVISOR, agreed, approval_details, approval_facts, check_ids, consultations, describe_approval, describe_design, known_ids, modules_option, outputs, pillar_hints, prepare_role, summary_lines, task_entries, unimplementable, with_checklist_review, with_graph_views, with_modules_skill, with_plan_views, ) from tests.reference_workflow.kinds import PHASE_ORDER, DeliverableKind, PhaseId from tests.reference_workflow.pillars import KEPT_FOR_CHANGES from tests.reference_workflow.presentation import to_generate_response from tests.reference_workflow.target_architecture import GRAPH_ATTACHMENT from tests.reference_workflow.work_breakdown import ( WORK_BREAKDOWN_FILE, check_work_breakdown, ) ABOUT = ( "I design cloud solution architectures. Tell me, at a high level, what you want " "built, and I will work through requirements, a target architecture, " "infrastructure code, validation and a packaged guide, asking for your approval " "at each Phase. Nothing was started for this message." ) _K = DeliverableKind DEPENDENCY_GRAPH: Mapping[str, DeliverableSpec] = { spec.kind: spec for spec in ( DeliverableSpec( _K.SCOPE, PhaseId.SCOPING, "scope-analyst", sections=("Scope statement",), # The completed scope spec, for people and for reuse; and what every # later Specialist reads of it. attachments=(SCOPE_FILE, SCOPE_DATA_FILE), ), DeliverableSpec( _K.REQUIREMENTS, PhaseId.REQUIREMENTS_DISCOVERY, "requirements-analyst", depends_on=(_K.SCOPE,), sections=( "Functional requirements", "Non-functional requirements", "Current state", "Dependencies", ), attachments=(REQUIREMENTS_FILE,), ), DeliverableSpec( _K.TECHNICAL_DECOMPOSITION, PhaseId.REQUIREMENTS_DISCOVERY, "decomposer", depends_on=(_K.REQUIREMENTS,), sections=("Components",), attachments=(COMPONENTS_FILE,), ), DeliverableSpec( _K.PRODUCT_SELECTION, PhaseId.SOLUTION_ARCHITECTURE, "product-selector", depends_on=(_K.TECHNICAL_DECOMPOSITION,), sections=("Products and features mapping",), attachments=(PRODUCTS_FILE,), ), DeliverableSpec( _K.DESIGN_RECOMMENDATIONS, PhaseId.SOLUTION_ARCHITECTURE, "design-advisor", depends_on=(_K.PRODUCT_SELECTION, _K.REQUIREMENTS), sections=( "Security, privacy, and compliance", "Reliability", "Operational excellence", "Cost optimization", "Performance efficiency", "Sustainability", ), attachments=(RECOMMENDATIONS_FILE,), ), DeliverableSpec( _K.TARGET_ARCHITECTURE, PhaseId.SOLUTION_ARCHITECTURE, "target-architect", depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS), # The Specialist writes the reasoning and the graph. On submission the # engine adds the Elements, Relationships and Checks tables to the content # and architecture.mmd to the attachments, both rendered from the graph. sections=("Design rationale",), attachments=(GRAPH_ATTACHMENT,), graph=GRAPH_SHAPE, ), DeliverableSpec( _K.ARCHITECTURE_DESCRIPTION, PhaseId.SOLUTION_IMPLEMENTATION, "describer", depends_on=(_K.TARGET_ARCHITECTURE,), sections=("Components", "Flow"), # It describes the Elements and how they connect. A Revision that only # adds or rewords Checks leaves it true. written_from=graph_structure, ), DeliverableSpec( _K.DEPLOYMENT_GUIDANCE, PhaseId.SOLUTION_IMPLEMENTATION, "iac-author", depends_on=(_K.TARGET_ARCHITECTURE,), sections=( "Deployment prerequisites", "Step-by-step deployment instructions", ), attachments=( "terraform/main.tf", "terraform/variables.tf", IMPLEMENTATION_FILE, ), # The graph is all the code is written from. reads_in_full=(), not_shown=( _K.REQUIREMENTS, _K.TECHNICAL_DECOMPOSITION, _K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS, ), working_copy=_K.DEPLOYMENT_GUIDANCE, ), DeliverableSpec( _K.VALIDATION_RESULTS, PhaseId.SOLUTION_VALIDATION, "validator", depends_on=(_K.DEPLOYMENT_GUIDANCE,), sections=("Deployment dry-run", "Architecture and policy analysis"), attachments=(VERDICTS_FILE,), # It judges the code against the Checks; the prose describing the # design is not what it judges. not_shown=(_K.ARCHITECTURE_DESCRIPTION,), working_copy=_K.DEPLOYMENT_GUIDANCE, ), DeliverableSpec( _K.WORK_BREAKDOWN, PhaseId.PACKAGING, "delivery-planner", depends_on=(_K.VALIDATION_RESULTS,), sections=("Approach",), attachments=(WORK_BREAKDOWN_FILE,), # A plan covers the design and how it is built: the graph and the code. reads_in_full=(_K.TARGET_ARCHITECTURE, _K.DEPLOYMENT_GUIDANCE), not_shown=( _K.REQUIREMENTS, _K.DESIGN_RECOMMENDATIONS, _K.ARCHITECTURE_DESCRIPTION, ), ), DeliverableSpec( _K.SOLUTION_GUIDE, PhaseId.PACKAGING, "packager", depends_on=(_K.VALIDATION_RESULTS,), sections=( "Executive summary and workload overview", "Requirements and current state", "Technical decomposition of the workload", "Proposed solution architecture", "Design and configuration recommendations", "Deployment guidance", "Validation plan", "References", ), # The guide is assembled from every Deliverable's prose. reads_in_full=tuple(_K)[:-1], ), ) } # What each data file along the Requirements chain must hold, checked at submission. DATA_CHECKS: Mapping[str, tuple[str, DataCheck]] = { _K.SCOPE: (SCOPE_DATA_FILE, check_scope), _K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements), _K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components), _K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products), _K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations), _K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture), _K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation), _K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts), _K.WORK_BREAKDOWN: (WORK_BREAKDOWN_FILE, check_work_breakdown), } # Sections code appends to a Deliverable for the person reading it. A Specialist # working from that Deliverable has the same facts as data, and is not shown them. FOR_READERS: Mapping[str, str] = { _K.DESIGN_RECOMMENDATIONS: "Architecture framework checklist review", } # One small, coherent Requirements chain, so sample submissions pass every link. SAMPLE_DATA: dict[str, str] = { "scope.yaml": "engagement:\n kind: workload\nintent:\n statement: Accept events.\n", "scope.json": json.dumps( { "kind": "workload", "stated": {"intent": {"statement": "Accept events."}}, "to_decide": [], "to_ask": [], "not_applicable": [], } ), "requirements.json": json.dumps( [ {"id": "FR-1", "kind": "functional", "text": "Accept events."}, { "id": "NFR-1", "kind": "non_functional", "text": "99.9% availability.", "conditions": ["The service stays available when one instance fails."], }, ] ), "components.json": json.dumps( [{"id": "C-1", "name": "Ingress", "requirements": ["FR-1", "NFR-1"]}] ), "products.json": json.dumps([{"component": "C-1", "product": "Example Run"}]), "recommendations.json": json.dumps( [ { "id": "DR-1", "pillar": "security", "text": "Use a dedicated identity.", "components": ["C-1"], "conditions": ["The service runs as an identity nothing else uses."], } ] ), "target-architecture.json": json.dumps( { "elements": [ { "id": "E-1", "name": "Ingress service", "component": "C-1", "product": "Example Run", "resource_type": "example_run_service", }, { "id": "E-2", "name": "Ingress identity", "product": "Example IAM", "resource_type": "example_service_account", }, ], "relationships": [ {"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"} ], "checks": [ { "id": "K-1", "applies_to": "E-1", "statement": "The service runs at least two instances.", "source": "NFR-1", }, { "id": "K-2", "applies_to": "E-2", "statement": "The identity is used by this service only.", "source": "DR-1", }, ], } ), "implementation.json": json.dumps( [ {"check": "K-1", "file": "terraform/main.tf", "address": "example.run"}, {"check": "K-2", "file": "terraform/main.tf", "address": "example.sa"}, ] ), "work-breakdown.json": json.dumps( { "work_packages": [ { "id": "WP-1", "name": "Ingress", "parent": None, "elements": ["E-1", "E-2"], "scope": "The service and its identity.", "produces": ["a running service"], "skills": ["platform engineering"], } ], "activities": [ { "id": "A-1", "work_package": "WP-1", "name": "Create the identity", "days": 1, "after": [], }, { "id": "A-2", "work_package": "WP-1", "name": "Deploy the service", "days": 2, "after": ["A-1"], }, ], } ), "verdicts.json": json.dumps( { "dry_run": {"verdict": "pass", "evidence": "terraform validate passed."}, "checks": [ {"check": "K-1", "verdict": "pass", "evidence": "min instances is 2."}, {"check": "K-2", "verdict": "pass", "evidence": "One binding."}, ], "proposed_additions": [], } ), } def _approval_details(phase, deliverables, baseline): return approval_details( phase, deliverables, baseline, in_phase=[ str(kind) for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase == phase ], design_phase=PhaseId.SOLUTION_ARCHITECTURE, ) WORKFLOW = Workflow( name="solution-architecture", about=ABOUT, phases=tuple(PHASE_ORDER), deliverables=DEPENDENCY_GRAPH, final=_K.SOLUTION_GUIDE, data_checks=DATA_CHECKS, baseline_checks={_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirement_changes)}, for_readers=FOR_READERS, spec_deliverable=_K.SCOPE, validation=ValidationPolicy( kind=_K.VALIDATION_RESULTS, data_file=VERDICTS_FILE, implementation=_K.DEPLOYMENT_GUIDANCE, design=_K.TARGET_ARCHITECTURE, read=validation_outcome, check_ids=check_ids, unimplementable=unimplementable, known_ids=known_ids, ), on_submit={ _K.DESIGN_RECOMMENDATIONS: with_checklist_review, _K.WORK_BREAKDOWN: with_plan_views, _K.TARGET_ARCHITECTURE: with_graph_views, }, approval_details=_approval_details, approval_facts=approval_facts, summary_lines=summary_lines, agreed=agreed, changes=CHANGES, subject="a cloud solution architecture", describe_design=describe_design, prepare_role=prepare_role, task_entries=task_entries, task_hints=pillar_hints(), kept_for_changes=tuple(KEPT_FOR_CHANGES), final_file=GUIDE_FILENAME, outputs=outputs, assess=assess, options={MODULES_OPTION: modules_option(available=False, default=False)}, card=CARD, done="The solution architecture is complete and approved.", describe_approval=describe_approval, response=to_generate_response, roles=(PILLAR_ADVISOR,), optional_roles=(COVERAGE_REVIEWER,), adjust_roles=with_modules_skill, samples=SAMPLE_DATA, ) def with_pillars( pillar_skills: Mapping[str, str], workflow: Workflow = WORKFLOW ) -> Workflow: """The Workflow for a provider bundle's pillar Skills: one advisor for each.""" return dataclasses.replace(workflow, role_tools=consultations(pillar_skills)) def with_modules( available: bool, default: bool = False, workflow: Workflow = WORKFLOW ) -> Workflow: """The Workflow for a provider that does, or does not, approve module sources.""" return dataclasses.replace( workflow, options={MODULES_OPTION: modules_option(available, default)} ) # The Reference's tests call these as functions of its one graph. inputs_of = WORKFLOW.inputs_of dependencies_for = WORKFLOW.dependencies_for shown = WORKFLOW.shown deliverables_in = WORKFLOW.deliverables_in check_submission = WORKFLOW.check_submission sample_submission = functools.partial(fake_runtime.sample_submission, WORKFLOW)