# Decoder foundation Import `image_codec/api` (dependency alias `image_codec`). Standalone tests pass `--module-path image_codec=src` and `--module-path std="$ZIRAN_ROOT/std"`. The named standard library path separates this package's `image` module from `std/image`. ## Result and ownership `DecodeResult` contains `is_ok`, `image: std/image.Image`, `metadata: ImageMetadata`, and `error: DecodeError`. Check `is_ok` before reading output. `DecodeFailure(error)` returns no pixels. `AllocateImage(metadata,limits,token)` returns a fallible, zero-filled, tight RGBA8 image; it does no decoding. The owned Vec storage uses one bulk `VecResizeBounded(storage,bytes,bytes)` and drops automatically. Its backing capacity equals the requested byte count, including non-power-of-two images; allocator overhead/RSS are not covered by this bound. Cancellation is checked before/after allocation. Move a result or its image once; explicitly clone for an independent copy. No alternate pixel type is defined. `BorrowedBytes { data: []u8 }` and `BorrowBytes(data)` borrow input synchronously. `ByteRange(input,offset,count)` checks signed bounds before slicing and returns `(BorrowedBytes, DecodeError)`. Ziran's mutable slice is not const: the caller keeps backing storage alive and unchanged until every decoder/view returns. `Plane` owns `storage: Vec(u8)` and describes `width`, `height`, byte `stride` and `sample_bytes`. `PlaneView` has the same layout and borrowed `data: []u8`. A plane holds one component, with 1-byte or little endian 2-byte samples. `ValidatePlane(view,limits)` checks layout, span and dimension/working-byte limits; it does not infer subsampling or bit depth. Construct a view from live caller-owned storage. Current `VecSlice` cannot borrow arbitrary pointer-backed Vec fields, so no unsafe automatic pointer-to-plane view helper is promised. `OutputBuffer { data: []u8, stride: s64 }` borrows caller-owned RGBA8 output. `ValidateOutput(output,width,height,limits)` allows padding and requires `(height-1)*stride + width*4` bytes. `CopyImageToOutput(image*,output,limits,token)` leaves padding untouched, validates before writing, and checks cancellation per row. Source and destination must not overlap. Cancellation during work can leave complete rows written; pre-cancellation and invalid layout write nothing. This borrowed buffer never becomes the owned `DecodeResult.image`. ## Limits and metadata `DefaultLimits()` sets 256 MiB input, 32768 per dimension, 67108864 pixels, 256 MiB output, 512 MiB engine scratch, 1 MiB metadata, 4096 source frames, one decoded frame and one worker. Caps are positive except `max_metadata_bytes`, which may be zero. Zero never means unlimited. `ValidateLimits`, `ValidateInputSize`, `ValidateDimensions`, `ValidateMetadata` and `ValidateDecodedFrames` return structured errors. `ValidatePixelDimensions(width,height,limits)` checks the limits, positive dimensions, `max_width`/`max_height` and `max_pixels` with a widened s64 product. It assumes no sample storage, so planar or YUV engines apply their own output byte budget. `ValidateDimensions` calls it, then requires tight RGBA8 `width*height*4 <= max_output_bytes`. `RequiredSpan(width,height,sample_bytes,stride)` checks multiplication overflow. Scratch, metadata, input and output are separate budgets, not a process RSS guarantee. Providers reserve engine scratch and enforce container/metadata caps before allocation. `ImageMetadata` describes transformed output width/height, source bit depth, alpha presence, source premultiplication, source `frame_count`, optional CICP color fields guarded by `color_known`, and retained `metadata_bytes`. Zero source depth/frame count means unknown. Color fields matter only when `color_known` is true. `frame_count` is the source total; `max_decoded_frames` bounds requested work. A two-frame source can return one frame under defaults. No ICC/EXIF payload, HDR rendering, animation playback, transform interpretation or color conversion is implemented by these records. Engines explicitly reject unsupported features. ## Workers and cancellation `DecodeOptions { limits, cancellation: *Cancellation, workers: *WorkerBudget, color_mode }` is made with `DefaultOptions()`. `ValidateOptions` checks limits, the optional worker budget, color mode, then cancellation. Null cancellation means none; null workers means serial caller execution. Both pointed-to values must outlive every operation using them. `Cancellation { requested: bool }`, `Cancel(token*)` and `CancellationError(token*)` provide cooperative checkpoints. This state is single-threaded and non-atomic. Threaded engines adapt their atomic tokens or serialize access; they cannot read/write this flag concurrently. `NewWorkerBudget(limits)` counts every execution lane including the caller. `AcquireWorker`/`ReleaseWorker` enforce the cap and update `peak_workers`. `ReserveWorkingBytes`/`ReleaseWorkingBytes` track scratch and `peak_working_bytes`. Failed reservations leave counts unchanged. Providers release successful leases on every exit. These accounting helpers launch no threads and supply no allocator or locks. Concurrent access needs provider synchronization. ## Providers and errors `DecodeProcedure` is an ordinary procedure type: ```zi (input: BorrowedBytes, metadata: ImageMetadata, options: *DecodeOptions) -> DecodeResult ``` A container codec can expose its own parsing facade and adapt to this procedure without a global plugin registry. `DecodeRGBA8` handles already decoded tight RGBA8 bytes, checks exact length, depth 8, straight alpha, limits and cancellation, and returns independent owned pixels. It leases one worker when supplied. `StrictColor` is supported. `FastColor` and other source representations return `UnsupportedCapability`. It does not identify or decode encoded formats. `DecodeError { code: s32, offset: s64 }` carries a byte offset or -1 when unknown. Use `Error(code,offset)` and `ErrorText(code)`. Codes are `DecodeOK`, `InvalidLimits`, `InvalidInput`, `TruncatedInput`, `MalformedInput`, `UnsupportedCapability`, `LimitExceeded`, `OutputTooSmall`, `DecodeCancelled`, `AllocationFailed`, `WorkerBudgetExceeded`, `InputOutputFailed` and `CorrectnessMismatch`. Unknown codes return "unknown error" text. `DecodeFailure(Error(DecodeOK))` becomes `InvalidInput`. Native tests inject one failed allocation and verify `AllocationFailed`, empty output and one bulk allocation attempt. Limit/overflow failures also pass. This is deterministic allocator fault injection, not OS out-of-memory recovery; Go may terminate on physical exhaustion. ## Example ```zi #import "image_codec/api" options := DefaultOptions() workers := NewWorkerBudget(options.limits) options.workers = *workers metadata: ImageMetadata metadata.width = 1; metadata.height = 1 metadata.source_bit_depth = 8; metadata.frame_count = 1 rgba: [4]u8 = .[20, 40, 60, 255] result := DecodeRGBA8(BorrowBytes(rgba[:]), metadata, *options) // Check result.is_ok; result.image owns pixels until moved or dropped. ```