# ISIS v2 NPC Crowd Variation Pack Cost Estimation and Budget Guardrails

Generated: 2026-08-02T17:39:31.915Z Checklist: `MXA-0104` (ISIS2-00302) Asset
Family: `npc-crowd-variation-pack` Phase: Phase 4 | Milestone: M3 Launch
(2026-07-27 to 2026-10-30)

## Objective

Deliver deterministic per-run cost/runtime estimation and threshold-based budget
guardrails for npc-crowd-variation-pack workflow execution, with enforcement and
observability integrated into workflow run APIs and provider compatibility
diagnostics.

## Workflow Coverage

| Workflow                                       | Cost Utils Coverage | Jobs Strategy Coverage | Workflow Surface Coverage |
| ---------------------------------------------- | ------------------- | ---------------------- | ------------------------- |
| `npc-crowd-variation-pack-baseline`            | yes                 | yes                    | no                        |
| `npc-crowd-variation-pack-image-conditioned`   | yes                 | yes                    | no                        |
| `npc-crowd-variation-pack-control-conditioned` | yes                 | yes                    | yes                       |
| `npc-crowd-variation-pack-consistency-locked`  | yes                 | yes                    | yes                       |

## Guardrail Environment Keys

| Env Key                                                                        | Cost Utils Coverage | Jobs Strategy Coverage |
| ------------------------------------------------------------------------------ | ------------------- | ---------------------- |
| `ISIS_NPC_CROWD_VARIATION_PACK_BUDGET_GUARDRAIL_ENABLED`                       | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_BUDGET_SOFT_LIMIT_USD`                          | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_BUDGET_HARD_LIMIT_USD`                          | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_RUNTIME_SOFT_LIMIT_SECONDS`                     | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_RUNTIME_HARD_LIMIT_SECONDS`                     | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_BUDGET_RETRY_AFTER_SECONDS`                     | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_COST_RATE_FLUX_USD_PER_SECOND`                  | yes                 | yes                    |
| `ISIS_NPC_CROWD_VARIATION_PACK_COST_RATE_CHARACTER_CONSISTENCY_USD_PER_SECOND` | yes                 | yes                    |

## Verification Commands

- `pnpm --filter @isis/generation-api exec vitest run src/routes/npc-crowd-variation-pack-budget-utils.spec.ts src/routes/workflows.spec.ts src/routes/jobs.spec.ts`

## Acceptance Criteria

- NPC crowd variation pack workflow variants return deterministic estimated
  runtime/cost signals before dispatch.
- Budget guardrail thresholds enforce hard-fail rejection when estimated
  runtime/cost envelopes exceed configured limits.
- Workflow run responses and headers expose estimation and guardrail diagnostics
  for operator visibility and downstream tooling.
- Provider compatibility diagnostics expose npc-crowd-variation-pack cost
  estimation profiles and budget guardrail policy metadata.

## Traceability

- Checklist item: `MXA-0104`
- Ticket key: `ISIS2-00302`
- Enforcement route: `/api/v1/workflows/:workflowId/run`
- Error code: `NPC_CROWD_VARIATION_PACK_BUDGET_GUARDRAIL_LIMIT_EXCEEDED`
