AGPL-3.0-or-later · forever.

project state · live

Persist proof, not mystery.

Understand which .nika paths carry run journals, armed-beat claims, receipts and watermarks before a server volume is mounted.

Workflows and nika.yaml are source. .nika is runtime state. A production deployment chooses retention, backup and access policy for each lane instead of treating the directory as disposable cache.

Know every generated lane.

Traces belong to workflow runs. Arm state belongs to the project clock and is partitioned by beat label. The tree below is unified only when the direct process cwd is the project root, which is the recommended server setup.

<project>/.nika/
├── traces/
│   └── <run>.ndjson
└── arm/
    └── <label>/
        ├── history.ndjson
        ├── last.json
        ├── watermark
        └── ledger.lock  # transient

Use the SDK for run receipts.

LocalNika can verify the hash-chained run trace and returns its head and exit contract. The arm report reads the firing ledger separately and distinguishes a declared beat from a proved fire.

const trace = await nika.traceVerify()
if (!trace.intact) throw new Error(trace.output)

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

Give a resident server a durable volume.

Arm and serve enter the discovered project root before firing. A container that loses project/.nika on restart also loses recent triggered-run journals and the cadence watermark used to reason about silence. Mount that project state path with the retention and access controls the workload requires.

Keep generated state out of review diffs.

Ignore the live state by default. Export selected evidence packs or sealed receipts through a deliberate artifact path when a review or audit needs them.

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