​

ADR-0003: Policy-Resolved Workflow

​

Context

• durable control over request preprocessing behavior
• one workflow selected per request, with deterministic matching
• immutable workflow version history so a request can be traced back to the exact workflow used
• in-memory lookup for the hot path
• a storage-backed source of truth that works in future clustered deployments

• immutable raw request capture via RequestSnapshot
• optional best-effort semantic extraction via WhiteBoxPrompt

​

Decision

​

1. Keep Two Distinct Concepts

1. persisted workflow versions
2. request-scoped core.Workflow

• the matched persisted workflow version
• process-level feature configuration for the running gateway instance
• request facts captured from ingress
• request-scoped resolution results such as endpoint metadata and model resolution

​

2. First-Slice Scope Model

• global
• provider
• provider plus model

• (provider=NULL, model=NULL) means the single global workflow
• (provider=openai, model=NULL) means the provider-scoped workflow
• (provider=openai, model=gpt-5) means the provider-plus-model workflow

​

3. Matching Rule

1. provider + model
2. provider
3. global

​

4. Persistence Model

• id
• scope_provider nullable
• scope_model nullable
• version
• active
• name
• workflow_payload
• workflow_hash
• created_at
• optional operator metadata such as description

• rows are immutable after creation
• changing a workflow means inserting a new row
• for a given scope, only one row may be active at a time
• requests reference the immutable row id of the matched version
• scope_provider=NULL, scope_model!=NULL is invalid in this slice

​

5. Hot-Path Runtime Model

• one global workflow pointer
• one map keyed by provider
• one nested map keyed by provider and model

1. determine request selector inputs
2. check provider + model
3. else check provider
4. else use global
5. materialize request-scoped core.Workflow
6. attach the matched immutable workflow version id to request context

​

6. Request Traceability

• workflow_version_id

​

7. V1 Workflow Payload

Amended by ADR-0012. Payload schema_version: 2 renames the guardrails array to steps and adds phase (prompt | response | stream, default prompt) to each step. Version 1 payloads stay valid and compile as prompt-phase steps. The rest of this section describes the version 1 shape.

• simple feature flags for gateway-owned behaviors
• guardrail execution order inside the predefined guardrails phase

{
  "schema_version": 1,
  "features": {
    "cache": true,
    "audit": true,
    "usage": true,
    "guardrails": true
  },
  "guardrails": [
    {
      "ref": "pii-redaction",
      "step": 10
    },
    {
      "ref": "prompt-injection-check",
      "step": 10
    },
    {
      "ref": "system-prompt-inject",
      "step": 20
    }
  ]
}

• the top-level gateway flow stays hardcoded
• the guardrails array configures only the guardrails phase
• guardrails are sorted by numeric step
• guardrails with the same step run in parallel
• later steps start only after the previous step fully completes
• if features.guardrails is false, the guardrails array is ignored
• ref must point to an existing named guardrail managed by the gateway
• process-level feature configuration is a hard upper bound over workflow features
• the effective runtime feature value is process_enabled AND workflow_enabled
• if a process-level feature switch is disabled, the corresponding workflow field is ignored by that process

• missing feature flags may mean “use defaults” in write-time input
• persisted workflow versions must store effective resolved values, not implicit defaults

​

8. Future Evolution

​

Consequences

​

Positive

• Cluster-ready source of truth: All instances can load workflows from the same database
• Deterministic matching: One request maps to one workflow version using a simple precedence rule
• Fast hot path: Request matching uses in-memory snapshots instead of per-request database reads
• Immutable traceability: Audit records can point to the exact workflow version used
• Clear control-plane boundary: Persisted workflow versions become the durable policy layer, while core.Workflow remains request-scoped runtime state
• Simple v1 payload: The first implementation stays focused on flags plus ordered guardrails instead of a premature workflow engine

​

Negative

• More runtime machinery: The gateway now needs workflow loading, validation, indexing, and refresh behavior
• Activation constraints: The database must enforce one active workflow per scope
• Limited expressiveness in v1: Only the guardrails phase is explicitly configurable beyond feature toggles
• Broader test surface: Matching precedence, immutability, refresh, and audit linkage all need focused tests

​

Notes

• workflow authoring APIs
• admin UI behavior
• rollout workflows
• a general-purpose workflow graph
• path or key hierarchy