Skip to content

feat(config): define renderflow execution spec v2 - #372

Merged
szmyty merged 1 commit into
mainfrom
feat/spec-v2-353
Sep 1, 2026
Merged

feat(config): define renderflow execution spec v2#372
szmyty merged 1 commit into
mainfrom
feat/spec-v2-353

Conversation

@szmyty

@szmyty szmyty commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Defines the versioned Renderflow execution specification v2 required by #353 while preserving the existing unversioned configuration through an explicit v1 compatibility path.

This PR establishes the declarative contract that #354 can consume for canonical planning/execution without prematurely rewriting the current build engine.

Architecture

  • Adds schema: renderflow/v2 as an explicit execution-spec identifier.
  • Adds a public v2 model for immutable source artifacts, ordered collections, target selection, derivative profiles, execution policy, and output layout.
  • Supports exact targets, named derivative profiles, all_reachable, and include/exclude selectors by format, family, capability, transform, and profile.
  • Separates named derivative profiles from per-target preset values so publication bundles and encoder/quality settings remain unambiguous.
  • Makes resource/network/AI behavior policy-visible, including concurrency and byte/artifact/depth budgets, tool/transform allow/deny sets, deterministic/local/offline requirements, validation requirements, fidelity thresholds, and policy references.
  • Defaults network and AI execution to deny in v2 unless explicitly enabled.
  • Defines deterministic bundle roots, naming templates, intermediate retention policy, and collision handling.

Compatibility and migration

  • Unversioned configuration files remain the explicit v1 compatibility format.
  • Unsupported declared schema identifiers are rejected instead of silently reinterpreted.
  • renderflow spec migrate deterministically maps current v1 intent into v2, preserving source format/detection behavior, output targets, templates, output presets, variables, optimization mode, output directory, and transform registry path.
  • Existing v1 build commands remain unchanged; canonical v1/v2 planner execution is intentionally left to Unify legacy build and graph build behind one canonical planner and executor #354.

Validation and schema

  • Adds structured diagnostics with stable field paths such as $.sources[1].id and $.execution.max_parallel.
  • Validates source identity, artifact/collection shape, collection references, target selectors, named profiles, execution budgets, fidelity bounds, allow/deny conflicts, and deterministic output fields.
  • Adds positive and negative spec fixtures for multi-source collections, exact/profile targeting, duplicate IDs, and invalid policy.
  • Emits the canonical Draft 2020-12 JSON Schema from the Renderflow runtime via renderflow spec schema.
  • Adds renderflow spec validate with text/JSON/YAML reporting.

Documentation

  • Adds a comprehensive renderflow/v2 example.
  • Adds CLI documentation for validate/migrate/schema commands.
  • Updates the configuration guide to clearly distinguish v1 compatibility from v2 intent.
  • Generates the spec v2 reference from the runtime-emitted JSON Schema.
  • Extends docs CI so schema/reference drift fails the build.

Boundary

#353 defines source/target/policy intent, compatibility, validation, migration, and the machine-readable schema. It does not duplicate or preempt #354's canonical planner/executor work. This keeps configuration intent separate from the resolved execution plan.

Final validation

Final review commit: 7cd761acbcabf88942845ecadd0e357768013126 (single Conventional Commit).

All PR-triggered workflows passed on that exact SHA:

  • CI 33460471072 — success
    • Clippy with warnings denied
    • full Rust workspace build and tests
    • web formatting/lint/typecheck/tests/build
    • portable installer build/install smoke test
    • Arch Linux stable and git PKGBUILD validation
    • Snap build/install/version smoke test and artifact upload
    • bundled hello-world/transforms dry-runs
    • library embedding and plugin registration examples
  • docs 33460471031 — success
    • runtime JSON Schema regeneration
    • generated spec/tool/format documentation regeneration
    • generated-artifact zero-diff verification
    • strict MkDocs build
    • versioned docs build smoke test
  • Commit Lint 33460471008 / 33460480708 — success

Closes #353

Introduce the versioned execution-intent contract for arbitrary source artifacts,
ordered collections, derivative profiles, maximal target selection, explicit
execution policy, and deterministic output layout.

Keep unversioned v1 configuration behind an explicit compatibility and migration
path. Emit structured field-path diagnostics and publish the runtime-owned JSON
Schema through CLI and generated documentation.

Closes #353
@szmyty szmyty changed the title feat(spec): define renderflow execution spec v2 feat(config): define renderflow execution spec v2 Sep 1, 2026
@szmyty
szmyty merged commit 6b646f7 into main Sep 1, 2026
20 checks passed
@szmyty
szmyty deleted the feat/spec-v2-353 branch September 1, 2026 02:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define Renderflow spec v2 for arbitrary sources, artifact forests, profiles, and execution policy

1 participant