Squidie.Workflow.EditorSpec (squidie v0.1.2)

JSON-safe workflow spec projection for visual editors.

This module keeps editor round-trips on the data side of the boundary. It does not load workflow modules, create atoms from input, resolve editor input into modules, or start runs. Runtime execution of validated specs remains a separate boundary.

Summary

Types

diff_map()

editor_map()

validation_error()

validation_opts()

Functions

diff(source, draft)

Compares a source workflow spec with an edited JSON-safe draft.

diff(source, draft, opts)

Compares a source workflow spec with an edited draft after option-aware validation.

preview_graph(spec)

Builds a draft graph preview from a JSON-safe editor spec map.

preview_graph(spec, opts)

Builds a draft graph preview after option-aware editor validation.

to_map(spec)

Converts a normalized workflow spec into a JSON-safe editor map.

validate_map(value)

Validates an editor spec map without starting a run.

validate_map(map, opts)

Validates an editor spec map with optional host-owned action validation.

Types

diff_map()

@type diff_map() :: %{required(String.t()) => term()}

editor_map()

@type editor_map() :: %{required(String.t()) => term()}

validation_error()

@type validation_error() :: %{
  path: [atom() | non_neg_integer()],
  code: atom(),
  message: String.t(),
  details: map()
}

validation_opts()

@type validation_opts() :: [
  {:action_registry, Squidie.Workflow.ActionRegistry.registry()}
]

Functions

diff(source, draft)

@spec diff(Squidie.Workflow.Spec.t() | map(), Squidie.Workflow.Spec.t() | map()) ::
  {:ok, diff_map()}
  | {:error, {:invalid_workflow_editor_spec, [validation_error()]}}

Compares a source workflow spec with an edited JSON-safe draft.

The result is JSON-safe and reports added, removed, and changed preview nodes and edges. Both inputs stay on the editor side of the boundary: this validates and previews data, but does not resolve draft specs into runtime definitions or start runs.

diff(source, draft, opts)

@spec diff(
  Squidie.Workflow.Spec.t() | map(),
  Squidie.Workflow.Spec.t() | map(),
  validation_opts()
) ::
  {:ok, diff_map()}
  | {:error, {:invalid_workflow_editor_spec, [validation_error()]}}

Compares a source workflow spec with an edited draft after option-aware validation.

Pass :action_registry when either side contains runtime-authored top-level action keys that must stay inside the host allowlist.

preview_graph(spec)

@spec preview_graph(Squidie.Workflow.Spec.t() | map()) ::
  {:ok, editor_map()}
  | {:error, {:invalid_workflow_editor_spec, [validation_error()]}}

Builds a draft graph preview from a JSON-safe editor spec map.

preview_graph(spec, opts)

@spec preview_graph(Squidie.Workflow.Spec.t() | map(), validation_opts()) ::
  {:ok, editor_map()}
  | {:error, {:invalid_workflow_editor_spec, [validation_error()]}}

Builds a draft graph preview after option-aware editor validation.

Pass :action_registry to reject unapproved top-level action keys before the graph is returned.

to_map(spec)

@spec to_map(Squidie.Workflow.Spec.t() | map()) :: editor_map()

Converts a normalized workflow spec into a JSON-safe editor map.

The projection keeps only editor-owned fields and serializes atoms, module atoms, keyword lists, nested maps, and lists into JSON-compatible values.

validate_map(value)

@spec validate_map(term()) ::
  :ok | {:error, {:invalid_workflow_editor_spec, [validation_error()]}}

Validates an editor spec map without starting a run.

Without :action_registry, validation stays structural and does not load workflow modules. When :action_registry is supplied, editor-owned top-level action keys are checked against the host allowlist before the draft can be previewed or accepted.

validate_map(map, opts)

@spec validate_map(term(), validation_opts()) ::
  :ok | {:error, {:invalid_workflow_editor_spec, [validation_error()]}}

Validates an editor spec map with optional host-owned action validation.

Pass :action_registry when editor-owned top-level action keys should be checked against the same allowlist used by runtime-authored spec activation.