Centralize link URL validation

docs/internal/link.md

@@ -0,0 +1,27 @@
+# Link URL Policy
+
+## Purpose
+
+`internal/link` defines shared validation for configured and persisted HTTP link URLs.
+
+## Inputs and outputs
+
+Input is a URL string. Output is either nil for an accepted URL or a concise validation error that callers wrap with field context.
+
+## Validation behavior
+
+Accepted URLs must parse successfully, use `http` or `https`, include a host, and omit query strings and fragments.
+
+## Boundaries
+
+This package validates URL shape only. It does not construct destination output URLs, choose primary URLs, infer public URLs from backend configuration, or read configuration files.
+
+## Tests
+
+Before changing link URL policy, inspect tests under `internal/link` and callers in `internal/config`, `internal/state`, and `internal/publish`.
+
+## Invariants
+
+- Configured `links.base_url`, persisted `links.primary_url`, persisted output `url`, and publish link planning use the same URL policy.
+- Callers own field-specific error context.
+- URL path construction remains in `internal/publish`.

docs/policy/architecture.md

@@ -202,6 +202,7 @@ Use this current layout unless the project has a documented reason to differ:
 - `internal/config`: configuration structs, defaults, loading, precedence, and validation.
 - `internal/bundle`: storage-backed source bundle discovery and validation over the public manifest contract.
 - `internal/state`: `.distributor.json` parsing, validation, comparison, and output metadata.
+- `internal/link`: shared HTTP URL validation for configured and persisted link metadata.
 - `internal/storage`: backend interfaces, shared path/resource types, backend registry, and storage errors.
 - `internal/adapters/local`: local filesystem backend.
 - `internal/adapters/ssh`: SSH/SFTP backend.