a 404 at adoption has a third reading, and the tool can resolve it

externals names two readings of a 404 — withdrawn, or access lost — and those are
the two a locked document can have. Adoption by name has a third: a document that
was never there under that name. Found in use, where a missing s reported the
ambiguity instead of the typo.

The tool was reporting an ambiguity it had the means to resolve: the by-name form
knows the repository, so on a 404 it now lists the published surface and says which
names exist. It claims that only when the listing succeeds — if listing fails too,
the repository is unreachable and the original ambiguity is the honest answer,
which is the same discipline as recording public and not-public rather than
private.

Not filed as a gap against externals. The third reading cannot occur where that
document is speaking, which is check against a lock; it exists only at adoption,
which is ours.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris

internal/external/external.go

@@ -253,6 +253,19 @@ func warnIfNotPublic(root, raw, vis string, out io.Writer) {
 	fmt.Fprintf(out, "         record only the dependency, which loomctl cannot do yet.\n")
 }
 
+// NotFoundError is a 404, which over HTTP carries more than one reading.
+//
+// The convention names two — withdrawn, or access lost — because those are the
+// two a locked document can have. Adoption by name has a third: a document that
+// was never there under that name. Callers that know the repository can tell
+// them apart; this type is how they get the chance.
+type NotFoundError struct{ URL string }
+
+func (e *NotFoundError) Error() string {
+	return fmt.Sprintf("404 unresolved: %s was withdrawn, or this credential cannot see it — "+
+		"over HTTP these are the same response", e.URL)
+}
+
 type fetched struct {
 	data []byte
 	url  string
@@ -281,8 +294,7 @@ func fetch(cfg *config.Config, raw, ifNoneMatch string) (*fetched, string, error
 		}
 		return &fetched{data: b, url: resp.Request.URL.String()}, resp.Header.Get("ETag"), nil
 	case http.StatusNotFound:
-		return nil, "", fmt.Errorf("404 unresolved: %s was withdrawn, or this credential cannot see it — "+
-			"over HTTP these are the same response", raw)
+		return nil, "", &NotFoundError{URL: raw}
 	default:
 		return nil, "", fmt.Errorf("%s: %s", resp.Status, raw)
 	}