Add OCI image unpack and run

Turn a pulled image into something `elfuse` can actually execute:

- vendor decode-only zstd v1.5.6 (compression / dictBuilder /
  legacy paths excluded; only oci/decompress.c includes the header)
- tar reader: ustar + GNU long-name records, used by layer apply
- decompression dispatch: gzip via system zlib, zstd via vendored
  decode-only build, dispatched by layer media type
- layer applier with whiteout-aware merge: typeflag '1' (hardlink),
  '2' (symlink), '5' (directory), `.wh.*` markers, symlink-escape
  containment
- per-image sysroot on a case-sensitive APFS sparsebundle
  (hdiutil-provisioned, image_layout v1)
- per-run rootfs via clonefile(2) on top of the sysroot
- `oci unpack` and `oci clone` subcommands that exercise the above
- `oci inspect` extended with the image-config runtime block
  (Entrypoint / Cmd / Env / WorkingDir / User)
- runspec resolver merging image-config defaults with CLI
  Entrypoint / Cmd / Env / WorkingDir / User overrides
- PATH resolver that walks the guest /usr/local/sbin..:/sbin chain
  inside the sysroot (no host PATH leakage)
- `elfuse_launch` extraction from main.c so the elfuse runtime can
  be reused by both legacy ./binary mode and the new `oci run`
- `oci run` subcommand that ties pull -> unpack -> clone -> launch
- `oci-layout` 1.0.0 marker at the store root
- migrate store pins from `refs/<name>` flat files to a single
  `index.json` (OCI image-layout 1.0); auto-migrate on store open

Author: Max042004

.gitignore

@@ -2,10 +2,11 @@ build/
 archive/
 # externals/ holds downloaded fixtures (kernel, rootfs, packages) that are
 # fetched on demand; tracking them in git would balloon the repo. The
-# vendored cJSON tree is an exception: it ships with the source so the
-# OCI parser builds out of the box.
+# vendored cJSON and zstd trees are exceptions: they ship with the source
+# so the OCI parser and layer unpacker build out of the box.
 externals/*
 !externals/cjson/
+!externals/zstd/
 lib/modules/
 *.o
 *.bin

Makefile

@@ -24,6 +24,7 @@ SRCS := \
     core/stack.c \
     core/vdso.c \
     core/bootstrap.c \
+    core/launch.c \
     core/sysroot.c \
     runtime/thread.c \
     runtime/futex.c \
@@ -74,7 +75,17 @@ SRCS := \
     oci/fetch.c \
     oci/store.c \
     oci/pull.c \
-    oci/inspect.c
+    oci/inspect.c \
+    oci/tar.c \
+    oci/decompress.c \
+    oci/layer-meta.c \
+    oci/layer-apply.c \
+    oci/volume.c \
+    oci/clone-rootfs.c \
+    oci/unpack.c \
+    oci/runspec.c \
+    oci/path-resolve.c \
+    oci/run.c
 
 SRCS := $(addprefix src/,$(SRCS))
 OBJS := $(patsubst src/%.c,$(BUILD_DIR)/%.o,$(SRCS))
@@ -91,10 +102,34 @@ $(CJSON_OBJ): $(CJSON_DIR)/cJSON.c $(CJSON_DIR)/cJSON.h | $(BUILD_DIR)
 	@echo "  CC      $<"
 	$(Q)$(CC) $(CFLAGS) -c -o $@ $<
 
+# Vendored zstd v1.5.6 (decode-only). Phase 2 OCI layer unpack consumes
+# zstd-compressed layer media types. Compression, dictBuilder, deprecated,
+# and legacy v01-v06 paths are NOT vendored; do not call ZSTD_compress*.
+# Only src/oci/decompress.c includes externals/zstd/lib/zstd.h.
+ZSTD_DIR := externals/zstd
+ZSTD_SRCS := $(wildcard $(ZSTD_DIR)/lib/common/*.c) \
+             $(wildcard $(ZSTD_DIR)/lib/decompress/*.c)
+ZSTD_OBJS := $(patsubst $(ZSTD_DIR)/%.c,$(BUILD_DIR)/externals/zstd/%.o,$(ZSTD_SRCS))
+OBJS += $(ZSTD_OBJS)
+
+ZSTD_CFLAGS := -DZSTD_DISABLE_ASM=1 -DZSTD_LEGACY_SUPPORT=0 \
+               -DZSTD_MULTITHREAD=0 -DZSTDLIB_VISIBILITY= \
+               -Wno-pedantic -Wno-shadow -Wno-strict-prototypes \
+               -Wno-missing-prototypes -Wno-unused-parameter \
+               -Wno-cast-align -Wno-implicit-fallthrough \
+               -I$(ZSTD_DIR)/lib -I$(ZSTD_DIR)/lib/common
+
+$(BUILD_DIR)/externals/zstd/%.o: $(ZSTD_DIR)/%.c | $(BUILD_DIR)
+	@mkdir -p $(dir $@)
+	@echo "  CC      $<"
+	$(Q)$(CC) $(CFLAGS) $(ZSTD_CFLAGS) -c -o $@ $<
+
 DISPATCH_MANIFEST := src/syscall/dispatch.tbl
 DISPATCH_GENERATOR := scripts/gen-syscall-dispatch.py
 DISPATCH_HEADER := $(BUILD_DIR)/dispatch.h
-HVF_LDFLAGS := -framework Hypervisor -arch arm64 -lcurl
+# -lz: gzip-compressed OCI layers route through zlib (system library).
+# -lcurl: HTTPS fetch for the Phase 1 oci pull path.
+HVF_LDFLAGS := -framework Hypervisor -arch arm64 -lcurl -lz
 
 # Generated headers under build/ that must exist before compiling sources that
 # include them.
@@ -198,8 +233,9 @@ $(BUILD_DIR)/test-oci-fetch: $(BUILD_DIR)/test-oci-fetch.o $(BUILD_DIR)/lib/oci-
 	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lcurl -lpthread $(OPENSSL_LDFLAGS)
 
 ## Build the OCI local store unit test (native macOS, no HVF). Pure C; links
-## against the store wrapper plus its blob-store and digest dependencies.
-$(BUILD_DIR)/test-oci-store: $(BUILD_DIR)/test-oci-store.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/ref.o | $(BUILD_DIR)
+## against the store wrapper plus its blob-store, digest, and cJSON deps.
+## cJSON is required because store.c now reads / writes index.json.
+$(BUILD_DIR)/test-oci-store: $(BUILD_DIR)/test-oci-store.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/ref.o $(CJSON_OBJ) | $(BUILD_DIR)
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^
 
@@ -217,6 +253,98 @@ $(BUILD_DIR)/test-oci-inspect: $(BUILD_DIR)/test-oci-inspect.o $(BUILD_DIR)/oci/
 	@echo "  LD      $@"
 	$(Q)$(CC) $(CFLAGS) -o $@ $^
 
+## Build the OCI tar reader unit test (native macOS, no HVF). Pure C; the
+## test constructs ustar / GNU long-name streams in memory and drives them
+## through the reader via a callback that exercises short-read chunking.
+$(BUILD_DIR)/test-oci-tar: $(BUILD_DIR)/test-oci-tar.o $(BUILD_DIR)/oci/tar.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI runspec unit test (native macOS, no HVF). Pure-data
+## merge of image-config runtime block + CLI overrides; the test feeds
+## oci_image_runtime_t literals directly through oci_runspec_build with
+## no filesystem or libcurl dependency.
+$(BUILD_DIR)/test-oci-runspec: $(BUILD_DIR)/test-oci-runspec.o $(BUILD_DIR)/oci/runspec.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI path-resolve unit test (native macOS, no HVF). Touches
+## the host filesystem to build a small fake sysroot tree and drives
+## oci_path_resolve through realpath / stat / symlink-follow scenarios.
+## Pure C; no libcurl, no zstd, no HVF.
+$(BUILD_DIR)/test-oci-path-resolve: $(BUILD_DIR)/test-oci-path-resolve.o $(BUILD_DIR)/oci/path-resolve.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI run orchestrator unit test (native macOS, no HVF). Links
+## the same OCI graph the unpack test pulls in, plus oci/run.o,
+## oci/runspec.o, and oci/path-resolve.o. Does NOT link core/launch.o:
+## the test ships an in-file elfuse_launch stub that aborts when called,
+## and every case installs a launch hook via oci_run_set_launch_for_testing
+## before invoking oci_run, so the real VM bring-up never runs from a test.
+$(BUILD_DIR)/test-oci-run: $(BUILD_DIR)/test-oci-run.o $(BUILD_DIR)/oci/run.o $(BUILD_DIR)/oci/runspec.o $(BUILD_DIR)/oci/path-resolve.o $(BUILD_DIR)/oci/unpack.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/oci/clone-rootfs.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/decompress.o $(BUILD_DIR)/oci/tar.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o $(CJSON_OBJ) $(ZSTD_OBJS) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lz
+
+## Build the OCI fixture builder (Phase 3 compat tests). Standalone tool
+## that synthesises a complete OCI store from uncompressed-tar layers
+## plus image-config flags. Used by tests/test-oci-compat.sh and
+## available standalone for one-off "shape an image from local files"
+## experiments.
+$(BUILD_DIR)/oci-fixture-builder: $(BUILD_DIR)/lib/oci-fixture-builder.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/ref.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## decompress.c is the only translation unit in elfuse that includes
+## externals/zstd/lib/zstd.h. Attach the zstd include path as a target-
+## specific CFLAG so the rest of the codebase never sees zstd headers.
+$(BUILD_DIR)/oci/decompress.o: CFLAGS += -I$(ZSTD_DIR)/lib
+
+## Build the OCI sidecar metadata unit test (native macOS, no HVF). Pure
+## C; links against cJSON for the JSON round-trip plus the layer-meta
+## translation unit.
+$(BUILD_DIR)/test-oci-meta: $(BUILD_DIR)/test-oci-meta.o $(BUILD_DIR)/oci/layer-meta.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI layer applier unit test (native macOS, no HVF). Builds
+## tar payloads in memory, drives them through oci_layer_apply into a
+## tmp tree, and verifies filesystem state via lstat/readlink.
+$(BUILD_DIR)/test-oci-layer-apply: $(BUILD_DIR)/test-oci-layer-apply.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/tar.o $(CJSON_OBJ) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI volume bootstrap unit test (native macOS, no HVF).
+## Default-volume test is gated behind OCI_VOLUME_TEST=1 because it
+## costs ~150 ms of hdiutil orchestration on first run. Links
+## src/core/sysroot.o for the hdiutil wrappers PR #33 introduced.
+$(BUILD_DIR)/test-oci-volume: $(BUILD_DIR)/test-oci-volume.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI clone-rootfs unit test (native macOS, no HVF). The
+## test skips itself if clonefile returns ENOTSUP (non-APFS scratch).
+$(BUILD_DIR)/test-oci-clone: $(BUILD_DIR)/test-oci-clone.o $(BUILD_DIR)/oci/clone-rootfs.o | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^
+
+## Build the OCI unpack orchestrator integration smoke (native macOS,
+## no HVF). Pulls in the full Phase 2 OCI stack so the dependency
+## edges between modules are exercised at link time.
+$(BUILD_DIR)/test-oci-unpack: $(BUILD_DIR)/test-oci-unpack.o $(BUILD_DIR)/oci/unpack.o $(BUILD_DIR)/oci/volume.o $(BUILD_DIR)/oci/clone-rootfs.o $(BUILD_DIR)/oci/layer-apply.o $(BUILD_DIR)/oci/layer-meta.o $(BUILD_DIR)/oci/decompress.o $(BUILD_DIR)/oci/tar.o $(BUILD_DIR)/oci/store.o $(BUILD_DIR)/oci/blob-store.o $(BUILD_DIR)/oci/digest.o $(BUILD_DIR)/oci/manifest.o $(BUILD_DIR)/oci/media-type.o $(BUILD_DIR)/oci/ref.o $(BUILD_DIR)/core/sysroot.o $(BUILD_DIR)/debug/log.o $(CJSON_OBJ) $(ZSTD_OBJS) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lz
+
+## Build the OCI decompression dispatch unit test (native macOS, no HVF).
+## Links zstd objects + system zlib so gzip and zstd payloads both round-
+## trip through oci_stream_t. The gzip fixture is generated at test time
+## via zlib; the zstd fixture is an embedded byte array because the
+## vendored libzstd is decode-only.
+$(BUILD_DIR)/test-oci-decompress.o: CFLAGS += -I$(ZSTD_DIR)/lib
+$(BUILD_DIR)/test-oci-decompress: $(BUILD_DIR)/test-oci-decompress.o $(BUILD_DIR)/oci/decompress.o $(ZSTD_OBJS) | $(BUILD_DIR)
+	@echo "  LD      $@"
+	$(Q)$(CC) $(CFLAGS) -o $@ $^ -lz
+
 # Guest test binaries (cross-compiled, aarch64-linux)
 # Only used when GUEST_TEST_BINARIES is not set.
 

docs/usage.md

@@ -99,6 +99,93 @@ and memory access, and per-thread inspection. Implementation details, including
 the snapshot protocol used to keep Hypervisor.framework register access on the
 owning thread, are documented in [internals.md](internals.md).
 
+## Running OCI Images (`elfuse oci run`)
+
+Phase 3 adds a direct-execution path for pulled OCI images:
+
+```sh
+elfuse oci run [OPTIONS] IMAGE [ARG...]
+```
+
+The subcommand reads the image's runtime block (Entrypoint, Cmd, Env,
+WorkingDir, User) and folds in any CLI overrides, then unpacks the image
+into the local APFS sysroot volume, clones a per-run rootfs via APFS
+`clonefile(2)`, resolves argv[0] against PATH inside the rootfs, and
+hands off to the same VM bring-up the legacy positional-ELF `elfuse`
+entry uses.
+
+The image must already be pulled. `oci run` does not auto-pull on miss.
+The usual workflow is:
+
+```sh
+elfuse oci pull alpine:3
+elfuse oci run  alpine:3 /bin/sh -c 'echo hello from inside'
+```
+
+### Options
+
+| Option | Meaning |
+|--------|---------|
+| `--store DIR` | Override the local store root |
+| `--volume DIR` | Override the APFS sysroot volume mount point |
+| `--entrypoint PROG` | Replace the image Entrypoint with `PROG` |
+| `-e KEY=VAL`, `--env KEY=VAL` | Set or replace one env var (repeatable) |
+| `-e KEY`, `--env KEY` | Import `KEY` from the host environ (repeatable) |
+| `-w DIR`, `--workdir DIR` | Override image WorkingDir |
+| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (numeric only) |
+| `--keep` | Keep the per-run cloned rootfs after exit |
+| `--name NAME` | Reserved: deterministic clone-dir suffix (ignored today) |
+
+### Argv override matrix
+
+| Image Entrypoint | Image Cmd | CLI ARGV | `--entrypoint` | Result argv |
+|--|--|--|--|--|
+| set | set | none | none | Entrypoint ++ Cmd |
+| set | set | provided | none | Entrypoint ++ CLI ARGV (Cmd dropped) |
+| set | none | provided | none | Entrypoint ++ CLI ARGV |
+| none | set | none | none | Cmd |
+| none | set | provided | none | CLI ARGV (Cmd dropped) |
+| set | set | optional | provided | [`--entrypoint`] ++ CLI ARGV |
+| none | none | provided | none | CLI ARGV |
+| none | none | none | none | `EINVAL` "image has no entrypoint or cmd; pass one on the CLI" |
+
+### Env merge policy
+
+The merged guest env is built in this order:
+
+1. Image `Env` (verbatim, in spec order)
+2. Each CLI `-e KEY=VAL` set-or-replaces by key
+3. Each CLI `-e KEY` (no `=`) imports the host's value when present, otherwise drops silently
+4. `TERM` auto-imported from the host iff the merged env has no `TERM`
+5. `PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` injected iff the merged env has no `PATH`
+6. `container=elfuse` injected unconditionally so systemd-style sandbox detection works
+
+CLI `-e DYLD_*=...` overrides are hard-rejected with `EINVAL`: `DYLD_*` is a
+macOS-only loader contract with no meaning inside an aarch64-linux guest.
+Image-provided `DYLD_*` entries pass through (the guest ignores them).
+
+### User and WorkingDir
+
+`User` accepts numeric `UID` or `UID:GID` only. Symbolic users (`User
+nginx`) are rejected with a deterministic Phase 4 pointer message;
+static `/etc/passwd` parsing waits for Phase 4 along with the rest of
+the NSS resolution work. `--user UID` alone defaults GID to the same
+value.
+
+`WorkingDir` must be absolute and free of `..` segments. If neither the
+image nor the CLI sets it, the guest starts in `/`. The directory is
+materialized under the cloned rootfs (`mkdir -p`, mode 0755, best-
+effort chown to the resolved uid:gid when `--user` or image User
+selects credentials).
+
+### Scope guardrails
+
+- Symbolic `User` -> Phase 4 (NSS / static `/etc/passwd` resolution)
+- `/etc/resolv.conf`, `/etc/hosts`, `/dev/*`, `/proc/*` synthesis -> Phase 4
+- Auto-pull on `run` miss -> never; `elfuse oci pull` must run first
+- Network policy, `docker run -p`-style port mapping -> later phases
+- Live `docker exec`-style attach -> never
+
 ## Guest Compatibility Model
 
 `elfuse` is designed for Linux user-space workloads, not for booting a Linux

externals/zstd/LICENSE

@@ -0,0 +1,30 @@
+BSD License
+
+For Zstandard software
+
+Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook, nor Meta, nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

externals/zstd/VENDORING.md

@@ -0,0 +1,72 @@
+# Vendored zstd (decode-only)
+
+This directory contains a decode-only subset of [zstd](https://github.com/facebook/zstd),
+the streaming compression library from Facebook. Phase 2 needs zstd to
+decompress OCI image layers that ship with `application/vnd.oci.image.layer.v1.tar+zstd`
+or `application/vnd.docker.image.rootfs.diff.tar.zstd` media types.
+
+Licensed under BSD-3-Clause (see `LICENSE`).
+
+## Why vendored, decode-only
+
+`oci-roadmap.md` Q9 commits the OCI work to hand-rolled C: no Go, no Rust,
+no `cargo` / `go` in the build matrix. zstd is the only OCI-spec layer
+compression beyond gzip that has wide registry support, and the upstream
+library cleanly separates decoder-only from the full encoder. Phase 2 only
+reads layers, so the encoder, dictionary builder, and legacy v01-v06
+support are all excluded.
+
+Resulting footprint:
+
+- `lib/{zstd,zstd_errors}.h`
+- `lib/common/*.{c,h}` (allocator, error tables, FSE/Huff decoders,
+  threading stubs, xxhash, portability shims)
+- `lib/decompress/*.{c,h}` (the streaming decode state machine)
+
+Compression, dictBuilder, deprecated, and legacy paths are NOT vendored.
+Do not call `ZSTD_compress*`, `ZDICT_*`, or any `ZSTD_v0X_*` symbol.
+
+## Version
+
+Pinned to upstream tag `v1.5.6` (2024-03-30). Fetched with:
+
+```
+curl -fsSL -o zstd-v1.5.6.tar.gz \
+    https://github.com/facebook/zstd/archive/refs/tags/v1.5.6.tar.gz
+tar -xzf zstd-v1.5.6.tar.gz
+SRC=zstd-1.5.6
+cp $SRC/LICENSE externals/zstd/LICENSE
+cp $SRC/lib/zstd.h $SRC/lib/zstd_errors.h externals/zstd/lib/
+cp $SRC/lib/common/*.[ch] externals/zstd/lib/common/
+cp $SRC/lib/decompress/*.[ch] externals/zstd/lib/decompress/
+```
+
+Note: `lib/decompress/huf_decompress_amd64.S` is intentionally NOT
+copied. The build sets `-DZSTD_DISABLE_ASM=1` so `huf_decompress.c`
+references no AMD64 assembly symbols; the elfuse host is Apple Silicon
+in any case.
+
+## Local modifications
+
+None. The files are byte-identical to the upstream tag so future
+security updates can be applied by re-running the curl + cp commands
+above.
+
+## Build integration
+
+The Makefile compiles each `externals/zstd/lib/**/*.c` translation unit
+with project warning flags relaxed (`-Wno-pedantic -Wno-shadow
+-Wno-strict-prototypes -Wno-missing-prototypes`) and with the
+configuration macros:
+
+```
+-DZSTD_DISABLE_ASM=1
+-DZSTD_LEGACY_SUPPORT=0
+-DZSTD_MULTITHREAD=0
+-DZSTDLIB_VISIBILITY=
+```
+
+Only `src/oci/decompress.c` includes `externals/zstd/lib/zstd.h`; the
+rest of the codebase never sees zstd headers. The zstd objects are
+statically embedded into the `elfuse` binary, so no `-lzstd` link line
+is needed.