From 58656dea4591ea11bb950be28b85ee447be8b6cd Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 2 Nov 2026 17:57:05 +0000 Subject: [PATCH] Clarify recovery transport settings and partial discovery --- docs/roadmap/publication-reconciliation.md | 57 +++++++++++++++++++++- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/docs/roadmap/publication-reconciliation.md b/docs/roadmap/publication-reconciliation.md index 3773eda..6926ba4 100644 --- a/docs/roadmap/publication-reconciliation.md +++ b/docs/roadmap/publication-reconciliation.md @@ -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.