# 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](../consumers/publish.md) owns storage placement,
permissions, retention, and sensitive-data handling. The
[CLI reference](../cli.md) owns command behavior, path selection, and exit
statuses; the exported Go contract is documented in [GoDoc](../../recovery.go).

## Private attempt record

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

```json
{
  "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](../consumers/publish.md#retain-and-reconcile-publication-evidence).

## 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:

```json
{
  "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:

```json
{
  "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](../cli.md#recover-a-saved-publication-attempt-or-discover-local-attempts)
for invocation and status behavior.