velocity-python 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.3.2"
+__version__ = version = "0.4.0"
 
 import importlib as _importlib
 

velocity/aws/authz.py

@@ -961,6 +961,36 @@ SECURITY_EVENTS_TABLE = "sys_security_events"
 protect_tables(SECURITY_EVENTS_TABLE)
 confidential_tables(SECURITY_EVENTS_TABLE)
 
+# velocity.workflow's tables, registered here for the same reason: the generic
+# Data actions must refuse them whether or not anything imported
+# velocity.workflow first. Route definitions change only through the
+# workflow's own functions; dockets are read only through its contract
+# builder (a generic read would bypass the visibility rule and expose, for
+# one, every wait's correlation token). velocity.workflow.schema checks that
+# it declares exactly these.
+WORKFLOW_DEFINITION_TABLES = (
+    "sys_route",
+    "sys_route_station",
+    "sys_route_pass",
+    "sys_route_test",
+)
+WORKFLOW_DOCKET_TABLES = (
+    "sys_docket",
+    "sys_docket_position",
+    "sys_docket_document",
+    "sys_docket_mark",
+    "sys_docket_hold",
+    "sys_docket_flag",
+    "sys_docket_wait",
+    "sys_docket_link",
+    "sys_docket_outbox",
+    "sys_docket_seen",
+    "sys_notice",
+    "sys_tray_handover",
+)
+protect_tables(*WORKFLOW_DEFINITION_TABLES, *WORKFLOW_DOCKET_TABLES)
+confidential_tables(*WORKFLOW_DOCKET_TABLES)
+
 
 # ── the action index ───────────────────────────────────────────────────────
 

velocity/aws/capabilities/__init__.py

@@ -46,6 +46,7 @@ from . import security  # noqa: E402,F401
 from . import infra  # noqa: E402,F401
 from . import single_session  # noqa: E402,F401
 from . import jobs  # noqa: E402,F401
+from . import workflow  # noqa: E402,F401
 from .security import SecurityMixin  # noqa: E402,F401
 
 __all__ = [

velocity/aws/capabilities/workflow.py

@@ -0,0 +1,48 @@
+"""workflow: the timers and the outbox of :mod:`velocity.workflow`, on a schedule.
+
+Dockets keep time through this capability: once a minute ``sweep`` marks SLA
+breaches (they stay), missed waits, expired claims and due hand-overs
+(:func:`velocity.workflow.sweep`), then drains the outbox (program jobs,
+notice emails; :func:`velocity.workflow.outbox.drain`). ``drain`` alone is
+also schedulable.
+
+Schema: the tables are the ``workflow`` infrastructure group
+(``ensure_infrastructure(tx, include=("workflow",))``); the parts a column
+list cannot declare — append-only, audit-required marks and the possession
+constraint — come from :func:`velocity.workflow.ensure_schema`, which the
+app's schema lane runs (it does both).
+
+Handler mixins: ``WorkflowMixin`` on the Data handler (client actions),
+``WorkflowQueueMixin`` on the queue handler.
+"""
+
+from __future__ import annotations
+
+from .base import Capability, capability
+
+EVERY_MINUTE = "* * * * *"
+
+
+@capability
+class Workflow(Capability):
+    name = "workflow"
+    label = "Workflow"
+    description = (
+        "Dockets moving along routes of stations: SLA breaches, missed waits, "
+        "expired claims and hand-overs once a minute, and the outbox (program "
+        "jobs and notice emails) drained. No per-site policy."
+    )
+    schedules = (("sweep", EVERY_MINUTE),)
+    mixins = (
+        "velocity.aws.handlers.mixins.workflow_actions:WorkflowMixin",
+        "velocity.aws.handlers.mixins.workflow_actions:WorkflowQueueMixin",
+    )
+
+    def handle(self, action, tx, context, config):
+        from velocity.workflow import engine, outbox
+
+        if action == "sweep":
+            return {"swept": engine.sweep(tx), "drained": outbox.drain(tx, context)}
+        if action == "drain":
+            return {"drained": outbox.drain(tx, context)}
+        raise ValueError(f"workflow: unknown action {action!r}")

velocity/aws/handlers/mixins/__init__.py

@@ -17,6 +17,9 @@ This package provides mixins for common Lambda handler patterns:
   reportClientError / ErrorBoundary) to velocity.aws.failures
 - DirtyPipelineMixin: the process-dirty-object queue consumer and the
   sweep-dirty-rows action (velocity.aws.dirty_pipeline)
+- WorkflowMixin / WorkflowQueueMixin: the workflow-* actions over dockets
+  (velocity.workflow): trays, the docket contract, acts, claims, flags,
+  notices; and the queue side (program jobs, outbox drain, timers)
 - SchedulerMixin: run-schedules, the once-a-minute tick over sys_schedules
   (velocity.aws.scheduler)
 """
@@ -30,6 +33,12 @@ from .session_control import SessionControlMixin
 from .action_names import action_names
 from .permissions_actions import PERMISSION_ACTIONS, PermissionsMixin
 from .tiles_actions import TILE_ACTIONS, TilesMixin
+from .workflow_actions import (
+    WORKFLOW_ACTIONS,
+    WORKFLOW_QUEUE_ACTIONS,
+    WorkflowMixin,
+    WorkflowQueueMixin,
+)
 from .client_errors import ClientErrorReporting, AnonymousClientErrorReporting
 from velocity.aws.dirty_pipeline import DirtyPipelineMixin
 from velocity.aws.scheduler import SchedulerMixin
@@ -47,6 +56,10 @@ __all__ = [
     "PERMISSION_ACTIONS",
     "TilesMixin",
     "TILE_ACTIONS",
+    "WorkflowMixin",
+    "WorkflowQueueMixin",
+    "WORKFLOW_ACTIONS",
+    "WORKFLOW_QUEUE_ACTIONS",
     "action_names",
     "ClientErrorReporting",
     "AnonymousClientErrorReporting",

velocity/aws/handlers/mixins/workflow_actions.py

@@ -0,0 +1,491 @@
+"""The actions behind the workflow screens (``velocity.workflow``).
+
+A site adds :class:`WorkflowMixin` to its Data handler and lists the actions
+in ``client_actions`` (``client_actions = MINE | WORKFLOW_ACTIONS``)::
+
+    workflow-tray        {view, station?, cursor?, limit?}   -> {counts, rows, cursor?, as_of}
+    workflow-docket      {docket}                            -> Docket
+    workflow-act         {docket, action, inputs?, comment?, request_key}
+                                                             -> {ok, docket} | 4xx {ok: false, reasons}
+    workflow-flag        {docket, note?} | {docket, clear}   -> {ok, docket}
+    workflow-claim       {docket, position, release?}        -> {ok, docket}
+    workflow-notices     {unread_only?, cursor?, limit?}     -> {unread, rows, cursor?}
+    workflow-notice-ack  {notice} | {all: true}              -> {ok, unread}
+
+and :class:`WorkflowQueueMixin` to its queue handler (never reachable over
+HTTP): ``workflow-program`` (a program station's job), ``workflow-drain``
+(the outbox) and ``workflow-sweep`` (the timers).
+
+**Authorization.** Every action is :func:`velocity.aws.authz.require` on a
+named action (:mod:`velocity.workflow.access`) with the docket as a resource
+whose relations come from the person's seats — the site's
+``workflow_seats`` (default: :func:`velocity.workflow.register_seats`'s
+hook), never from the request. An act or claim allowed only by
+``workflow.oversee`` or ``workflow.act_any`` is a privileged use: authz
+records it before it happens, and the engine then acts with ``override``.
+
+**Refusals** are ``{ok: false, reasons: [Reason]}`` with HTTP 403 (not
+yours) or 409 (the docket's state or a guard said no), or 400 for a
+malformed request. A docket the person may not see is refused exactly like
+one that does not exist.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+
+from velocity.aws import authz
+from velocity.aws.handlers.exceptions import AccessError
+from .action_names import action_names
+
+logger = logging.getLogger(__name__)
+
+FORBIDDEN = 403
+CONFLICT = 409
+BAD_REQUEST = 400
+
+
+def _workflow():
+    # imported lazily: velocity.workflow pulls in the rules package
+    from velocity import workflow
+
+    return workflow
+
+
+class _Refusal(Exception):
+    def __init__(self, status, reasons):
+        super().__init__(status)
+        self.status = status
+        self.reasons = reasons
+
+
+def _reasons_status(reasons) -> int:
+    codes = {r.get("code") for r in reasons or ()}
+    return (
+        FORBIDDEN if codes & {"not_available", "not_yours", "forbidden"} else CONFLICT
+    )
+
+
+class WorkflowMixin:
+    """See the module docstring."""
+
+    workflow_tray_limit = 50
+
+    # ── seams ──────────────────────────────────────────────────────────────
+
+    def workflow_seats(self, tx, context, principal):
+        """Where the signed-in person sits (override, or register a seats
+        hook). Seats without a ``person`` get the user row id."""
+        return _workflow().hooks.seats_for(tx, principal)
+
+    # ── helpers ────────────────────────────────────────────────────────────
+
+    def _wf_principal(self, context):
+        principal = authz.principal_for(self, context)
+        if principal.user_sys_id is None:
+            raise AccessError(authz.REFUSED)
+        return principal
+
+    def _wf_seats(self, tx, context, principal):
+        seats = self.workflow_seats(tx, context, principal)
+        wf = _workflow()
+        if seats is None:
+            seats = wf.NO_SEATS
+        if not isinstance(seats, wf.Seats):
+            raise AccessError(authz.REFUSED)
+        if not seats.person:
+            seats = dataclasses.replace(seats, person=str(principal.user_sys_id))
+        return seats
+
+    def _wf_docket(self, tx, payload, key="docket"):
+        wf = _workflow()
+        try:
+            docket = wf.engine.docket_row(tx, (payload or {}).get(key))
+        except wf.WorkflowError:
+            # never say whether a docket the person can't see exists
+            raise AccessError(authz.REFUSED) from None
+        route = wf.engine._Ctx(tx).route(docket["route_id"])
+        return docket, route
+
+    def _wf_require(self, tx, context, action, docket, relations):
+        """``authz.require`` on a docket-scoped action. Every refusal says the
+        same sentence (``authz.REFUSED``): not which permission was missing,
+        and not whether the docket exists."""
+        wf = _workflow()
+        try:
+            return authz.require(
+                self, tx, context, action, wf.access.resource(docket, relations)
+            )
+        except AccessError:
+            raise AccessError(authz.REFUSED) from None
+
+    def _wf_masquerading(self, principal) -> bool:
+        return principal.real_user is not None
+
+    def _wf_decider(self, context):
+        """The viewer's ``may_view``: the site's authz decision on
+        ``workflow.docket.view`` for one docket (a forbid rule hides it from
+        trays and links too). A privileged permit (``view_any``) is not
+        used here: listing is never a recorded use."""
+        wf = _workflow()
+
+        def decide(docket, relations):
+            decision = authz.decide(
+                self, wf.access.VIEW, wf.access.resource(docket, relations), context
+            )
+            return decision.allowed and not decision.audit
+
+        return decide
+
+    def _wf_allows(self, tx, context, *, record=True):
+        """The actor's write decisions: ``authz.require`` on the named action
+        (``workflow.sheet.write`` / ``workflow.hold.release``) with the
+        docket's entity scope and the permission it needs, so scoped grants,
+        denials, forbids (and masquerade) apply. A refusal answers False."""
+        wf = _workflow()
+
+        def allows(action, permission, docket):
+            if not record:
+                # for display only (the action list): never a recorded use
+                decision = authz.decide(
+                    self,
+                    action,
+                    wf.access.resource(docket, (), permission=permission),
+                    context,
+                )
+                return decision.allowed and not decision.audit
+            try:
+                authz.require(
+                    self,
+                    tx,
+                    context,
+                    action,
+                    wf.access.resource(docket, (), permission=permission),
+                )
+            except AccessError:
+                return False
+            return True
+
+        return allows
+
+    def _wf_actor(self, seats, decision, principal, tx=None, context=None):
+        """The actor a decision allows: ``override`` for a route owner or
+        ``workflow.act_any`` (both recorded by authz), ``cross_entity`` only
+        for ``workflow.act_any``."""
+        wf = _workflow()
+        return wf.engine.Actor.person(
+            seats,
+            override=decision.rule in wf.access.OVERRIDE_RULES,
+            cross_entity=decision.rule == "workflow.act_any",
+            allows=self._wf_allows(tx, context) if tx is not None else None,
+        )
+
+    def _wf_viewer(self, tx, context, docket, route, principal, seats):
+        """Require ``workflow.docket.view`` and build the viewer; whether an
+        override would let them act is asked (not recorded) for the action
+        list."""
+        wf = _workflow()
+        relations = wf.access.view_relations(tx, docket, route, seats)
+        self._wf_require(tx, context, wf.access.VIEW, docket, relations)
+        probe = authz.decide(
+            self,
+            wf.access.ACT,
+            wf.access.resource(docket, relations & {wf.access.OVERSEES}),
+            context,
+        )
+        override = probe.allowed and probe.rule in wf.access.OVERRIDE_RULES
+        return wf.contract.Viewer(
+            seats=seats,
+            principal=principal,
+            act_override=override,
+            cross_entity=override and probe.rule == "workflow.act_any",
+            view_decider=self._wf_decider(context),
+            allows=self._wf_allows(tx, context, record=False),
+        )
+
+    def _wf_refuse(self, context, status, reasons):
+        context.response().set_status(status)
+        context.response().set_body({"ok": False, "reasons": list(reasons)})
+
+    def _wf_after_change(self, tx, context, docket_id):
+        """Ask for the outbox to be drained once this transaction commits."""
+        wf = _workflow()
+        if not wf.outbox.has_pending(tx, docket_id):
+            return
+        try:
+            context.enqueue(wf.outbox.DRAIN_ACTION, {}, suppress_job_activity=True)
+        except Exception:
+            # the scheduled drain picks it up within a minute
+            logger.warning("workflow drain enqueue failed", exc_info=True)
+
+    def _wf_guarded(self, tx, context, work):
+        """Run ``work`` in a savepoint; a refusal rolls back everything it
+        wrote and answers ``{ok: false, reasons}`` with its status."""
+        wf = _workflow()
+        try:
+            with tx.savepoint():
+                return work()
+        except AccessError:
+            self._wf_refuse(
+                context, FORBIDDEN, [{"code": "forbidden", "text": authz.REFUSED}]
+            )
+        except _Refusal as exc:
+            self._wf_refuse(context, exc.status, exc.reasons)
+        except wf.WorkflowRefused as exc:
+            status = exc.status if exc.status in (400, 403, 409) else CONFLICT
+            self._wf_refuse(context, status, exc.reasons)
+        except wf.WorkflowError as exc:
+            self._wf_refuse(
+                context, BAD_REQUEST, [{"code": "invalid", "text": str(exc)}]
+            )
+        return None
+
+    def _wf_docket_body(self, tx, context, docket_id, principal, seats):
+        wf = _workflow()
+        docket, route = self._wf_docket(tx, {"docket": docket_id})
+        viewer = self._wf_viewer(tx, context, docket, route, principal, seats)
+        # under masquerade nothing is written, not even "seen"
+        return wf.contract.build_docket(
+            tx,
+            docket["sys_id"],
+            viewer,
+            record_seen=not self._wf_masquerading(principal),
+        )
+
+    # ── reading ────────────────────────────────────────────────────────────
+
+    def OnActionWorkflowTray(self, tx, context):
+        wf = _workflow()
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        authz.require(self, tx, context, wf.access.TRAY)
+        seats = self._wf_seats(tx, context, principal)
+        viewer = wf.contract.Viewer(
+            seats=seats, principal=principal, view_decider=self._wf_decider(context)
+        )
+
+        def work():
+            body = wf.contract.tray(
+                tx,
+                viewer,
+                payload.get("view") or "mine",
+                station=payload.get("station"),
+                cursor=payload.get("cursor"),
+                limit=payload.get("limit") or self.workflow_tray_limit,
+                counts=payload.get("counts") is not False,
+            )
+            context.response().set_body(body)
+
+        self._wf_guarded(tx, context, work)
+
+    def OnActionWorkflowDocket(self, tx, context):
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        seats = self._wf_seats(tx, context, principal)
+        body = self._wf_docket_body(
+            tx, context, payload.get("docket"), principal, seats
+        )
+        context.response().set_body(body)
+
+    # ── acting ─────────────────────────────────────────────────────────────
+
+    def OnActionWorkflowAct(self, tx, context):
+        wf = _workflow()
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        seats = self._wf_seats(tx, context, principal)
+
+        def work():
+            action = payload.get("action")
+            # a malformed action id is a bad request, before anything is
+            # looked up (it names no target to authorize)
+            wf.engine.parse_action(action)
+            docket, route = self._wf_docket(tx, payload)
+            request_key = payload.get("request_key")
+            if isinstance(request_key, str) and wf.engine.already_acted(
+                tx, docket["sys_id"], wf.engine.Actor.person(seats), request_key
+            ):
+                # a retry of this person's own request that succeeded: answer
+                # with the docket as it is (seeing it is still checked)
+                body = self._wf_docket_body(
+                    tx, context, docket["sys_id"], principal, seats
+                )
+                context.response().set_body({"ok": True, "docket": body})
+                return
+            relations = wf.access.act_relations(tx, docket, route, seats, action)
+            decision = self._wf_require(tx, context, wf.access.ACT, docket, relations)
+            # the rest of the payload is checked only once the act is allowed
+            if not isinstance(request_key, str) or not request_key.strip():
+                raise _Refusal(
+                    BAD_REQUEST,
+                    [{"code": "request_key", "text": "A request key is required."}],
+                )
+            inputs = payload.get("inputs")
+            if inputs is not None and not isinstance(inputs, dict):
+                raise _Refusal(
+                    BAD_REQUEST,
+                    [{"code": "inputs", "text": "inputs must be an object."}],
+                )
+            comment = payload.get("comment")
+            if comment is not None and not isinstance(comment, str):
+                raise _Refusal(
+                    BAD_REQUEST, [{"code": "comment", "text": "comment must be text."}]
+                )
+            result = wf.engine.act(
+                tx,
+                docket["sys_id"],
+                action,
+                inputs,
+                self._wf_actor(seats, decision, principal, tx, context),
+                request_key,
+                comment=comment,
+            )
+            if not result.ok:
+                raise _Refusal(_reasons_status(result.reasons), result.reasons)
+            self._wf_after_change(tx, context, docket["sys_id"])
+            body = self._wf_docket_body(tx, context, docket["sys_id"], principal, seats)
+            context.response().set_body({"ok": True, "docket": body})
+
+        self._wf_guarded(tx, context, work)
+
+    def OnActionWorkflowClaim(self, tx, context):
+        wf = _workflow()
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        seats = self._wf_seats(tx, context, principal)
+
+        def work():
+            docket, route = self._wf_docket(tx, payload)
+            try:
+                position = wf.engine._position(tx, payload.get("position"))
+            except wf.WorkflowError:
+                raise AccessError(authz.REFUSED) from None
+            if position["docket_id"] != docket["sys_id"]:
+                raise AccessError(authz.REFUSED)
+            relations = wf.access.act_relations(
+                tx, docket, route, seats, position=position
+            )
+            decision = self._wf_require(tx, context, wf.access.CLAIM, docket, relations)
+            wf.engine.claim(
+                tx,
+                docket["sys_id"],
+                position["sys_id"],
+                self._wf_actor(seats, decision, principal, tx, context),
+                release=payload.get("release") is True,
+            )
+            self._wf_after_change(tx, context, docket["sys_id"])
+            body = self._wf_docket_body(tx, context, docket["sys_id"], principal, seats)
+            context.response().set_body({"ok": True, "docket": body})
+
+        self._wf_guarded(tx, context, work)
+
+    def OnActionWorkflowFlag(self, tx, context):
+        wf = _workflow()
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        seats = self._wf_seats(tx, context, principal)
+
+        def work():
+            docket, route = self._wf_docket(tx, payload)
+            relations = wf.access.view_relations(tx, docket, route, seats)
+            self._wf_require(tx, context, wf.access.FLAG, docket, relations)
+            actor = wf.engine.Actor.person(seats)
+            if payload.get("clear") is not None:
+                wf.engine.clear_flag(tx, docket["sys_id"], payload.get("clear"), actor)
+            else:
+                note = payload.get("note")
+                if note is not None and not isinstance(note, str):
+                    raise _Refusal(
+                        BAD_REQUEST, [{"code": "note", "text": "note must be text."}]
+                    )
+                wf.engine.flag(tx, docket["sys_id"], actor, note)
+            body = self._wf_docket_body(tx, context, docket["sys_id"], principal, seats)
+            context.response().set_body({"ok": True, "docket": body})
+
+        self._wf_guarded(tx, context, work)
+
+    # ── notices ────────────────────────────────────────────────────────────
+
+    def OnActionWorkflowNotices(self, tx, context):
+        wf = _workflow()
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        authz.require(self, tx, context, wf.access.NOTICES)
+        seats = self._wf_seats(tx, context, principal)
+
+        def work():
+            body = wf.notices.list_for(
+                tx,
+                seats.person,
+                unread_only=bool(payload.get("unread_only")),
+                cursor=payload.get("cursor"),
+                limit=payload.get("limit") or 50,
+            )
+            context.response().set_body(body)
+
+        self._wf_guarded(tx, context, work)
+
+    def OnActionWorkflowNoticeAck(self, tx, context):
+        wf = _workflow()
+        payload = context.payload() or {}
+        principal = self._wf_principal(context)
+        authz.require(self, tx, context, wf.access.NOTICE_ACK)
+        seats = self._wf_seats(tx, context, principal)
+
+        def work():
+            unread = wf.notices.ack(
+                tx,
+                seats.person,
+                notice_id=payload.get("notice"),
+                all=payload.get("all") is True,
+            )
+            context.response().set_body({"ok": True, "unread": unread})
+
+        self._wf_guarded(tx, context, work)
+
+
+class WorkflowQueueMixin:
+    """Queue-handler actions: program jobs, the outbox drain, the timers.
+    Refused over HTTP (queue records and scheduled ticks only)."""
+
+    def OnActionWorkflowProgram(self, tx, context):
+        from velocity.aws.dirty_pipeline import refuse_http
+
+        refuse_http(self, "workflow-program")
+        wf = _workflow()
+        payload = context.payload() or {}
+        result = wf.engine.run_program(
+            tx, payload.get("position"), payload.get("attempt")
+        )
+        drained = wf.outbox.drain(tx, context)
+        context.response().set_body({"result": result, "drained": drained})
+
+    def OnActionWorkflowDrain(self, tx, context):
+        from velocity.aws.dirty_pipeline import refuse_http
+
+        refuse_http(self, "workflow-drain")
+        context.response().set_body({"drained": _workflow().outbox.drain(tx, context)})
+
+    def OnActionWorkflowSweep(self, tx, context):
+        from velocity.aws.dirty_pipeline import refuse_http
+
+        refuse_http(self, "workflow-sweep")
+        wf = _workflow()
+        swept = wf.engine.sweep(tx)
+        context.response().set_body(
+            {"swept": swept, "drained": wf.outbox.drain(tx, context)}
+        )
+
+
+# every client action WorkflowMixin serves: ``client_actions = MINE | WORKFLOW_ACTIONS``
+WORKFLOW_ACTIONS = action_names(WorkflowMixin)
+# the queue handler's (never list these in client_actions)
+WORKFLOW_QUEUE_ACTIONS = action_names(WorkflowQueueMixin)
+
+__all__ = [
+    "WORKFLOW_ACTIONS",
+    "WORKFLOW_QUEUE_ACTIONS",
+    "WorkflowMixin",
+    "WorkflowQueueMixin",
+]

velocity/aws/schema.py

@@ -29,6 +29,9 @@ Groups:
 * ``tiles`` — tiles and who sees them (:mod:`velocity.aws.tiles`).
 * ``scheduler`` — ``sys_schedules`` (:mod:`velocity.aws.scheduler`).
 * ``rules`` — rules, rule tests and the decision log (:mod:`velocity.rules.storage`).
+* ``workflow`` — routes, dockets, marks, notices (:mod:`velocity.workflow.schema`);
+  run :func:`velocity.workflow.ensure_schema` too for the append-only marks
+  and the possession constraint.
 
 Each module's ``SCHEMA`` maps a table name to ``Table.ensure_schema`` keyword
 arguments (``columns`` plus optional ``indexes`` / ``unique_indexes``). Two
@@ -67,6 +70,8 @@ SCHEMA_SOURCES: Dict[str, Tuple[str, ...]] = {
     "scheduler": ("velocity.aws.scheduler",),
     # data-driven rules (velocity.rules); opt-in, for apps that evaluate them
     "rules": ("velocity.rules.storage",),
+    # dockets on routes (velocity.workflow); opt-in, for apps that use them
+    "workflow": ("velocity.workflow.schema",),
     "payment": ("velocity.payment.schema",),
 }
 GROUPS = tuple(SCHEMA_SOURCES)

velocity/rules/__init__.py

@@ -37,6 +37,7 @@ from .engine import (  # noqa: F401
     evaluate,
     run_rule_tests,
     set_status,
+    valid_rule_id,
     validate_rules,
 )
 from .expressions import ExpressionError  # noqa: F401
@@ -107,5 +108,6 @@ __all__ = [
     "run_rule_tests",
     "save_rule",
     "set_status",
+    "valid_rule_id",
     "validate_rules",
 ]

velocity/rules/engine.py

@@ -120,6 +120,13 @@ DEFAULT_PRIORITY = 100
 DIGEST_DOMAIN = "velocity.rules.tested/v1\n"
 
 
+def valid_rule_id(value) -> bool:
+    """Whether ``value`` is a rule id the engine accepts (a non-empty
+    string: ``"credit_limit"``, ``"co.excise_due"``). The one definition other
+    modules (velocity.workflow's route rows) validate rule references with."""
+    return isinstance(value, str) and bool(value)
+
+
 class RuleTestError(RuleError):
     """A rule cannot change status because its tests fail."""
 
@@ -485,7 +492,7 @@ class CompiledRule:
         self.point = point
         if rule.point != point.name:
             raise RuleError(f"{label} is for {rule.point!r}, not {point.name!r}")
-        if not rule.id or not isinstance(rule.id, str):
+        if not valid_rule_id(rule.id):
             raise RuleError("a rule needs an id")
         point.layer_rank(rule.layer)
         if rule.status not in STATUSES: