Project runtime state

Source describes intent. .nika/ records what the machine did. A production deployment should choose storage and retention for that distinction before it runs its first armed beat.

State map

The unified tree below assumes the recommended setup: direct processes use the project root as cwd.

PROJECT STATE · TWO JOURNALS, TWO QUESTIONS

Verify a run trace through the SDK

const verdict = await nika.traceVerify()

if (!verdict.intact) {
  throw new Error(verdict.output)
}

console.log(verdict.head, verdict.exitCode)

The SDK verifies the run journal. nika arm reads the arming sidecar. They are related evidence, but they are not interchangeable. A direct SDK run stores its journal under cwd/.nika/traces; arm and serve enter the project root before the workflow run starts.

Persist the clock on servers

A resident server or OS unit needs a durable project state path. If a container discards .nika/ on restart, it also discards recent traces and the watermark used to reason about missed slots.

The firing contract is at-least-once. A crash after a durable claim and before its receipt leaves an unmatched claim in history.ndjson. Keep external effects idempotent when a repeated fire must be harmless.

Source-control boundary

.gitignore

.nika/traces/
.nika/arm/
.env

Ignoring live state does not mean deleting it on deployment. Mount, back up or export it according to the workload’s evidence and retention policy.

Evidence lifecycle

project source ── review ── deploy
                               │
                               ├── arm claim
                               ├── run trace
                               ├── arm receipt
                               └── selected evidence export

Export evidence deliberately. Do not turn the entire state directory into a public application artifact.

Continue

Receipts and replay

Verify and replay the workflow journal.

Resident server

Operate the process that writes arming state.

Arm registry

Understand what the ledger is proving.

CWD and monorepos

See exactly which root owns each state lane.

Trace concepts

The durable run journal and its integrity chain.

Overview

Start

Project · live

Local API · live

Runtime · live

Remote API · preview

Operations

Reference

Project runtime state

State map

Verify a run trace through the SDK

Persist the clock on servers

Source-control boundary

Evidence lifecycle

Continue

Receipts and replay

Resident server

Arm registry

CWD and monorepos

Trace concepts

​State map

​Verify a run trace through the SDK

​Persist the clock on servers

​Source-control boundary

​Evidence lifecycle

​Continue

Receipts and replay

Resident server

Arm registry

CWD and monorepos

Trace concepts

State map

Verify a run trace through the SDK

Persist the clock on servers

Source-control boundary

Evidence lifecycle

Continue