Dockerfile

# =============================================================================
# core-timeline dev container
# -----------------------------------------------------------------------------
# WHAT THIS PROVIDES
#   A Linux/amd64 toolchain for building and post-mortem-debugging the project:
#     - gcc + clang (C compilers; clang for sanitizers/UBSan if wanted)
#     - gdb               (confirm same crashing PC across the two paths; Gate A)
#     - binutils + elfutils (readelf / eu-readelf / eu-unstrip; build-id, PT_LOAD)
#     - python3           (the core_timeline_read reader prototype)
#     - procps / strace   (inspect /proc, coredump_filter; trace the fixture)
#   The whole project is ELF-core-dump-specific: it needs /proc, MADV_DODUMP,
#   coredump_filter, and a kernel that writes cores. The HOST is darwin/arm64,
#   which has none of these — so ALL build/crash/read steps run in this container.
#
#   ARCHITECTURE — run NATIVE, never emulated. (M0 preflight finding, 2026-06-22.)
#   An earlier revision pinned --platform=linux/amd64 "for consistency". On Apple
#   Silicon that runs the image under Rosetta, and the kernel then dumps a core of
#   the *Rosetta translator process* (aarch64, ~290 MB, execfn /run/rosetta/rosetta)
#   instead of our x86_64 guest — gdb shows only `???` frames and our PT_LOAD /
#   build-id correlation has nothing real to resolve against. Emulation breaks the
#   exact address-space correlation this project lives on. So we DROP the platform
#   constant: the base image below is a multi-arch OCI index, and Docker selects the
#   host's native arch (arm64 on this Mac, amd64 on x86 CI). The spec is
#   architecture-neutral — it needs ELF cores + /proc + MADV_DODUMP + coredump_filter,
#   all of which native arm64 Linux provides. Native arm64 produces a clean core
#   (`from './crash_demo'`, gdb resolves `#0 ... in die ()`), which is what M0 needs.
#
# RUNTIME REQUIREMENTS (cores are written by the *host* kernel for the container)
#   Core dumps come from the kernel, governed by /proc/sys/kernel/core_pattern,
#   ulimit -c, and coredump_filter. To get cores + gdb to work, run with:
#
#     docker build -t core-timeline .
#     docker run --rm -it \
#       --cap-add=SYS_PTRACE \              # gdb / ptrace on the crashed binary
#       --security-opt seccomp=unconfined \ # allow the syscalls the fixture uses
#       --ulimit core=-1 \                  # equivalent of `ulimit -c unlimited`
#       -v "$PWD":/work -w /work \
#       core-timeline bash
#
#   Inside the container, BEFORE trusting any run (this is the M0 preflight):
#       ulimit -c unlimited
#       cat /proc/sys/kernel/core_pattern    # know where cores land
#       cat /proc/self/coredump_filter       # confirm file-backed mappings included
#   NOTE: core_pattern is a HOST-KERNEL setting and is NOT controlled from inside
#   the container. If the host pipes cores to systemd-coredump (a leading "|"),
#   set a plain path on the host or recover via `coredumpctl dump` (see spec.md:282).
#   If your environment cannot produce cores at all, run the demo in a Linux VM.
#   Full privileged mode (--privileged) also works but is broader than needed; the
#   three flags above are sufficient.
#
# This Dockerfile is intentionally NOT built here — it is scaffolding for the
# future agent. Do not run `docker build` as part of authoring the docs.
# =============================================================================

# Pinned for reproducibility: Ubuntu 24.04 LTS (Noble), multi-arch OCI index.
# This digest is the manifest LIST (index), so no --platform is needed: Docker
# resolves it to the host's native architecture. Do NOT re-add --platform=amd64
# (see the ARCHITECTURE note above — it forces Rosetta and breaks the core claim).
FROM ubuntu:24.04@sha256:786a8b558f7be160c6c8c4a54f9a57274f3b4fb1491cf65146521ae77ff1dc54

ENV DEBIAN_FRONTEND=noninteractive \
    LANG=C.UTF-8

# Toolchain. Versions track Ubuntu 24.04 (gcc-13, clang-18, gdb-15) — pinned at
# the distro level so a given 24.04 image gives a reproducible compiler set.
RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        gcc \
        clang \
        gdb \
        make \
        binutils \
        elfutils \
        libelf-dev \
        python3 \
        python3-pip \
        ca-certificates \
        file \
        strace \
        procps \
        less \
        vim-tiny \
    && rm -rf /var/lib/apt/lists/*

# Sane defaults for the post-mortem workflow. core_pattern itself is a host
# setting and cannot be set from inside the container; we document the dance in
# the header and rely on the M0 preflight to validate the real environment.
WORKDIR /work

# A login shell so `ulimit -c unlimited` and the preflight are easy to run.
CMD ["bash", "-l"]