Pure constructors for workflow audit trail entries.

No I/O — entries are plain data maps. Persistence lives in the shell layer.

Pure workflow state-machine introspection.

Helpers for reading the shape of a WorkflowDefinition map (states, initial
state, transitions). No mutable state and no I/O.

The definition registry and the `defworkflow` macro live in the shell
(wagoe.workflow.shell.registry) — this namespace holds no mutable state.

Pure business logic for workflow transition decisions.

All functions are pure — no I/O, no side effects.
Guards and side-effect dispatch rely on data maps, not concrete impls.

Pure Hiccup UI components for workflow admin visualization.

All functions are pure — they receive data and return Hiccup structures.
No side effects, no I/O, no logging.

Components:
  state-badge          — colored state pill
  state-machine-vis    — read-only workflow state diagram
  audit-log-table      — chronological audit trail table
  instances-filter-form — search/filter form for instance list
  instances-table      — paginated instance list table
  instances-page       — full page: instance list
  instance-detail-page — full page: instance detail with state viz + audit trail

Port definitions for the wagoe-workflow library.

Three protocols cover the full lifecycle:

IWorkflowStore    — persistence of instances and audit log
IWorkflowEngine   — high-level transition orchestration
IWorkflowRegistry — in-process registry of workflow definitions

Malli schemas for declarative workflow state machines.

A workflow defines:
- A set of named states
- Transitions between states, with optional guards and permissions
- Side effects triggered on transition

A workflow instance tracks:
- Which entity (type + id) is being managed
- The current state of that entity
- Metadata for guard / context evaluation

The admin's `IEntityWorkflows` port over this module's store (BOU-563).
Here and not in the admin, because this library depends on the admin and
not the other way round.

workflow_instances.entity_uuid: entity_id as a UUID, NULL when it is not one
(BOU-589). entity_id stays text, since not every entity is keyed by a UUID;
this generated column is what an entity table keyed by one joins on:

  JOIN workflow_instances w ON w.entity_type = 'invoice' AND w.entity_uuid = i.id

Idempotent. On PostgreSQL the column is stored, so adding it rewrites the
table once; on SQLite, which has no uuid type, it is virtual text.

HTTP API routes and admin web UI handlers for workflow management.

API Endpoints (canonical):
  GET  /api/v1/workflow/instances?entity-type=&entity-id= — an entity's instances
  GET  /api/v1/workflow/instances/:id            — current state + metadata
  GET  /api/v1/workflow/instances/:id/audit      — full audit log
  POST /api/v1/workflow/instances                — start a new workflow instance
  POST /api/v1/workflow/instances/:id/transition — execute a transition

Compatibility:
  /api/workflow/* redirects to /api/v1/workflow/* via versioning middleware.

Admin Web UI (mounted under /web/admin):
  GET  /workflows        — list all workflow instances
  GET  /workflows/:id    — instance detail with state viz + audit trail

Every route requires authentication and answers 401 without it.

Integrant lifecycle management for the workflow module.

Config keys:

:wagoe/workflow-db-schema
  {:ctx (ig/ref :wagoe/db-context) :profile :prod}   ; alters tables in :dev :test :acc only

:wagoe/workflow
  Minimal config (no side-effects):
    {:db-ctx    (ig/ref :wagoe/db-context)
     :db-schema (ig/ref :wagoe/workflow-db-schema)}

  Full config (with jobs side-effects):
    {:db-ctx        (ig/ref :wagoe/db-context)
     :db-schema     (ig/ref :wagoe/workflow-db-schema)
     :job-queue     (ig/ref :wagoe/job-queue)
     :guard-registry {}}

:wagoe/workflow-routes
  {:workflow-service (ig/ref :wagoe/workflow)
   :user-service     (ig/ref :wagoe/user-service)}

  Returns {:api [...] :web [...] :static []} for composition
  by the HTTP handler.

Database persistence for workflow instances and audit trail.

Implements IWorkflowStore using next.jdbc + HoneySQL.
Applies snake_case <-> kebab-case conversion at the DB boundary only.

Load-time registry of workflow definitions.

The registry is mutable process state, so it lives in the shell — the core
(wagoe.workflow.core.machine) stays pure (state-machine introspection
only). Definitions are registered at namespace load via the `defworkflow`
macro and read at runtime by the workflow service/wiring.

No business logic here — just the definition registry, the `defworkflow`
convenience macro, and the IWorkflowRegistry adapter.

Workflow engine service.

Orchestrates the full transition lifecycle:
  1. Load workflow definition from registry
  2. Load workflow instance from store
  3. Validate transition (existence, permissions, guards)
  4. Persist new state + audit entry
  5. Enqueue side-effect jobs (if job-queue provided)

Implements IWorkflowEngine.

One instance per workflow and entity (BOU-581). Without the unique index two
lazy starts could both find none and both insert. Idempotent, and refuses by
name a table that already holds duplicates.