JSON Contract

Stability

Every machine document declares its schema. Command results use schema; domain artifacts use schema_version. Consumers must branch on that identifier rather than the installed binary version.

The current artifact identifiers are:

Within an artifact schema major version:

• Existing field meaning will not change.
• Enum values will not be silently reinterpreted.
• New fields may be added.
• Consumers should ignore unknown fields.
• Native paths in command diagnostic context and artifact references use a lossless tagged UTF-8 or Unix-byte representation. Historical artifact path fields retain their existing compatibility representation.

Standard output

Pass global --output-format json or its compatible --json alias before or after the subcommand. When structured rendering is possible, standard output contains exactly one complete optiflow.command-result.v1 document and a trailing newline for success, partial success, and blocking failures. Do not parse human output.

Example:

optiflow \
  --output-format json \
  --state-directory "/tmp/optiflow-state" \
  scan "/data/media" > "optiflow-result.json"

The process status exactly matches outcome.exit_code. JSON stdout never contains banners, progress text, warnings, color, or logs. Diagnostics remain inside the envelope; JSON-mode stderr stays empty during ordinary rendering. The renderer buffers the full document before writing it.

Before this contract, --json scan, report, and plan wrote the domain value directly. They now wrap that value in result, with committed outputs listed in artifacts. This is a pre-1.0 machine-output compatibility change. Immutable v1 through v4 artifact schemas were not changed.

New v5 run and plan documents and v5-v6 report documents are accepted only with a matching optiflow.artifact-set.v1 marker. The marker records member schemas, lossless relative paths, byte lengths, and BLAKE3-256 digests. See the artifact-set commit protocol for reader and recovery behavior.

See CLI Outcome Contract for the exit-code matrix, typed diagnostics, partial-run semantics, stream ownership, and signal behavior. See Configuration and Effective Policy for policy canonicalization, provenance, fingerprints, and historical sidecars. See the safe extension SDK for exact provider identity, operator locks, effect grants, result acceptance, and compatibility behavior.

Reports

Reports embed:

• The immutable run manifest
• Aggregate counts and reclaimable bytes
• Exact duplicate groups and evidence
• Complete observations, warnings, cache facts, and optional media descriptors
• Versioned media-profile coverage, limitations, provider identity, normalized evidence, and review opportunities

New runs also commit a validated effective-policy.json sidecar. Its immutable location is derived from the run's existing artifact_directory; historical runs without it remain reviewable with explicitly unknown policy evidence.

Report v6 embeds optiflow.media-profile-evidence.v1. The initial optiflow.builtin.lossless-png-review@1.0.0 profile never creates an output and always records savings as not_estimated; see Media-profile evidence.

Plans

Plans contain no executable mutation in v0.1.0. Each action includes:

• Exact relationship evidence
• A deterministic review default
• Candidate paths
• Potential reclaimable bytes
• Size, time, and hash preconditions
• Required future apply-time re-hashing and byte confirmation

flow should retain both the report and plan as provenance artifacts when it invokes optiflow. Other consumers should do the same when reproducibility matters.

Execution evidence v1 (development source)

schemas/execution-v1.schema.json contains closed definitions for optiflow.execution-plan.v1, execution-approval.v1, execution-run.v1, execution-attempt.v1, execution-validation.v1, execution-commit.v1 and execution-recovery.v1 (all with the optiflow. prefix). Runtime validation checks both schemas and fingerprint/scope/authority invariants. Existing review plans are not migrated to execution authority. Future versions and unknown or duplicate keys fail closed. See execution previews for canonical fingerprints, examples and compatibility rules. Frozen examples live in tests/fixtures/execution-v1/.