@ -8,28 +8,35 @@ This plan is the authoritative delivery checklist. A source file, unit test, bui
## Source authority
- AV1 codec syntax, tables, fixed-point arithmetic, prediction, transforms, entropy behavior, filters, and lifecycle behavior must be ported and checked only against libaom commit 03087864cf4bea6abb0d28f95cf7843511413d8f.
- The AV1 specification is the normative behavioral description. It does not authorize copying an implementation from another codec library.
- Existing ImageSharp and JPEG code is the architecture, allocator, SIMD dispatch, pixel conversion, and test-API pattern. It is not an alternate AV1 algorithm source.
- AV1 codec syntax, tables, fixed-point arithmetic, prediction, transforms, entropy behavior, filters, encoder decisions, and lifecycle behavior must be ported and checked only against the current `main` branch of the official libaom checkout at `D:\GitHub\AOMediaCodec\aom`.
- Libaom is the sole external codec implementation source. Do not use HM, libheif, FFmpeg, GPAC, SVT-AV1, dav1d, libgav1, or any other codec implementation as an algorithm, arithmetic, output, or architecture reference.
- Existing ImageSharp and JPEG code is authoritative only for ImageSharp architecture, allocator ownership, SIMD dispatch, pixel conversion, and test API patterns. It is not an alternate AV1 algorithm source.
- Production code must not load, invoke, install, or fall back to a native codec.
- External artifacts may be retained only as test inputs or expected outputs with recorded provenance. They must never become an implementation source.
- Existing independent container files may be used only as interoperability inputs. Native AV1 expected output must be generated by the current libaom `main` checkout, and no independent decoder output may substitute for it.
Reference checkout evidence on 2026-08-31:
- `D:\GitHub\AOMediaCodec\aom` is attached to `main`, clean, and aligned with `origin/main` after a fresh fetch.
- Both `HEAD` and `origin/main` resolved to `441c439b9916474cac15d2822af47a9ad70674a8`. This records the tree audited on that date; it is not a pin and must not prevent later work from updating to the then-current `main`.
## Status notation
- [x] Verified: the current behavior has exact evidence from the pinned reference and the evidence proves the production contract.
- [x] Verified: the current behavior has exact evidence from the current libaom `main` tree and the evidence proves the production contract.
- [~] Locally implemented, checkpoint open: production source exists, but current-tree verification is missing or a known audit issue invalidates the checkpoint.
- [ ] Remaining: the production behavior is absent, incomplete, or has not reached its required implementation boundary.
## Current source reconciliation
Reconciled with the worktree on 2026-08-30.
Reconciled with the worktree on 2026-08-31.
- [~] The bounded container reader, still-image path, sequence parser, AV1 decoder, color pipeline, presentation pipeline, and broad AV1 test suite exist locally.
- [~] The inter-frame decoder contains implementations for single-reference prediction, compound references, inter-intra prediction, selectable compound blending, OBMC, scaled references, local warped motion, and global motion. These downstream paths must not be called verified until the single-reference checkpoint below is corrected and rerun.
- [~] Loop filtering, CDEF, super-resolution, restoration, film grain, layered presentation, alpha composition, and color conversion exist locally. Shared-source cleanup changed the current tree, so final production-path verification is open.
- [~] AV1 writer primitives, forward transforms, symbol encoding, and tile-writing source exist locally, but they are not connected to the public encoder.
- [ ] The public AV1 encoder is not implemented. HeifEncoderCore.Encode throws NotSupportedException when AV1 is selected.
- [x] Removed codec production code, registrations, tests, benchmarks, fixtures, reference outputs, downloaded tools, downloaded source trees, and notices have been manually deleted and verified by the cleanup evidence below.
- [x] Patented codec production code, registrations, tests, benchmarks, fixtures, reference outputs, and notices were manually deleted and committed by `78a74d448`.
- [x] Remaining task-created HM, HEVC, libheif, GPAC, Nokia, FFmpeg, Pillow HEIF, libavif-build, and libjpeg-build directories were traced to their creation commands in the recovered Codex session history and deleted on 2026-08-31. The user-provided repositories and all libaom-only source, build, and reference data were left untouched.
- [~] A PNG metadata-suppression fix and three HEIF/AV1 diagnostic-save call-site corrections are implemented in the current worktree. The exact 34 cases that failed in the net11.0 ARM CI job now pass in Release, but these changes are not yet committed and are not decoder or encoder completion evidence.
- [ ] The complete decoder and encoder release matrix is not complete.
## Immediate execution queue
@ -40,68 +47,131 @@ Work must proceed in this order. Do not skip to a later item while an earlier ch
- [x] Remove production types, registrations, constants, parser branches, properties, tests, benchmarks, fixtures, reference outputs, notices, and documentation for removed codec work.
- [x] Remove downloaded non-libaom reference source, tools, generated outputs, and local installations.
- [x] Retain the pinned libaom source and build artifacts required for AV1 verification.
- [x] Retain the official current-main libaom checkout and libaom-only build artifacts required for AV1 verification.
- [x] Retain user-supplied AV1 fixtures and their recorded expected outputs.
- [x] Audit production source, tests, benchmarks, assets, project files, notices, and documentation for stale removed-code references.
- [x] Build the current source targets in Release with restore disabled, build servers disabled, and one MSBuild node.
- [x] Run the focused AV1/container tests needed to prove the cleanup did not damage AVIF behavior.
- [x] Run scoped semantic and StyleCop inspection, whitespace inspection, and git diff --check.
- [x] Record the exact verified evidence in this plan.
- [~] The prior cleanup tree built in Release with restore disabled, build servers disabled, and one MSBuild node. A fresh current-worktree build remains required after the local PNG cICP fix.
- [~] The prior focused AV1/container set passed, but it missed the net11.0 PNG cICP diagnostic-save failures. The exact 34 CI failures now pass after the local fix; the final current-worktree checkpoint set remains required.
- [~] Roslynk currently reports zero compiler errors for the local fix, and `git diff --check` passes. Scoped StyleCop and final current-worktree inspection remain required.
- [~] Record the final current-worktree cleanup and cICP evidence after the checkpoint verification completes.
Verified cleanup evidence on 2026-08-30:
Historical cleanup evidence from 2026-08-30, retained with its limitation:
- Release source builds passed for net10.0 and net11.0 with zero warnings and zero errors. Both builds used `--no-restore`, `--disable-build-servers`, and one MSBuild node.
- The focused net10.0 HEIF decoder, encoder, metadata, sequence-parser, and AV1 reconstruction set passed 221 of 221 tests with zero failures and zero skips.
- The focused net10.0 HEIF decoder, encoder, metadata, sequence-parser, and AV1 reconstruction set passed 221 of 221 tests with zero failures and zero skips. It did not execute the net11.0 diagnostic-save path that later failed in CI.
- The Roslyn compiler and configured StyleCop analyzers accepted the changed production source. Roslynk's `open_solution` entry point was attempted separately but failed before returning a solution handle, so no Roslynk result is claimed.
- The final text and filename audit found no removed-code references outside the unchanged repository and shared-infrastructure `.gitattributes` patterns.
- The tracked-source text and filename audit found no removed-code references outside the unchanged repository and shared-infrastructure `.gitattributes` patterns. A later history reconstruction found ignored task-created reference directories that this audit missed; those directories were deleted on 2026-08-31.
- `git diff --check` passed and neither `.gitattributes` file changed.
Current cICP failure correction evidence from 2026-08-31:
- The failure was not decoded HEIF metadata. `PngEncoderCore.WriteCicpChunk` ignored `PngChunkFilter.ExcludeAll`, so diagnostic PNG saves attempted to write a non-identity source matrix that PNG cannot represent.
- `PngEncoderCore` now honors the existing `SkipMetadata` contract for cICP, and the three affected HEIF/AV1 diagnostic saves explicitly use `PngEncoder { SkipMetadata = true }`. Actual comparisons and decoded-image metadata assertions remain unchanged.
- The direct embedded-ICC case and every row of the 12-case profile matrix passed: 13 of 13 net11.0 Release cases.
- The exact 34 cases reported by CI passed: 34 of 34 net11.0 Release cases, with zero failures and zero skips.
- Roslynk reported zero compiler errors after the fix, and `git diff --check` passed.
Recovered task-history evidence from 2026-08-31:
- The primary session beginning on 2026-08-24 was reopened from task ID `01a03239-831b-7831-84e7-7f6947279ccb`: 96,777 records, 295 turn contexts, 211 compactions, 190 user messages, 1,920 assistant messages, and 13,671 tool calls.
- The continuation beginning on 2026-08-27 was reopened from task ID `01a04314-f1c6-7133-b1bc-5c74a94dd714`: 61,129 records at the audit point, 166 turn contexts, 96 compactions, 223 user messages, 1,113 assistant messages, and 8,942 tool calls.
- The restored first session records the user selecting official AOM/libaom as the AV1 source after the ImageSharp discussion was inspected. It does not authorize another codec implementation as an AV1 source and does not authorize importing a patented codec.
- The restored tool calls identify the exact creation commands for the non-libaom source, tool, and output directories removed on 2026-08-31. No directory was selected for deletion from its name alone.
- The recovered Git sequence establishes that `78a74d448` removed the patented codec implementation and `92fa7a8ca` merged the later upstream ImageSharp changes. The current branch and worktree, not an older summary, remain authoritative.
### 2. Correct the single-reference inter-frame checkpoint
The following findings are confirmed by direct source inspection and keep the checkpoint open.
- [ ] Correct interpolation-filter syntax in Av1TileReader.
- Current source treats every global-motion type other than Translation as non-translational.
- Pinned libaom omits interpolation-filter syntax only when the selected model type is greater than Translation.
- Identity GLOBALMV blocks of sufficient size must consume switchable-filter symbols.
- Add production-path syntax coverage using the default Identity model. A test that forces Translation does not prove this rule.
- [ ] Correct both spatial reference-MV extension loops in Av1ReferenceMotionVectors.
- Current source stops spatial extension when the stack reaches two entries.
- Pinned libaom extends the stack through MAX_REF_MV_STACK_SIZE, which is eight.
- Preserve DRL candidates and consume every required DRL symbol.
- Describe this as spatial single-reference extension, never temporal extension.
- [ ] Replace the contiguous-span dependency in Av1FrameBuffer and all affected inter reconstruction callers.
- Current GetPaddedPlaneSpan calls DangerousGetSingleSpan.
- Buffer2D may use multiple memory groups under a constrained allocator.
- Implement an efficient group-safe row-oriented contract using established ImageSharp Buffer2D access patterns, or prove and enforce a real contiguous-allocation invariant at the allocator boundary.
- Do not copy planes and do not allocate per block, row, or scanline.
- Audit direct DangerousGetSingleSpan use in reconstruction, reference-border extension, film grain, copying, and encoder work rather than fixing only one wrapper.
- [ ] Prove the real Av1BlockDecoder.DecodeBlock inter-reconstruction branch.
The checkpoint implementation is complete. The first two inherited audit findings were rechecked against current libaom `main` and did not require production changes; the remaining production boundary, reconstruction, and ownership work is now implemented and verified.
- [x] Reconcile interpolation-filter syntax in `Av1TileReader` with current libaom `main`.
- Current libaom `av1_is_interp_needed` calls `is_nontrans_global_motion`, whose loop rejects only `TRANSLATION`. Identity GLOBALMV therefore omits switchable-filter symbols.
- Current `Av1TileReader` uses the same non-Translation classification. The existing Identity test leaves sentinel filter symbols unread, while the Translation test consumes them.
- No production change is required. The stale test comment was changed from “pinned” to “current” libaom.
- [x] Reconcile both spatial single-reference extension loops in `Av1ReferenceMotionVectors` with current libaom `main`.
- Current libaom `setup_ref_mv_list` stops both loops at `MAX_MV_REF_CANDIDATES`, which is two. `MAX_REF_MV_STACK_SIZE`, which is eight, is the stack capacity used by the earlier direct and temporal candidate collection; it is not the stop condition for these two extension loops.
- Current `Av1ReferenceMotionVectors` uses the same two-entry stop condition and retains an eight-entry stack for earlier candidates and DRL selection.
- No production change is required. This remains spatial single-reference extension, not temporal extension.
- [x] Establish and enforce the contiguous frame-plane invariant used by `Av1FrameBuffer` and inter reconstruction.
- Every frame plane is allocated with `preferContiguosImageBuffers: true`, so a constrained allocator cannot split a representable padded plane into normal memory groups.
- `Av1FrameBuffer` now rejects an external frame geometry whose padded plane reaches the `int.MaxValue` fallback boundary before any allocation. This makes every direct `DangerousGetSingleSpan` call an enforced owner invariant rather than a memory-group accident.
- `ConstructorRequestsContiguousPaddedPlanes` proves that a plane larger than the allocator's group capacity is one group. `ConstructorRejectsPaddedPlaneThatCannotBeContiguous` proves that an unrepresentable plane is rejected before allocation.
- The production path performs no plane copy and no per-block, per-row, or per-scanline allocation.
- [x] Prove the real `Av1BlockDecoder.DecodeBlock` inter-reconstruction branch.
- Decode the progressive dependent-frame fixture through the complete public production path.
- Compare the final frame's native Y, Cb, and Cr planes exactly with pinned libaom output.
- Compare the final frame's native Y, Cb, and Cr planes exactly with current-main libaom output.
- Compare the final presented image through the established ImageSharp reference-image comparison API.
- Do not substitute an internal helper test, fake tile reader, non-zero assertion, custom pixel loop, or tolerant comparison.
- [] Prove motion-field ownership and lifetime.
- [x] Prove motion-field ownership and lifetime.
- Track initialization, retained-slot aliases, failure unwinding, presentation ownership, decoder-result ownership, and final disposal.
- Every allocator-owned object must be returned exactly once.
- [] Correct stale documentation.
- [x] Correct stale documentation.
- Av1InterFrameModeInfoTests must describe the behavior it actually proves.
- Do not claim production reconstruction, constrained allocation, ownership, or reference-stack coverage unless the test executes that contract.
- [ ] Only after all evidence is recorded may this checkpoint be committed.
Verified single-reference checkpoint evidence on 2026-08-31:
- The current-main `aomdec` was rebuilt directly from `D:\GitHub\AOMediaCodec\aom` and identified itself as `3.15.0-13-g441c439b99`.
- Decoding the 72-byte progressive payload with `--all-layers`, one thread, and row multithreading disabled produced 2,178 YUV444 color samples. All samples in both layers match the first three planes of the stored YUV444-alpha reference exactly.
- `DecodeProgressiveSingleReferenceMatchesPinnedReferences` executes the production decoder through FeatureTestRunner and compares the complete presented `Rgba32` image with `CompareToReferenceOutput(ImageComparer.Exact, provider)`. The redundant manual alpha loop was removed.
- `DecodeProgressiveSingleReferenceWithConstrainedAllocator` executes the same production reconstruction with a 1,024-byte allocator group capacity and verifies that every allocation is returned exactly once.
- `MotionFieldsFollowReferenceAliasesAndPresentationOwnership`, `MotionFieldAllocationFailureUnwindsTileReaderOwnership`, `DecodeProgressiveSingleReferenceTracksMotionFieldResultOwnership`, and the reference-store replacement, reset, and transfer tests cover initialization, aliases, presentation ownership, decoder-result ownership, failure unwinding, repeated disposal, and exactly-once final returns.
- The focused Release set passed 17 of 17 tests on net10.0 and 17 of 17 tests on net11.0, with zero failures and zero skips. This includes both GLOBALMV syntax cases, spatial extension, plane invariants, production reconstruction, FeatureTestRunner dispatch, and ownership.
- Release source builds passed for net10.0 and net11.0 with zero warnings and zero errors.
- Roslynk reported zero compiler errors. The scoped changed-file analyzer inspection reported no StyleCop diagnostics attributable to this checkpoint; its only remaining match is the pre-existing xUnit cancellation warning in an unrelated `HeifDecoderTests` method.
- `git diff --check` passed, and neither `.gitattributes` file changed.
Exact verification commands, run directly in the foreground from `D:\GitHub\ynse01\ImageSharp`:
### 3. Reverify downstream inter prediction in recorded order
These implementations exist locally but inherit the open single-reference syntax, buffer, and ownership foundation.
@ -119,7 +189,7 @@ These implementations exist locally but inherit the open single-reference syntax
For every item:
- [ ] Trace syntax and arithmetic to the pinned libaom commit.
- [ ] Trace syntax and arithmetic to the current libaom `main` tree.
- [ ] Execute the real production decoder path.
- [ ] Compare native planes exactly.
- [ ] Compare presentation through the established reference-image API.
@ -131,8 +201,8 @@ For every item:
Previously verified algorithm checkpoints remain valuable evidence, but the final decoder gate requires a fresh current-tree run after the inter and cleanup corrections.
- [x] Bounded OBU framing, sequence headers, frame headers, tile groups, alignment, and trailing-bit parsing have pinned-reference checkpoint evidence.
- [~] Bounded OBU framing, sequence headers, frame headers, tile groups, alignment, and trailing-bit parsing have historical checkpoint evidence against an obsolete pinned tree. Re-audit the current libaom `main` implementation before restoring verified status.
- [~] Partition traversal, mode information, segmentation, delta quantization, transform-size selection, coefficient decoding, inverse quantization, and inverse transforms have historical checkpoint evidence against an obsolete pinned tree. Re-audit the current libaom `main` implementation before restoring verified status.
- [x] Intra prediction covers directional, DC, smooth, Paeth, chroma-from-luma, filter-intra, and palette families with the established operator architecture.
- [x] Intra-block copy has exact native reconstruction and feature-isolated SIMD evidence.
- [x] Lossless inverse transform, loop filtering, CDEF, super-resolution, restoration, and film grain have focused checkpoint evidence.
@ -148,7 +218,7 @@ Previously verified algorithm checkpoints remain valuable evidence, but the fina
Decoder exit gate:
- [ ] Every supported native format and AV1 tool has exact pinned-libaom production-path evidence.
- [ ] Every supported native format and AV1 tool has exact current-main libaom production-path evidence.
- [ ] Every supported presentation behavior has established reference-image evidence at the correct output precision.
- [ ] No decoder path relies on a native codec, copied plane, per-block allocation, or contiguous memory-group accident.
- [ ] All allocator ownership is deterministic and exactly once.
@ -181,7 +251,7 @@ Writer primitives are not an encoder. The public encoder remains incomplete unti
James Jackson-South
3 days ago