Jizoku Usage Rules

Copy Markdown View Source

Use these rules when building host apps with Jizoku or changing Jizoku itself.

Core Model

  • Jizoku is an embedded durable workflow runtime for Elixir applications.
  • Workflow authors define compiled Elixir workflow modules with triggers, payload contracts, steps, transitions, waits, approvals, retries, and recovery routes.
  • The Jido-native journal runtime is the source of truth for run, dispatch, attempt, manual-control, and terminal facts.
  • Host workers provide execution capacity by calling Jizoku.execute_next/1.
  • Runtime command, run, runnable, and attempt trace lineage is durable journal data; public telemetry is a best-effort projection of committed lifecycle facts and execution spans.
  • Optional schedulers can deliver cron payloads through Jizoku.Runtime.Runner.perform/2.
  • Optional backend adapters, such as the Bedrock example, can own durable delivery and lease mechanics without changing workflow modules.

Rules To Follow

  • Prefer use Jizoku.Step for custom workflow steps.
  • Use raw Jido.Action modules only for explicit interop.
  • Schedule raw Jido.Instruction values only through Jizoku.schedule_dynamic_work/3, with an explicit applied runnable origin and a host-owned action registry.
  • Return {:ok, output} or {:ok, output, []} from raw Jido.Action modules. Jizoku rejects non-empty or malformed action extras as an explicit action failure; it never silently discards Jido directives.
  • Pass recognized Jizoku command Jido.Signal envelopes directly to Jizoku.apply_signal/2. Do not manually call the adapter first. Route arbitrary domain signals only through a host-owned Jizoku.Jido.SignalResolver that returns closed lifecycle commands.
  • Resolver start commands must name compiled workflow modules in host code. Never derive modules, runtime options, queues, storage, or dispatch adapters from signal strings.
  • Treat the Jido envelope source as durable provenance, not authorization. Authenticate and authorize inbound signals before applying them.
  • Keep workflow definitions backend-neutral.
  • Keep delivery and job boundaries thin; call host-owned modules that wrap Jizoku public APIs.
  • Pass the same trusted :partition through every start, worker, cron, signal, control, replay, and read-model boundary when a host isolates workflow state by tenant or domain. Omitting it selects the legacy unpartitioned namespace.
  • Treat partitions as storage routing, not authorization. Authorize the caller before selecting a partition or returning its run data.
  • Use Jizoku.list_runs/2 for index views and Jizoku.inspect_run/2, Jizoku.inspect_run_graph/2, Jizoku.inspect_run_timeline/2, or Jizoku.explain_run/2 for details.
  • Use continue-as-new to bound recurring workflow history. Keep successor input explicit, choose a stable continuation key, and use Jizoku.inspect_continuation_chain/2 with a bounded :max_hops when more than the immediate lineage edge is required.
  • Use Jizoku.record_dynamic_work/3 when host/runtime code needs to persist bounded, inspection-only dynamic work metadata for a run.
  • Use Jizoku.preview_dynamic_work/3 when dashboards or visual editors need to validate candidate dynamic work and inspect the graph overlay before appending.
  • Use Jizoku.preview_graph_mutation/3 before proposing dependency-ordered graph changes. Commit with Jizoku.apply_graph_mutation/3, and call Jizoku.reconcile_dynamic_graph/2 when the report or inspection state says reconciliation is required.
  • Use Jizoku.preview_spec/3 or Jizoku.preview_spec/4 when visual editors need execution-style node output for a runtime-authored draft. Pass a host-owned :action_registry; preview calls only registry entries that opt into dry_run behavior and does not append durable runtime state.
  • Use :guardrail_registry with runtime-authored specs that declare step opts[:guardrails]; guardrail keys are host-owned validator contracts and decisions are exposed through previews, inspection, and explanations.
  • Add idempotency keys or domain duplicate detection to side-effecting steps.
  • Use Jizoku.Telemetry.metrics/0 for the default bounded-cardinality metric set. Keep reporters, exporters, dashboards, alerts, and logging host-owned.
  • Treat external exactly-once behavior as out of scope for Jizoku.

Rules To Avoid

  • Do not configure :executor for step execution.
  • Do not use or document :runtime_tables.
  • Do not deliver step or compensation payloads through Jizoku.Runtime.Runner.perform/2.
  • Do not append :dynamic_work_recorded journal entries directly from host app code; use the public recording API so validation stays centralized.
  • Do not make workflow modules depend on Bedrock, Oban, or another backend's APIs.
  • Do not use String.to_atom/1 on external input or persisted untrusted data.

Topic Rules