releasekit/docs/integrations/publication-records.md

Publication records and recovery output

This guide describes the supported private publication-record envelope and the versioned JSON documents emitted by the recovery CLI. The publication consumer guide owns storage placement, permissions, retention, and sensitive-data handling. The CLI reference owns command behavior, path selection, and exit statuses; the exported Go contract is documented in GoDoc.

Private attempt record

Each saved attempt is one complete JSON document with this versioned envelope:

{
  "format_version": 1,
  "evidence": {
    "repository_dir": "/work/project",
    "module_dir": "/work/project",
    "module_path": "example.com/project",
    "version": "v1.2.3",
    "tag": "v1.2.3",
    "candidate_commit": "<full Git object ID>",
    "tag_object": "<full Git object ID>",
    "endpoint": "ssh://git.example/owner/project.git",
    "remote": "origin",
    "recorded_at": "2026-11-02T12:00:00Z"
  }
}

The format version is an integer. Evidence fields may be absent when publication stopped before they were captured; loading preserves that partial evidence and does not fill fields from the current checkout. Additional fields in a supported version are ignored. A missing or unsupported version, malformed or multiple JSON documents, or fields with invalid structural types are reported as record-format errors. The codec supports versions 1 and 2; no migration from an unsupported version is performed.

Ordinary UTF-8 evidence uses version 1. Evidence containing other pathname or endpoint bytes uses version 2 with the same evidence object and an additional evidence_bytes object. Each entry in evidence_bytes uses an evidence field name and a standard base64 string containing its exact bytes. That entry supplies the field's value when loading; the writer omits its lossy string form from evidence. Invalid known-field types or base64 encodings produce a record-format error with the available decoding cause. Unknown field names are ignored. This representation applies to every evidence field and preserves the same identity as typed Go evidence. Older CLIs that support only version 1 report an unsupported version for these byte-containing records; use a CLI supporting version 2 to load them.

The endpoint value is stored exactly as captured and may contain credentials. Private records are sensitive. Do not copy them into public logs or source control. For their location, permissions, and lifecycle, see the publication consumer guide.

Recovery CLI JSON

After valid command arguments, --json emits one JSON document to standard output for both successful and failed recovery operations. Each document has schema_version: 1 and a command name. These are CLI presentation documents, not private attempt records or a Go serialization of public structs.

reconcile includes record_path, safe evidence, and state when a record was read. Available observed_tag_object and observed_commit fields are included when present. A diagnostic is included for unresolved observation or record loading failure. Loading failure omits evidence, state, and observed IDs.

publication-attempts includes record_dir, an attempts array with each record_path and safe evidence, and a diagnostics array. A top-level diagnostic describes enumeration or cancellation failure. Both arrays are present when empty so consumers can decode the same shape for empty stores.

For example, an unresolved reconciliation can have this shape:

{
  "schema_version": 1,
  "command": "reconcile",
  "record_path": "/private/attempt-abc.json",
  "evidence": {
    "repository_dir": "/work/project",
    "module_path": "example.com/project",
    "version": "v1.2.3",
    "tag": "v1.2.3",
    "candidate_commit": "<full Git object ID>",
    "tag_object": "<full Git object ID>",
    "endpoint": "ssh://git.example/owner/project.git",
    "remote": "origin"
  },
  "state": "unknown",
  "diagnostic": {
    "kind": "remote_observation",
    "message": "<credential-safe diagnostic>"
  }
}

A discovery document always contains both arrays, including for an empty store:

{
  "schema_version": 1,
  "command": "publication-attempts",
  "record_dir": "/private/publication-attempts",
  "attempts": [],
  "diagnostics": []
}

CLI evidence uses the private record's snake-case field names. Endpoint strings in CLI output are credential-redacted; the private record and typed PublicationEvidence retain the exact endpoint. A diagnostic contains kind and safe message, with record_path and missing_fields when applicable. Raw Go errors and private record contents are not emitted as JSON fields.

Consumers should select attempts by their returned record paths and evidence. The listing order is deterministic by path, not a recommendation to choose the first or newest attempt. Unknown fields may be added in later CLI schema versions; reject unsupported schema_version values rather than interpreting them as version 1. See the CLI reference for invocation and status behavior.