Clarify recovery transport settings and partial discovery

This commit is contained in:
2026-11-02 17:57:05 +00:00
parent 58c20fa863
commit 58656dea45

View File

@@ -29,6 +29,8 @@ the [maintainer runbook](../release.md#resolve-failures) describes manual recove
- `internal/git.Endpoint.QueryTag` verifies the captured endpoint's scoped URL
resolution before querying the full tag and peeled ref. Inconsistent exact-ref
records remain unresolved.
- The temporary remote carries selected remote-specific transport settings,
including proxy, upload-pack, and server options, alongside the captured URL.
- The CLI masks HTTP(S) endpoint userinfo in diagnostics. The runbook still asks
maintainers to copy the displayed endpoint and compare remote object IDs.
- There is no public operation or CLI command for later reconciliation, and no
@@ -68,6 +70,9 @@ Reconciliation uses the original captured endpoint and full tag, including neste
module prefixes. It checks that URL rewriting still permits observation of that
endpoint. A changed remote configuration does not substitute a new destination.
Authentication remains locally supplied through the supported Git mechanisms.
The original remote name is optional transport context. Later reconciliation
uses its current supported transport settings while keeping the recorded endpoint
fixed, allowing operators to repair local configuration before observation.
The operation observes remote state without creating, pushing, moving, or
deleting tags, changing branches, validating a candidate, or delivering hosted
@@ -95,6 +100,11 @@ query behavior. Keep immediate failed-push reconciliation bounded and preserve
its existing error context. Later reconciliation should honor caller cancellation
and return an unresolved outcome when observation cannot complete. It should not
invoke the current-remote equality guards that belong to an active publication.
Read the supported transport settings using the recorded remote name when
available, and apply them to the temporary remote with the recorded endpoint.
Keep the endpoint-resolution check. Missing remote settings permit observation
with available endpoint/global configuration; configuration-read failures remain
unresolved with their causes. Distinguish these cases from a changed destination.
### 2. Define public evidence and reconciliation results
@@ -118,6 +128,9 @@ Return a single facade-owned evidence value from publication that reconciliation
accepts directly. Provide a supported record-loading helper returning that same
type so Go consumers can recover without copying fields or implementing JSON
parsing.
Include the original remote name as optional context in typed evidence and saved
records. Recovery uses current connection settings rather than a stored snapshot
of transport configuration; the recorded endpoint retains its identity role.
Keep facade ownership and internal Git boundaries. Exact type names, field names,
and signatures belong in API design; no new public implementation package is
@@ -170,6 +183,13 @@ and recording time when available, with credentials redacted. Record the time
as discovery metadata; it does not establish whether a push occurred. Listing
reads saved records without querying remotes or choosing an attempt for recovery.
Include discovery in the recovery guide for interrupted processes and lost output.
Return readable attempts alongside per-record diagnostics for unreadable,
malformed, or unsupported-format records. Identify the affected paths and retain
credential redaction. Expose entries and diagnostics to Go callers and structured
output; the CLI shows usable entries and indicates incomplete discovery. Report
failure to enumerate the storage location as a discovery failure, not an empty
collection. An explicitly selected unreadable or unsupported record produces its
own error without selecting a different attempt.
Make unresolved diagnostics identify missing evidence, unreadable records,
endpoint rewriting, and failed remote observation distinctly. Identify the
@@ -207,6 +227,13 @@ overridden storage locations, partial records, and credential redaction. Verify
that listing performs no remote observation or automatic attempt selection.
Cover the diagnostic distinctions and expected/observed conflict identities
without requiring incidental error wording.
Cover current remote-specific transport settings, repaired configuration,
missing or renamed remotes, and configuration-read failures. Verify that changed
fetch or push URLs do not replace the recorded endpoint and that endpoint
rewriting still receives the existing check. Exercise discovery containing both
readable and damaged or unsupported records, storage-enumeration failure, and
explicit selection of an unusable record. Preserve useful partial discovery
results and credential-safe diagnostics across the API and CLI.
Run the normal offline suite and facade checks when code lands. Update GoDoc,
CLI documentation, the publication guide, and recovery instructions together.
@@ -232,8 +259,8 @@ this information and the CLI presents it.
Report the record path and require explicit selection for stored-record
reconciliation. Record evidence before the push once the necessary identity
exists. Treat storage failure as a clearly reported loss of the saved handoff,
while preserving the
actual publication result and existing publication prerequisites. An override
while preserving the actual publication result and existing publication
prerequisites. An override
changes the location, not publication's response to a recording failure.
Automatic storage removes a routine setup decision and keeps default records
@@ -295,3 +322,29 @@ and failed remote observation, and identify useful next actions when known.
Conflict output includes expected and observed tag-object IDs. This makes
recovery actionable while preserving the existing outcome classifications and
explicit corrective-action workflow.
### 6. Current transport settings with a fixed recorded endpoint
Record the original remote name as optional transport context. During later
reconciliation, read its current supported transport settings and use them with
the exact recorded endpoint. The remote's current fetch and push URLs do not
replace that endpoint. Retain the existing check that URL rewriting leaves the
recorded endpoint unchanged.
A missing or renamed remote alone does not invalidate the evidence. Observation
can use available endpoint/global configuration; operators may restore required
settings locally. Configuration-read failures and failed observations remain
unresolved with cause information. This separates original publication identity
from repairable connection settings without snapshotting transport configuration.
### 7. Discovery preserves readable attempts
An unreadable, malformed, or unsupported record produces a diagnostic while
other readable attempts remain discoverable. Results expose both entries and
per-record diagnostics, identifying affected paths with credential-safe output.
The CLI presents usable entries and makes incomplete discovery clear.
Failure to enumerate storage is a discovery failure rather than an empty result.
Explicit reconciliation of an unusable record reports that record's error and
retains the caller's selection. Discovery and record errors do not authorize
automatic selection or corrective actions.