feat(optiflow): publish a reusable OptiFlow image-optimization workflow

[szmyty]

Outcome

After OptiFlow v1 and the Flow suite are stable, publish a reusable Relay workflow that dogfoods OptiFlow for bounded image optimization in GitHub Actions.

Relay must consume an immutable, independently released OptiFlow artifact and its versioned public contracts. Relay adds CI installation, invocation, evidence publication, permission handling, and optional Git publication behavior; it must not become another media engine or duplicate OptiFlow policy and validation.

Scheduling gate

Status: deferred and blocked. Do not begin implementation yet.

All of the following must be true before an implementation branch is opened:

• OptiFlow v1.0.0 is tagged and published from a green default branch.
• OptiFlow v1 provides independently installable immutable artifacts, checksums/provenance, installation documentation, stable CLI behavior, structured output, capability discovery, and documented compatibility rules.
• OptiFlow v1 exposes the bounded planning, candidate production, validation, apply, failure, and recovery semantics required for safe automation.
• The Flow suite stabilization epic has satisfied its suite definition of done, including independently released holons, a version/capability compatibility table, stable provider seams, clean-room fixture evidence, and agreement between releases, documentation, manifests, and observed behavior.
• The static-publication and time-based suite fixtures prove that released artifacts can be orchestrated without source-tree coupling.
• Any open OptiFlow work that can still materially change the public automation contract has been completed or explicitly assigned to a named post-v1 compatibility boundary.

When these gates are satisfied, re-query live repository, release, issue, pull-request, and CI state. Record the exact OptiFlow release, artifact digests, public contract versions, Flow compatibility evidence, and Relay starting commit. Historical observations in this issue are planning context, not future execution pins.

Ownership boundary

Owner	Owns	Does not own here
OptiFlow	Media inspection, capability discovery, profiles and policy, optimizer/provider selection, plans, candidates, validation, safe apply/recovery semantics, and machine-readable evidence	GitHub permissions, reusable workflow packaging, or consumer publication policy
Relay	Thin reusable CI orchestration: install a pinned OptiFlow release, invoke its public contract, enforce the GitHub trust boundary, publish summaries/artifacts, and optionally perform explicitly authorized Git publication	Codec behavior, format detection, optimization algorithms, perceptual thresholds, metadata semantics, or a second media policy
Flow	Cross-tool suite planning, multi-holon run state, recovery, compatibility, and explanations	This single-tool Relay wrapper or OptiFlow internals
Consumer repository	Eligible paths, repository policy/configuration, lossless/lossy and metadata authority, resource ceilings, branch permissions, publication mode, and final merge/release decisions	Weakening OptiFlow invariants or treating Relay as the media engine

Integration must use versioned public APIs/CLIs and immutable released artifacts. Relay must never import OptiFlow's source tree or copy its implementation.

Workflow contract

The final interface must be derived from the released OptiFlow v1 contract rather than guessed in advance. It must nevertheless:

• discover Git-tracked inputs within caller-provided include/exclude boundaries by default;
• scope this workflow to images while querying OptiFlow's versioned capability report instead of hard-coding a format matrix in Relay;
• pass repository-specific OptiFlow policy without creating a competing Relay configuration language;
• skip cleanly when no eligible images exist;
• default to a read-only check/plan mode;
• separate authorization to apply validated changes from authorization to publish a patch, artifact, or commit;
• keep lossless behavior as the default; lossy transforms, metadata removal, and format conversion require explicit consumer authority;
• distinguish no-input, unsupported, unchanged, candidate, rejected, validation-failed, applied, partial, and failed outcomes;
• publish OptiFlow's machine- and human-readable evidence rather than inferring success from an exit code or Git diff;
• report the pinned version, selected profile, effective policy, provider/tool versions, checksums, byte deltas, validation result, mutation state, and publication state where the v1 contract provides them; and
• document local reproduction with the same released artifact and effective policy used by CI.

Safety and authority

• Check/plan mode requires no repository write permission and never pushes.
• Fork and other untrusted pull requests stay read-only, receive no write token or protected secrets, and cannot select a write-capable path through untrusted inputs.
• Apply mode is explicit, trusted-context only, and must use OptiFlow's validated transactional apply boundary.
• Relay must not replace a source merely because a candidate exists or is smaller.
• OptiFlow's candidate validation, source retention, revalidation, rollback/recovery, and honest partial-state semantics must not be bypassed.
• Bound paths, file count, bytes, temporary storage, and runtime where supported. A ceiling produces explicit bounded evidence, never silent scope widening.
• Unsupported, corrupt, changed-during-run, or unverifiable inputs must never be reported as optimized.
• Git publication, when enabled, uses least privilege, stages only paths in OptiFlow's applied-result manifest, avoids empty commits and self-triggering loops, and records exact committed evidence.
• Cache entries are never authoritative evidence.

Validation

Use small deterministic fixtures and mocked contract outputs for orchestration branches, plus at least one end-to-end fixture against the real immutable OptiFlow v1 binary. Cover:

1. no eligible images;
2. already optimized input;
3. a validated optimizable image with checksum and byte evidence;
4. unsupported capability;
5. ignored or untracked input;
6. include/exclude boundaries;
7. spaces and Unicode in paths;
8. invalid configuration or incompatible contract version;
9. corrupt candidate or failed validation;
10. input changed between plan and apply;
11. resource/runtime ceiling;
12. untrusted pull request;
13. trusted apply without publication;
14. trusted publication staging only OptiFlow-reported paths;
15. idempotent re-run;
16. advertised capability drift;
17. immutable artifact/version/checksum verification; and
18. agreement between machine and human failure/partial-state summaries.

Acceptance criteria

• Every scheduling gate is satisfied with live, immutable evidence before implementation starts.
• Relay publishes a documented reusable image-optimization workflow backed by OptiFlow v1.
• The workflow installs and verifies an immutable released OptiFlow artifact, never a mutable branch or source checkout.
• Relay remains a thin CI/Git adapter and duplicates no media engine, format policy, optimizer registry, or candidate-validation implementation.
• The supported image surface comes from the pinned OptiFlow capability contract.
• Git-tracked, path-bounded discovery is safe and deterministic.
• No-input, unsupported, unchanged, candidate, rejected, applied, partial, and failed outcomes are distinguishable.
• Check mode is the default, needs no write permission, and never pushes.
• Apply and publication are separate explicit authority choices available only in trusted contexts.
• Lossy transforms, metadata removal, and format conversion cannot occur by default.
• Candidate application cannot bypass OptiFlow validation, preconditions, source retention, or recovery semantics.
• Git publication stages only exact applied paths, avoids empty commits/loops, and uses least privilege.
• Machine evidence and the job summary identify versions, effective policy, checksums, validation, byte deltas, and mutation/publication state where supported.
• Local reproduction uses the same released OptiFlow boundary as CI.
• Deterministic fixtures and at least one real OptiFlow integration fixture pass.
• Third-party actions and downloaded artifacts follow Relay's immutable-pinning and dependency-review policy.
• Relay's canonical validation passes.
• The workflow catalog and consumer docs include a minimal commit-pinned adoption example and exact permissions for each mode.

Prior-art disposition

The original toy/image_optim prototype remains useful historical evidence for tracked-file discovery, explicit no-input handling, deterministic paths, smaller-only candidates, separate check/write behavior, savings evidence, and idempotence.

However, image_optim is not a Relay runtime dependency or the architecture target for this issue. Relay will not invoke it directly, reproduce its worker-selection behavior, wrap it in a Relay-owned image, port its Ruby orchestration, or encode its current format surface as Relay's support promise. OptiFlow may independently study it or expose selected tools through typed provider boundaries; Relay consumes only the stable released OptiFlow contract.

Non-goals

• Implementing, porting, or maintaining image codecs or optimization algorithms in Relay.
• Recreating OptiFlow's provider registry, detection, policy, validation, reporting, or transactional replacement behavior.
• Stabilizing or releasing OptiFlow or Flow from this issue.
• Coupling Relay to an OptiFlow source checkout or mutable branch.
• Using Flow orchestration when one released OptiFlow invocation is sufficient.
• Expanding this first contract to audio, video, or arbitrary multi-holon pipelines.
• Promising formats that the pinned OptiFlow release does not advertise.
• Organization-wide rollout, implicit mutation, or pushes from untrusted contexts.

Dependencies and references

• Suite stabilization source of truth: egohygiene/flow#11
• OptiFlow capability and optimizer strategy: egohygiene/optiflow#83
• Future immutable OptiFlow release: v1.0.0 — re-query and link the actual release when published
• Historical prior art: toy/image_optim

Decision impact

Reference; no new ADR is required for this rewrite.

This preserves the established boundary: OptiFlow owns media optimization, Relay owns reusable CI orchestration, Flow owns cross-tool orchestration/recovery, and consumers own paths, policy, authority, and final publication decisions.

Run the decision-impact check again during implementation. Pause for the owning-repository ADR if implementation would move durable media-policy ownership into Relay, create a new cross-repository configuration contract, bypass OptiFlow safety, make mutation implicit, or introduce mutable source coupling.