Evidencectl workflow reference

View as Markdown

evidencectl is Evidence Gateway adopter tooling. It creates key material and editable projects, compiles production candidates, and invokes the evidence binary for Evidence Gateway semantic decisions. It does not approve, deploy, promote, register production clients, or write production secret values. Its client registration commands manage local development only.

Contract status

Evidencectl is outside the frozen Evidence Gateway Version 1 runtime contract. Its command line can change before a compatibility promise covers it. Evidencectl compiles editable authoring input into a closed bundle. The evidence runtime remains the authority for bundle validation and semantic acceptance, fixture evaluation, secret validation, and startup acceptance. The canonical adopter commands do not change the numeric Evidence Gateway Version 1 runtime.yaml grammar or the existing evidence-project.yaml marker.

Project workflow

Command	Inputs	Result	Does not do
`evidencectl check <project>`	Editable project	Reports authoring completeness and field-addressed findings	Claim deployment closure, run fixtures, resolve secrets, or contact a dependency
`evidencectl check <project> --target <target>`	Editable project and one explicit target	Adds the target’s governance, runtime structure, public keys, source connections, and governed-bundle validation	Require target-host paths or secrets to exist, run fixtures, or contact a dependency
`evidencectl check <project> --target <target> --production`	Editable project and one explicit production or evidence-grade target	Refuses incomplete deployment closure under that target’s own assurance profile	Select a target, upgrade its profile, or prove live readiness
`evidencectl explain <project> [--target <target>]`	Editable project and optional explicit target	Applies the same offline authoring validation, then reports status, findings, revision, and the authored inventory; includes target governance only when selected	Contact sources or expose secret and subject values
`evidencectl package <project> --target <target> --output <new-candidate>`	Editable project and one explicit production target	Creates a new candidate with `runtime.yaml` and closed `bundle/`	Overwrite output, contact source services or OIDC, create production secrets, or start a listener
`evidencectl test <project>`	A deployment project with `runtime.yaml`, or an editable project with `questions/` and `sources/`, plus referenced synthetic fixtures	Uses runtime `check` and `evaluate` for a deployment; privately compiles an editable project, then uses runtime `bundle-check` and `bundle-evaluate`	Start HTTP, call a source, or write a production audit entry
`evidencectl test <candidate> --explain`	The same, and asks each evaluation to explain itself	Relays each fixture’s stage trace beside its step, or as that fixture’s `trace` field under `--format json`	Print a response, fact, derived, or selector value, or explain a served request
`evidencectl doctor --runtime-config <absolute-file>`	Runtime file on its target host	Runs the runtime-owned startup dependency preflight without opening the public listener	Send an Evidence request or establish that a fixture passed
`evidencectl artifact inspect <candidate>`	Completed candidate	Inspects artifact custody without contacting dependencies	Establish live dependency readiness

package is create-only. It rejects an existing output directory, unauthenticated or non-HTTPS production HTTP sources, source transports with no stated production conditions, missing governance metadata or fixtures, unresolved review markers, unknown fields, symlink traversal, and references outside the allowed project directories. A failed package publishes no candidate.

An ordinary check can succeed with status: incomplete and visible findings. Add --deny-findings when any finding must refuse the command. All findings carry severity, code, artifact, path, message, and suggestedAction. Human output is the default. Add the global --format json option for the same result as structured JSON. A command that provides no JSON report accepts only --format human, and the CLI reference shows which commands those are; --format json on one of them is the usage error evidencectl.format.unsupported.

The workflow exit classes are 0 for success, 1 for a domain refusal or denied finding, 2 for command-line usage, and 3 for an operational failure. These classes belong to adopter tooling; they do not change the Evidence Gateway runtime verifier’s frozen exit contract.

Compatibility spellings

The released new, fixtures run, and build spellings remain available during the command transition. New projects, examples, and current procedures use init, test, and package. The doctor --project <candidate> compatibility form retains artifact inspection; use artifact inspect <candidate> for that operation and reserve doctor --runtime-config for live startup dependency checks. Do not combine a canonical positional project with its former --project flag; conflicting old and new forms are usage errors. Request preparation uses --response-format signed-jws|sd-jwt-vc so the response choice cannot collide with global report formatting. The released request prepare --format spelling remains accepted only for those two legacy response values. Supplying both response selectors is a usage error.

Production input reference

An editable project becomes a production build input only after it has:

A fixtures/ regular file referenced by every production question.
Stable concept identifiers and production governance metadata in every question.
<target>/governance.yaml with bundle-owned fields for one environment.
<target>/runtime.yaml with one environment’s runtime bindings.
Public JWK files beneath <target>/ for every active and published service key referenced there.

governance.yaml is strict. It must carry version 1, an assuranceProfile of production or evidence-grade, service, issuer, authentication, audit, subject binding, rate limits, signing, optional response formats, and authority profiles. It cannot supply selector profiles, sources, or requirements. It accepts logical secret:file/<name> references, not values or absolute secret paths.

The output runtime document is copied byte-for-byte. Its paths and secret posture are accepted only by the final target-host evidence check.

The maintained reference layout keeps the editable project under shared/evidence-project/ and each complete deployment target under environments/<target>/evidence/. That layout is a repository convention, not part of the --target path grammar. Do not use overlays, environment branches, symlinks, or runtime substitutions. Git contains public keys and nonsecret provider configuration, but no private JWKs, HMAC keys, provider tokens, auto-auth credentials, access tokens, live responses, or real identifiers.

Local-only commands

evidencectl init requires a destination and exactly one authoring source:

evidencectl init <directory> --openapi <path-or-https-url> --profile local
evidencectl init <directory> --transport sqlite-extract --profile local

OpenAPI mode creates an authoring workspace whose source, question, and fixture directories remain empty. SQLite mode creates a synthetic source, question, query, adapters, schemas, derivation, and fixture. Both create disposable, unbound Evidence Gateway key material in the ignored owner-only secrets/ directory. Neither creates a production target, issuer configuration, or deployable bundle.

evidencectl dev start [<project>] starts Evidence Gateway and the pinned local issuer on loopback. When borrowing a shared issuer, pass --issuer-project <owner> and an exact --resource <URI> registered for this Evidence Gateway service. The default resource is urn:registrystack:evidence:local:gateway; a retained session keeps its selected resource and refuses a different one on restart. The compiled governed bundle binds this audience. For a nondefault resource, the compiler also derives distinct governed provider, issuer, and service identifiers from that resource, so multiple local Evidence services remain separate in Discovery.

It creates a session-scoped P-256 pair for an SD-JWT VC holder and an implicit caller pair only when the project has no explicit access policy; explicit local clients use their keys under .evidence/clients/. Nothing under .evidence/dev or .evidence/clients enters a production target.

evidencectl dev token <client> [<project>] obtains a fresh service token and writes an owner-only Authorization header file under .evidence/dev/generated/keys/. It reports the path and never prints the token. Task grants come from the configured Casework authority and are not static local client attributes.

evidencectl access manages caller access for one local project:

Command	State	Result
`evidencectl access policy add <policy> --question <question>`	Creates `access/policies/<policy>.yaml`	Defines one or more repeated `--question` values for the next Evidence Gateway generation
`evidencectl access policy list`	Reads `access/policies/`	Lists the governed local policies and their questions
`evidencectl access client add <client> --policy <policy> --generate-local-key`	Creates `access/clients/<client>.yaml` and `.evidence/clients/<client>/private.jwk`	Registers a local client for repeated `--policy` values with non-overlapping question sets
`evidencectl access client list`	Reads `access/clients/`	Lists local client status and policy membership
`evidencectl access client revoke <client>`	Updates `access/clients/<client>.yaml`	Revokes the local client for the next issuer generation and removes `.evidence/clients/<client>/`, the client’s local private key

For an institutional task exchange, author an optional taskGrant on the policy with its kind, exact sourceIssuer, active requesterClients, and one bindings entry for each question, subject role, and selector alternative. Each binding maps the selector’s complete field set to verified access-token valueClaims. The compiler emits authenticated-grant origins and binds the policy tag to the full grant semantics; it refuses revoked, unassigned, or incomplete requester bindings. Create the requester with evidencectl access client add <client> --policy <policy> --generate-local-key --grant-bootstrap-scope <scope>. Use --grant-bootstrap-resource <URI> only if its issuer bootstrap resource differs from the shared issuer owner’s default. The borrowed issuer must register that same key and bootstrap binding for institutional exchange. A direct client omits both bootstrap flags. For a portal that signs first-party context, create an active policy client with --first-party-bootstrap-scope evidence:invoke --first-party-bootstrap-resource <Evidence resource> --first-party-issuer <issuer>. The borrowed owner must register the same client key and bootstrap permission, and an exact first_party exchange issuer. Its bootstrap registration carries no static Evidence requester tags or audience; the signed context supplies those attributes for each request. The client still needs an active Evidence policy assignment and cannot use a task-grant policy.

Public, reviewable local access configuration lives under access/. Owner-only private client keys live only under .evidence/clients/. Generated issuer resources under .evidence/dev/generated/issuer/ are disposable.

Stop the local development session before adding or revoking a client. The next start validates the complete client and policy registry, then provisions it as one issuer generation. A policy change also requires a new Evidence Gateway generation.

The local access commands do not define production authority or production clients. Production authority profiles remain in the deployment target’s governed governance.yaml. Production client registrations remain in the deployment’s governed OAuth issuer. Files under access/ and .evidence/ do not become production candidate inputs.

Use keygen, source suggest, request, verify, and audit for their documented authoring or local inspection roles. Do not use a local request, local audit record, or disposable key as a production candidate input.

Editor support

evidencectl tooling groups the two commands that serve an editor rather than a deployment.

Command	Inputs	Result	Does not do
`evidencectl tooling editor --project <project>`	Editable project directory, defaulting to the current directory	Writes the project-local schema mappings VS Code and Zed read, and reports all six managed files	Install an extension, change editor settings outside the project, or replace a file it did not write
`evidencectl tooling language-server`	No arguments; speaks the Language Server Protocol over standard input and output	Reports Evidence Gateway authoring diagnostics for every document it indexes in the project, not only the open one	Open a socket, contact a source, read source values, or observe SQLite

tooling editor writes six files into the project:

.evidence-editor/manifest.json
.evidence-editor/schemas/project-marker.schema.json
.evidence-editor/schemas/question.schema.json
.vscode/extensions.json
.vscode/settings.json
.zed/settings.json

Commit all six with the rest of the project. They are generated, nonsecret configuration matched to the schemas the checks apply, and the .gitignore that evidencectl init writes excludes secrets/ and .evidence/ only. A later run refreshes exactly what an earlier run recorded writing. A managed file someone has edited by hand stops the command, which names that file and changes nothing.

The mappings cover evidence-project.yaml and questions/*.yaml, the two document kinds a Rust type stands behind. Sources, selectors, derivations, answer schemas, and fixtures carry no static schema; the language server checks those.

A diagnostic in your editor carries the sentence evidencectl reports for the same input, because both read one shared set of authoring checks. Fixing what the editor reports satisfies the command line for that rule. The editor bounds a message at 1024 characters.

Base Registry Engine projects

The language server serves Evidence Gateway and Registry Relay projects. A Base Registry Engine (BReg) project is neither, and it names its own project document registry.yaml. The editor tooling in this page reports nothing about one, and starts no language server over one.

BReg publishes its authoring JSON Schemas as registry-project.schema.json and registry-module.schema.json. No command writes a mapping for them, so copy both into the BReg project and map them yourself in .vscode/settings.json:

{
  "yaml.schemas": {
    "./schemas/registry-project.schema.json": "registry.yaml",
    "./schemas/registry-module.schema.json": "modules/*/module.yaml"
  }
}

The generated evidencectl syntax is published only after its exact source version receives a recorded human review.