feat: add supervised process recording outputs

Author: chrisbbreuer

.github/workflows/ci.yml

@@ -87,6 +87,9 @@ jobs:
           env LD_LIBRARY_PATH=zig-out/lib DYLD_LIBRARY_PATH=zig-out/lib zig-out/rtp-abi-test
           cc -std=c11 -Wall -Wextra -Werror -Iinclude tests/socket_output.c -Lzig-out/lib -lzigcamera -o zig-out/socket-output-test
           env LD_LIBRARY_PATH=zig-out/lib DYLD_LIBRARY_PATH=zig-out/lib zig-out/socket-output-test
+          cc -std=c11 -Wall -Wextra -Werror -Iinclude tests/process_output.c -Lzig-out/lib -lzigcamera -o zig-out/process-output-test
+          env LD_LIBRARY_PATH=zig-out/lib DYLD_LIBRARY_PATH=zig-out/lib zig-out/process-output-test
+          test -x zig-out/bin/zig-camera-output-host
           bun tests/ts/check-sensor-hdr-cli.ts zig-out/bin/zig-camera
           bun test tests/ts
           bun test tests/ts/processes.test.ts -t 'worker failure and deadline' --rerun-each 10

.github/workflows/home-process-output.yml

@@ -0,0 +1,58 @@
+name: Home process output
+on:
+  push:
+    branches: [main]
+    paths: ['src/home/byte_tail.zig', 'src/home/process_output*.zig', 'src/process_output*.zig', 'ts/process-output.ts', 'ts/transport-sink.ts', 'ts/elementary-output.ts', 'tests/process_output.c', 'tests/ts/process-output.test.ts', 'tests/fixtures/process-output*.ts', '.github/workflows/home-process-output.yml']
+  pull_request:
+    paths: ['src/home/byte_tail.zig', 'src/home/process_output*.zig', 'src/process_output*.zig', 'ts/process-output.ts', 'ts/transport-sink.ts', 'ts/elementary-output.ts', 'tests/process_output.c', 'tests/ts/process-output.test.ts', 'tests/fixtures/process-output*.ts', '.github/workflows/home-process-output.yml']
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  output:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-15]
+        zig: ['0.15.2', master]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29
+        with:
+          version: ${{ matrix.zig }}
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          repository: home-lang/home
+          ref: 6b9c9000460501866cecaa809b5f65bba2254987
+          path: .home-process-upstream
+          sparse-checkout: packages/video
+          persist-credentials: false
+      - name: Exact upstream tail framing and public exports
+        shell: bash
+        run: |
+          set -euo pipefail
+          cmp src/home/byte_tail.zig .home-process-upstream/packages/video/src/core/byte_tail.zig
+          cmp src/home/process_output_wire.zig .home-process-upstream/packages/video/src/core/process_output_wire.zig
+          sed 's#../core/process_output_wire.zig#process_output_wire.zig#' .home-process-upstream/packages/video/src/io/process_output_host.zig > /tmp/process-output-host.zig
+          cmp src/home/process_output_host.zig /tmp/process-output-host.zig
+          for mode in Debug ReleaseSafe; do
+            zig test -lc -O "$mode" src/home/byte_tail.zig
+            zig test -lc -O "$mode" src/home/process_output_wire.zig
+            zig test -lc -O "$mode" --dep video -Mroot=.home-process-upstream/packages/video/tests/process_output.zig -Mvideo=.home-process-upstream/packages/video/src/video.zig
+          done
+      - name: Install pinned Bun for native host acceptance
+        if: matrix.zig == '0.15.2'
+        shell: bash
+        run: |
+          curl -fsSL https://bun.sh/install | bash -s 'bun-v1.4.3'
+          echo "$HOME/.bun/bin" >> "$GITHUB_PATH"
+      - name: Native ABI and standalone POSIX supervisor
+        if: matrix.zig == '0.15.2'
+        shell: bash
+        run: |
+          set -euo pipefail
+          zig test -lc -Iinclude -O Debug src/process_output.zig
+          zig test -lc -Iinclude -O ReleaseSafe src/process_output.zig
+          zig build-exe -lc -O ReleaseSafe src/process_output_host_main.zig -femit-bin=process-output-host
+          bun .home-process-upstream/packages/video/tests/process_output_host.ts "$PWD/process-output-host"

NOTICE

@@ -710,3 +710,9 @@ flattened nal_convert import. All are under the MIT license above.
 src/home/socket_write.zig is copied verbatim from home-lang/home
 packages/video/src/core/socket_write.zig at revision
 b32fcc0e9cb086d29ae37f0d463b9cccfd43fcb9, under the MIT license above.
+
+src/home/byte_tail.zig and process_output_wire.zig are copied verbatim from
+home-lang/home packages/video/src/core at revision
+6b9c9000460501866cecaa809b5f65bba2254987. process_output_host.zig is copied from
+packages/video/src/io with only its process_output_wire import flattened. All
+are under the MIT license above.

README.md

@@ -345,3 +345,8 @@ SDP, cancellation, recovery and circular snapshot integration.
 [Raw socket outputs](docs/socket-output.md) send elementary JPEG/AVC/HEVC over
 bounded TCP/UDP with joined cancellation and partial-write/deadline handling.
 `SocketSink` also carries Home Matroska A/V through `MuxedOutput` without seeking.
+
+[Supervised process outputs](docs/process-output.md) pipe Home media to explicit
+Bun/Zig consumer argv with bounded diagnostics, producer backpressure, joined
+process-group cancellation and parent-exit handling. `ProcessOutput` sends raw
+video; `MuxedOutput(new ProcessSink(...), 'mkv')` carries timestamped Home A/V.

build.zig

@@ -77,6 +77,13 @@ pub fn build(b: *std.Build) void {
         .imports = &.{.{ .name = "camera", .module = mod }},
     }) });
     b.installArtifact(exe);
+    const output_host = b.addExecutable(.{ .name = "zig-camera-output-host", .root_module = b.createModule(.{
+        .root_source_file = b.path("src/process_output_host_main.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    }) });
+    b.installArtifact(output_host);
     const run = b.addRunArtifact(exe);
     if (b.args) |args| run.addArgs(args);
     b.step("run", "Run the capture CLI").dependOn(&run.step);

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .zig_camera,
-    .version = "0.103.0",
+    .version = "0.104.0",
     .fingerprint = 0x774c3582060c5787,
     .minimum_zig_version = "0.15.2",
     .dependencies = .{},

docs/home-os-reuse.md

@@ -653,3 +653,14 @@ allocation-free send-progress primitive is therefore implemented in Home video
 stdlib and copied verbatim into camera; hosted queues remain in camera's native
 mailbox and Bun owns OS sockets. No Home OS source is copied, changed or executed;
 no kernel declaration establishes physical networking or Pi capture acceptance.
+
+The 0.104 process-output audit fetches unchanged clean Home OS main at
+151269666bc09aa15a271f1c1f4603f681132e65 and inspects CLAUDE.md, ADR-MC3,
+kernel/src/ipc/pipe.home and kernel/src/core/process.home. Its finite kernel pipe
+and PCB/PGID tables are useful ownership references, not a hosted Bun media stdin
+sink, exec handshake or POSIX child-group wait owner. Home basics process I/O and
+video pipe wrappers were checked too. The bounded tail/wire and standalone host
+are implemented in Home video stdlib, while camera retains native queue ownership
+and Bun transport hooks. No OS source is copied, changed or executed. Kernel
+process declarations do not supply Pi capture, microphone sync or process-output
+performance acceptance evidence.

docs/home-reuse.md

@@ -1879,3 +1879,29 @@ hosted socket ownership. Neither is copied into the Bun host. Home OS remains
 151269666bc09aa15a271f1c1f4603f681132e65 (clean fetched main): kernel UDP queues and
 the AirPlay RTSP control module do not provide this hosted transport. No OS source
 is copied, changed or executed. See socket-output.md for ownership/transport limits.
+
+## Supervised process outputs (0.104)
+
+Home main 6b9c9000460501866cecaa809b5f65bba2254987 adds the allocation-free caller-owned
+ByteTail, strict process_output_wire framing and optional standalone POSIX output
+host. Camera copies tail/wire verbatim and adapts only the host's flattened wire
+import. The portable helpers/public exports pass Debug/ReleaseSafe on pinned Zig
+0.15.2 and current 0.18-dev.470; the native ABI host uses 0.15.2. Both Linux CPU
+host executables cross-compile, with native execution in CI. Exact-copy consumer
+checks pin that revision.
+
+Inspected packages/basics/src/process.zig, video/src/io/pipe.zig and existing
+camera process-pool supervision. Home basics already drains stdout/stderr
+concurrently but targets a different I/O/compiler API and bounded whole captures.
+Video's pipe wrappers do not provide process-group startup/cancel/exit proof.
+The new shared host therefore owns a standalone fork/exec boundary, private
+control fd, exec confirmation, monotonic grace, unreaped-leader group termination
+and Linux adopted-child joins. The new tail provides bounded binary diagnostics
+without allocating on append or confusing raw bytes with text.
+
+Camera reuses its native output mailbox and Home send-progress cursor through a
+shared Bun transport engine for socket/process sinks. No external codec/muxer dependency or
+OS source is introduced. Source argv/env snapshots, stdout/stderr drains, child
+exit and all borrowed bytes remain joined through cancellation. Full parity,
+escaped/hard-killed-supervisor policies and all hardware/performance acceptance
+remain open; see process-output.md.

docs/parity-plan.md

@@ -23,7 +23,7 @@ manual review before completion. Recheck upstream changes during the final audit
 | Preview/UI | SDL/headless preview through the shared native request pump, explicit suspension and joined lifecycle, bounded native RGBA overlays, SDL alpha composition, window/view/aspect controls, independent orthogonal image/overlay transforms and rectangles, main/RGB-BGR-RGBX-BGRX-RGB16-BGR16-I420-YVU-NV-422 lores/background selection with atomic live replacement, isolated display failure and mode restoration | Additional display formats, DRM/KMS and GPU/GUI integrations and their buffer-lifetime rules |
 | Still media | Home JPEG/PNG/BMP/TIFF/PPM/GIF, independent main/lores RGB8/RGB16 image objects with checked clone/crop/gray-RGB-RGBA conversion, exact orthogonal transforms, and bounded sync/async PNG/APNG loading with raw animation/metadata ownership, bounded native-precision resizing with capture-time dimensions and encoding/saves, bounded async APNG byte/file encoding and RGB8/RGB16 main/lores capture bursts with joined cancellation/publication, and calibrated Bayer/mono DNG with checked CSI-2 and PiSP COMP1 row decoding; atomic files and owned encoded bytes from main/RGB-BGR-RGBX-BGRX-RGB16-BGR16-I420-YVU-NV-422 lores across capture/CAF/mode jobs; negotiated color metadata and copied RGB ICC and typed/raw capture Exif in JPEG/PNG/TIFF across capture jobs | Remaining image-object transforms, additional external decoded formats and animation compositing, APNG metadata/temporary-mode animation capture conveniences, additional pixel formats/demosaicing, complete Exif/tag/thumbnail semantics and physical metadata acceptance, advanced DNG/decompression behavior and color conversions |
 | Encoders/recording | Home MJPEG, AVC, HEVC, AAC, MKV/MP4; named software JPEG/AVC quality tiers and a shared HEVC rate heuristic with exact rational planning, limits admission and session propagation; repeated in-band parameter sets on packet keyframes with immutable first-only opt-out across outputs and sessions; counted public IDR requests with synchronous/async producer ordering, cancellation and per-session accounting; copied AVC profile ceilings, validated codec presets and fixed-QP session policies with Baseline/Main container configuration; mixed tiny/4K HEVC with shared CTU32 and visible conformance crops; copied decoder-level ceilings and VBV/CPB policies with nominal resource/actual-header checks and explicit coordinated resets; copied session color profiles with matching matrix/range conversion and ISO/VUI/nclx across native/Bun outputs, snapshots, restart/reconfiguration and coordinated modes; main/RGB-BGR-RGBX-BGRX-RGB16-BGR16-I420-YVU-NV-422 lores encoder sources, compact producer ownership, shared encoding and session transactions, bounded independent encoders with wait/drop policy and shared PCM retention/catch-up and coordinated all-active encoder mode transactions | Complete upstream quality/rate-control behavior, additional pixel formats/raw input, general gamut/transfer conversion, MJPEG/Matroska color metadata options, independent cadence/resampling and physical shared-audio acceptance, hardware encoder paths where available, timestamps and metadata inputs |
-| Output families | File/custom output objects, circular/delayed A/V, PTS, split/rotation/recovery, bounded async I/O; Home AVC/HEVC/AAC RTP framing and bounded Bun UDP sender with signed AAC priming, shared RTCP correlation, actual-header SDP and recorder recovery/circular snapshots; bounded raw TCP/UDP elementary video and Home Matroska TCP A/V with joined prefix/flush/close semantics | Remaining upstream buffering/flush semantics, remaining muxer/network/process-output equivalents through Home/Bun, RTCP feedback/congestion/RTSP/SRTP session behavior, full close/reopen/failure coverage |
+| Output families | File/custom output objects, circular/delayed A/V, PTS, split/rotation/recovery, bounded async I/O; Home AVC/HEVC/AAC RTP framing and bounded Bun UDP sender with signed AAC priming, shared RTCP correlation, actual-header SDP and recorder recovery/circular snapshots; bounded raw TCP/UDP elementary video and Home Matroska TCP A/V with joined prefix/flush/close semantics; supervised raw/Home-container process outputs with bounded diagnostics and parent-fd/group joins | Remaining upstream buffering/flush semantics, remaining muxer/network/process-output equivalents through Home/Bun, RTCP feedback/congestion/RTSP/SRTP session behavior, full close/reopen/failure coverage |
 | Scheduling/extensibility | Bounded Bun jobs, cancellation, completion callbacks, drains, joined native ownership, exact frame dropping/timestamp waits, scoped pre/post callbacks with main-thread mode-worker handoff and explicit retained acquisition | Complete arbitrary dispatch/wait/cancel/flush semantics and remaining callback/allocator integration behavior |
 | Memory/process boundaries | Retained pointer-free descriptor exports with duplicated fds, explicit fd-less staging, full typed metadata and one whole-frame gate; bounded actual SCM_RIGHTS channels, cached shared catalogs, checked receiver-owned maps, explicit ACK primitives, request-owned configuration across source/export/remote/process boundaries, parent-controlled process byte-result publication after matched result/ACK with source retirement before I/O and retained task drains, bounded joined remote asynchronous still encoding/staged saves with owned metadata, remote owned image copies, compact/shaped/physical/raw16 copies, calibrated DNG and processed saves with request-derived Exif/ICC encoding, and opt-in scoped write planes; supervised actual Bun process pools with native moved-export/argument/result admission, matched ACK/result routing, verified-exit cancellation, isolated failures, generations and callback-aware prefix drains; persistent DMA maps, bounded retained requests, scoped read/shared and write/exclusive native mappings; opt-in Bun write contexts with detached views on close | Allocator/persistent-allocation equivalents, remaining remote conveniences, richer value and automatic recovery semantics, remaining IPC/allocator behavior; GPU integration remains unimplemented |
 | Camera-specific integrations | Generic typed libcamera controls; bounded pre-open IMX708 sensor HDR helper with exact identity, exclusive manager/layout guards, readback diagnostics and fresh mode catalogs; independent runtime HdrMode with staged control replay | Remaining IMX708 workflows and physical HDR acceptance, IMX500 tensor/network/inference/ROI workflows, Hailo integration and postprocessing equivalents; hardware-backed validation |
@@ -207,3 +207,12 @@ joined lifecycle/deadlines, shared PTS, isolated recovery and async output split
 See socket-output.md. Listening/process outputs, broader network protocols and
 sessions, remaining buffering/flush behaviors and all other capability families
 and physical acceptance remain open. This does not complete full parity.
+
+Version 0.104 adds supervised process video output and Home-container byte sinks,
+with shared Home bounded diagnostics/control framing and a standalone Zig host,
+exec readiness, joined cancellation, ordinary descendant groups and parent-fd
+loss, immutable argv/env, shared socket/process admission, isolated recovery and
+async splits. See process-output.md. Additional media containers/protocols,
+escaped or hard-killed-supervisor process-tree policy, remaining output semantics
+and every other required family and physical acceptance remain open. This does
+not complete Picamera2 parity.