[FEATURE] Add the native boot-image backend and exact-output publisher #6

Open
opened 2026-10-24 03:35:24 +02:00 by erikinkinen · 2 comments
Owner

Problem and motivation

An EriX-hosted build needs to construct, inspect and verify boot images with
native boot-tool. The shared command already separates parsing and image logic
from effects, but only the Linux backend currently implements the complete file
and stream contract.

Proposed behavior and scope

Implement the native backend and executable over shared EriX clients. Preserve
all build, inspect, validate, verify, extraction and signing-payload behavior,
including raw path bytes, input order and deterministic successful artifacts.
Keep the Linux command and its existing build recipes usable.

Publication must create an exclusive adjacent temporary, write all bytes, confirm
file synchronization, close the writer and atomically replace the selected
destination. The existing exact-entry rename refuses an occupied destination;
the native publisher therefore needs a coherent replacement contract rather
than a path-based workaround. Prefer a reusable exact-output publication owner
shared with other build tools. Coordinate its admission and provider semantics
before assigning new wire operations.

Authority, security and reliability

Prepare the original arguments before binding authority. Bind only the selected
command's original read objects, output publications and inherited streams.
Paths, environment values and numeric coordinates cannot discover or widen a
namespace. Read-only commands receive no publisher. Use the original allocation
region and checked startup inventory, with no libc or host execution fallback.

A publication owner binds the original parent, destination and exclusive
temporary. It may publish only that output and remove only its own unpublished
temporary. Existing file-write rights must not silently acquire namespace
replacement rights. Preserve request, generation, partial-progress and actual
persistence evidence through close, commit and retirement.

Retain the first operation error separately from cleanup uncertainty. Never
replay an accepted prefix or uncertain rename, remove the destination after an
uncertain commit, or exit while unresolved owners survive only in local storage.
Drain positively or transfer exact custody to an authenticated surviving owner;
otherwise remain alive holding it. Payload and image are separate ordered
commits. No ordinary invocation opens a private signing key: detached signing
and explicitly selected public-key verification remain unchanged.

Acceptance criteria

  • Implement every shared command on the native backend with the same effect
    order and deterministic native error-detail contract.
  • Provide exclusive adjacent publication, full writes, actual sync, writer
    close and atomic replacement through an exact retained output owner.
  • Cover denial, collision, short I/O, malformed replies, missing EOF,
    cancellation, uncertain sync/rename and independent cleanup failures without
    replay, stale-owner reuse or destination deletion.
  • Bind minimal command-specific file and stream authority before execution;
    preserve final drain or authenticated custody transfer before exit.
  • Package the native executable, authenticated metadata and manual page, and
    add bounded matching-image guest workloads with read and publication refusal.
  • Compare Linux and native build, inspect, verify and extraction results on
    identical valid, empty, large and malformed inputs; preserve detached signing.
  • Update component documentation, rustdoc and the technical manual, and keep
    strict checks and existing Linux CI free of warnings.

Alternatives and tradeoffs

A read-only native port leaves image construction outside EriX. Reopening the
temporary by name after closing it loses its original publication custody.
Giving the tool general directory mutation rights would expose more authority
than one output needs. A shared retained publisher keeps this boundary explicit;
its provider work must preserve actual replacement and persistence semantics.

Tracking and rollout

Coordinate Boot-tool PR 2 and
Integration PR 12.
Reuse the shared native clients developed for
native SHA-2.
Land coherent admission, client and provider changes before adopting the native
executable in build images. Keep Linux parity and actual guest acceptance as
separate required results.

## Problem and motivation An EriX-hosted build needs to construct, inspect and verify boot images with native `boot-tool`. The shared command already separates parsing and image logic from effects, but only the Linux backend currently implements the complete file and stream contract. ## Proposed behavior and scope Implement the native backend and executable over shared EriX clients. Preserve all build, inspect, validate, verify, extraction and signing-payload behavior, including raw path bytes, input order and deterministic successful artifacts. Keep the Linux command and its existing build recipes usable. Publication must create an exclusive adjacent temporary, write all bytes, confirm file synchronization, close the writer and atomically replace the selected destination. The existing exact-entry rename refuses an occupied destination; the native publisher therefore needs a coherent replacement contract rather than a path-based workaround. Prefer a reusable exact-output publication owner shared with other build tools. Coordinate its admission and provider semantics before assigning new wire operations. ## Authority, security and reliability Prepare the original arguments before binding authority. Bind only the selected command's original read objects, output publications and inherited streams. Paths, environment values and numeric coordinates cannot discover or widen a namespace. Read-only commands receive no publisher. Use the original allocation region and checked startup inventory, with no libc or host execution fallback. A publication owner binds the original parent, destination and exclusive temporary. It may publish only that output and remove only its own unpublished temporary. Existing file-write rights must not silently acquire namespace replacement rights. Preserve request, generation, partial-progress and actual persistence evidence through close, commit and retirement. Retain the first operation error separately from cleanup uncertainty. Never replay an accepted prefix or uncertain rename, remove the destination after an uncertain commit, or exit while unresolved owners survive only in local storage. Drain positively or transfer exact custody to an authenticated surviving owner; otherwise remain alive holding it. Payload and image are separate ordered commits. No ordinary invocation opens a private signing key: detached signing and explicitly selected public-key verification remain unchanged. ## Acceptance criteria - [ ] Implement every shared command on the native backend with the same effect order and deterministic native error-detail contract. - [ ] Provide exclusive adjacent publication, full writes, actual sync, writer close and atomic replacement through an exact retained output owner. - [ ] Cover denial, collision, short I/O, malformed replies, missing EOF, cancellation, uncertain sync/rename and independent cleanup failures without replay, stale-owner reuse or destination deletion. - [ ] Bind minimal command-specific file and stream authority before execution; preserve final drain or authenticated custody transfer before exit. - [ ] Package the native executable, authenticated metadata and manual page, and add bounded matching-image guest workloads with read and publication refusal. - [ ] Compare Linux and native build, inspect, verify and extraction results on identical valid, empty, large and malformed inputs; preserve detached signing. - [ ] Update component documentation, rustdoc and the technical manual, and keep strict checks and existing Linux CI free of warnings. ## Alternatives and tradeoffs A read-only native port leaves image construction outside EriX. Reopening the temporary by name after closing it loses its original publication custody. Giving the tool general directory mutation rights would expose more authority than one output needs. A shared retained publisher keeps this boundary explicit; its provider work must preserve actual replacement and persistence semantics. ## Tracking and rollout Coordinate [Boot-tool PR 2](https://git.erikinkinen.fi/erix/boot-tool/pulls/2) and [Integration PR 12](https://git.erikinkinen.fi/erix/integration/pulls/12). Reuse the shared native clients developed for [native SHA-2](https://git.erikinkinen.fi/erix/sha2-tool/issues/4). Land coherent admission, client and provider changes before adopting the native executable in build images. Keep Linux parity and actual guest acceptance as separate required results.
Author
Owner

The command-specific broker contract is tracked in Launchd issue 26. Launchd will validate exact prepared operation, class, selector and lifetime rows against the original manifest, script and session ceilings. The native client must retire its broader original sender before ordinary effects; inspect and verify retain only their selected reads. Publication remains a distinct admitted operation with its own original transaction custody.

The command-specific broker contract is tracked in [Launchd issue 26](https://git.erikinkinen.fi/erix/launchd/issues/26). Launchd will validate exact prepared operation, class, selector and lifetime rows against the original manifest, script and session ceilings. The native client must retire its broader original sender before ordinary effects; inspect and verify retain only their selected reads. Publication remains a distinct admitted operation with its own original transaction custody.
Author
Owner

57ca22b3 retains each selected file operand’s original argv index during the sole parse. Reads and publications keep their raw bytes and distinct occurrences when execution order differs from option order. Native admission can bind that footprint without reparsing or searching for equal paths. The existing path-only visitor remains a projection of the same records. The manual chapter describes the binding contract.

57ca22b3 retains each selected file operand’s original argv index during the sole parse. Reads and publications keep their raw bytes and distinct occurrences when execution order differs from option order. Native admission can bind that footprint without reparsing or searching for equal paths. The existing path-only visitor remains a projection of the same records. The [manual chapter](https://git.erikinkinen.fi/erix/docs/src/commit/db3a0fbba6dd61113aa3d15ea3a44217f3ce5251/manual/9-command-line-tools/25-boot-tool.tex) describes the binding contract.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:33 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/boot-tool#6
No description provided.