ss-tools/specs/038-dashboard-scenario-model/data-model.md

#region DashboardScenarioModel.DataModel [C:5] [TYPE ADR] [SEMANTICS data-model,scenario,graph,step,validation] @BRIEF Canonical immutable Verification Program IR: scenario_key, content_hash, navigation/evidence/transform/assertion/semantic programs, typed steps, parameters, capability and authoring-validation models. Runtime state is owned by 044. @RELATION DEPENDS_ON -> [DashboardScenarioModel.Research] @RELATION DEPENDS_ON -> [ScenarioExecution.DataModel] @RATIONALE 038 is the clean IR/compiler layer; identity/revision/runtime are reconciled with 042-047. Semantic identity (scenario_key) is separated from entity identity (scenario_id UUID, assigned by 042) and content identity (content_hash). @REJECTED scenario_id as a deterministic slug — rejected because clones of the same dashboard+objective would collide; entity identity MUST be a UUID assigned at Registry persistence. @REJECTED revision_hash/parent_revision_hash — rejected in favor of revision_id (UUID) + content_hash; the compiler does not fabricate identity. @REJECTED Runtime state (VlmFinding dispositions, HumanCheckpoint) inside the canonical scenario — rejected because an immutable revision must not embed runtime observations; VlmAnalysisSpec describes WHAT, VlmFinding/Disposition are 044 runtime. @REJECTED Direct SQL forbidden as an absolute principle — rejected because source-mart evidence is necessary for real checks; only validated, immutable, read-only SqlEvidenceSpec is permitted. @REJECTED Runtime LLM SQL/DSL rewrite — rejected because a ScenarioRun must execute precisely the content-addressed program saved in its revision.

DashboardTestScenario — compiled definition (no persistence identity)

Required:

• schema_version, compiler_version, template_version;
• scenario_key (semantic = dashboard key + normalized objective slug; human/domain identity);
• content_hash (SHA-256 of the canonical executable graph only — timestamps/display-only excluded);
• dashboard_context and objective;
• input_fingerprints: query model, checklist catalog, baseline_version, parameters;
• parameters, phases, steps, and required verification_program (navigation_program, evidence_program, transformation_program, assertion_program, semantic_evaluation_program);
• outputs and artifact_plan;
• checklist_coverage;
• warnings, blockers, risk_summary.

No scenario_id / revision_id here. The compiler emits scenario_key + content_hash. scenario_id (UUID) and revision_id (UUID) are assigned by the 042 registry at Save (CreateScenario). Provenance is orthogonal (see CompileProvenance below).

CompileProvenance

Compiler input MUST NOT require an AgentRun. Provenance is passed separately:

• source_type: agent_run | editor | migration | api
• source_id: nullable

ParameterDefinition

Fields: name, label, type, required, default (optional), source, validation, affected_logical_step_ids. Supported types: string, integer, decimal, boolean, date, datetime, enum, string_list, baseline_choice, selector_hint.

This immutable definition contains no resolved value or runtime status. Those belong exclusively to 044 ParameterBinding, so a value such as test_date=2026-08-10 never changes a scenario content_hash.

VerificationProgram — first-class executable IR

VerificationProgram is the canonical runtime program embedded in every saved scenario: navigation declares registered browser/API actions; evidence declares source/chart/XLSX observations; transformations declare bounded deterministic TransformSpec DSL; assertions declare ComparisonSpec/AssertionSpec; semantic evaluation declares only explicitly necessary AgentEvaluationSpec. All program entries are ref-addressed by logical_step_id, version-pinned and canonicalized into content_hash.

SqlEvidenceSpec is a small source-evidence statement: 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. It is an authoring artifact, saved only after the SQL compilation gate. Runtime may bind declared parameters but MUST execute exactly the pinned template through the Superset SQL Lab adapter; it cannot rewrite SQL, relations, joins, projections or filters.

TransformSpec is a bounded DSL only: select, filter, rename, cast, join, group_by, sum, count, distinct, coalesce, normalize_string, normalize_date, difference, ratio, tolerance_compare. ComparisonSpec/AssertionSpec model numeric tolerance, rows/columns/sets, aggregates, maps, null/fill and cross-dashboard checks. Arbitrary Python, shell and executable code are forbidden.

AgentEvaluationSpec is the exception for declared semantic/visual/ambiguous evaluation. It pins provider/model/prompt/input manifest/evidence/tool allowlist/output schema and DecisionPolicy. It is not an orchestration instruction and cannot mutate program content.

ScenarioStep — with logical identity

Field	Rule
logical_step_id	UUID, immutable across revisions/edits (analytics + compare key)
step_key	Semantic stable identifier (phase + case + action slug) — readable, not an identity
position	Derived ordering within the graph (mutable; NOT an identity)
step_content_hash	SHA-256 of the step's executable content (mutable across edits)
phase	setup/interact/observe/assert/evidence/report
title/description	Bounded display text
tool	browser, superset_api, sql_evidence, transform, assertion, agent_evaluation, xlsx, screenshot, report, artifact, human
action	Must be allowed by the version-pinned ActionRegistry for its tool; never free-form runtime dispatch
inputs	Typed refs only
outputs	Unique ScenarioRef declarations
expected	Structural expectation or baseline ref, never raw numeric truth
depends_on	Existing logical_step_ids; DAG
automation_status	ready, needs_context, needs_selector, needs_baseline, manual, unsupported, blocked
checklist_case_ids	Known catalog ids
risk	READ_ONLY, UI_INTERACTION, TEST_DATA_MUTATION, EXTERNAL_MUTATION, DANGEROUS_MUTATION, human
mutation_contract	Mandatory for every mutating action: safe_test_fixture_id, scope, allowed environment, affected keys, cleanup/reconciliation, side-effect key
capture_spec	Required when tool=screenshot; null otherwise
vlm_analysis_spec	Required when tool=assertion and input is screenshot; null otherwise

The compiler assigns a UUID when it creates an initial graph. An editor/migration MUST carry an existing logical_step_id forward for the same logical step; it MUST mint a new UUID only for a genuinely new step. step_key and position are never identity inputs. Analytics (047) and comparison (045) key on it.

ActionRegistry and mutation safety

ActionRegistry(version) is the canonical 038 catalog of every allowed {tool, action}. Each entry declares typed inputs/outputs, allowed risk, timeout, idempotency, retry safety, mutation policy and version. 044 resolves every executor action only from this same pinned registry; unknown {tool, action} is a validation error, not a fallback dispatch.

Mutating actions require mutation_contract. Policy: DANGEROUS_MUTATION is never automated; mutating browser steps in PROD are prohibited; TEST_DATA_MUTATION is permitted only in an explicitly listed non-PROD environment against a named safe fixture, with bounded affected record keys, side-effect idempotency and rollback/reconciliation. Missing safety context maps the checklist case to needs_context or HumanCheckpoint, never automatic dispatch.

ScreenshotCaptureSpec

Field	Type	Rule
target	string	tab or viewport
tab_identifier	string/null	Required when target=tab
viewport	{width, height}	Required; default 1920×1200
readiness	string	canvas_stabilized, network_idle, fixed_wait
readiness_timeout_ms	integer	Default 15000
mask_selectors	string[]	CSS selectors applied before capture; empty if none
method	string	cdp, full_page, region

This is the SPEC of capture; execution is owned by 044 (CaptureService over ScreenshotService, artifacts owner_type=scenario_run).

VlmAnalysisSpec

Field	Type	Rule
profile_id	string	Registered VLM analysis profile
provider_id	string	Provider identifier
model_id	string	Model identifier
prompt_template_id	string	Versioned prompt template
prompt_version	string	Semver
prompt_template_hash	sha256	SHA-256 of prompt content
confidence_threshold	float	Minimum confidence to auto-flag (default 0.7)

This is the SPEC (what to analyze). Runtime VlmFinding/HumanCheckpointDisposition are 044 entities.

ScenarioRef

Namespaces:

• context.dashboard., context.query_model.;
• param.{name};
• step.{logical_step_id}.{output};
• baseline.{baseline_id} or candidate.{candidate_id};
• artifact.{artifact_key}.

Every consumed step ref has exactly one producer. Parameter/context/baseline refs are externally resolved roots.

ChecklistCase and CapabilityMapping

ChecklistCase holds id, section, goal, reusable expected semantics, required/optional capabilities, parameters, tool templates, evidence, fallback, and source page. Historic PDF outcome is stored only as source_note.

CapabilityMapping holds case_id, classification, matched/missing capabilities, selected template, rationale, and resulting step keys.

AuthoringValidation and RunPreflight

AuthoringValidation determines whether an immutable ScenarioRevision/DraftPack may be saved. Fields: valid, errors, warnings, blockers, coverage, topological_order, unresolved_selectors, unresolved_baselines, parameter_definitions_valid, verification_program_valid, sql_compilation_results, graph_hash. Required ParameterDefinitions without a default are valid authoring inputs and appear only as unbound_parameter_names warnings.

RunPreflight is owned by 044: it resolves ParameterBinding, target, baselines, RLS/principal and runtime policy for one launch. An unbound required parameter makes only that launch run_ineligible; it never changes content_hash or blocks saving a reusable scenario.

An agent may construct coverage, resolve missing context with the analyst, and create a WorkingDraft or executable revision under delegated policy. It never bypasses AuthoringValidation, ActionRegistry(version), mutation contracts, canonicalization, or immutable content hashing; those are deterministic authorities.

ArtifactPlan and DraftPack (authoring-only)

ArtifactPlan entries declare artifact_key, kind, relative_path_template, template_id, input_refs, required, and generation blockers.

DraftPack is the authoring output (generated files previewed before Save): contains scenario_key, content_hash, template version, manifest, authoring DraftArtifact refs, validation summary, and warnings. Status preview_only or save_eligible. Validation error, NEEDS_SELECTOR, forbidden action, or unresolved baseline makes it preview_only; unbound required runtime parameters do not.

Runtime evidence is NOT a DraftPack. During execution (044), screenshots/report/xlsx are Artifact(owner_type=scenario_run, ...), never authoring DraftArtifacts (reconciliation step 7). DraftPack is consumed by 042 CreateScenario to register the revision.

Deterministic Identity

• scenario_key = dashboard key + normalized objective slug (semantic; may repeat across clones);
• content_hash = SHA-256 of canonical executable graph (steps/params/refs/expected), timestamps and display-only excluded;
• logical_step_id = immutable UUID, minted on initial graph creation and carried forward by edits/migrations;
• step_content_hash = SHA-256 of a step's executable content;
• step_key = phase + case id + action slug (readable, NOT an identity; no ordinal).

scenario_id (UUID) and revision_id (UUID) are assigned by 042 at persistence, never by the compiler.

Forbidden Content

The schema/validator rejects:

• arbitrary/unvalidated SQL, query text outside SqlEvidenceSpec, shell command or executable code body;
• raw numeric expected value for a metric assertion;
• absolute or parent-traversing artifact paths;
• unregistered tool/action;
• implicit dependency or duplicate producer;
• runtime observations (VlmFinding dispositions, HumanCheckpoint) inside a canonical revision.

#endregion DashboardScenarioModel.DataModel