Dsxir.RuntimeProgram (dsxir v0.4.0)

Copy Markdown

Pure-data runtime-authored program shape.

from_map/2 parses a JSON-ish payload, validates it semantically, runs the configured program_plugs, optionally persists to a store, and returns the finished %RuntimeProgram{}. Parse-only access is available through parse/1 for callers that need pre-validation structural shape.

Construction pipeline

from_map/2 runs four steps in order:

  1. parse the payload into typed structs (raises Dsxir.Errors.Invalid.RuntimeProgram on structural malformation),
  2. validate the parsed program (returns {:error, %Invalid.RuntimeProgram{}} on semantic failures),
  3. run Dsxir.Settings.resolve(:program_plugs, []) in declared order; the first plug returning {:halt, reason} raises Dsxir.Errors.Halted.ProgramPlug and prevents the rest from running,
  4. if a :store opt of the shape {module, ref} is supplied, call module.put(ref, rp).

The content-hash :version is computed on the validated program before plugs run so plug-side bookkeeping sees the final version.

Summary

Types

from_map_opt()
t()

Functions

from_artifact_blob(blob)

Reconstruct a %RuntimeProgram{} from a JSON-decoded artifact blob, re-running Validator.validate/1 so predicate sources are re-parsed and type-checked. Raises Dsxir.Errors.Invalid.RuntimeProgram if the program fails to validate, including when the blob's claimed version does not match the recomputed canonical hash. program_plugs are not run on load.

from_map(payload, opts \\ [])

Parse, validate, run program_plugs, and optionally persist a runtime program built from payload.

to_artifact_blob(rp)

Serialize rp to a JSON-safe map suitable for embedding in a v2 artifact envelope. The inverse is from_artifact_blob/1.

version!(rp)

Compute the SHA-256 content hash of the canonical encoding of rp.

Types

from_map_opt()

@type from_map_opt() :: {:store, {module(), term()}}

t()

@type t() :: %Dsxir.RuntimeProgram{
  edges: [Dsxir.RuntimeProgram.Edge.t()],
  id: String.t(),
  inputs: [Dsxir.RuntimeProgram.FieldSpec.t()],
  metadata: map(),
  nodes: [Dsxir.RuntimeProgram.Node.t()],
  outputs: [Dsxir.RuntimeProgram.FieldSpec.t()],
  version: <<_::256>>
}

Functions

from_artifact_blob(blob)

@spec from_artifact_blob(map()) :: t()

Reconstruct a %RuntimeProgram{} from a JSON-decoded artifact blob, re-running Validator.validate/1 so predicate sources are re-parsed and type-checked. Raises Dsxir.Errors.Invalid.RuntimeProgram if the program fails to validate, including when the blob's claimed version does not match the recomputed canonical hash. program_plugs are not run on load.

from_map(payload, opts \\ [])

@spec from_map(map(), [from_map_opt()]) ::
  {:ok, t()} | {:error, Dsxir.Errors.Invalid.RuntimeProgram.t()}

Parse, validate, run program_plugs, and optionally persist a runtime program built from payload.

Returns {:ok, %RuntimeProgram{}} on success, {:error, %Dsxir.Errors.Invalid.RuntimeProgram{}} on validation failure, and raises:

to_artifact_blob(rp)

@spec to_artifact_blob(t()) :: map()

Serialize rp to a JSON-safe map suitable for embedding in a v2 artifact envelope. The inverse is from_artifact_blob/1.

Predicate ASTs are intentionally dropped — only :source strings survive a round-trip so re-validation always re-parses from the canonical source.

version!(rp)

@spec version!(t()) :: <<_::256>>

Compute the SHA-256 content hash of the canonical encoding of rp.