`crucible workspace`¶

workspace reads the project's canonical records and presents them as one normalized, read-only index: workspaces, the studies and attempts under them, evidence bundles, findings, and submission cases. It resolves nothing it cannot cite, and it writes nothing.

Advanced. Shipped and supported, but it reports on records that exist on the operator's machine, so its output is specific to that machine. See Support labels.

Why there is no sample record on this page

Every record this command prints is a real entry from the operator's index, including finding and submission identifiers. Public documentation does not reproduce them, so this page documents the surface: the command tree, the flags, the selector grammar, the exit codes, and the JSON shape. Every exit code and error message below was produced by running the command against synthetic inputs.

Commands¶

Command	Argument	Purpose
`workspace list`	none	List the approved imports, each with its resolved bindings
`workspace show`	`<workspace-id>`	One workspace, with its studies, attempts, evidence, findings and submission cases
`workspace map`	none	The same normalized graph for every imported workspace
`workspace verify`	`evidence:<id>` or `submission:<id>`	Explicitly verify one evidence bundle or submission packet

Flags on `workspace`¶

These are persistent and apply to every subcommand. The four documented subcommands above add no command-specific flags beyond --help.

Flag	Default	Meaning
`--repo-root`	`.`	Repository root holding the canonical records
`--evidence-root`	a host-local path	Root for `banked:` evidence locators. Pass an empty string to record every banked locator as unavailable rather than resolving it
`--json`	`false`	Emit the machine-readable index instead of the human view

--evidence-root "" is the setting to use when you want the command to describe what it cannot reach instead of reaching for it.

Selector grammar¶

verify takes one selector, and only these two forms:

evidence:<evidence-id>
submission:<case-id>

Anything else is a usage error:

Error: selector must be evidence:<id> or submission:<id>

Exit behaviour¶

Exit	Condition	Example
`0`	The command ran and reported	`crucible workspace list`
`1`	A named object does not exist	`crucible workspace show workspace-not-here`
`64`	Usage error: malformed selector, or a selector naming an unknown item	`crucible workspace verify evidence:does-not-exist`

Observed messages, each from a synthetic identifier that exists nowhere:

Error: unknown workspace "workspace-not-here"
Error: unknown evidence item "does-not-exist"
Error: unknown submission item "does-not-exist"

The split matters: 1 says the index was read and the object is absent from it; 64 says the request itself was not usable.

Resolution vocabulary¶

Every field the index resolves carries one of four resolutions, and never a bare value:

Resolution	Meaning
`KNOWN`	A value was read, and the record cites the source it came from
`UNKNOWN`	No authoritative source resolved it. The reason says which kind of absence
`CONFLICT`	Two sources disagree. The conflict stays visible; it is not averaged or preferred away
`NOT_APPLICABLE`	The field does not apply to this record's kind

An UNKNOWN carries a machine-readable reason drawn from a fixed vocabulary in pkg/operatorindex, including MISSING_IDENTITY_BINDING, SOURCE_UNREADABLE, NOT_VERIFIED_ON_CURRENT_HOST, DIGEST_MISMATCH, INCOMPLETE_RECEIPT and UNSUPPORTED_SCHEMA. Two of those are worth reading closely: NOT_VERIFIED_ON_CURRENT_HOST means the bytes were not checked here and now, and DIGEST_MISMATCH means they were checked and did not match.

JSON shape¶

--json emits one object. Its top level is:

Keys are written as JSON paths (.mode) to keep them distinct from command names.

Key	Contents
`.schema_version`	Integer schema version
`.mode`	`"read-only"`
`.source_snapshot`	`repository_revision`, `tree_state`, `repository_root`, `evidence_root`, each a resolution record
`.authority`	What this output does and does not authorise
`.sources`	Every source consulted, with its identity binding
`.workspaces`, `.studies`, `.attempts`, `.evidence_bundles`, `.findings`, `.submission_cases`	The normalized records
`.unassigned_objects`	Objects that resolved to no workspace
`.diagnostics`	Why anything failed to resolve

A resolution record is always the same three fields:

{
  "resolution": "UNKNOWN",
  "reason": "SOURCE_UNREADABLE",
  "sources": []
}

That example is the repository_revision of a run pointed at a directory holding no records, which is the one JSON fragment on this page that contains no operator data. Field-by-field notes are in the JSON result shapes reference.

What this command is not¶

It is an index, not an authority. workspace verify checks bytes against a recorded identity on the current host; it does not establish that a finding is valid, that a submission is ready, or that any decision has been taken. mode is read-only because the command has no write path at all.

crucible workspace¶