distributor/docs/roadmap/link_generation.md

# Roadmap: Link Generation Support

## Purpose

Add destination-aware link generation so distributor can record human-usable URLs
for published artifacts.

This feature should be implemented after destination path mapping so generated
URLs use the final archive or fixed destination path semantics. It prepares the
project for notification adapters, richer inspect/status output, static-site UX,
and future feed generation.

## Current Implementation Grounding

Current publish planning produces `publish.Output` values with destination path,
source path, kind, transform, SHA-256, size, and optional generated data.

Current `.distributor.json` output records contain path, kind, source path,
transform, SHA-256, and size. They do not contain URL metadata, and destination
state has no top-level links block.

Current destination bundle paths preserve the source-root-relative bundle path.
Latest/fixed path mapping is not implemented yet.

## Goals

- Add optional destination-level link configuration.
- Generate per-output URLs when a destination has `links.base_url`.
- Record generated URLs in destination state when configured.
- Select a deterministic primary URL when possible.
- Keep link generation destination-local and independent of producer manifests.
- Do not infer public URLs from backend configuration automatically.

## Non-Goals

- Do not deliver notifications.
- Do not require every destination to expose URLs.
- Do not add static-site indexes or feeds.
- Do not add latest path mapping.
- Do not change source manifest schema.

## Configuration Shape

Add optional destination-level config:

```yaml
links:
  base_url: https://weather.example.com
  primary: auto
```

Semantics:

- `links.base_url`: absolute HTTP or HTTPS URL corresponding to the destination
  backend root.
- `links.primary`: optional primary-link selection policy.

Initial `primary` policies:

- `auto`: choose the best available output;
- `html`: prefer generated HTML outputs;
- `source`: prefer copied source outputs.

If `links` is absent, no URL metadata is generated.

## URL Construction

Construct URLs from:

1. `links.base_url`;
2. destination bundle path relative to the destination backend root;
3. output path relative to the destination bundle path.

Use URL path joining and escaping rules, not filesystem or storage path joins.
Preserve any path prefix in `base_url`. Reject `base_url` values with query
strings or fragments.

For `index.html`, generate a directory-style URL by omitting the filename:

```text
https://weather.example.com/daily/brentwood/2026-06-01/
```

For other outputs, include the output filename:

```text
https://weather.example.com/daily/brentwood/2026-06-01/report.html
```

`index.html` recognition should apply to any output path ending in
`/index.html` or exactly `index.html`.

## Primary Link Selection

For `primary: auto`, select in deterministic publish-plan order:

1. any `index.html` output;
2. first generated HTML output;
3. first source output;
4. no primary URL.

For `primary: html`, prefer generated HTML outputs. For `primary: source`,
prefer source outputs. If no output matches the policy, record no primary link
rather than failing publication.

## Destination State

When links are configured, destination state should record:

- optional per-output URL metadata;
- optional top-level primary URL metadata.

Destinations without `links` should continue producing state without URL
metadata.

Because distributor is still pre-release, URL metadata should be added as
optional state schema version 1 fields rather than introducing destination state
schema version 2 for this feature. Post-release, materially richer state
semantics should use an explicit schema versioning policy.

## Relationship To Other Roadmaps

HTML index mode is not required, but link generation should treat `index.html`
as the preferred URL shape when present.

Latest path destinations should provide the destination bundle path mapping
needed to build fixed/latest URLs correctly.

Producer-facing manifest creation and remote validation are independent of URL
metadata.

CLI display of generated primary links should follow
`docs/roadmap/cli_output_policy.md` so link output is exposed through the shared
`--format text|json` model rather than one-off command output.

## Testing Expectations

Suggested coverage:

- config validation accepts absent `links`;
- config validation accepts valid HTTP and HTTPS base URLs;
- config validation rejects invalid schemes, query strings, and fragments;
- nested bundle paths generate correct URLs;
- `index.html` URLs omit the filename;
- non-index URLs include filenames;
- primary selection is deterministic;
- state records URLs when configured;
- destinations without `links` produce no URL metadata.

## Documentation Updates After Implementation

- Update `docs/config.md` with destination `links` fields.
- Update `docs/operations.md` with static-site URL examples.
- Update `docs/internal/state.md` if destination state changes.
- Update `docs/cli.md` only if run or inspect output displays links.

Keep this roadmap under `docs/roadmap/` until implemented.

## Decisions

- URL metadata is added as optional destination state schema version 1 fields
  while distributor remains pre-release.
- v1 implements `links.primary` so future notification and operator-output
  features have one canonical primary-link selection policy.
- `run` and `inspect` output should not display generated primary links
  immediately. Link display should wait for
  `docs/roadmap/cli_output_policy.md` or another explicit inspect/status output
  mode.

## Future Work

- Define a post-release destination state schema bump policy before introducing
  materially incompatible state changes.
- Add CLI display of primary links through an explicit output mode or status
  command, preferably the shared `--format text|json` policy in
  `docs/roadmap/cli_output_policy.md`, rather than changing routine `run`
  output opportunistically.
- Add richer link policies only if `auto`, `html`, and `source` prove
  insufficient.