Skip to content

Make execution results provenance-complete and align artifact evidence with Flow contracts #355

Description

@szmyty

Outcome

Turn ExecutionResult and ArtifactManifest into authoritative machine-readable evidence of what Renderflow actually planned, executed, reused, skipped, validated, and produced.

This is the core integration seam required by egohygiene/flow.

Audit evidence

The public SDK exposes promising result types, but the current Engine::execute implementation returns target names while hard-coding these evidence fields empty:

  • reused_cached_outputs
  • skipped_transforms
  • diagnostic warnings
  • recoverable failures

The current ArtifactManifest contains only output_dir and outputs: Vec<String>.

Flow already defines a provisional flow.artifact/v1 contract containing artifact identity, role, media type, SHA-256 digest, size, producer information, and source relationships. Renderflow should be able to project its richer native evidence into that interchange shape without making Flow its internal domain model.

Scope

Introduce a versioned Renderflow run/result evidence model that records at minimum:

Run identity

  • run/execution identifier
  • execution-plan digest
  • source/spec digest
  • engine version
  • start/completion timestamps
  • final state: complete, partial, failed, cancelled

Artifact evidence

For each source, intermediate when retained, and terminal artifact:

  • stable artifact identifier
  • logical role
  • path or artifact-store locator
  • canonical format and media type
  • SHA-256 digest
  • byte size
  • producer transform/capability
  • producer/tool version
  • source artifact identifiers
  • cache/reuse status
  • validation state
  • warnings and loss/fidelity declarations

Step evidence

  • transform identifier and version
  • resolved tool/provider
  • input/output artifact IDs
  • configuration digest
  • started/completed state
  • cache hit/miss
  • skip reason
  • duration and optional metrics
  • structured failure/diagnostic data

Flow compatibility

  • Provide an explicit adapter/projection to Flow's provisional flow.artifact/v1 shape.
  • Keep Flow-specific serialization outside stable Renderflow domain types where practical.
  • Add compatibility fixtures that fail loudly when a supported Flow contract version becomes incompatible.

Acceptance criteria

  • ExecutionResult is populated from actual executor outcomes rather than request/config intent.
  • ArtifactManifest lists concrete artifacts with identity, digest, size, role, media type/format, producer, and source relationships.
  • Cache hits and skipped transforms appear explicitly in structured results.
  • Warnings, recoverable failures, fatal failures, and cancellation are distinguishable.
  • Partial execution never reports itself as complete success.
  • A versioned machine-readable run manifest can be persisted alongside outputs.
  • Renderflow can emit Flow-compatible artifact records for the currently supported Flow contract version.
  • Human CLI summaries are rendered from the structured result rather than separate state.
  • Secrets and sensitive environment/config values are absent from manifests and diagnostics.
  • Fixtures cover clean success, cache reuse, partial failure, fatal failure, cancellation, and validation failure.
  • Formatting, Clippy, tests, examples, and CI pass.

Dependencies

Depends on #352 and #354. This is a prerequisite for the Renderflow side of the Flow integration gate.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions