Skip to main content
Every run writes a hash-chained record. The result hands your code a receipt, an engine-issued pointer to that record, and nika.traceVerify(receipt) asks the engine to check the record against it. The SDK never reads a trace or does cryptography itself.
verify.mts
That is a machine with a run-signing key in ~/.nika/keys/ (quickstart step 2). Without one, the same run succeeds and prints false invalid receipt_mismatch and sealed: false.

Admitted, executed, sealed: three different facts. check() refuses a file that runs ls under permits: {} (NIKA-SEC-004, with its fix) and run() never starts it: no run, events or trace exist. One permits line fixes it. On a machine with no signing key, prove.mts runs hello.nika: the run succeeds, its receipt reads sealed false · 5 events and traceVerify(receipt) answers receipt_mismatch. After the quickstart’s NIKA_KEYCHAIN=off nika key init (step 1 in the SDK README on GitHub, as the comment on screen says), the next run reads sealed true · 6 events and verified. Then tamper.mts changes one byte on line 4 of the trace, and the stored receipt no longer verifies: the engine reports BROKEN at line 5. Recorded in a terminal from @supernovae-st/nika 0.123.0 and its bundled engine nika 0.123.0 (0bfde3765); every model call is mock/echo, the engine’s offline rehearsal model, with no provider key and no network.

What the verdict means

Measured with @supernovae-st/nika 0.123.0 on both transports: Over HTTP, the server runs the CLI verifier on the journal it wrote for the job and answers in the CLI’s words, lower case: ok, sealed, anchored and replayed hold; incomplete, tampered and broken do not; unavailable means the server holds no journal for that job (refused before its first event, or still queued). The SDK sets verified: true only for a verdict that holds and names this receipt’s trace_id.
verified: true therefore means different things on the two doors. When the signature matters, require verdict === 'sealed' over HTTP, or receipt.sealed === true with verdict === 'verified' locally. Locally, receipt_mismatch is also the answer for an edited or forged receipt: do not read every one as “just unsigned”.

What a receipt carries

Pass a receipt back exactly as you received it.
  • A local receipt carries trace_path, chain_head, chain_len, sealed, trace_id, execution_id, snapshot_digest and receipt_format.
  • A nika serve receipt carries job_id, execution_id, trace_id, snapshot_digest, origin ({ kind: 'manual' } for a job your code submitted) and chain_head. Store it with the job id.

Keep a local receipt verifiable

A local receipt points at its trace file by a path relative to the client’s cwd, and that file is subject to retention:
  • Verify it from a client with the same cwd. From another directory, or once the file is gone, traceVerify(receipt) answers verdict: 'invalid' with exitCode 3 and no reason: the engine cannot read the trace.
  • By default the engine keeps the last 10 traces per workflow, at most 30 days old, within 256 MB. NIKA_TRACE_KEEP, NIKA_TRACE_MAX_AGE_DAYS and NIKA_TRACE_BUDGET_MB change the three bounds, and traces.keep in nika.yaml sets the age cap. For long-lived audit evidence, export a dossier (journal, manifest, receipt and VERIFY.md) when the run ends:
    The pack is redacted by default: it proves the run’s integrity, not its content. --full includes the content verbatim.
  • Store receipt.trace_id and receipt.execution_id to identify a run. run.id is a throwaway id on the local transport.

Inspect a trace from the command line

A verified record proves the record is intact and matches the receipt. It does not prove that the workflow was right, or that a person read its output: it is tamper-evident, not tamper-proof. Traces explains the evidence tiers.

Run receipts pattern

Carry receipts through application boundaries.

Traces

The journal under the receipt.