cozip 2026.4.29__tar.gz

cozip-2026.4.29/.gitignore

@@ -0,0 +1,16 @@
+
+.DS_Store
+
+spec/main.md
+demo.py
+demo.zip
+.vscode/
+
+.pytest_cache/
+__pycache__/
+*.pyc
+build/
+*.egg-info/
+.DS_Store
+
+*.dylib

cozip-2026.4.29/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: cozip
+Version: 2026.4.29
+Summary: Cloud-Optimized ZIP — Python bindings
+Requires-Python: >=3.10
+Requires-Dist: cffi>=1.16
+Requires-Dist: pyarrow>=14

cozip-2026.4.29/cozip/__init__.py

@@ -0,0 +1,14 @@
+"""cozip — Cloud-Optimized ZIP."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._core import CozipError, ffi, lib
+from ._writer import create
+
+try:
+    __version__ = version("cozip")
+except PackageNotFoundError:
+    # Running from a checkout without `pip install`.
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["CozipError", "create", "ffi", "lib", "__version__"]

cozip-2026.4.29/cozip/_core.py

@@ -0,0 +1,124 @@
+"""cffi bindings to libcozip. Loads the bundled shared library at import time."""
+
+import os
+import sys
+from pathlib import Path
+
+import cffi
+
+# Status codes. Must match cozip.h.
+COZIP_OK                    = 0
+COZIP_ERR_INVALID_LFH       = 1
+COZIP_ERR_ARCHIVE_TOO_SMALL = 2
+COZIP_ERR_INVALID_ARGUMENT  = 100
+COZIP_ERR_BUFFER_TOO_SMALL  = 101
+COZIP_ERR_IO                = 102
+
+# Profile selector for cozip_build_index_payload.
+COZIP_PROFILE_NONE = 0
+COZIP_PROFILE_FLAT = 1
+COZIP_PROFILE_TACO = 2
+
+# Source kind for cozip_entry_t.source.kind.
+COZIP_SOURCE_NONE   = 0
+COZIP_SOURCE_PATH   = 1
+COZIP_SOURCE_BUFFER = 2
+
+
+ffi = cffi.FFI()
+ffi.cdef("""
+typedef struct { int code; char message[192]; } cozip_error_t;
+
+typedef struct {
+    int kind;
+    union {
+        const char* path;
+        struct { const uint8_t* data; size_t size; } buffer;
+    } u;
+} cozip_source_t;
+
+typedef struct {
+    const char* arc_name;
+    uint64_t payload_size;
+    bool in_index;
+    cozip_source_t source;
+    uint64_t lfh_offset, lfh_size, payload_offset;
+} cozip_entry_t;
+
+const char* cozip_status_string(int status);
+
+int cozip_plan(cozip_entry_t*, size_t, cozip_error_t*);
+int cozip_index_payload_size(const cozip_entry_t*, size_t,
+                             size_t*, cozip_error_t*);
+int cozip_build_index_payload(const cozip_entry_t*, size_t, int,
+                              uint8_t*, size_t, cozip_error_t*);
+int cozip_write_archive(const char*, const cozip_entry_t*, size_t,
+                        const uint8_t*, size_t, cozip_error_t*);
+int cozip_patch_integrity_hash(const char*, size_t, cozip_error_t*);
+""")
+
+
+def _lib_filename() -> str:
+    """Returns the shared library filename for the current platform.
+
+    No 'lib' prefix anywhere because the CMakeLists sets PREFIX ""
+    so the artifact name is identical across Linux/macOS/Windows.
+    """
+    if sys.platform == "darwin":
+        return "cozip.dylib"
+    if sys.platform == "win32":
+        return "cozip.dll"
+    return "cozip.so"  # linux + bsd
+
+
+def _resolve_lib_path() -> str:
+    """Searches for the shared library in several candidate locations."""
+    name = _lib_filename()
+
+    # 1. Env var override (for debug / development).
+    env = os.environ.get("COZIP_LIB_PATH")
+    if env:
+        if not Path(env).exists():
+            raise ImportError(f"cozip: COZIP_LIB_PATH={env!r} does not exist")
+        return env
+
+    # 2. Canonical path, next to this file, under _lib/.
+    here = Path(__file__).resolve().parent
+    canonical = here / "_lib" / name
+    if canonical.exists():
+        return str(canonical)
+
+    # 3. Fallback to any neighboring build/ dir (dev mode without reinstall).
+    repo = here.parent.parent
+    for build_dir in (repo / "python" / "build", repo / "build"):
+        if build_dir.is_dir():
+            for found in build_dir.rglob(name):
+                return str(found)
+
+    raise ImportError(
+        f"cozip: native library {name!r} not found.\n"
+        f"  Tried: {canonical}\n"
+        f"  Fix: run `pip install -e python/` from the repo root, "
+        f"or set COZIP_LIB_PATH=/abs/path/to/{name}"
+    )
+
+
+lib = ffi.dlopen(_resolve_lib_path())
+
+
+class CozipError(RuntimeError):
+    """Raised when libcozip returns a non-zero status."""
+
+    def __init__(self, code: int, name: str, message: str):
+        super().__init__(f"[{name}] {message}")
+        self.code = code
+        self.name = name
+        self.message = message
+
+    @classmethod
+    def from_struct(cls, err) -> "CozipError":
+        """Builds the exception from a cozip_error_t struct."""
+        code = int(err.code)
+        msg = ffi.string(err.message).decode("utf-8", errors="replace")
+        name = ffi.string(lib.cozip_status_string(code)).decode("ascii")
+        return cls(code, name, msg)

cozip-2026.4.29/cozip/_writer.py

@@ -0,0 +1,295 @@
+"""High-level archive writer (PROFILE_FLAT only, path sources only).
+
+Walks the libcozip pipeline end-to-end and drops a `__metadata__.parquet`
+at the tail with a row per indexed user file. Extra columns from the
+input table flow through to the parquet untouched.
+
+For TACO/NONE profiles or buffer sources, drop down to the low-level
+API: `cozip.lib.cozip_build_index_payload` etc.
+"""
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from ._core import (
+    COZIP_PROFILE_FLAT,
+    COZIP_SOURCE_PATH,
+    CozipError,
+    ffi,
+    lib,
+)
+
+# Names the writer reserves for itself; users cannot use them.
+_RESERVED_NAMES = frozenset({"__cozip__", "__metadata__"})
+
+
+def _check(status: int, err: Any) -> None:
+    """Raise a CozipError if a libcozip call returned a non-zero status.
+
+    Args:
+        status (int): Return code from a libcozip function call.
+        err (Any): Pointer to a populated `cozip_error_t` struct.
+
+    Raises:
+        CozipError: When `status != 0`, built from the error struct.
+    """
+    if status != 0:
+        raise CozipError.from_struct(err)
+
+
+def _build_metadata_parquet(
+    table: pa.Table,
+    entries: Any,
+    n_users: int,
+    in_idx: list[bool],
+    create_options: dict | None,
+    temp_dir: str | Path | None,
+) -> Path:
+    """Build the `__metadata__.parquet` temp file.
+
+    Filters the input table to in-index rows, drops the columns the
+    spec considers writer-private (`path`, `in_index`), and appends
+    `offset` (uint64) and `size` (uint64) computed by `cozip_plan`.
+    The output column order is `name, offset, size, ...` followed by
+    every other user-supplied column in input order.
+
+    Args:
+        table (pa.Table): Original input table from the caller.
+        entries (Any): cffi `cozip_entry_t[]` array, post-`cozip_plan`,
+            so each entry's `payload_offset` and `payload_size` are set.
+        n_users (int): Number of user entries (excludes `__metadata__`,
+            which sits at index `n_users`).
+        in_idx (list[bool]): Per-user-row indexing flag, length `n_users`.
+        create_options (dict | None): kwargs forwarded to
+            `pyarrow.parquet.write_table`.
+        temp_dir (str | Path | None): Directory for the temp parquet.
+            None means use `tempfile.gettempdir()` (which respects the
+            `TMPDIR` env var).
+
+    Returns:
+        Path: Filesystem path of the written `.parquet` file. The caller
+            is responsible for deleting it.
+    """
+    indexed = [i for i in range(n_users) if in_idx[i]]
+    offsets = [int(entries[i].payload_offset) for i in indexed]
+    sizes   = [int(entries[i].payload_size)   for i in indexed]
+
+    mask = pa.array(in_idx, type=pa.bool_())
+    meta = table.filter(mask)
+    drop = [c for c in ("path", "in_index") if c in meta.column_names]
+    if drop:
+        meta = meta.drop_columns(drop)
+
+    meta = meta.append_column("offset", pa.array(offsets, type=pa.uint64()))
+    meta = meta.append_column("size",   pa.array(sizes,   type=pa.uint64()))
+
+    # Column order: name, offset, size, ...rest-in-input-order.
+    rest = [c for c in meta.column_names if c not in ("name", "offset", "size")]
+    meta = meta.select(["name", "offset", "size"] + rest)
+
+    if temp_dir is not None:
+        Path(temp_dir).mkdir(parents=True, exist_ok=True)
+
+    tmp = tempfile.NamedTemporaryFile(
+        suffix=".parquet",
+        dir=str(temp_dir) if temp_dir is not None else None,
+        delete=False,
+    )
+    tmp.close()
+    parquet_path = Path(tmp.name)
+
+    try:
+        pq.write_table(meta, str(parquet_path), **(create_options or {}))
+    except Exception:
+        parquet_path.unlink(missing_ok=True)
+        raise
+
+    return parquet_path
+
+
+def create(
+    out_path: str | Path,
+    table: pa.Table,
+    create_options: dict | None = None,
+    temp_dir: str | Path | None = None,
+) -> str:
+    """Build a FLAT-profile .cozip archive on disk.
+
+    Walks the libcozip pipeline end-to-end: plan offsets, drop a
+    `__metadata__.parquet` describing the indexed user files, serialize
+    the cozip index, write the archive via libzip, and patch the
+    FNV-1a 64 integrity hash. The output file is overwritten if it
+    exists. The temp parquet is always cleaned up.
+
+    The metadata parquet contains: `name` (str), `offset` (uint64),
+    `size` (uint64), plus every additional column from `table` other
+    than `path` and `in_index`. Only rows with `in_index=True` are
+    listed.
+
+    Args:
+        out_path (str | Path): Destination file path. Resolved to an
+            absolute path before writing.
+        table (pa.Table): Source entries. Must provide 'name' (str) and
+            'path' (str). Optional 'in_index' (bool, default True)
+            controls whether the entry is listed in the cozip index
+            and the metadata parquet. Any other columns flow through
+            to the metadata parquet.
+        create_options (dict | None, optional): Forwarded as kwargs to
+            `pyarrow.parquet.write_table` when writing the metadata
+            parquet. Use this to set compression, row_group_size, etc.
+            Defaults to None (pyarrow defaults).
+        temp_dir (str | Path | None, optional): Directory where the
+            temporary metadata parquet is written before being absorbed
+            into the archive. Created if missing. Defaults to None,
+            which uses `tempfile.gettempdir()` (respects the `TMPDIR`
+            env var, useful when /tmp is restricted or full).
+
+    Raises:
+        ValueError: A required column is missing, the table is empty,
+            a row uses a reserved name, or names contain duplicates.
+        FileNotFoundError: A row's source path does not exist.
+        CozipError: A libcozip call failed (I/O, allocation, malformed
+            archive output, etc.).
+
+    Returns:
+        str: Absolute path of the created archive.
+    """
+    cols = table.column_names
+    missing = {"name", "path"} - set(cols)
+    if missing:
+        raise ValueError(
+            f"cozip.create: table is missing required column(s): "
+            f"{sorted(missing)}"
+        )
+
+    n_users = len(table)
+    if n_users == 0:
+        raise ValueError("cozip.create: empty entry list")
+
+    names = table.column("name").to_pylist()
+    paths = table.column("path").to_pylist()
+    in_idx = (
+        table.column("in_index").to_pylist()
+        if "in_index" in cols
+        else [True] * n_users
+    )
+
+    # Reserved names + duplicates: format-level rules belong to the
+    # binding, not to libcozip (cozip.c only protects memory).
+    seen: set[str] = set()
+    for i, name in enumerate(names):
+        if name in _RESERVED_NAMES:
+            raise ValueError(
+                f"cozip.create: row {i} uses reserved name {name!r}"
+            )
+        if name in seen:
+            raise ValueError(
+                f"cozip.create: duplicate name {name!r} at row {i}"
+            )
+        seen.add(name)
+
+    out_path = str(Path(out_path).resolve())
+
+    # Allocate one extra slot for the __metadata__ entry, which always
+    # sits last so its size never shifts the offsets of user entries.
+    n_total = n_users + 1
+    entries = ffi.new(f"cozip_entry_t[{n_total}]")
+    keepalive: list[Any] = []
+
+    for i in range(n_users):
+        path = Path(paths[i])
+        if not path.exists():
+            raise FileNotFoundError(
+                f"cozip.create: row {i} ({names[i]!r}): "
+                f"source file not found: {path}"
+            )
+
+        name_c = ffi.new("char[]", names[i].encode("utf-8"))
+        path_c = ffi.new("char[]", str(path).encode("utf-8"))
+        keepalive.extend((name_c, path_c))
+
+        entries[i].arc_name      = name_c
+        entries[i].payload_size  = path.stat().st_size
+        entries[i].in_index      = bool(in_idx[i])
+        entries[i].source.kind   = COZIP_SOURCE_PATH
+        entries[i].source.u.path = path_c
+
+    # __metadata__ entry: real size and source path are unknown until
+    # we generate the parquet. Use 0/NULL placeholders for the first
+    # cozip_plan call.
+    meta_idx = n_users
+    meta_name_c = ffi.new("char[]", b"__metadata__")
+    keepalive.append(meta_name_c)
+
+    entries[meta_idx].arc_name      = meta_name_c
+    entries[meta_idx].payload_size  = 0
+    entries[meta_idx].in_index      = True
+    entries[meta_idx].source.kind   = COZIP_SOURCE_PATH
+    entries[meta_idx].source.u.path = ffi.NULL
+
+    err = ffi.new("cozip_error_t*")
+
+    # 1. First plan: produces correct payload_offset/size for every
+    #    user entry. The __metadata__ slot's offset is also correct
+    #    (it sits last and its placeholder size doesn't perturb anyone
+    #    earlier in the archive).
+    _check(lib.cozip_plan(entries, n_total, err), err)
+
+    # 2. Build the metadata parquet using the user offsets we just got.
+    parquet_path = _build_metadata_parquet(
+        table, entries, n_users, in_idx, create_options, temp_dir
+    )
+
+    try:
+        # 3. Now we know the real parquet size — patch it into the
+        #    __metadata__ entry and re-plan. Re-planning is cheap and
+        #    handles the rare case where the parquet crosses 4 GiB and
+        #    needs a ZIP64 LFH extra (which would shift the metadata
+        #    payload_offset by 20 bytes; user offsets stay untouched).
+        parquet_size = parquet_path.stat().st_size
+        meta_path_c = ffi.new("char[]", str(parquet_path).encode("utf-8"))
+        keepalive.append(meta_path_c)
+
+        entries[meta_idx].payload_size  = parquet_size
+        entries[meta_idx].source.u.path = meta_path_c
+
+        _check(lib.cozip_plan(entries, n_total, err), err)
+
+        # 4. Size the cozip index payload buffer.
+        idx_size = ffi.new("size_t*")
+        _check(
+            lib.cozip_index_payload_size(entries, n_total, idx_size, err),
+            err,
+        )
+
+        # 5. Serialize the cozip index payload (profile = FLAT).
+        payload = ffi.new(f"uint8_t[{idx_size[0]}]")
+        _check(
+            lib.cozip_build_index_payload(
+                entries, n_total, COZIP_PROFILE_FLAT, payload, idx_size[0], err
+            ),
+            err,
+        )
+        
+        # 6. Write the archive (libzip-backed).
+        out_path_b = out_path.encode("utf-8")
+        _check(
+            lib.cozip_write_archive(
+                out_path_b, entries, n_total, payload, idx_size[0], err
+            ),
+            err,
+        )
+
+        # 7. Patch the FNV-1a 64 integrity hash into bytes 43..50.
+        _check(
+            lib.cozip_patch_integrity_hash(out_path_b, idx_size[0], err),
+            err,
+        )
+    finally:
+        parquet_path.unlink(missing_ok=True)
+
+    return out_path

cozip-2026.4.29/hatch_build.py

@@ -0,0 +1,16 @@
+"""Tag the wheel as platform-specific but ABI-agnostic.
+
+cffi ABI mode loads the native library via libffi at runtime, so the
+wheel works on any Python 3.x — but the bundled .dylib is for one
+specific OS+arch.
+"""
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict) -> None:
+        # Force a platform-tagged wheel (e.g. py3-none-macosx_11_0_arm64)
+        # instead of the default py3-none-any.
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = True

cozip-2026.4.29/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cozip"
+version = "2026.4.29"
+description = "Cloud-Optimized ZIP — Python bindings"
+requires-python = ">=3.10"
+dependencies = ["cffi>=1.16", "pyarrow>=14"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cozip"]
+# Include the prebuilt native lib in the wheel.
+artifacts = ["cozip/_lib/*.dylib", "cozip/_lib/*.so", "cozip/_lib/*.dll"]
+
+# Mark the wheel as platform-specific (because of the bundled .dylib),
+# but ABI-agnostic (cffi ABI mode works on any Python 3.x).
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cozip-2026.4.29/tests/__init__.py

@@ -0,0 +1 @@
+# empty — just so pytest recognizes the tests/ package

cozip-2026.4.29/tests/test_smoke.py

@@ -0,0 +1,343 @@
+"""Smoke + roundtrip tests for the cozip Python binding."""
+
+import io
+import struct
+import zipfile
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import pytest
+
+import cozip
+
+# Optional geo stack — only needed for the geoparquet test.
+try:
+    import geopandas as gpd
+    from shapely.geometry import Point
+    HAS_GEO = True
+except ImportError:
+    HAS_GEO = False
+
+
+# ---------------------------------------------------------------- bindings
+
+def test_library_loads():
+    """The shared library loads and exposes the expected symbols."""
+    assert cozip.lib is not None
+    for sym in (
+        "cozip_plan",
+        "cozip_index_payload_size",
+        "cozip_build_index_payload",
+        "cozip_write_archive",
+        "cozip_patch_integrity_hash",
+    ):
+        assert hasattr(cozip.lib, sym), f"missing symbol: {sym}"
+
+
+def test_error_struct():
+    """cozip_error_t can be instantiated and read back."""
+    err = cozip.ffi.new("cozip_error_t*")
+    err.code = 42
+    cozip.ffi.memmove(err.message, b"oops\x00", 5)
+    assert err.code == 42
+    assert cozip.ffi.string(err.message).decode() == "oops"
+
+
+# ---------------------------------------------------------------- helpers
+
+def _make_payload(seed: int, size: int) -> bytes:
+    """Deterministic byte payload — same seed always yields same bytes."""
+    return bytes([(seed + i) & 0xFF for i in range(size)])
+
+
+# ---------------------------------------------------------------- roundtrip
+
+def test_roundtrip(tmp_path: Path):
+    """End-to-end: create a .cozip archive and validate every layer.
+
+    Validates:
+      1. archive exists and clears the spec minimum size (>= 32819)
+      2. zipfile sees a valid ZIP with __cozip__ first and __metadata__ present
+      3. LFH layout for the __cozip__ entry (filename len, extra len, 0xCA0C)
+      4. integrity hash (bytes 43..50) is non-zero
+      5. CZIP magic at byte 51
+      6. cozip index lists 4 entries (3 users + __metadata__)
+      7. user payloads round-trip byte-for-byte through zipfile
+      8. __metadata__.parquet has the expected schema and offsets
+    """
+    sizes = [12000, 13000, 14000]
+    src_files: list[Path] = []
+    src_payloads: list[bytes] = []
+    for i, sz in enumerate(sizes):
+        p = tmp_path / f"src_{i}.bin"
+        payload = _make_payload(0xA0 + i, sz)
+        p.write_bytes(payload)
+        src_files.append(p)
+        src_payloads.append(payload)
+
+    arc_names = [f"data/file_{i}.bin" for i in range(3)]
+    table = pa.table({
+        "name": arc_names,
+        "path": [str(p) for p in src_files],
+    })
+
+    out = tmp_path / "out.cozip"
+    returned = cozip.create(out, table)
+
+    # 1. exists + size >= minimum
+    assert Path(returned).exists()
+    assert out.exists()
+    archive_size = out.stat().st_size
+    assert archive_size >= 32819, f"archive too small: {archive_size}"
+
+    # 2. valid ZIP, first entry __cozip__, __metadata__ present
+    with zipfile.ZipFile(out, "r") as z:
+        names = z.namelist()
+        infos = z.infolist()
+    assert names[0] == "__cozip__", f"first entry is {names[0]!r}"
+    assert "__metadata__" in names, "__metadata__ entry missing"
+    for arc in arc_names:
+        assert arc in names, f"missing entry: {arc}"
+
+    cozip_info = next(i for i in infos if i.filename == "__cozip__")
+    assert cozip_info.compress_type == zipfile.ZIP_STORED
+
+    # 3. inspect raw bytes for the __cozip__ LFH
+    raw = out.read_bytes()
+    assert raw[:4] == b"PK\x03\x04", "missing local file header signature"
+
+    fname_len = struct.unpack_from("<H", raw, 26)[0]
+    extra_len = struct.unpack_from("<H", raw, 28)[0]
+    assert fname_len == 9, f"__cozip__ name length: {fname_len}"
+    assert extra_len == 12, f"0xCA0C extra length: {extra_len}"
+    assert raw[30:39] == b"__cozip__"
+
+    extra_id = struct.unpack_from("<H", raw, 39)[0]
+    assert extra_id == 0xCA0C, f"unexpected extra id: 0x{extra_id:04X}"
+    assert struct.unpack_from("<H", raw, 41)[0] == 8
+
+    # 4. hash patched (non-zero)
+    assert raw[43:51] != b"\x00" * 8, "integrity hash was not patched"
+
+    # 5. CZIP magic at byte 51
+    assert raw[51:55] == b"CZIP", f"bad magic: {raw[51:55]!r}"
+
+    # 6. index header: version, profile, n_entries
+    version = struct.unpack_from("<H", raw, 55)[0]
+    profile = raw[57]
+    n_index = struct.unpack_from("<I", raw, 58)[0]
+    assert version == 1
+    assert profile == 1, f"profile must be FLAT (1), got {profile}"
+    assert n_index == 4, f"index count: expected 4 (3 users + meta), got {n_index}"
+
+    # 7. user payloads round-trip via zipfile
+    with zipfile.ZipFile(out, "r") as z:
+        for arc, expected in zip(arc_names, src_payloads):
+            assert z.read(arc) == expected, f"payload mismatch for {arc}"
+
+    # 8. __metadata__.parquet schema and content
+    with zipfile.ZipFile(out, "r") as z:
+        meta_bytes = z.read("__metadata__")
+    meta = pq.read_table(io.BytesIO(meta_bytes))
+
+    assert meta.column_names[:3] == ["name", "offset", "size"]
+    assert "path" not in meta.column_names, "path must not appear in __metadata__"
+    assert "in_index" not in meta.column_names, "in_index must not appear in __metadata__"
+    assert len(meta) == 3, f"expected 3 rows in __metadata__, got {len(meta)}"
+
+    # offsets + sizes in the parquet must point to the actual user payloads
+    meta_names = meta.column("name").to_pylist()
+    meta_offsets = meta.column("offset").to_pylist()
+    meta_sizes = meta.column("size").to_pylist()
+    for arc, expected in zip(arc_names, src_payloads):
+        idx = meta_names.index(arc)
+        off = int(meta_offsets[idx])
+        sz = int(meta_sizes[idx])
+        assert raw[off:off + sz] == expected, f"offset/size wrong for {arc}"
+
+
+def test_roundtrip_in_index_false(tmp_path: Path):
+    """Entries with in_index=False are written but not listed in the index.
+
+    The cozip index still gets __metadata__ entry, so n_index = 1 + 1 = 2
+    when only one user is in_index=True.
+    """
+    src = tmp_path / "small.bin"
+    big = tmp_path / "big.bin"
+    src.write_bytes(_make_payload(0x10, 100))
+    big.write_bytes(_make_payload(0x20, 33000))  # alone clears the 32 KiB minimum
+
+    table = pa.table({
+        "name":     ["a.bin", "b.bin"],
+        "path":     [str(src), str(big)],
+        "in_index": [True, False],
+    })
+
+    out = tmp_path / "out.cozip"
+    cozip.create(out, table)
+
+    raw = out.read_bytes()
+    n_index = struct.unpack_from("<I", raw, 58)[0]
+    assert n_index == 2, f"expected a.bin + __metadata__ in index, got {n_index}"
+
+    with zipfile.ZipFile(out, "r") as z:
+        names = z.namelist()
+    assert "a.bin" in names
+    assert "b.bin" in names
+    assert "__metadata__" in names
+
+    # The metadata parquet must NOT list b.bin (in_index=False).
+    with zipfile.ZipFile(out, "r") as z:
+        meta_bytes = z.read("__metadata__")
+    meta = pq.read_table(io.BytesIO(meta_bytes))
+    meta_names = meta.column("name").to_pylist()
+    assert meta_names == ["a.bin"], f"expected only a.bin in metadata, got {meta_names}"
+
+
+# ---------------------------------------------------------------- geoparquet
+
+@pytest.mark.skipif(not HAS_GEO, reason="geopandas/shapely not installed")
+def test_geoparquet_metadata_roundtrip(tmp_path: Path):
+    """A GeoDataFrame as input survives as a GeoParquet inside __metadata__.
+
+    Validates:
+      1. user-supplied geometry + CRS reach the metadata parquet
+      2. extra user columns flow through unchanged
+      3. offsets in the metadata parquet point at the correct user payloads
+      4. GeoPandas can read __metadata__ directly from the zip
+    """
+    n = 3
+    src_files: list[Path] = []
+    src_payloads: list[bytes] = []
+    for i in range(n):
+        p = tmp_path / f"src_{i}.bin"
+        payload = _make_payload(0xA0 + i, 12000 + i * 1000)
+        p.write_bytes(payload)
+        src_files.append(p)
+        src_payloads.append(payload)
+
+    arc_names = [f"data/file_{i}.bin" for i in range(n)]
+    countries = ["Peru", "Chile", "Brazil"]
+    elevations = [3000, 4500, 1200]
+    points = [
+        Point(-77.0, -12.0),  # Lima
+        Point(-70.7, -33.4),  # Santiago
+        Point(-47.9, -15.7),  # Brasilia
+    ]
+
+    gdf = gpd.GeoDataFrame(
+        {
+            "name": arc_names,
+            "path": [str(p) for p in src_files],
+            "country": countries,
+            "elevation": elevations,
+            "geometry": points,
+        },
+        crs="EPSG:4326",
+    )
+
+    # GDF -> parquet -> pa.Table preserves the b"geo" schema metadata that
+    # GeoParquet readers (incl. GeoPandas) look for.
+    in_parquet = tmp_path / "input.parquet"
+    gdf.to_parquet(in_parquet)
+    table = pq.read_table(in_parquet)
+
+    assert table.schema.metadata is not None
+    assert b"geo" in table.schema.metadata, \
+        "input table should carry the b'geo' schema metadata"
+
+    # Build the cozip.
+    out = tmp_path / "out.cozip"
+    cozip.create(out, table)
+    assert out.exists()
+
+    raw = out.read_bytes()
+
+    # Read __metadata__ straight out of the zip and parse with GeoPandas.
+    with zipfile.ZipFile(out, "r") as z:
+        assert "__metadata__" in z.namelist()
+        meta_bytes = z.read("__metadata__")
+
+    meta_gdf = gpd.read_parquet(io.BytesIO(meta_bytes))
+
+    # 1. CRS preserved
+    assert meta_gdf.crs is not None, "CRS lost in roundtrip"
+    assert meta_gdf.crs.to_epsg() == 4326
+
+    # Geometry round-trip
+    assert "geometry" in meta_gdf.columns
+    assert set(meta_gdf.geometry.geom_type) == {"Point"}
+    assert len(meta_gdf) == n
+
+    # 2. Extra columns preserved, writer-private columns dropped
+    assert "country" in meta_gdf.columns
+    assert "elevation" in meta_gdf.columns
+    assert "path" not in meta_gdf.columns
+    assert "in_index" not in meta_gdf.columns
+
+    # Writer-added columns
+    assert "name" in meta_gdf.columns
+    assert "offset" in meta_gdf.columns
+    assert "size" in meta_gdf.columns
+
+    # User column values come back intact
+    by_name = meta_gdf.set_index("name")
+    for arc, country, elev, pt in zip(arc_names, countries, elevations, points):
+        row = by_name.loc[arc]
+        assert row["country"] == country
+        assert int(row["elevation"]) == elev
+        assert row["geometry"].equals(pt), f"geometry mismatch for {arc}"
+
+    # 3. offsets/sizes resolve to the original user payloads
+    for arc, expected in zip(arc_names, src_payloads):
+        row = by_name.loc[arc]
+        off = int(row["offset"])
+        sz = int(row["size"])
+        assert raw[off:off + sz] == expected, f"offset/size wrong for {arc}"
+
+
+# ---------------------------------------------------------------- negatives
+
+def test_create_rejects_empty(tmp_path: Path):
+    """create() refuses to build a 0-entry archive."""
+    out = tmp_path / "empty.cozip"
+    with pytest.raises(ValueError, match="empty"):
+        cozip.create(out, pa.table({"name": [], "path": []}))
+
+
+def test_create_rejects_missing_source(tmp_path: Path):
+    """Missing source file is caught before any C call."""
+    out = tmp_path / "out.cozip"
+    table = pa.table({
+        "name": ["does/not/exist.bin"],
+        "path": [str(tmp_path / "nope.bin")],
+    })
+    with pytest.raises(FileNotFoundError):
+        cozip.create(out, table)
+
+
+def test_create_rejects_reserved_name(tmp_path: Path):
+    """User cannot use names the writer reserves for itself."""
+    src = tmp_path / "src.bin"
+    src.write_bytes(_make_payload(0x33, 33000))
+    table = pa.table({
+        "name": ["__metadata__"],
+        "path": [str(src)],
+    })
+    with pytest.raises(ValueError, match="reserved"):
+        cozip.create(tmp_path / "out.cozip", table)
+
+
+def test_create_rejects_duplicate_names(tmp_path: Path):
+    """Duplicate names within one archive are rejected upfront."""
+    src1 = tmp_path / "a.bin"
+    src2 = tmp_path / "b.bin"
+    src1.write_bytes(_make_payload(0x10, 100))
+    src2.write_bytes(_make_payload(0x20, 33000))
+    table = pa.table({
+        "name": ["dupe.bin", "dupe.bin"],
+        "path": [str(src1), str(src2)],
+    })
+    with pytest.raises(ValueError, match="duplicate"):
+        cozip.create(tmp_path / "out.cozip", table)