> Source: https://vitna.ai/docs/routing/stackfile
> Raw Markdown: https://vitna.ai/docs/routing/stackfile.md
> Corpus index: https://vitna.ai/llms.txt
# Declarative Stackfile and CI policy lock
Check your organisation's workload register into git as `vitna.stack.json` (`vitna.stackfile.v1`), preview and apply register changes deterministically, and gate deployments in CI with `vitna-runtime-lock` and `vitna.lock.json`.
## Why two files
A Stackfile (`vitna.stack.json`) declares what your team intends: workloads, unit profiles, quality and latency floors, data-handling boundaries (`requiresZeroRetention`, `requiresNoTraining`, `requiresRegions`, `allowsProviders`), private infrastructure rates, candidate pools, fallback chains, shadow rules, and watches.
A [signed policy](policy.md) (`policy.json`) records what accepted rulings currently authorise `vitna-runtime` to serve. Keeping the two separate preserves the decision boundary: editing `vitna.stack.json` updates the register and its constraints, while routing never moves until a decision is accepted and a signed policy is emitted.
`vitna.lock.json` (`vitna-policy-lock-v1`) binds the two together in git so CI refuses any pull request where `vitna.stack.json` tightened a boundary that `policy.json` does not satisfy, or where `policy.json` changed without updating the lockfile.
## Stackfile format
```json
{
"schema": "vitna.stackfile.v1",
"org": "convexity",
"privateSkus": [
{
"slug": "vllm-h100-prod",
"name": "vLLM H100 cluster",
"classId": "model",
"status": "active",
"notes": "Dedicated inference nodes",
"rates": [
{
"dimension": "input_per_mtok",
"amount": 0.18,
"from": "2026-09-01",
"notes": "Amortised cluster rate"
}
]
}
],
"workloads": [
{
"slug": "deep-research",
"name": "Deep research synthesis",
"classId": "model",
"status": "active",
"priority": "quality",
"unitLabel": "briefs",
"incumbentSkuId": "anthropic/claude-opus-4-8",
"monthlyVolume": 12000,
"unitProfile": {
"inputTokensPerUnit": 24000,
"outputTokensPerUnit": 3200
},
"constraints": {
"qualityFloor": 92,
"economicThresholdPct": 15,
"requiresZeroRetention": true,
"allowsProviders": ["anthropic", "openai"]
},
"delivery": {
"envKey": "MODEL_DEEP_RESEARCH",
"policyAlias": "deep-research"
},
"notes": "Customer-facing synthesis lane",
"candidates": [
{ "skuId": "openai/gpt-5.6-sol", "status": "watching" }
],
"fallbacks": [
{ "skuId": "anthropic/claude-sonnet-5", "notes": "Same-provider failover" }
],
"rules": [
{ "kind": "traffic_share", "share": 5, "skuId": "openai/gpt-5.6-sol", "notes": "Shadow canary" }
],
"watches": [
{ "kind": "price_move", "thresholdPct": 10, "direction": "down" }
]
}
]
}
```
Every field in `vitna.stackfile.v1` is validated by the same pure functions in `platform/engine/register.mjs` that guard `/console`, the CLI, and [`/api/v1/org/stackfile`](../api/v1/engine/org-stackfile.md). Unknown fields, negative profiles, out-of-range thresholds, duplicate lane aliases, and malformed identifiers fail immediately with the register's own refusal messages.
A Stackfile may also carry an optional top-level `"pipelines"` array declaring multi-stage workflows (`slug`, `name`, `runLabel`, `monthlyRuns`, and ordered `stages` referencing declared `workloadSlug` entries with `invocationsPerRun` and `criticalPath`) for offline Bill of Materials evaluation and CI spend budget gates via [`aperture:pipeline`](../cli/aperture/pipeline.md).
## Exporting, planning, and applying from a checkout
```bash
DATABASE_MIGRATE_URL=... npm run aperture:stackfile -- --export --org convexity --out vitna.stack.json
npm run aperture:stackfile -- --validate vitna.stack.json
DATABASE_MIGRATE_URL=... npm run aperture:stackfile -- --plan vitna.stack.json
DATABASE_MIGRATE_URL=... npm run aperture:stackfile -- --apply vitna.stack.json
```
Reconciliation never deletes behind your back:
- Workloads in the database that are omitted from `vitna.stack.json` stay untouched and are listed under `unmanaged.workloads`. Retire or pause a lane explicitly by setting `"status": "paused"` or `"status": "archived"`.
- New lane rules declared in `vitna.stack.json` enter in `shadow` mode, matching `aperture:rule:add`. Promoting a rule to `route` requires an accepted decision citing shadow readings (`aperture:rule:promote`).
- Existing armed watches omitted from `vitna.stack.json` stay armed and are reported under `unmanaged.watches` unless `--disarm-reason <note>` is supplied.
## Offline CI verification (`vitna-runtime-lock`)
`vitna-runtime` ships `vitna-runtime-lock` with zero external dependencies and zero network calls. Pin `VITNA_PUBLIC_KEY` in CI secrets and run:
```bash
VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
vitna-runtime-lock \
--policy policy.json \
--stackfile vitna.stack.json \
--write vitna.lock.json
```
Commit `vitna.lock.json` alongside `vitna.stack.json` and `policy.json`, then enforce it on every pull request:
```bash
VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
vitna-runtime-lock \
--policy policy.json \
--stackfile vitna.stack.json \
--lockfile vitna.lock.json \
--max-age-hours 168
```
From a checkout of this repository, the same command is available as an operator script:
```bash
VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
npm run runtime:lock -- --policy policy.json --stackfile vitna.stack.json --lockfile vitna.lock.json
```
`vitna-runtime-lock` exits with code `3` when any invariant breaks:
- `invalid_policy`: unreadable JSON, digest mismatch, untrusted signing key, or invalid Ed25519 signature.
- `org_mismatch` / `lock_org_mismatch`: `policy.json`, `vitna.stack.json`, and `vitna.lock.json` disagree on the organisation slug.
- `stale_policy`: `policy.json` is older than `--max-age-hours`.
- `missing_lane` / `missing_required_lane`: an active workload's `delivery.policyAlias` (or `--require-lane`) is missing from `policy.json`.
- `inactive_workload_routed`: `policy.json` still serves a workload marked `paused` or `archived` in `vitna.stack.json`.
- `unapproved_provider` / `unapproved_fallback_provider` / `unapproved_rule_provider`: a primary model, fallback, or rule uses a provider outside `constraints.allowsProviders`.
- `substrate_leak`: a lane, fallback, or rule carries an OpenRouter route while the workload requires zero retention, no training, regional residency, or excludes `openrouter` from `allowsProviders`.
- `fallback_drift` / `lane_drift` / `policy_digest_drift` / `stackfile_digest_drift`: `policy.json` or `vitna.stack.json` moved without updating `vitna.lock.json`.