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.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
{
"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
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.jsonReconciliation never deletes behind your back:
- Workloads in the database that are omitted from
vitna.stack.jsonstay untouched and are listed underunmanaged.workloads. Retire or pause a lane explicitly by setting"status": "paused"or"status": "archived". - New lane rules declared in
vitna.stack.jsonenter inshadowmode, matchingaperture:rule:add. Promoting a rule torouterequires an accepted decision citing shadow readings (aperture:rule:promote). - Existing armed watches omitted from
vitna.stack.jsonstay armed and are reported underunmanaged.watchesunless--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:
VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
vitna-runtime-lock \
--policy policy.json \
--stackfile vitna.stack.json \
--write vitna.lock.jsonCommit vitna.lock.json alongside vitna.stack.json and policy.json, then enforce it on every pull request:
VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
vitna-runtime-lock \
--policy policy.json \
--stackfile vitna.stack.json \
--lockfile vitna.lock.json \
--max-age-hours 168From a checkout of this repository, the same command is available as an operator script:
VITNA_PUBLIC_KEY="$(cat policy-key.pub)" \
npm run runtime:lock -- --policy policy.json --stackfile vitna.stack.json --lockfile vitna.lock.jsonvitna-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, andvitna.lock.jsondisagree on the organisation slug.stale_policy:policy.jsonis older than--max-age-hours.missing_lane/missing_required_lane: an active workload'sdelivery.policyAlias(or--require-lane) is missing frompolicy.json.inactive_workload_routed:policy.jsonstill serves a workload markedpausedorarchivedinvitna.stack.json.unapproved_provider/unapproved_fallback_provider/unapproved_rule_provider: a primary model, fallback, or rule uses a provider outsideconstraints.allowsProviders.substrate_leak: a lane, fallback, or rule carries an OpenRouter route while the workload requires zero retention, no training, regional residency, or excludesopenrouterfromallowsProviders.fallback_drift/lane_drift/policy_digest_drift/stackfile_digest_drift:policy.jsonorvitna.stack.jsonmoved without updatingvitna.lock.json.
