124 lines
5.2 KiB
Markdown
124 lines
5.2 KiB
Markdown
# 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.
|