Get started

Declarative Stackfile and CI policy lock

Source

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.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`. 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`.

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.