Local-first by design.
Explicit on failure.

REQUEST LIFECYCLE

What happens on a cache miss?

1. containerd sends an OCI manifest or blob request to the local SIC registry mirror.
2. SIC checks its content-addressed local cache and validates cached content when required.
3. On a miss, SIC tries ready peers discovered through the Kubernetes API. A peer is expected to return content or a miss, not redirect the caller elsewhere.
4. If configured and allowed, SIC may contact an upstream registry. Upstream fallback is disabled by default and constrained by an explicit registry allow-list.
5. New content is written to a temporary file, hashed against the requested digest, and only published after verification. Download and disk-space limits are enforced.

CONTENT INTEGRITY

Verify before publishing.

Blob content is hashed as it arrives. A digest mismatch or interrupted download is not published as a valid cache entry. Existing files are checked when needed; SIC records verified file identity metadata and uses a background scrubber to detect disk corruption that metadata checks alone might miss.

Streaming responses can begin before a complete blob is available, but the final byte is held until digest verification passes. If the source fails or the digest is wrong, the response is cut short so the containerd client sees a failure rather than a falsely complete layer. containerd also checks layer digests.

COORDINATION

Concurrent requests share work safely.

Single-flight coordination coalesces requests for the same missing object within a SIC process. Manifest flights account for representation and authorization differences. Per-digest write coordination and capacity reservations limit duplicate writes and concurrent over-admission. These guarantees are process-local; the cache is not a distributed transactional store.

CONTAINERD INTEGRATION

Use the supported content API.

SIC imports existing content and image-name aliases through containerd's gRPC services. It does not scrape containerd's on-disk layout or call a ctr subprocess. The importer can skip content that disappears during containerd garbage collection and reports other import errors. Import copies data into SIC's independent cache, so the same image bytes may occupy disk twice on a node.

NETWORK SECURITY

Redirects are not peer instructions.

A peer redirect is treated as a faulty response and is not followed. Registry redirects are supported only over HTTPS, with a bounded chain. Authorization headers are not forwarded by Go's HTTP client to a different host from the one they were intended for.