OCI Image Specs support — resolve #5 vs main + finish read/write paths

[sashml]

Summary

Resolves PR #5 (OCI Image Specs support) against current main and finishes the implementation. This branch (oci-image-specs-resolve) is main + #5's OCI feature, conflict-free, building clean under -Werror, with the previously-incomplete paths now actually working.

What was wrong with #5 (found by building it under -Werror)

• Conflicts with main across 20 files (main added encryption + Windows/MSVC + TOCTOU hardening since Add OCI Image Specs support #5 branched).
• Did not compile with BFC_WITH_OCI=ON: missing _GNU_SOURCE (strdup/fmemopen), -Werror=format-truncation on path building.
• Write path never worked: passed NULL to bfc_add_file (which rejects NULL) and never serialized the manifest/index to JSON.
• Read path was a stub: bfc_get_oci_manifest/config, bfc_list_oci_layers returned BFC_OK without doing anything.
• Wrong schema constant "2.0.1" — per the OCI image-spec schemaVersion MUST be 2.
• Dead duplicate src/bfc_oci.c; a triple-pointer bug + invalid ... digests in tests/example (tripped the .. path-traversal guard).

Changes

Merge: union of main's encryption/portability work and #5's OCI feature (20 files).

Write path: bfc_create_from_oci_manifest/_index now serialize real OCI JSON via open_memstream.

Read path (new): implemented with libcjson

• bfc_get_oci_manifest — parses schemaVersion/mediaType/config{digest,size}/layers[].digest
• bfc_get_oci_config — parses architecture/os/created/author
• bfc_list_oci_layers — parses layers[] into bfc_oci_layer_t[]

Dependency: libcjson is wired as the OCI feature's dep via pkg-config under BFC_WITH_OCI, mirroring the existing libzstd/libsodium optional-dep pattern. Build OCI with: apt install libcjson-dev (or vcpkg on Windows).

Correctness: schemaVersion → "2"; truncation guards on all path snprintfs; removed dead src/bfc_oci.c; fixed the test triple-pointer + example digests.

Tests: added a write→read round-trip covering manifest, config and layers.

Docs: CALM + Mermaid C4 model of the OCI↔core boundary under docs/architecture/.

Architecture (critical parts)

OCI module ↔ BFC core boundary — the OCI layer only touches BFC's public API; gated behind BFC_WITH_OCI (default OFF):

                ┌───────────────────────────────────────────────────┐
   CLI / app ──►│  OCI module  src/lib/bfc_oci.c   [BFC_WITH_OCI]    │
                │   write: create_from_oci_manifest/_index, add_layer│
                │   read : get_oci_manifest/_config, list_oci_layers │
                └──────┬─────────────────────────────────┬──────────┘
          write path   │                       read path  │
        bfc_add_file   ▼                    bfc_stat +     ▼
                ┌───────────────────────────  bfc_read ───────────────┐
                │              BFC core  (bfc_reader / bfc_writer)     │
                └──────────────────────────────────────────────────────┘
   build JSON: open_memstream            parse JSON: libcjson (pkg-config)

Write path — struct → JSON → container entry:

  bfc_oci_manifest_t ──open_memstream──► {"schemaVersion":2,"mediaType":…,
        │                                 "config":{…},"layers":[{…}]}
        │                                        │ fmemopen
        ▼                                        ▼
   (caller-owned)                           bfc_add_file ──► "manifest.json"

Read path — container entry → JSON → struct (was a BFC_OK no-op, now real):

  "manifest.json" ──bfc_stat+bfc_read──► raw bytes ──cJSON_ParseWithLength──►
        DOM ──extract schemaVersion/mediaType/config/layers──► bfc_oci_manifest_t

Resulting BFC container layout for an OCI image:

  image.bfc
  ├── manifest.json            schemaVersion=2, mediaType, config{digest,size}, layers[]
  ├── config.json              architecture, os, created, author
  └── blobs/sha256/<digest>    layer blobs (bfc_add_oci_layer)

Verification

Config	Build	Tests
Default (OCI off)	clean	11/11
Release + OCI + ZSTD (-Werror)	clean	11/11 (incl. round-trip)
oci_example end-to-end	—	runs, exit 0

BFC_WITH_OCI defaults OFF.

[sashml]

Folded into #5: fast-forwarded the conflict resolution + write/read implementation + fixes onto oci-image-specs-support (maintainer edit). #5 now carries this work, so closing this duplicate.