fix: image ref parse consistency in storage

[scook12]

#246

I ran into this ^ while working on a project that has smolvm upstream and ended up down the rabbit hole. This is one of my first "real" chunks of work in Rust, so don't be shy about rejecting/tearing down the PR.

Thanks for reading!

Changes:

• extract image ref parsing to dedicated module
• ensure the storage layer consistently uses canonical form of all image refs with wiring in main/storage
• extract the pull/use cache decision to a small, testable layer between query_image and call sites
• unit + integration tests
• unrelated: some cfg flags to avoid cstr/libcmount type errors on macOS

TODO:

• change Reference['digest'] over to Option<String>
• fill in empty test stubs
• better/complete doc strings
• there's small duplication in oci.rs - review, find any todos
• fix fail branch; always clean and pull on error

[scook12]

This is a tidbit I'm uncertain about; is there a reason to fail when manifest parsing errors out? This can easily be swapped out for just pulling instead

[BinSquare]

Are there cases that lead to manifest failures where it is still wise to continue to pull?

My thinking is that there isn't a good reason to fail to parse the manifest ever unless something unrecoverable has happened.

[scook12]

Yeah, it does seem like in most cases we'd just end up pulling instead of panicking. If we have an io/parse error, we can always just remove the manifest and pull, similar to how we do when there's missing layers.

If we panicked and didn't remove the manifest when it's corrupted or otherwise blocking the pull, then subsequent pulls for that image would always fail which seems undesirable.

[scook12]

At call site, we now handle the Err branch by performing cleanup

[stage-review]

Ready to review this PR? Stage has broken it down into 4 individual chapters for you:

	Title
1	Add regex dependency and platform compatibility flags
2	Implement canonical image reference parsing module
3	Refactor storage to use canonical image references
4	Extract cache resolution logic and add tests

_{Chapters generated by Stage for commit e9fe1cf on May 28, 2026 7:25pm UTC.}