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 and CHAR(36).

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: the API answers 401 without it, the
admin pages send to the login form. Instances live in the tenant's schema,
read through the request's tenant-bound transaction, so every route also
refuses a caller outside the request's tenant with 403. The API's reads,
and starting an instance, need an admin or a :workflow/read grant; the
admin pages need an admin. In a tenant, both are the tenant's: its admins
(`access/tenant-admin?`) and grants scoped {:tenant-id <its id>}.

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)
     :each-tenant   (ig/ref :wagoe/each-tenant)   ; with tenancy
     :guard-registry {}}

:wagoe/workflow-routes
  {:workflow-service (ig/ref :wagoe/workflow)
   :user-service     (ig/ref :wagoe/user-service)
   :group-service    (ig/ref :wagoe/user-group-service)   ; for the :workflow/read grant
   ;; With the admin on, for the admin shell's brand:
   :admin            {:logo-url <the admin's :logo-url>}}

  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.

Workflow's tables: their one definition, and where a tenant's are. A tenant
schema gets them from the same migrations public does, which the tenant
module runs in each tenant schema.

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.