Simulate Policy Impact#

Before you promote a draft, preview its effect. Intended gives you two complementary tools: a draft impact summary that projects how the change shifts outcomes across a sample of traffic, and an intent-level dry run that shows exactly what a single intent would decide. Use the summary to size the change and the dry run to confirm specific cases.

Prerequisites#

• A draft created through Author a Policy.
• The authority:policy:write permission to read the impact summary, or intent:create to run an intent dry run.
• Matching tenant scope on credential, x-tenant-id, and body tenantId.

Draft impact summary#

GET /policy/drafts/:id/impact-summary projects how a draft would change outcomes if deployed. It samples recent intents, re-evaluates them under the draft, and returns three things:

1. A semanticDiff — what changed between the active set and the draft, in rule terms.
2. An impact projection — sample size, the changed-outcome rate, deltas in approval load and token issuance, a confidence figure, and a lowData flag when the sample is too small to trust.
3. A rolloutSafety checklist with a recommendedMode of shadow, review, or enforce.

curl "https://api.intended.so/policy/drafts/draft_123/impact-summary?tenantId=tenant_acme_prod" \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod"

Reading the result#

{
  "semanticDiff": {
    "addedRules": ["rule_prod_release"],
    "removedRules": [],
    "changedRules": []
  },
  "impact": {
    "sampleSize": 1842,
    "changedOutcomeRate": 0.011,
    "approvalLoadDelta": 21,
    "tokenIssuanceDelta": -21,
    "confidence": 0.86,
    "lowData": false
  },
  "rolloutSafety": {
    "recommendedMode": "review",
    "checks": [
      { "name": "changed-outcome rate within bound", "ok": true },
      { "name": "sample size sufficient", "ok": true }
    ]
  }
}

Intent-level dry run#

To confirm a specific case — "would this intent be approved under the new rules?" — run an intent through POST /intent/simulate. It returns the same decision shape as /intent but mints no token and executes nothing.

intended simulate \
  --tenant tenant_acme_prod \
  --actor svc-ci-bot \
  --action "dispatch release workflow" \
  --risk 42

curl -X POST https://api.intended.so/intent/simulate \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "simulation": true,
    "tenantId": "tenant_acme_prod",
    "actor": { "id": "svc-ci-bot", "type": "service" },
    "targetSystem": "acme/platform-api",
    "proposedAction": "dispatch release workflow",
    "riskContext": {
      "baseRiskScore": 42,
      "policyCompliant": true,
      "touchesProduction": true,
      "github": { "owner": "acme", "repo": "platform-api", "ref": "refs/heads/main" }
    }
  }'

From simulation to review#

Carry the simulation forward so the reviewer sees what you saw. When you submit the draft for review, pass the simulationRunId that produced the impact summary:

curl -X POST https://api.intended.so/policy/drafts/draft_123/review \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "tenant_acme_prod", "submittedBy": "user_admin", "simulationRunId": "sim_abc123" }'

Simulation best practices#

Next steps#

• Author a Policy — create or refine the draft you are simulating.
• Deploy and Rollback — promote the draft once the impact is acceptable.
• Incident Response — investigate when a deployed change behaves unexpectedly.