# PIXELFLOW-FILTERS KNOWLEDGE BASE
## OVERVIEW
Cross-crate layering lives in `crates/AGENTS.md`; below only local stdlib filter rules.
`pixelflow-filters/` owns official in-repo filter semantics for `pixelflow/std`.
Planner side: `register_builtin_filters` wires stable descriptors to `plan_*` entry points.
Runtime side: `build_builtin_executors` walks reachable filter nodes and installs concrete `FrameExecutor`s.
## STRUCTURE
- `src/lib.rs` — crate root; module exports; planner registration; executor assembly; test-only tolerance re-exports.
- `src/contracts.rs` — `OfficialFilterContract`, `SupportedFormats`, `STDLIB_PUBLISHER`, `STDLIB_PLUGIN`, upfront fixed-media validation.
- `src/options.rs` — shared option parsing helpers used by planners and executor constructors.
- `src/dither.rs` — deterministic Fruit dither table/helpers shared by conversion filters.
- `src/bit_depth.rs` — `convert_bit_depth`; scalar bit-depth conversion; optional dither.
- `src/colorspace.rs` — `convert_colorspace`; Phase 1 range-focused colorspace conversion surface.
- `src/colorspace/{metadata,math,pipeline,range}.rs` — metadata resolution, transfer/matrix math, sampling pipeline, range-only fast path.
- `src/format.rs` — `convert_format`; format alias conversion plus source/target color metadata overrides.
- `src/crop.rs` — `crop`; validates rectangle and chroma-alignment rules.
- `src/resize.rs` — `resize`; scalar kernels, parameter validation, resampling executor.
- `src/planes.rs` — `split_plane` and `merge_planes`; gray extraction and multi-input plane assembly.
- `src/props.rs` — `set_prop`, `clear_prop`, `require_prop`; metadata-schema-aware property helpers.
- `src/select.rs` — `select`; explicit frame-map temporal filter with schedule metadata.
- `src/trim.rs` — `trim`; finite-range temporal slicing.
- `src/testkit.rs` — filter-local test helpers layered on `pixelflow-test-support`.
## WHERE TO LOOK
- New official filter registration/order: `src/lib.rs`.
- Built-in source of truth: internal `BUILTIN_FILTERS` table in `src/lib.rs` drives both planner registration and runtime executor-factory lookup.
- Namespace and compatibility contract rules: `src/contracts.rs`.
- Typical filter shape: `*_output_media`, `plan_*`, `*_executor_from_options`, `add_*_filter` in each module.
- Metadata-schema interactions: `src/props.rs`; all property filters validate keys/values through `MetadataSchema`.
- Color metadata inference and metadata-only fast paths: `src/colorspace/metadata.rs` and `src/format.rs`.
- Spatial organization: `crop.rs`, `resize.rs`, `planes.rs`.
- Conversion organization: `bit_depth.rs`, `colorspace.rs`, `format.rs`, shared `dither.rs`.
- Temporal organization: `select.rs`, `trim.rs`.
- Shared synthetic frames, golden assertions, metadata fixtures: `src/testkit.rs` plus `crates/pixelflow-test-support/`.
## CONVENTIONS
- Stable script-facing names come from per-module `FILTER_*` constants; descriptor namespace always `pixelflow/std` via `contracts.rs`.
- Planner/runtime split explicit. Upfront media/option validation decides output media first; executor creation should mirror, not redefine, semantics.
- Public filter modules usually expose contract constant, typed options, validated state, output-media helper, graph-builder helper, executor type.
- `FilterCompatibility` must state exact axis changes. Spatial filters touch resolution only when declared; temporal filters declare frame-count/frame-rate effects.
- `props` is schema-aware boundary. Use passed `MetadataSchema`, not ad-hoc metadata key/value checks.
- `format` and `colorspace` share color metadata logic; keep source-of-truth helpers under `colorspace/`, not duplicated across modules.
- Tests stay close to modules. Prefer `testkit` + `pixelflow-test-support` over custom synthetic frame builders or golden math.
## ANTI-PATTERNS
- Do not move official filter semantics into script rewrite, facade glue, or CLI registration code.
- Do not bypass `OfficialFilterContract` for fixed-format/fixed-resolution checks.
- Do not hardcode alternate stdlib namespaces or filter names outside `contracts.rs` and per-module `FILTER_*` constants.
- Do not skip `MetadataSchema` validation in `set_prop`, `clear_prop`, or `require_prop` paths.
- Do not duplicate colorspace metadata resolution in `format.rs` or future filters when `colorspace/metadata.rs` already owns it.
- Do not assume `FilterCompatibility::Preserve` fits multi-input or temporal filters; `merge_planes` and scheduling filters need closer review.
## NOTES
- Organization clusters: color/format/bit-depth conversion, spatial crop/resize, plane split/merge, metadata props, temporal select/trim.
- `convert_colorspace` currently advertises range-only Phase 1 subset; read module docs before extending matrix/transfer behavior.
- `build_builtin_executors` only materializes reachable nodes and errors if registered filter lacks Phase 1 runtime executor.
- `testkit` adds standard media timing plus metadata helpers on top of shared workspace test support.
# PIXELFLOW-SOURCE-FFMS2 KNOWLEDGE BASE
## OVERVIEW
- Cross-crate layering lives in `crates/AGENTS.md`; below only FFMS2-local rules.
- `pixelflow-source-ffms2` = FFMS2-backed source boundary crate under `crates/`.
- `src/lib.rs` looks small, but crate owns more than source-name registration now.
- Real work split into `backend`, `cache`, `executor`, `indexer`, `options`.
- Public surface from `lib.rs`: `SourceRegistry`, `SOURCE_FILTER_NAME`, `register_ffms2_source`, `index_reachable_sources`, `SourceIndexContext`, `IndexProgressSink`, `NoopIndexProgressSink`, `IndexedSources`.
- Dependency shape from `Cargo.toml`: native bridge uses `ffms2`; cache/fingerprint uses `blake3`; temp materialization uses `tempfile`; bounds checks use `semisafe`; shared contracts stay in `pixelflow-core`.
## STRUCTURE
- `src/lib.rs` — crate boundary, re-exports indexing entrypoints, defines script-facing source name and tiny registry.
- `src/backend.rs` — FFMS2 system backend, index read/write, video open/decode bridge, backend traits for tests/system split.
- `src/cache.rs` — persistent cache file format, source fingerprinting, cache read/write helpers.
- `src/executor.rs` — `FrameExecutor` bridge; copies decoded backend frames into PixelFlow-owned `Frame` storage.
- `src/indexer.rs` — reachable-source walk, cache reuse/build path, graph media fixup, executor map assembly, progress callbacks.
- `src/options.rs` — `SourceRequest` option parsing and path/default resolution.
## WHERE TO LOOK
- Public API and re-export list: `crates/pixelflow-source-ffms2/src/lib.rs`.
- Dependency truth and native-library clue: `crates/pixelflow-source-ffms2/Cargo.toml`.
- Reachable-source indexing flow: `crates/pixelflow-source-ffms2/src/indexer.rs`.
- Native FFMS2/FFmpeg calls and error mapping: `crates/pixelflow-source-ffms2/src/backend.rs`.
- Cache naming, fingerprint, payload format: `crates/pixelflow-source-ffms2/src/cache.rs`.
- Source option contract: `crates/pixelflow-source-ffms2/src/options.rs`.
- Decoded-frame ownership handoff: `crates/pixelflow-source-ffms2/src/executor.rs`.
## CONVENTIONS
- Keep public surface narrow. New externally visible entrypoints should route through `src/lib.rs`.
- Keep FFMS2-specific mechanics inside `backend`; avoid leaking raw native details outward.
- Keep cache semantics local to `cache`; indexer should orchestrate, not duplicate file-format logic.
- Keep source request parsing in `options`; current option names visible in code: `cache`, `fps`, `vfr`, `format`, `track`, `threads`.
- Keep graph mutation and executor creation in `indexer`; crate boundary already treats indexing as reachable-source preparation step.
- Preserve executor contract: backend-decoded data gets copied into PixelFlow-owned frame memory before render use.
## ANTI-PATTERNS
- Do not treat this crate as placeholder registration shell only. `lib.rs` is thin; implementation is not.
- Do not move FFMS2/FFmpeg setup logic into CLI or facade layers.
- Do not bypass `options` with ad hoc source-option parsing in callers or tests.
- Do not duplicate cache header/fingerprint logic outside `cache`.
- Do not expose internal `backend`/`executor` details publicly without clear crate-boundary need.
- Do not invent VFR or passthrough behavior not already supported by code.
## NOTES
- Native dependency caveat: common failures come from missing FFMS2 headers/libs, missing FFmpeg dev packages, or runtime shared-library lookup, not only Rust code.
- `index_reachable_sources` only processes sources reachable from final output, then returns updated graph plus executor map in `IndexedSources`.
- `SourceIndexContext` carries optional script dir and logger; `IndexProgressSink` reports begin/progress/cache-hit/finish lifecycle for each source.
- `SourceRegistry` still only records names in registration order; current source filter name constant is `"source"`.
- Cache files use crate-local `.ffms2.pfidx` naming path and fingerprint source files before reusing persisted FFMS2 index bytes.