vitna.ai/docs/routing/stackfile Machine view
Raw .md llms.txt
> 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`.
Human Machine Shift+M