3.8 KiB
#region VerificationProgram.Contract [C:5] [TYPE ADR] [SEMANTICS verification-program,ir,sql,evidence,transform,assertion,agent-evaluation] @BRIEF Canonical immutable IR compiled by the authoring agent and deterministically executed by 044. @RELATION DEPENDS_ON -> [DashboardScenarioModel.DataModel] @RELATION BINDS_TO -> [ScenarioExecution.DataModel] @RATIONALE A scenario is a verification program, not merely a browser-click DAG: business checks often require source-mart evidence, deterministic transformations and explicit semantic evaluation. @REJECTED Runtime SQL/code generation or rewrite — rejected because it destroys reproducibility, security review and content-addressed revision identity.
Program shape
VerificationProgram { navigation_program, evidence_program, transformation_program, assertion_program, semantic_evaluation_program } is required executable content of DashboardTestScenario and is included, canonically, in content_hash and every step_content_hash that references it. Programs use only declared refs and version-pinned action/DSL/prompt registries.
SqlEvidenceSpec
SqlEvidenceSpec { snippet_id, logical_step_id, connection_ref, database_identity, sql_template, sql_hash, parameter_definitions[], expected_output_schema, relation_refs[], execution_limits, generation_provenance, validation_result } is a small, read-only source-evidence query. It is authored only during creation, edit, migration/revalidation or investigation proposal; runtime executes exactly the pinned sql_template through the Superset SQL Lab adapter with typed ParameterBinding substitution. It cannot add WHERE/JOIN/projection/relation text, mutate SQL, or accept credentials from an agent/client.
TransformSpec and ComparisonSpec
TransformSpec is a bounded, versioned DSL — select|filter|rename|cast|join|group_by|sum|count|distinct|coalesce|normalize_string|normalize_date|difference|ratio|tolerance_compare — over declared evidence refs. No Python, shell, SQL or arbitrary code is permitted.
ComparisonSpec / AssertionSpec declares numeric equality/tolerance, row/column/set equality, aggregate checks, field mappings, null/fill checks and cross-dashboard comparisons. Its expected values are evidence/baseline/typed-control refs, never runtime prose.
AgentEvaluationSpec and DecisionPolicy
AgentEvaluationSpec { spec_id, logical_step_id, provider_id, model_id, prompt_template_id, prompt_template_version, prompt_template_hash, input_manifest, evidence_refs, tool_allowlist, output_schema, decision_policy_id } is permitted only for semantic/visual/ambiguous checks that cannot reasonably compile to SqlEvidenceSpec + TransformSpec + AssertionSpec. It has bounded declared evidence/tool access and no mutation authority.
DecisionPolicy { policy_id, version, deterministic_hard_failure, high_confidence_failure, low_confidence, disagreement, missing_evidence } deterministically maps evidence plus a typed AgentEvaluation to StepOutcome. A bare model verdict is never ScenarioResult authority.
SQL compilation gate
Before a SqlEvidenceSpec can be saved, compiler validation MUST parse its AST; require one SELECT/WITH statement; prohibit DDL/DML, mutation SETTINGS, unsafe/external/file functions; enforce connection/relation/schema allowlists, typed binds, timeout/row/byte/complexity limits, expected-output schema, and bounded preview/test execution. Exploratory authoring SQL is a separate bounded policy class and must be minimized to the columns/filters actually used before persistence.
Runtime boundary
044 orchestration stays deterministic. It may dispatch an explicitly declared AgentEvaluationSpec, but that step cannot change the ScenarioGraph, SQL/DSL, run lifecycle, executor order or mutations. Bad runtime evidence becomes a finding → 043 proposal → validated new revision → later run.
#endregion VerificationProgram.Contract