distributor/docs/roadmap/implementation.md

Implementation Roadmap

This roadmap records current implementation status and deferred work for distributor. Implemented behavior is documented in the user, operator, and internal documentation listed below.

Canonical current-behavior docs:

• README.md
• docs/cli.md
• docs/config.md
• docs/operations.md
• docs/troubleshooting.md
• docs/internal/
• docs/integrations/markdown.md
• docs/policy/
• examples/

Future, planned, or aspirational behavior belongs under docs/roadmap/ until it is implemented.

Current State

distributor is ready for routine use against producer pipelines using the implemented local, SSH/SFTP, and S3-compatible backends.

Implemented capabilities:

• standard-library CLI commands for version, run, validate, and inspect;
• YAML config loading, defaults, known-field rejection, and validation;
• local, SSH/SFTP, and S3-compatible source and destination backends;
• structured SSH/SFTP configuration with agent and key-file authentication, known-hosts handling, and backend-rooted path confinement;
• S3-compatible configuration with endpoint, region, addressing mode, TLS controls, credential environment references, streaming reads and writes, listing, metadata, and managed deletion;
• top-level secrets.directory loading for credential values, with process environment precedence and without mutating the process environment;
• backend-rooted storage interfaces with typed errors, safe logical paths, traversal, collision checks, managed deletion, and explicit forced replacement;
• source bundle discovery, manifest parsing, RFC3339 timestamp handling, duplicate path checks, path safety checks, symlink rejection, per-file digest validation, and bundle digest validation;
• destination .distributor.json state parsing, validation, output metadata, and source comparison;
• publication of source files, Markdown sidecar HTML, or both;
• destination output collision detection before writes;
• managed replacement for older destination state;
• conservative conflict failures by default for unmanaged destination content and conflicting managed destination content;
• explicit forced replacement with run --force, limited to the configured destination bundle path;
• deterministic dry-run output and final run summaries;
• deterministic sequential fan-out with aggregated destination failures;
• cleanup of outputs written during failed publish attempts where practical;
• no-op notification hook after successful publish or replacement;
• current user, operator, internal, integration, and development documentation for implemented behavior.

Active Roadmap

There are no active implementation items in this roadmap.

Before implementing new product behavior, add a focused roadmap entry when the work changes storage semantics, config, CLI behavior, state schema, transform behavior, notification behavior, operational safety, or user-visible workflows. Keep those entries out of current-behavior docs until the behavior exists.

Deferred Work

These items are not implemented and should stay out of current-behavior docs until a roadmap entry is selected and implemented:

• external notification adapters;
• warning-only digest mismatch handling;
• additional auth mechanisms beyond the implemented SSH and S3 credential paths;
• compatibility parsing for legacy SSH URI config;
• broad recursive destination deletion outside managed bundle paths;
• concurrent fan-out publishing;
• resumable multipart S3 uploads;
• cloud-provider-specific IAM integration docs;
• repository-managed packaging, release, and deployment automation.

Roadmap Maintenance

When adding future roadmap work:

• describe user-visible behavior and safety boundaries;
• define which existing docs must change after implementation;
• keep examples secret-free and runnable or clearly environment-gated;
• avoid workflow labels in production code, tests, config fields, and user documentation;
• run focused tests for the changed behavior and go test ./... for cross-package changes.