Artifact reference

Local planning and post-merge publication serve different purposes and have separate schema lifecycles. Use tool-produced evidence where specified; do not fabricate captured inputs, identities or publication outcomes.

You choose output destinations and are responsible for their placement relative to source, configuration, existing evidence and other data. Commands write to the supplied locations without checking for input collisions. Each writer manages only its documented artifacts and owned workspace directories.

Preview validates captured inputs before invalidating its previous completion marker. Missing or malformed preparation and stale captured inputs leave that marker untouched. An existing completion marker does not prove that the captured inputs are still valid; consumers still check those inputs.

Captured source inputs

Preparation and preview capture declared inputs, Git-tracked files and source-directory contents. Source directories include src and dedicated custom target or build-script directories below each package root, including path dependencies. A target at the package root or outside it contributes its declared file without recursively capturing the package root or its ancestors.

Supporting modules and other build inputs outside those source directories must be Git-tracked. Use git add; a commit is not required. The tool does not interpret Rust modules or invoke a compiler to discover additional inputs.

Local decisions and plans

A decisions document is caller-authored literal JSON:

{
  "schema_version": 2,
  "changes": [
    { "name": "widget", "impact": "nonbreaking" },
    { "name": "widget_impl", "impact": "patch" }
  ]
}

changes[].impact is semantic: breaking, nonbreaking or patch. Non-publishable packages have no semantic impacts.

The proposed-plan format uses report/plan schema revision 8. This is a literal example of that format:

{
  "schema_version": 8,
  "increments": [
    { "name": "widget", "bump": "minor" },
    { "name": "widget-cli", "version": "2.0.1" }
  ]
}

increments[].bump is numeric: major, minor or patch. Supply exactly one of bump and version per entry. Names select tracked workspace members; group members expand together. Explicit targets cannot lower declared versions, and group targets use plain major.minor.patch versions.

Preview produces an expanded plan with explicit package versions and the resolved source/files needed for application, including resolved file contents, original inputs and evidence_manifest_path.

Treat prepared.json and the resolved object as opaque. Preserve them intact; regenerate unsupported or stale evidence with prepare and preview.

Reports

The revision-8 report’s top level contains:

Each publishable entry includes name, declared_version, status, changed, stat, dependencies, public_origins, dependents, consumer_contract and proc_macro. Optional evidence includes its group, anchor, patch path and advisory untracked files. An anchor can identify a release-history version change or the final snapshot of an anticipated parent version; the report’s history/target fields identify that context.

Changed entries distinguish:

Dependencies record name, req and exact_pin. public_origins is the sorted set of defining workspace package names exposed directly or through another exposed owner’s API. It is independent of the dependency paths supplying the types and is required even when empty. consumer_contract is true for a library offering a supported API for direct consumers, rather than declaring private-api = true. proc_macro independently records Cargo’s procedural-macro library target kind. Both booleans are required. A public macro can have both true while remaining unsupported for direct comparison. Neither flag removes semantic, dependency or publication obligations.

Non-publishable packages carry name, declared_version and an optional group, not a status or semantic impact. Group records include complete sorted members and their highest declared version.

Patch paths are relative to the report directory. Patches are zero-context unified file diffs, not the complete report. An inherited-only or lockfile-only change can have no patch.

A report’s HEAD alone does not prove that an arbitrary dirty checkout matches the evidence. check-compatibility regenerates a bound read-only report from prepared inputs, a resolved preview or a fresh source assessment. It does not accept a detached report.

Release context

release-context prints JSON with these fields:

This is acquired context, not publication intent. Save it for the local planning run and reuse its history/target pair. Refresh both before application; do not replace either beneath prepared evidence.

Compatibility evidence

Each check-compatibility invocation uses a new output directory and writes compatibility.json, semver-checks.log and a regenerated read-only report. The evidence retains checker identity and exact comparison versions. Its linked report identifies any anticipated-parent anchor supplying the comparison source.

Compatibility evidence uses schema 3:

Each comparison record contains name, compared, nullable baseline_version, and nullable required_impact. A compared package uses a published version or its anticipated parent’s version and final source. An unavailable comparison has compared: false and no comparison version or required impact. Unavailable records also contain not_compared_reason: unsupported-proc-macro for a target the checker cannot compare directly, or no-baseline for a supported target without a comparison version. Compared records omit this field. Affected macro records include private packages and macro members of affected version groups; unrelated unchanged packages need no record. An operational failure can leave only earlier completed records; inspect the overall completion flag and retained diagnostics rather than treating absent records as passes.

Require completed: true before using the result. A package’s compared: false means no comparison was available, not proof of compatibility. required_impact is a semantic breaking or nonbreaking floor; null establishes no minimum. The author still judges behavioral, CLI, format and feature-subset effects. This includes APIs and behavior supplied through re-exports, which are not fully covered by the checker, and macro invocation syntax and generated code. See semantic assessment.

Do not confuse a completed comparison with a passing merge gate: --deny-findings additionally rejects insufficient increments. Source inputs are checked at command entry. Callers and tools invoked for read-only work must keep assessed source, configuration and history unchanged during comparison; operational errors never become semantic passes.

Artifact-only command output

analysis-order emits a dependency-first array:

[
  { "order": 1, "packages": ["widget_impl"], "cyclic": false },
  { "order": 2, "packages": ["widget"], "cyclic": false },
  { "order": 3, "packages": ["widget-cli"], "cyclic": false }
]

This example assumes those are the publishable packages. Every publishable member appears once, including unchanged ones; non-publishable packages do not. Cycle batches represent actual dependencies, not group alignment.

semver-targets emits sorted directly checkable public package names, or [] when none are selected. Procedural macros are excluded regardless of consumer policy; their public version-group members remain eligible. inspect-plan emits:

{
  "publication_targets": ["widget", "widget-cli", "widget_impl"],
  "evidence_manifest_path": null
}

This example represents structural inspection without retained preview evidence. For a resolved artifact, the manifest path identifies the verified prospective workspace. Request --require-resolved before relying on that workspace for the complete local release flow.

Publication manifest

prepare-publish creates this envelope:

{
  id,
  publication: {
    schema_version: 1,
    tool_version,
    source,
    workspace_manifest,
    config_path,
    configuration,
    packages: [
      { name, version, manifest, binary: null | { name, targets } }
    ]
  }
}

This is a field-shape sketch, not JSON input. source is the full publication commit. Workspace, package and configuration paths are repository-relative. configuration captures the effective committed configuration. A binary’s name is the executable name, not necessarily its package name.

The package array includes every publishable exact version at that source, including unchanged packages, and excludes non-publishable packages. The artifact records producer identity and schema independently of local-plan schemas.

id links subsequent work to the captured payload. It is an integrity and linkage check, not a signature or independent authorization. A fetched branch tip is not part of the captured intent digest. Do not change the payload, recompute its identity by hand or add mutable publication flags.

Registry outcome

Registry outcomes use schema 1 and record:

The exact state spellings are:

A dry run never sets complete to true. Use the outcome and command diagnostics together; unknown queries and partial failure are not reduced to successful skips. Each attempt writes a new outcome path.

GitHub outcome

GitHub reconciliation outcomes use schema 1:

Each package record contains name, version, tag and state, with these state spellings:

The nullable source field retains an observed commit identity. A failure can retain an unverified observation; this field alone does not authorize a build. The nullable recovery_source is the original publication source retained for missing-tag recovery, while observed_version is the candidate version when available. Failures need not have missing-tag recovery evidence.

A dry run never sets the outcome’s complete field to true. A live complete GitHub outcome does not imply that its binary archives are uploaded. Each batch path is relative to the separately emitted batch directory; retain those files and the parent publication manifest alongside the outcome.

Platform batch

publish github produces a separate schema 1 platform-batch file for each selected native target. Its shape is:

{
  schema_version: 1, publication_id, repository, target, batch_id,
  binaries: [{name, bin, version, tag, source_sha}]
}

This is a field-shape sketch, not caller-authored JSON. name identifies the Cargo package and bin its executable. source_sha is the frozen peeled package-tag commit. publication_id identifies the parent manifest; batch_id identifies the batch’s exact work, including those source commits. repository and target retain their configured identities.

Binary outcome

publish binaries produces a schema 1 outcome:

{
  schema_version: 1, publication_id, phase: "binaries",
  target, no_upload, complete, batch_id,
  github?: {run_id, run_attempt},
  items: [
    {
      binary: {name, bin, version, tag, source_sha},
      status, stage, diagnostic, cleanup_error
    }
  ]
}

github is omitted outside GitHub Actions. Item diagnostic and cleanup_error values are nullable strings. The supported status/stage combinations are:

A failed item includes a diagnostic. Cleanup failure is recorded separately without replacing the item’s operation status. complete requires successful upload-mode results for every requested binary and no cleanup failures. no_upload staging never establishes delivery completion.

Retain the original manifest and platform batch with these outcomes. Consume the tool-produced artifacts rather than synthesizing them; their identities and attempt ordering are required evidence for reporting.

Derived batches and later outcomes

GitHub reconciliation emits new platform batches linked to the original manifest. A batch fixes the native target, package versions, executable names, tags and actual peeled tag commits. Its stable batch_id binds that content; each outcome routing entry supplies target, relative path and batch_id. Those observations do not get written back into the original manifest.

Native execution refreshes remote completeness before building. Later reconciliation can emit another batch for remaining work without mutating an older batch. Binary outcomes link both the publication and batch identities. Phase outcomes include optional github: {run_id, run_attempt} metadata, which the workflow preserves across artifact transport.

An older successful binary outcome cannot satisfy newer GitHub evidence of missing assets. This remains true when the new batch contains exactly the same requests and therefore has the same batch_id. Its outcome must be at least as new as the selected GitHub reconciliation.

Consume these artifacts through the matching tool/action interface rather than writing them manually. Missing or incompatible artifacts require explicit recovery; they are not a valid empty work set.

Reporter job results

publish report --jobs reads a JSON object with fixed keys. Each value is one of success, failure, cancelled or skipped, taken from GitHub’s workflow job-result context rather than the broader check-run conclusion vocabulary:

{
  "prepare": "success",
  "registry": "success",
  "github": "success",
  "binaries": "success"
}

This demonstrates the format, not a default successful state. Supply observed results from the current workflow; binaries is the binary matrix job result. Skipped required phases are incomplete. A skipped binary matrix is acceptable only when the selected GitHub outcome requires no platform batches. Do not omit failed/skipped jobs, rename keys after your caller’s display names, or synthesize success from existing assets.

The reporter recursively reads outcome.json files beneath --outcomes, retaining their artifact subdirectories and run/attempt linkage. It compares the latest applicable outcomes with current job results and the original manifest. Old successes cannot hide failed jobs or newer missing-asset evidence.

--output names the new Markdown report. The command can report and file a failure issue without the publication manifest, but always marks that case incomplete. --no-issue suppresses issue writes, not GitHub-context validation or incomplete-delivery failure.