AGPL-3.0-or-later · forever.

{"id":"local/check-and-plan","slug":"check-and-plan","section":"local","label":"Check and plan","summary":"Read findings, cost, permits, requirements and waves.","status":"live","docsPath":"https://docs.nika.sh/sdk/local/check-and-plan","eyebrow":"local API · admission","title":"Read the run before it exists.","description":"Turn check and dry-run output into an admission decision over findings, permits, requirements, cost and wave shape.","promise":"check answers whether the file is admissible. dryRunPlan answers what the clean file would ask the engine to schedule. Neither method spends a token or runs a command.","facts":[{"label":"report envelope","value":"report_version 1"},{"label":"plan envelope","value":"plan_version 1"},{"label":"cost meaning","value":"floor + unbounded flag"},{"label":"authority","value":"declared + needed"}],"sections":[{"label":"01 · check","title":"Treat findings as data.","body":"A dirty workflow resolves to a report. Reserve exceptions for process failures such as an unavailable binary so product code can show every finding in one pass.","code":"const report = await nika.check('workflows/release.nika.yaml')\n\nif (!report.clean) {\n  for (const finding of report.findings) {\n    console.error(finding.code, finding.message)\n  }\n}","language":"typescript","filename":"admit.ts"},{"label":"02 · cost","title":"Never read the floor as a ceiling.","body":"The static minimum can be zero while one model remains unpriced. The boolean beside the floor is part of the decision, not optional metadata.","points":["min_path_total_usd is the cheapest statically known path","has_unbounded means at least one spend branch lacks a finite ceiling","a task usd value of null means unpriced, never free"]},{"label":"03 · plan","title":"Inspect waves and authority.","body":"Only ask for the plan after a clean report. The result carries task verbs, wave membership, requirements and permits in one versioned object.","code":"if (report.clean) {\n  const plan = await nika.dryRunPlan('workflows/release.nika.yaml')\n  renderPlan({\n    waves: plan.waves,\n    tasks: plan.tasks,\n    permits: plan.permits,\n    requirements: plan.requirements,\n  })\n}","language":"typescript","filename":"plan.ts","ascii":"[ check ]\n    │ clean\n    ▼\n[ plan v1 ] ── waves\n    ├───────── permits\n    ├───────── requirements\n    └───────── cost floor"},{"label":"04 · skew","title":"Survive additive engine releases.","body":"Unknown report or plan versions keep the known subset and append driver warnings. Product code should surface those warnings and retain raw for diagnostics."}],"related":[{"label":"LocalNika client","to":"/sdk/local/client"},{"label":"Run and cancel","to":"/sdk/local/run-and-cancel"},{"label":"Cost honesty","to":"/blog/the-two-clocks-behind-a-model-string"},{"label":"Machine surfaces","to":"/how/proof"}]}

local API · admission

Read the run before it exists.

Turn check and dry-run output into an admission decision over findings, permits, requirements, cost and wave shape.

check answers whether the file is admissible. dryRunPlan answers what the clean file would ask the engine to schedule. Neither method spends a token or runs a command.

Treat findings as data.

A dirty workflow resolves to a report. Reserve exceptions for process failures such as an unavailable binary so product code can show every finding in one pass.

const report = await nika.check('workflows/release.nika.yaml')

if (!report.clean) {
  for (const finding of report.findings) {
    console.error(finding.code, finding.message)
  }
}

Never read the floor as a ceiling.

The static minimum can be zero while one model remains unpriced. The boolean beside the floor is part of the decision, not optional metadata.

min_path_total_usd is the cheapest statically known path
has_unbounded means at least one spend branch lacks a finite ceiling
a task usd value of null means unpriced, never free

Inspect waves and authority.

Only ask for the plan after a clean report. The result carries task verbs, wave membership, requirements and permits in one versioned object.

[ check ]
    │ clean
    ▼
[ plan v1 ] ── waves
    ├───────── permits
    ├───────── requirements
    └───────── cost floor

if (report.clean) {
  const plan = await nika.dryRunPlan('workflows/release.nika.yaml')
  renderPlan({
    waves: plan.waves,
    tasks: plan.tasks,
    permits: plan.permits,
    requirements: plan.requirements,
  })
}

Survive additive engine releases.

Unknown report or plan versions keep the known subset and append driver warnings. Product code should surface those warnings and retain raw for diagnostics.