distributor/docs/internal/transform.md

# Transform Internals

Audience: developers and LLM coding agents changing `internal/transform` or transform implementations.

## Purpose

`internal/transform` defines generated publication artifacts, transform request/response types, transform registry behavior, and transform identifiers. `internal/transform/markdown` implements Markdown-to-HTML generation.

## Inputs And Outputs

Inputs are a validated source bundle, source storage backend, and transform options supplied by publish planning. Outputs are generated artifact records containing destination path, source path, transform id, generated bytes, SHA-256 digest, and byte size.

## Boundaries

Transforms do not mutate source bundles, publish files, write destination state, choose destination actions, parse config, or inspect destinations. Publish planning decides whether generated outputs are selected and writes destination state later.

The Goldmark renderer contract is documented in `docs/integrations/markdown.md`.

## Config Fields Used

Transform packages do not read config directly. Publish planning passes effective `transform.markdown_to_html.mode` and `transform.markdown_to_html.input` values.

## Adapters Used

Transforms read source files through `internal/storage.Backend`. The Markdown implementation uses `github.com/yuin/goldmark` for rendering.

## State And Manifest Behavior

Transform outputs carry metadata later projected into destination state. Markdown sidecar mode renders manifest-listed `.md` files to same-directory `.html` outputs. Markdown index mode renders one selected Markdown source to `index.html`.

## Skip And Resume Behavior

Transforms have no skip/resume state. They are deterministic for the same source bytes and transform options.

## Failure Behavior

Registry registration fails for empty names, nil transformers, and duplicate names. Transform resolution fails when publish planning requests an unregistered transform. Markdown rendering fails on source read errors, renderer errors, unsafe configured input, missing manifest input, non-Markdown input, ambiguous index input, or absent Markdown inputs.

## Tests To Inspect

- `internal/transform/*_test.go`
- `internal/transform/markdown/*_test.go`
- `internal/publish/*_test.go`

## Architectural Invariants

- Source bundle files are never mutated by transforms.
- Generated outputs record destination path, source path, transform id, SHA-256, and size.
- Markdown sidecar naming changes only the `.md` suffix to `.html`.
- Markdown index mode always writes `index.html`.
- Non-Markdown source files do not generate sidecar outputs.
- Transform registration stays outside publish planning.