Skip to content

One format contract per limited plugin: run_within(), limits probed from the bundle (task #48) - #209

Merged
StuartCameronCode merged 2 commits into
mainfrom
stuart/48-one-format-contract-helper-for-plugin-gu
Nov 16, 2026
Merged

StuartCameronCode merged 2 commits into
mainfrom
stuart/48-one-format-contract-helper-for-plugin-gu

Conversation

@StuartCameronCode

Copy link
Copy Markdown
Owner

Task #42's plan, R2b. Every 8-bit-only or depth-capped block in the script template had its own hand-written guard (convert down, run, convert back), and they kept going wrong the same ways: the whole low-depth result up-converted, quantising every sample (#34, #37); field-flagged 4:2:0 (#29); depth and size limits found by a user's job (#23, #31, #35).

What changes

  • worker/templates/plugin_formats.py: a Contract per depth-limited plugin (DeScratch, DeDot, Bifrost: 8-bit; havsfunc LUTDeCrawl, LUTDeRainbow: 8–10 bit) and run_within(clip, key, fn, label=…).
    • When the plugin accepts the clip, it adds no node.
    • Otherwise it converts with zimg, keeping _FieldBased, and applies only the plugin's change at full depth: src + back(fn(work)) - back(work).
    • It refuses an fn that changes the frame count, size or format, and refuses a frame below a contract's minimum size with a readable message.
    • It replaces the five guards and _low_depth_change.
  • 4:1:1 is converted once, at the top of the script, before the VFR placement and every pass. The per-pass 4:1:1 guards in Frame Rate, VFR placement, Cnr4 and RemoveDirt are removed. They were already dead code: the old top-level conversion ran before every pass.
  • Scripts/probe-plugin-formats.py runs all 69 pass-level plugin calls with the template's arguments. It covers {4:2:0, 4:2:2, 4:4:4} × {8, 10, 12, 16} bits × {progressive, BFF, TFF}, plus a frame-size axis up to 1080 lines and documentation rows for 4:1:1 and 9/14-bit. The result is committed as Tests/TestResources/plugin_format_table.json.
  • Guards:
    • test_251 (Rust): a contracted plugin called outside run_within fails the test, naming the line.
    • plugin_format_contracts_test.dart (push gate) checks four things:
      • every template call is probed
      • each contract matches the table, and any other refusal is explained in HANDLED or filed in KNOWN
      • a quick probe of the installed bundle agrees with the table
      • run_within keeps unchanged samples bit-exact on real low bits
    • plugin_format_probe_test.dart (heavy, nightly): the full probe.
  • Refusals no pass handles yet, listed in plugin_formats.KNOWN:
  • CLAUDE.md (step 8 of the new-filter checklist, "High Bit Depth Sources", "Source Pixel Formats"), ENGINEERING_NOTES and a report in docs/reports/task-48-plugin-format-contracts/.

Testing

  • Identity: each migrated pass was encoded alone, losslessly (FFV1), with the templates from before and after the change. It ran on every reachable format, progressive and TFF, plus 4:1:1.
  • cargo test --test filter_integration_test: 233 passed.
  • flutter test test/plugin_format_contracts_test.dart: 4 passed. The quick probe took about 3.5 minutes on an M1 Pro under load.
  • integration_filter_parameters_test and template_call_arguments_test pass.

Risks

  • The table was measured on macOS arm64 only. The quick probe will run on the Windows, Linux and macOS x64 push-gate jobs against it. A cell that genuinely differs on one of those bundles fails CI until it is measured on that platform and recorded under platforms in the table. macOS x64 is the most likely, since it has no akarin and an older MVTools.
  • Push-gate time: the quick probe adds about 3–4 minutes per platform.
  • Scope of "ok": a cell is ok when a frame can be requested. A plugin that accepts a format and misreads it (Depan, Make Flutter integration tests run headless in CI #32) still passes the probe.

🤖 Generated with Claude Code

…, limits probed from the bundle (task #48)

- worker/templates/plugin_formats.py: a Contract per depth-limited plugin
  (DeScratch, DeDot, Bifrost, LUTDeCrawl, LUTDeRainbow) and run_within(),
  which converts field-aware and adds only the plugin's change. Replaces the
  five hand-written guards and _low_depth_change.
- 4:1:1 converted once at the top of the script; the per-pass 4:1:1 guards
  (Frame Rate, VFR placement, Cnr4, RemoveDirt) removed.
- Scripts/probe-plugin-formats.py measures every pass-level plugin call at
  every reachable format and size; Tests/TestResources/plugin_format_table.json
  is the committed result. plugin_format_contracts_test (push gate: quick
  probe, contracts vs table, run_within on real low bits) and
  plugin_format_probe_test (heavy: full probe). test_251 keeps contracted
  plugins inside run_within.
- Refusals no pass handles yet (720x486 4:2:0, MCTD width 2 mod 4) listed in
  plugin_formats.KNOWN (tasks #57, #56).
- Report: docs/reports/task-48-plugin-format-contracts (output identical
  before/after except RemoveDirt, nondeterministic on both sides).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@StuartCameronCode
StuartCameronCode force-pushed the stuart/48-one-format-contract-helper-for-plugin-gu branch from 95e9d99 to 4a8a5ef Compare November 16, 2026 07:24
…S x64 bundles (task #48)

Found by the PR's first CI run: their vivtc builds accept deeper input,
the macOS arm64 and Windows ones refuse it. Recorded as per-platform cells
in the table; the template feeds VFM an 8-bit copy either way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@StuartCameronCode
StuartCameronCode merged commit e42b61b into main Nov 16, 2026
4 checks passed
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.

1 participant