12 KiB
12 KiB
#region DashboardScenarioModel.Modules [C:5] [TYPE ADR] [SEMANTICS contracts,scenario,graph,validator,compiler] @BRIEF C3+ contracts for checklist mapping, deterministic graph compilation, validation, resolution, serialization, and safe draft packs. Runtime capture/VLM/disposition are OWNED by 044 — this module defines VlmAnalysisSpec and the compiler/validator boundary only. @RATIONALE The scenario graph is the reviewable intermediate boundary between agent intent and generated artifacts; it centralizes safety, determinism, and capability coverage. @REJECTED Direct agent-to-script generation — rejected because missing refs, unsafe actions, and baseline truth would be discovered only after artifact generation or runtime. @REJECTED 038 owning runtime execution (capture/VLM/disposition/artifacts) — moved to 044; 038 is the clean IR/compiler layer, 044 is the single execution owner. @RELATION DEPENDS_ON -> [DashboardScenarioModel.DataModel] @RELATION DEPENDS_ON -> [DashboardScenarioModel.ChecklistCatalog] @RELATION DEPENDS_ON -> [SupersetBaselineEngine.Modules] @RELATION DEPENDS_ON -> [ScenarioExecution.Modules]
#region ScenarioGraph.Api [C:4] [TYPE Module] [SEMANTICS scenario,api,compile,validate]
@defgroup ScenarioGraph REST surface for compile, validate, resolve, and draft-pack operations.
@LAYER API
@RELATION DEPENDS_ON -> [ScenarioGraph.Compiler]
@RELATION DEPENDS_ON -> [ScenarioGraph.Validator]
@RELATION DEPENDS_ON -> [ScenarioGraph.Resolver]
@RELATION DEPENDS_ON -> [ScenarioGraph.PackCompiler]
@RATIONALE A thin REST surface exposes the deterministic scenario operations to 039 and agent tools without leaking compiler internals.
@REJECTED Exposing raw Pydantic models over the API — request schemas must forbid arbitrary code/unsafe paths and require SqlEvidenceSpec compilation.
@INVARIANT Request schemas permit only validated immutable SqlEvidenceSpec; executable code, raw baseline values and local paths are forbidden.
#endregion ScenarioGraph.Api
#region ScenarioGraph.Catalog.Load [C:4] [TYPE Function] [SEMANTICS scenario,checklist,catalog,version]
@ingroup ScenarioGraph
@BRIEF Load the versioned 19-case declarative catalog and validate ids/capability/template references.
@PRE Bundled catalog version is supported.
@POST Returns exactly B01–B09, C01–C07, T01–T03 in stable order.
@SIDE_EFFECT Bounded package-resource read.
@DATA_CONTRACT CatalogResource -> ChecklistCase[19]
@INVARIANT Historic PDF outcomes are source notes, not expected values.
@RATIONALE Versioned declarative catalog keeps the 19 PDF cases reusable and auditable across dashboards.
@REJECTED Embedding the checklist as Python conditionals — mixed intent/data makes coverage unverifiable.
@TEST_EDGE missing_case -> startup/catalog validation failure.
@TEST_EDGE source-mart evidence case -> validated SqlEvidenceSpec or needs_context; unsafe SQL -> rejected.
#endregion ScenarioGraph.Catalog.Load
#region ScenarioGraph.CapabilityMapper.Map [C:5] [TYPE Function] [SEMANTICS scenario,capability,mapping,coverage]
@ingroup ScenarioGraph
@BRIEF Classify every checklist case for a dashboard and select one allowed step template.
@PRE Query model, baseline summary, and capability registry validate.
@POST Every catalog case is automated, human_checkpoint, unsupported, or needs_context with rationale.
@SIDE_EFFECT None.
@DATA_CONTRACT ChecklistCase[] + DashboardCapabilities -> CapabilityMapping[]
@RATIONALE Capability mapping keeps checklist intent reusable while allowing each dashboard to receive only safe, applicable step templates.
@REJECTED One-size-fits-all scripts and user-facing low-level tool selection — rejected because capabilities, safety, and available evidence vary per dashboard.
@INVARIANT No case is dropped and no tool is selected outside its registered capabilities.
@TEST_EDGE xlsx_unavailable -> C04–C06 manual/unsupported with rationale.
@TEST_EDGE technical_without_dataset_fields -> human checkpoint, no SQL.
#endregion ScenarioGraph.CapabilityMapper.Map
#region ScenarioGraph.Compiler.Compile [C:5] [TYPE Function] [SEMANTICS scenario,compiler,deterministic,dag]
@ingroup ScenarioGraph
@BRIEF Compile canonical inputs and mappings into a stable dashboard-specific DAG.
@PRE Intent, query model, catalog, baseline summary, and parameters have valid fingerprints; provenance passed separately (no mandatory agent_run_id).
@POST Same canonical inputs/compiler version yield byte-identical graph and stable keys/order; emits scenario_key + content_hash (NO scenario_id/revision_id).
@SIDE_EFFECT None.
@DATA_CONTRACT CompileInput (scenario_key basis + ChangeRequestContext + objective + query model + checklist + ParameterDefinitions + capabilities + baselines) + CompileProvenance -> DashboardTestScenario (scenario_key + content_hash + VerificationProgram)
@INVARIANT Steps consume only context/parameter/baseline/earlier-step refs; initial graph creation mints logical_step_id and edits/migrations carry it forward.
@TEST_INVARIANT Deterministic_Graph -> VERIFIED_BY: repeated_compile, shuffled_input_order.
@TEST_EDGE missing_selector -> NEEDS_SELECTOR step and save blocker.
@TEST_EDGE missing_baseline -> NEEDS_BASELINE; no embedded numeric truth.
@RATIONALE Rule/template compilation makes the agent a planner/explainer, not an executable-code generator.
@REJECTED LLM-generated ids/dependencies/code — non-deterministic and unsafe.
@REJECTED Compiler emitting scenario_id/revision_id — identity is assigned by 042 at persistence.
#endregion ScenarioGraph.Compiler.Compile
#region ScenarioGraph.Validator.Validate [C:5] [TYPE Function] [SEMANTICS scenario,validator,graph,safety]
@ingroup ScenarioGraph
@BRIEF Return complete deterministic findings for schema, DAG, refs, parameters, baselines, tools, safety, and coverage.
@PRE Candidate graph parses against supported schema version.
@POST Valid is true only with zero errors/blockers; findings are stably ordered and actionable.
@SIDE_EFFECT None.
@DATA_CONTRACT DashboardTestScenario -> ScenarioValidationResult
@RATIONALE Validation is a hard safety boundary between agent-produced intent and artifact generation; deterministic findings give the user a recoverable explanation instead of a runtime surprise.
@REJECTED Silent graph repair or best-effort artifact generation — rejected because auto-fixing refs, cycles, or unsafe actions can change business intent without review.
@INVARIANT Cycles, missing/duplicate refs, unregistered tools/actions, arbitrary or unsafe SQL, raw metric truth and path traversal block compilation. SqlEvidenceSpec passes only its AST/policy/preview compilation gate.
@TEST_EDGE cycle -> error contains cycle path.
@TEST_EDGE duplicate_output -> both producer ids reported.
@TEST_EDGE raw_metric_expected -> forbidden baseline literal error.
@TEST_EDGE unreachable_step -> warning/error according to required coverage.
#endregion ScenarioGraph.Validator.Validate
#region ScenarioGraph.Resolver.Resolve [C:4] [TYPE Function] [SEMANTICS scenario,resolve,parameter,revision]
@ingroup ScenarioGraph
@BRIEF Apply typed ParameterDefinition/selector/manual resolutions and emit a new compiled definition (content_hash changes; identity unchanged).
@PRE Base content_hash matches; changes target declared unresolved items.
@POST Unrelated step keys/order remain unchanged; new content_hash links to base content_hash; logical_step_id stable.
@SIDE_EFFECT None.
@SIDE_EFFECT Logging (REASON/REFLECT markers required around emission).
@RATIONALE Immutable content hashes preserve auditability and byte-stable determinism for downstream pack compilation.
@REJECTED In-place graph mutation — destroys content-hash lineage.
@DATA_CONTRACT ResolveRequest + BaseScenario -> DashboardTestScenario (new content_hash)
@TEST_EDGE stale_base_content_hash -> 409.
@TEST_EDGE invalid_parameter_type -> 422.
@TEST_EDGE unrelated_graph_change -> invariant failure.
#endregion ScenarioGraph.Resolver.Resolve
#region ScenarioGraph.Serializer.Canonical [C:4] [TYPE Function] [SEMANTICS scenario,serialize,json,yaml]
@ingroup ScenarioGraph
@BRIEF Serialize graph to canonical JSON/YAML and compute content_hash.
@POST Key/order/decimal/date/newline rules are stable across runs; JSON and YAML represent equal domain data; content_hash excludes volatile fields.
@SIDE_EFFECT None.
@SIDE_EFFECT Logging (REASON marker before canonicalization; REFLECT with hash after).
@RATIONALE Canonical serialization is the content-identity boundary; volatile display fields must never enter the hash.
@REJECTED Pretty-printed human-first serialization — non-deterministic key ordering breaks byte-stable snapshots.
@DATA_CONTRACT DashboardTestScenario -> CanonicalBytes + content_hash
@TEST_EDGE shuffled_dicts -> identical bytes.
@TEST_EDGE timestamp_display_field -> excluded from content identity.
#endregion ScenarioGraph.Serializer.Canonical
#region ScenarioGraph.PackCompiler.Generate [C:5] [TYPE Function] [SEMANTICS scenario,artifact,template,draft]
@ingroup ScenarioGraph
@BRIEF Generate a preview-only or save-eligible draft pack using registered versioned templates.
@PRE Scenario validation result available; template ids registered; target paths safe.
@POST Outputs match ArtifactPlan, contain no LLM executable bodies, and are registered as 036 drafts.
@SIDE_EFFECT Renders bounded templates and calls AgentRuns.Artifacts.Register.
@DATA_CONTRACT DashboardTestScenario + ValidationResult -> DraftPack (authoring-only; runtime evidence is Artifact(owner_type=scenario_run) under 044, NOT DraftPack)
@INVARIANT Errors/unresolved required inputs make pack preview_only; direct code/path input is impossible.
@TEST_INVARIANT No_LLM_To_Code -> VERIFIED_BY: injected_code_field, template_registry_only.
@TEST_EDGE unknown_template -> blocked.
@TEST_EDGE path_traversal -> blocked before artifact registration.
@RATIONALE Versioned templates make generated behavior reviewable and reproducible.
@REJECTED Generate arbitrary Playwright/Python code then scan it — scanners cannot prove semantic safety.
@REJECTED Runtime evidence produced under 044 being classified as an authoring DraftArtifact — execution artifacts use owner_type=scenario_run.
#endregion ScenarioGraph.PackCompiler.Generate
#region ScenarioGraph.Capture.MovedTo044 [C:3] [TYPE Tombstone] [SEMANTICS scenario,capture,ownership]
@ingroup ScenarioGraph
@DEPRECATED Runtime capture execution is owned by 044 ScenarioExecution (CaptureService over
Plugin.Service.ScreenshotService, artifacts owner_type=scenario_run).
@REPLACED_BY -> [ScenarioExecution.Capture]
@BRIEF 038 defines ScreenshotCaptureSpec (WHAT); it does NOT own capture execution or its artifacts.
#endregion ScenarioGraph.Capture.MovedTo044
#region ScenarioGraph.Vlm.MovedTo044 [C:3] [TYPE Tombstone] [SEMANTICS scenario,vlm,ownership]
@ingroup ScenarioGraph
@DEPRECATED Runtime VLM submission + VlmFinding is owned by 044 ScenarioExecution (reuses
Plugin.Service.LLMClient via Services.LlmProvider.LLMProviderService).
@REPLACED_BY -> [ScenarioExecution.Vlm]
@BRIEF 038 defines VlmAnalysisSpec (WHAT to analyze); runtime VlmFinding/HumanCheckpointDisposition are 044.
#endregion ScenarioGraph.Vlm.MovedTo044
#region ScenarioGraph.Human.MovedTo044 [C:3] [TYPE Tombstone] [SEMANTICS scenario,human,ownership]
@ingroup ScenarioGraph
@DEPRECATED Human checkpoint disposition is owned by 044 as HumanCheckpoint (confirm | false_positive | inconclusive),
distinct from 036 ActionApprovalGate.
@REPLACED_BY -> [ScenarioExecution.HumanCheckpoint]
#endregion ScenarioGraph.Human.MovedTo044
#region AgentChat.Tools.ScenarioGraph [C:4] [TYPE Module] [SEMANTICS scenario,agent,tools,compiler]
@defgroup ScenarioGraph Thin agent tools that submit bounded intent and display compiler/validator results.
@RELATION DEPENDS_ON -> [ScenarioGraph.Api]
@RATIONALE Agent tools stay thin: the agent explains intent, the deterministic compiler owns the graph.
@REJECTED Agent-side graph construction with free-form tool selection — bypasses validation and determinism.
@INVARIANT Agent cannot submit executable code, custom tool categories, raw expected metrics, artifact paths or runtime rewrites; it may author bounded SqlEvidenceSpec/DSL only through compiler validation.
#endregion AgentChat.Tools.ScenarioGraph
#endregion DashboardScenarioModel.Modules