Managing Policy Changes

Policy edits can change customer traffic immediately. This workflow turns a draft policy-config.yaml into a verified canary rollout with defined stop and rollback decisions. Saving YAML does not prove live behavior. A local test or version upload also does not prove live behavior.

Before you start

Identify the gateway, agent, environment, provider targets, and request families in scope.
Keep the last known-good YAML, configuration version, and digest available.
Name the rollout owner, reviewer, observer, and person authorized to roll back.
Prepare one case that the policy must allow. Prepare one case that the policy must block or redact. Add routing and escalation cases when those behaviors change.
Use the same provider-secret environment and secret-store access that the target gateway service will receive.
Have a gateway runtime token for VERDICTAN_API_TOKEN and a different application token for VERDICTAN_REQUEST_TOKEN. Do not use a provider credential as one of the two tokens.

1. Define success and rollback gates

Write the necessary result before editing:

Which requests must be allowed, blocked, redacted, or escalated?
Which provider and model must receive each routed request?
What change in block rate, error rate, latency, or review volume is permitted?
How long will the canary be observed before expansion?
Which result must cause rollback immediately, and which result only pauses expansion for investigation?

Capture baseline request IDs and event JSON from the active version with verdictan events tail --since <window> --json or GET /v1/events?since=<window>. Use History only when capture is enabled and session content is necessary.

Events and request IDs are the runtime decision evidence.

2. Validate the draft

From the policy pack directory, run the checks in this sequence:

verdictan config validate --file policy-config.yaml --json
verdictan policy lint --mode runtime --file policy-config.yaml
verdictan policy test --pack-dir . --json
verdictan gateway check --config policy-config.yaml --verbose

Each command must succeed. The commands answer different questions:

Check	What it proves	What it does not prove
`config validate`	The declarative document parses and passes structural validation	Provider credentials or live policy outcomes
`policy lint`	The file is a correct runtime policy document without reported lint errors	That its allow and block results are correct
`policy test`	The JSON golden tests and inline `testing.suites[]` cases in this pack match their declared outcomes	Live provider routing or application connectivity
`gateway check`	The config resolves with the active environment, provider credentials, routing, and policy chain	A provider inference, deployment, or live application request

Run gateway check with the target service's environment. An interactive-shell check can pass while the installed service is not available.

The service can receive different variables or secret-store access.

3. Send representative traffic

Start a non-production or canary gateway bound to a registered agent:

export VERDICTAN_API_URL="https://api.verdictan.com"
export VERDICTAN_API_TOKEN="vdt_your_gateway_runtime_token"

verdictan gateway run \
  --agent policy-canary \
  --policy-config policy-config.yaml \
  --listen 127.0.0.1:41002

In a different terminal, use an application token and a model declared in the draft. Replace the example request ID with a unique 32-character lowercase hexadecimal value for each case:

export VERDICTAN_REQUEST_TOKEN="vdt_your_application_token"
export VERDICTAN_TEST_MODEL="gpt-5.4-mini"
export VERDICTAN_TEST_REQUEST_ID="0123456789abcdef0123456789abcdef"

curl -i http://127.0.0.1:41002/v1/chat/completions \
  -H "Authorization: Bearer ${VERDICTAN_REQUEST_TOKEN}" \
  -H "X-Request-Id: ${VERDICTAN_TEST_REQUEST_ID}" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"${VERDICTAN_TEST_MODEL}\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Run the reviewed policy canary case.\"}
    ]
  }"

Preserve the response status, body, and X-Request-Id header. Then query the selected region and match the normalized request ID:

verdictan events tail --since 10m --json

For each case, verify the Event verdict, cause code, configuration version, and gateway or agent attribution.

If an upstream call occurred, verify the provider and model. Test an invalid application token.

Make sure that the gateway rejects it before an upstream provider call.

If no matching Event is delivered, stop the rollout check. Verify the region, gateway control-plane connection, and request-family evidence support.

An empty History view does not prove that the request did not occur.

4. Review the rollout gate

Do not deploy until all of these are true:

The draft is narrower than or equal to the approved scope.
The cases that policy must allow, block, or redact pass. The routing and escalation cases also pass where applicable.
The provider metadata used for retention or route selection matches the necessary posture.
A reviewer has approved the version, digest, target gateways, observation window, and rollback criteria.
The last known-good config is retrievable and the rollback owner is available.
The team can observe Gateways, runtime Events, related Inbox queues, and application health during the window.

Roll out to one representative canary before expansion. A saved version in Configurations is not a deployment.

A completed upload does not prove that the runtime applied the reviewed content.

5. Verify the deployed runtime

verdictan gateway check reports the reviewed local version and digest. Copy those values. The running canary must match them:

export EXPECTED_CONFIG_VERSION="reviewed-version"
export EXPECTED_CONFIG_SHA256="reviewed-sha256"

verdictan gateway config \
  --gateway-url http://127.0.0.1:41002 \
  --expect-version "${EXPECTED_CONFIG_VERSION}" \
  --expect-sha256 "${EXPECTED_CONFIG_SHA256}"

Set VERDICTAN_API_TOKEN when the runtime protects its admin endpoint. Then run the representative request cases and Event correlation again against the deployed canary. Compare verdicts, routing, errors, latency, and human-review volume with the baseline for the full observation window before adding targets.

Use each surface for its owning proof:

Gateways: runtime health and applied version.
verdictan events or GET /v1/events with since set, plus request IDs: request-time decisions and routing.
Inbox: human-review volume and outcomes.
Trail: audit chronology for the rollout and follow-up actions.
History: captured session context only when capture is enabled.

6. Pause or roll back explicitly

Pause expansion if you cannot verify the active version or digest. Also pause if evidence is missing or a metric exceeds its review band.

Investigate before you identify the new policy as the cause of the problem.

Roll back when one pre-agreed trigger occurs, such as:

a request that is not safe is allowed or a necessary business flow is blocked.
routing selects an incorrect provider, model, or retention posture.
the canary has sustained errors or latency more than the approved limit.
escalation or human-review volume exceeds the staffed capacity.
the deployed version or digest does not match the approved artifact.

Do these actions:

Stop adding targets and preserve the related request IDs, event JSON, active version, and digest.
Restore the last known-good YAML through the same reviewed deployment workflow. In Configurations, save it as a new recovery version and deploy only to the related targets.
For a named local gateway previously changed with verdictan gateway reload, use its stored rollback target:
```
verdictan gateway revert \
  --name verdictan-proxy \
  --gateway-url http://127.0.0.1:41002
```
Re-run verdictan gateway config with the known-good version and digest. Send the representative requests again. Verify them through the same Events query.
Record the trigger, decision, restored version, request IDs, and verification evidence in the change record.

There is no universal automatic policy rollback. verdictan gateway reload tries to restore the previous config after activation verification fails immediately.

You can use this action only when a rollback target is available. For a subsequent regression, use the recovery workflow above.

A subsequent regression includes a problem after a reload succeeds. It can also occur after a console rollout or multi-gateway deployment.

Before you start​

1. Define success and rollback gates​

2. Validate the draft​

3. Send representative traffic​

4. Review the rollout gate​

5. Verify the deployed runtime​

6. Pause or roll back explicitly​

Next steps​