Squidie Tooling Usage Rules

Dashboard And Visual Editor Surfaces

• Use Squidie.list_runs/2 for global and workflow-filtered run indexes.
• Use Squidie.inspect_run/2 for factual run details.
• Use Squidie.inspect_run_graph/2 for graph-oriented dashboard and visual editor views.
• Use GraphInspection.to_map/1 child_links to render parent-to-child subflow overlays; do not invent client-side child link ids from raw history.
• Use Squidie.explain_run/2 for operator-facing diagnosis and next actions.
• Use Squidie.record_dynamic_work/3 to persist validated dynamic nodes and edges that visual editors or dashboards should show on a run graph without executing them.
• Use Squidie.schedule_dynamic_work/3 when host-approved dynamic nodes should be persisted and executed through the journal dispatch path.
• Only offer dynamic scheduling controls after the origin attempt has applied; preview and record remain available for inspection-only overlays on active runs.
• Use Squidie.preview_dynamic_work/3 to validate candidate dynamic nodes and render the graph overlay before committing them to the journal. Prefer its origin_node_id, added_node_ids, added_edge_ids, recordable?, and warnings fields over ad hoc graph diffing in visual editor clients.
• Use dynamic_work_overlays from Squidie.inspect_run_graph/2 or GraphInspection.to_map/1 to inspect recorded dynamic work groups; use raw dynamic_work only when the caller needs the full normalized durable record.
• Pass host-owned :action_registry options when previewing or recording dynamic nodes that represent executable work candidates, and always pass it when scheduling dynamic work.
• Render dynamic edges as visual structure only unless a later API explicitly reports dependency ordering for scheduled dynamic nodes.
• Keep list responses redacted by default; fetch detailed history only when the caller asks for it.
• Use definition_version from list, inspection, graph, and explanation surfaces as an operator label only; the definition fingerprint remains the compatibility guard.

Workflow Specs

• Use Squidie.Workflow.to_spec/1 for normalized workflow definitions.
• Use Squidie.Workflow.validate_spec/1 before trusting compiled workflow specs in tooling.
• Use Squidie.Workflow.validate_spec/2 with :action_registry before trusting runtime-authored specs that reference executable actions.
• Use Squidie.start_spec/3 or Squidie.start_spec/4 for runtime-authored activation after validation; the persisted run definition is the execution and graph-inspection source of truth.
• Use Squidie.Workflow.EditorSpec.to_map/1, Squidie.Workflow.EditorSpec.validate_map/1, and Squidie.Workflow.EditorSpec.preview_graph/1 for JSON-safe visual editor round trips and draft graph previews that do not start runs.
• Use Squidie.Workflow.EditorSpec.validate_map/2 and Squidie.Workflow.EditorSpec.preview_graph/2 with :action_registry when editor JSON carries runtime-authored top-level action keys.
• Use Squidie.Workflow.EditorSpec.diff/2 or Squidie.Workflow.EditorSpec.diff/3 to compare a source spec and an edited draft without starting a run.
• Pass :action_registry to Squidie.Workflow.EditorSpec.diff/3 when either side includes runtime-authored top-level action keys.
• Treat unresolved specs as data for editors, diagrams, and validation; only the host-owned action registry is the module ownership allowlist.
• Do not offer replay controls for runtime-authored spec runs until Squidie exposes replay support for that definition source.
• Reject client edits to runtime-owned fields such as fingerprints, run ids, journal history, attempts, dispatches, and audit history.
• Preserve stable ids for workflow, trigger, step, transition, and condition data so visual editors can round-trip safely.

SquidSonar

• SquidSonar should list existing workflows and runs through public Squidie APIs rather than reading storage adapter internals.
• SquidSonar should fetch specific workflow internals by module/spec and specific run internals by run id.