`crucible measurement`¶

Measurement envelopes are append-only observational sidecars. measurement validates them and does nothing else: it reads one bounded local JSON file and, for a correction, its complete oldest-to-newest predecessor chain. It does not collect usage, follow source locators, persist state, execute targets, access the network, update an index, or grant authority.

Stable. Built by make build, covered by pkg/measurement tests.

Commands¶

Command	Purpose
`crucible measurement validate <envelope.json>`	Validate one envelope, optionally against its predecessor chain

measurement itself takes no action; it is the parent of validate.

`measurement validate`¶

crucible measurement validate <envelope.json> [flags]

Exactly one envelope path, as a positional argument.

Flag	Default	Meaning
`--prior`	none	A predecessor envelope, in oldest-to-newest order. Repeat once per predecessor; the chain must be complete
`--json`	`false`	Emit the validation receipt as indented JSON instead of one summary line

Without --prior the envelope is validated on its own. With one or more, the whole chain is validated in the order given, so a correction is only accepted against the predecessors it claims. A chain of more than 64 envelopes, counting the one under validation, is refused before any file is read (pkg/measurement.MaxCorrectionChain).

A worked example¶

The repository ships a neutral template you can validate immediately. Copy it somewhere temporary so nothing is written back into the checkout:

cp pkg/measurement/testdata/prospective-template.json /tmp/envelope.json
crucible measurement validate /tmp/envelope.json

measurement-envelope VALID id=sha256:6c1b8e403d69486757e8e394c5371dece01c2c107f1a4bdb2baf352f26118232 activity=replace-with-existing-receipt-id projection=PROSPECTIVE correction=0 authority=NONE

The template's activity.id is literally replace-with-existing-receipt-id: it is a shape to copy, not a record of anything.

Machine-readable¶

crucible measurement validate /tmp/envelope.json --json

{
  "valid": true,
  "schema": "crucible.measurement-envelope.v1",
  "measurement_id": "sha256:6c1b8e403d69486757e8e394c5371dece01c2c107f1a4bdb2baf352f26118232",
  "activity_id": "replace-with-existing-receipt-id",
  "projection_mode": "PROSPECTIVE",
  "correction_sequence": 0,
  "authority_effect": "NONE"
}

Field meanings are in the JSON result shapes reference.

Exit behaviour¶

A receipt is written only on success, so valid is true wherever a receipt appears at all. Every failure prints its reason on standard error and emits no receipt.

Exit	Condition
`0`	The envelope, or the whole chain, validated
`1`	Wrong argument count, unreadable file, a file that is not a regular file, malformed JSON, schema violation, or a broken correction chain

Observed failure messages, each from a synthetic input:

Error: accepts 1 arg(s), received 0
Error: open measurement envelope: open missing.json: no such file or directory
Error: decode measurement envelope at $: invalid character 'o' in literal null
Error: invalid measurement envelope: measurement envelope must declare schema_version=1 and kind="crucible.measurement-envelope.v1"

What validation does not mean¶

authority_effect is carried out of the envelope and reported, never conferred. A valid envelope is a well-formed observation; it is not a decision, a budget grant, or evidence that the activity it describes happened. Nothing downstream should treat a passing validation as permission.

crucible measurement¶