[FEATURE] Audit authority, code quality and documentation in loaderd #1

Open
opened 2026-09-12 07:57:56 +02:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Audit loaderd throughout Phase 6. Authenticate executable source graphs and coordinate link/materialization requests and launch results for authorized callers.

Review each changed boundary at the final published revision. Prioritize security, reliability, then performance.

Proposed behavior and scope

Staged mediator handoff contract — 15 September 2026

Reserve Loaderd operation 0x654 (PREPARE_REALM) using the existing exact-executable preparation request/response layout. The operation selects the new Procd lifecycle class 0x448 (REALM_MEDIATOR); role values describe lifecycle policy and confer no capability authority. Launchd explicitly selects this operation after authenticating its executable object. The ordinary operation 0x652 keeps its existing behavior. Responses must echo the selected operation; no fallback is permitted.

Loaderd validates the same sole exact-executable SEND receipt, authenticates the complete image graph, and uses the existing semantic materialization pipeline. The mediator's temporary initial endpoint occupies child-local slot 4, after native root slots 1–3. This slot is an ABI destination, not a realm-count or resource-budget restriction. The child remains staged. Procd retains the actual endpoint master in the existing managed scratch endpoint column; it never exports that master to Loaderd or Launchd. Only the actual move-only install grant travels Procd → Loaderd → Launchd. The derived ordinary stream installer is absent for this class. Reply loss aborts the exact stage and accounts for the retained endpoint, grant and VSpace; cleanup uncertainty remains fail-stop.

Launchd may inspect, abort and stop only its owned lifecycle classes. Root, driver and powerbox routes cannot use the mediator class; generic staged-start, ordinary startup/stream installation and automatic restart reject it. The future separate bootstrap transaction must receive the actual grant back, authenticate the live caller, install a typed receiver/rendezvous inventory using exact process-bound installation, dispose temporary aliases and configure the startup bytes before private execution. No existing start path may bypass that gate.

This staged handoff is the first implementation increment of typed realm bootstrap. Acceptance for this increment requires malformed/foreign operation rejection, exact executable and grant receipts, unstarted materialization, private master retention, no derived stream grant, and rollback coverage across the actual producer paths. It does not establish mediator execution, seal, publication, client I/O, retirement fairness or either complete guest build generation. Those remain required under the existing acceptance criteria. Native VM coverage of the coordinated producer graph is required before claiming runtime acceptance.

Current inventory: 1 Cargo target (1 bin); manifests: Cargo.toml. Include explicit and automatically discovered targets, supported features and target-specific configurations.

Inventory every startup/runtime grant and authenticated peer, then success, denial, cancellation, failed transfer, restart and teardown. Trace callers and downstream providers so names, numeric identities and retained aliases never become implicit authority.

Authority, security and reliability

Record each finding's affected revision, invariant, reproduction, owner, regression coverage and resolution. Report suspected vulnerabilities through SECURITY.md and keep sensitive details private. Record a result and rationale for each audit criterion, including caller responsibilities when this component has no process or Rust target.

Acceptance criteria

Checklist
  • Record origin, recipient, object, operations, delegation ceiling, lifetime and aliases for each relevant capability or caller-supplied authority-bearing value.
  • Audit ambient discovery/selectors, cwd/PATH/environment, numeric identities, inherited routes and host fallbacks; require explicit authorized intake.
  • Account for residual authority after success, error, cancellation, timeout, restart, failed transfer and teardown, including fork/exec where implemented.
  • Remove unnecessary endpoints, broad rights, duplicate aliases, provider/admin grants and debug routes.
  • Exercise stale generations, replay, pending replies, forged descriptive identity and object/path resolution races at the owned boundary.
  • Prove independent cleanup attempts and caller-specific error precedence; quarantine or terminate when retained authority cannot be accounted for.
  • Review unsafe/FFI/parser/arithmetic/lifetime/lock/publication invariants and add adversarial coverage where practical.
  • Inventory obsolete APIs, wrappers, fallback/dead paths and duplicate validators with their maintained callers.
  • Migrate callers and delete deprecated contracts/shims in a coherent signed revision graph; reject retired input versions where relevant.
  • Classify each size/count/depth/time bound as ABI, hardware, explicit resource policy or accidental limitation.
  • Test beyond removed boundaries and at allocation/ABI limits while preserving exhaustion errors, denial-of-service controls and bounded waits.
  • Keep every tracked authored code/test/script/workflow file below 1000 physical lines through thematic refactoring.
  • Run the deterministic tracked-source size gate, covering executable fixtures/generators and excluding only genuine non-code data or external payloads.
  • Audit production/test feature and symbol separation, including this repository's effect on rootd test orchestration.
  • Supply changes affecting rootd semantic surface to the maintained same-toolchain baseline; record a justified component-specific applicability result.
  • Check bootstrap ownership and development/release authority parity at this repository's producer/consumer boundary.
  • Use maintained integration#3 profiler evidence before optimizing; preserve live access checks, ownership and success criteria.
  • Audit build/CI inputs, secret handling, private outputs, symlink containment, deletion, subprocess bounds, warnings and host dependencies.
  • meaningful public/private inline documentation, crate/target missing_docs enforcement without blanket allowances or hidden-API escapes, warning-denied private-item rustdoc and an undocumented-public-API negative gate.
  • Validation: Run cargo fmt --all -- --check, strict Clippy, unit/doctests and warning-denied builds/rustdoc for every owned crate/target under default and all valid feature, freestanding/host, SMP and profile combinations; test mutually exclusive combinations separately. Add focused VM regressions for runtime behavior and observe the older catalog and unit tests at the exact published heads.
  • Documentation: update applicable README/ARCHITECTURE/ROADMAP in meta's canonical format and affected technical-manual TeX/API references; keep README evergreen and shared governance byte-identical to meta.
  • Evidence: record exact source/dependency revisions, commands, configurations, real exit status, CI run URLs and results; repeat the audit on final heads and obtain independent review of security closures. No skipped/pending/predecessor result counts as a pass.

Alternatives and tradeoffs

Refactor within the component unless shared semantics justify extracting common code. Preserve regression coverage before deleting superseded paths. Profile before optimizing, and document ABI limits, hardware limits and explicit quotas. Preserve security and reliability requirements.

The mediator class cannot use ordinary start, immediate commit, TTY provisioning, powerbox installation or automatic restart. Procd has forty native binary builds and six new mediator refusal/cleanup regressions. No Posixd executable or coordinated realm VM acceptance is claimed. Actual grant-return provisioning, authenticated caller ownership, typed startup memory/inventory, readiness, configuration/seal, client I/O, fair retirement, complete consumer image adoption and both full guest build generations remain open.

Native bootstrap destination correction — 15 September 2026

The temporary endpoint destination is now child-local slot 4, after the mandatory CSpace, VSpace and TCB roots in slots 1–3. This proves the constructor boundary; coordinated mediator startup, seal, client I/O, retirement and full guest builds remain open.

Actual grant-return provisioning, authenticated receiver readiness, configuration/seal, client I/O, fair retirement, whole-codebase authority/documentation closure and both complete guest build generations remain required. No runnable Posixd realm or guest-build acceptance is claimed.

Procd's existing transaction remains the sole owner of privileged construction writes and final mappings; no new control endpoint, capability, lookup root or wire operation is introduced.

Rounded protection must neither leave a declared byte writable nor silently remove write permission from unrelated mutable data.

Transaction tests must preserve original relocation ranges while emitting final read-only permissions, apply construction relocations successfully and retain failure/abort behavior.

This checkpoint does not establish complete runtime permission, frame, authority, realm or guest-build acceptance.

Full frame proof, whole-codebase authority/documentation review, runnable realms and both complete guest build generations remain open.

An earlier image is rejected by the maintained observer.

The command's image CI gate awaits adoption of a coherent product catalog containing both required component fixes. Current Integration CI, complete frame proof, whole-codebase authority/documentation closure, runnable realms and both guest-build generations remain open.

Both are nonzero only for the realm mediator role; both must be zero for every other role. Reject the obsolete 56-byte shape.

The pair describes delegated lifecycle responsibility; numbers alone never confer creation, installation or rollback authority. Guard admission must match the original supervisor, never replace it with a later claimant.

Caller RELEASE initiates cancellation and must precede any ordinary abort request that could wait behind Procd delivery retirement.

Actual Launchd runtime preparation and scheduler adoption, deployment-sized ownership storage, adversarial host controls and real producer/consumer VM execution remain required.

Ordinary roles require zeros. Actual Launchd owned producer/runtime adoption, coordinated consumer VM execution, complete fairness, configuration/readiness/seal and both full guest builds remain open.

Matching catalog adoption and real consumer VMs remain requirements; complete realm and full in-guest build acceptance remain open.

Available original test logs pass without warnings, but the missing terminal output prevents complete CI acceptance or source-level diagnosis.

Tracking and rollout

Legacy destinations, exact source/rights/caller/relation checks, native empty-slot and capacity enforcement, and acknowledged disposal remain required.

Signed Docs ee08bab6 documents the contract. All 45 document tests pass, the full 2,653-page manual builds without final warnings, all 491,233 word bounds pass and three affected/adjacent pages are visually reviewed. Its original CI1083/1084 is under observation.

Signed Integration 04bff04f adopts those two original image sources. Both catalog policies, all 76 original signatures and complete transitive closure pass. The Cargo catalog contains neither changed component and remains unchanged. All helper, Rust, profiler and CI source bytes retain their previous validation; fresh formatting, source policy and Markdown pass. Original CI1799/1800 is queued. Fresh configured-client and older preparation/startup VM execution on this successor remains required by Loaderd issue 5; the previous two prerequisite passes and subsequent client failure remain retained.

Original Exsh CI281/282 now have complete failure logs: unit suites pass 507/478/1 and all 355 frame-checker controls pass, but both runtime profiles reach 256 functions with 101 unresolved observations and both all-feature profiles reach 286 with 68 unresolved observations. All four logs total 322,830 bytes with zero warning candidates. Exsh frame issue 4 and compiler issue 9 remain open. No unchanged CI was restarted and no acceptance bound was relaxed. These repairs add no checklist credit; native configured-client acceptance, managed-row reuse, profiling, complete authority closure and both full guest-build requirements remain open.

Guarded preparation uses the actual Posixd root with its required immutable layout, and actual private mediators reach readiness and retire independently.

The configured-client VM now passes all three inherited markers, then its first PREPARE_REALM_CLIENT request 34 (opcode 0x6d7) returns INTERNAL (5). The original failed run retains 109 artifacts and 56,226 serial bytes, with zero build-warning candidates and no process-owner cleanup failure. Loaderd issue 5 records the separate defect: the counted Launchd client producer selects its own grant column, while Loaderd's intake, handler and reply retain legacy fixed destination 645. Two independent actual-code tests reproduce intake refusal and reply redirection. A correction must preserve the exact original client destination while retaining legacy destination, source receipt, actual caller, relation and cleanup gates.

The mediator-fixture correction is demonstrated in both prerequisite VMs; Exsh issue 10 remains linked to full configured-client validation. No client execution, configuration/seal/byte-I/O acceptance, managed-row reuse, profiler observation or full guest build is claimed. Original Exsh CI281/282 is running, and original Integration CI1797/1798 is queued; earlier original Integration cohorts remain under observation. Exsh compiler/frame gates remain open, and no unchanged CI was restarted. These repairs add no canonical checklist credit.

No unchanged job was rerun; coordinated runtime acceptance remains separate.

Coordinated Procd/Launchd adoption and four-client native VM acceptance remain open in Loaderd PR2.

Complete client admission/lifecycle design — 25 September 2026: the shared codec design now defines public Launchd operations6D5–6DD using only original owned realm/client handles; private Procd provisioning43D–441; distinct authenticated never-started client disposal messages; and LCH1v4 counted client-row/plan-byte storage. No public caller nominates a native process or capability identity. Freeze verifies the complete canonical plan before effects; private provisioning preserves grant MOVE, receiver COPY and independent source/caller retirement. Client Start follows the two-sided seal, and exact terminal outcomes remain in counted storage until realm retirement. The first immutable byte cohort is explicitly scoped; it is no permanent POSIX process ceiling. A dedicated rootless byte-client binary will use RCS1 and its own ingress only. Implementation, strict validation and the real four-client VM witness remain open.

Retained cleanup design — 25 September 2026: lifecycle failures must return the exact original materialization and linker transaction owners to a cleanup-only boundary. Each owner advances independently and is removed only after correlated acknowledged disposition; ordinary request serving remains unavailable while either is unresolved. Complete linker cleanup precedes process commit. An idempotent Abort confirms an already idle peer, while a different active transaction remains refused and a new Begin preserves any live predecessor. Procd must retain and advance failed cleanup before it can acknowledge absence. Existing operation widths and authority routes remain unchanged. Source implementation, whole-graph fault controls, coherent dependency validation and native evidence are required before acceptance.

Native consumer development — 24 September 2026: authenticated target-layout extraction and original-transaction binding are under implementation. The consumer checks complete file-backed table extent, uniqueness, target identity and final RO/NX page permissions before effects. The original materialization owner is no longer copyable. Independent review also identified malformed reply error classification; its correction and whole-graph short/oversized response cleanup controls await full validation on the coherent successor dependencies. The distinct private-client staging contract above is being implemented with exact realm/mediator correlation before creation. Implementation review remains WIP. No new native image or guest-build acceptance is added.

Private client materialization contract — 24 September 2026: the existing materialization-begin frame carries only the supervisor pair. Role recognition alone cannot bind an actual client to its intended mediator before native creation. Use distinct private operations with explicit descriptive correlation, authenticated through the existing Loaderd and Launchd routes; no new capability or ordinary-launch fallback is introduced.

Loader PREPARE_REALM_CLIENT (0x655) is exactly 340 bytes: retain the existing 316-byte exact-executable selection offsets, then realm ID/generation u64 at 316/324 and native mediator process/generation u32 at 332/336. Its distinct 176-byte reply retains the existing 152-byte result/grant/digest fields, then echoes the complete relation at 152/160/168/172 on both success and refusal. Existing failure-zero rules still apply to staged/grant IDs and digest evidence. The old 316/152-byte parsers reject this selector. The exact executable SEND retains COPY semantics and independent source disposal; the staged install grant retains MOVE semantics.

Procd BEGIN_REALM_CLIENT_MATERIALIZATION (0x43C) is exactly 88 bytes: existing 64-byte begin field offsets, then realm ID/generation at 64/72 and native mediator process/generation at 80/84. Require private role 0x449, the original nonzero Launchd pair, and nonzero relation scalars. Generic Begin64 must reject role 0x449; mediator Begin64 remains unchanged. The existing 36-byte noncommit reply recognizes the new selector and echoes request, operation and original transaction, with zero materialization and staged IDs. Encoding preflights the complete request; neither decoding nor scalar correlation authenticates the native origin.

Before client CREATE, Procd authenticates actual Loaderd and the retained running Launchd, resolves the exact original Guarded and unstarted mediator, and checks the same supervisor. Because the final plan digest includes actual client generations, the first admitted client request may bind a previously unbound mediator to that realm pair before creation. Retain this first binding even if client creation later fails. All later client requests and counted Provision must match it. Reject the same realm pair on any other retained mediator belonging to that supervisor, including retirement or uncertain cleanup. Bootstrap-only Provision can still perform the first binding when there are no clients. Preserve the actual parent/mediator/client relationship through active materialization, staged commit, rollback and terminal custody; numeric realm metadata grants no authority.

Client startup, ingress installation, complete configuration, authenticated seal, source disposal and native caller retirement remain separate gates. Clients cannot start until committed seal and its caller retirement are proved. The required two-realm/four-client byte-I/O and cross-realm refusal witness remains open. This is the implementation contract; it adds no native or phase acceptance.

Counted client configuration continuation — 24 September 2026:

Proposed coordinated continuation: configure each private Posixd instance with two actual staged clients and mediator-owned bounded byte channels. Preserve the existing startup/control handshake and native identity checks. Configuration is canonical, counted and digest-bound; labels select already held owners and never confer authority. This is a first nonblocking byte-I/O slice. Full filesystem/TTY configuration, complete POSIX semantics, libc, all resource-retirement criteria, rebuilding Rust/LLVM inside EriX and both complete EriX guest builds remain required later work.

Extend the private exact-image path for the new RealmClient class. Authenticate the scoped executable bytes and original stage/grant independently of ordinary launch manifests or TTY/stream installers. Return only the exact prepared client identity to the retained owner; keep client image preparation distinct from later digest-bound startup provisioning, so all client pairs can be frozen before the plan is hashed.

Authenticate the target layout descriptor/version through this same selected-image path before Procd allocates it, using the exact binding below. Do not accept public-supplied widths, host layout assumptions, path labels as authority or a second fallback executable route. Preserve partial mapping/grant ownership and exact cleanup after malformed image/layout or lost completion.

Authenticate target geometry through the existing selected-image path. Posixd exports one immutable 96-byte target-generated descriptor in read-only file-backed ELF load storage: magic16 ERIXPXSCAPLAY001, then ten little-endian u64 words for version1, total size96, ELF machine, pointer bits, and client/descriptor/channel row size/alignment pairs. Sizes are nonzero and alignments powers of two; target fields match the selected executable. Loaderd extracts exactly one complete descriptor from its already authenticated root ELF bytes, refusing missing, duplicate, malformed or writable records. No host-derived type size or reopened pathname supplies geometry.

An exact 144-byte BindRealmLayout request uses the existing authenticated LoaderMaterialization route: request/op u32, original active transaction u64, root ELF SHA-25632 and descriptor96. Its response uses the existing 36-byte materialization shape with zero noncommit materialization/staged fields. Procd accepts it only from actual Loaderd for that original active mediator transaction, retains the description through staged commit/rollback, and requires it before mediator commit. The startup carries the descriptor SHA-256, which Posixd compares against its own compiled descriptor before any typed arena borrow. Canonical checked sizing partitions client rows, descriptor rows, channel rows, plan bytes, ring bytes, retained per-client results and immediate packet storage; every multiplication, alignment, address and page round must fit. This grants no additional endpoint or allocation authority.

Ordinary endpoint transfer copies authority. Every source and possible receive destination remains owned across submission, collection and native retirement, including ambiguous results. Reserve each prospective receive slot before COLLECT; validate its normalized receipt and actual Generic kind/rights, then independently reconcile its disposal before reuse. Unique InstallGrant and RevocationGrant transfers keep MOVE semantics. Do not infer source deletion from successful copy or use deletion to manufacture successful unique-grant movement.

Track this continuation with Posixd realm lifecycle, POSIX ABI and Phase 6 completion. This is a proposed contract; no runtime or implementation acceptance is claimed.

Counted private startup dependency adoption — 24 September 2026.

These host/build results do not establish actual running mediator readiness or retirement, a complete service-image pass, configuration/seal, client I/O, or either required guest rebuild.

Tracking: owning issue, WIP PR and Phase 6 acceptance.

Detailed scope and contracts

Runtime consumer dependency alignment — 15 September 2026

The product catalog, product VM acceptance and guest build remain pending.

Signed commit cdf08f8e5f2cf208390099598f86ccfaa7cc96eb requires exact GRANT-only final installer receipts and selects the original shared dependency graph.

Lifetime now exercises 27 ordinary CPL3 grant-right controls and requires INSTALL_GRANT_RIGHTS_OK before its existing cleanup assertions. These minimal native scenarios establish neither full service-image acceptance nor a guest build.

Full coordinated consumer acceptance remains open under Kernel design 19 and phase completion.

Full service CPU/profiler VM acceptance and guest builds remain open in Phase 6 completion.

Digest-selected exact executable preparation

Retire the fixed-path private Loaderd preparation family after migrating Launchd and all native consumers. Add V2 operations 0x718 (ordinary executable), 0x719 (realm mediator) and 0x71A (realm client). Their 104-byte base request retains request/opcode, transaction, install destination, actual executable SEND source/staging, mode, size and original object identity. Replace pathname fields with the nonzero command-entry digest already defined as SHA-256(domain V1 || u64 little-endian raw entry length || exact authenticated entry bytes). Realm clients append the unchanged 24-byte original relation, for 128 bytes total. The 184-byte base response preserves original preparation measurements and appends that command-entry correlation; clients append the relation for 208 bytes. Refusal echoes the original entry and relation while withholding success evidence. Old operations and codecs are removed without a fallback.

Launchd derives the digest only from existing Vfsd-authenticated executable evidence, never argv[0], a caller selector or optional display labels. Loaderd compares that digest against entries of the complete runtime graph after authenticating its configured digest. Require exactly one matching executable root, then materialize the actual received executable endpoint with existing exact size, manifest and content measurement checks. The selector digest is data and cannot acquire a filesystem object, bypass runtime-graph integrity, select a service role or start a process.

Separate graph-root selection explicitly: authenticated bootstrap/service pathname selection remains on its own native lifecycle; exact executable/realm/client preparation accepts only the digest selector with actual executable SEND custody. Do not copy a graph source path into another fixed buffer, synthesize a pathname or reopen the selected executable. Preserve graph closure/cycle checks, native caller/realm relation, unique install-grant MOVE, uncertain cleanup and original rollback obligations. Both success and refusal must correlate the requested command entry before Launchd accepts returned evidence.

This completes Loaderd selection within the ongoing native launch migration. Vfsd executable/sidecar framing, counted authenticated entry evidence, retained program display, provider adapter retirement and coherent runtime adoption remain required. Author literal wire, wrong/zero digest, same-content distinct entries, long names, retired frames, native authority and cleanup controls; keep tests/builds/checks/CI deferred under the current waiver. Publish immutable dependencies bottom-up and update the manual and affected tracking records.

Native SEND and entry-digest
validation return a borrowed complete raw label; ordinary preparation copies it
before transport reuse and admits the sidecar in the remaining exact scratch. Labels create no capability or replacement authority.

Seven new controls cover long raw preparation, reused caller scratch, original
job ownership, capacity/identity refusal, compaction, stale generations, successor
transfer, literal startup geometry and missing/unaddressable budgets.

The containing native migration remains open for remaining provider/name adapters,
complete cross-provider lifetime/refusal controls and coherent runtime catalog
adoption. Existing broad acceptance remains unchanged. Full EriX guest build
generations, external Rust/LLVM rebuilding inside EriX and profiler evidence remain
required and unperformed.

Related records and contracts
Repository Links
docs issue 1, PR 4
integration issue 101, issue 2, PR 12
kernel issue 20
launchd issue 1, PR 2
lib-bootstrap issue 1, PR 2
lib-capabi issue 3
lib-ipc PR 2
loaderd issue 3
powerboxd PR 2
refspecs.linuxfoundation.org progheader.html
rootd PR 2
sourceware.org Options.html
ttyd PR 3
## Problem and motivation Audit `loaderd` throughout Phase 6. Authenticate executable source graphs and coordinate link/materialization requests and launch results for authorized callers. Review each changed boundary at the final published revision. Prioritize security, reliability, then performance. ## Proposed behavior and scope ### Staged mediator handoff contract — 15 September 2026 Reserve Loaderd operation `0x654` (PREPARE_REALM) using the existing exact-executable preparation request/response layout. The operation selects the new Procd lifecycle class `0x448` (REALM_MEDIATOR); role values describe lifecycle policy and confer no capability authority. Launchd explicitly selects this operation after authenticating its executable object. The ordinary operation `0x652` keeps its existing behavior. Responses must echo the selected operation; no fallback is permitted. Loaderd validates the same sole exact-executable SEND receipt, authenticates the complete image graph, and uses the existing semantic materialization pipeline. The mediator's temporary initial endpoint occupies child-local slot 4, after native root slots 1–3. This slot is an ABI destination, not a realm-count or resource-budget restriction. The child remains staged. Procd retains the actual endpoint master in the existing managed scratch endpoint column; it never exports that master to Loaderd or Launchd. Only the actual move-only install grant travels Procd → Loaderd → Launchd. The derived ordinary stream installer is absent for this class. Reply loss aborts the exact stage and accounts for the retained endpoint, grant and VSpace; cleanup uncertainty remains fail-stop. Launchd may inspect, abort and stop only its owned lifecycle classes. Root, driver and powerbox routes cannot use the mediator class; generic staged-start, ordinary startup/stream installation and automatic restart reject it. The future separate bootstrap transaction must receive the actual grant back, authenticate the live caller, install a typed receiver/rendezvous inventory using exact process-bound installation, dispose temporary aliases and configure the startup bytes before private execution. No existing start path may bypass that gate. This staged handoff is the first implementation increment of typed realm bootstrap. Acceptance for this increment requires malformed/foreign operation rejection, exact executable and grant receipts, unstarted materialization, private master retention, no derived stream grant, and rollback coverage across the actual producer paths. It does not establish mediator execution, seal, publication, client I/O, retirement fairness or either complete guest build generation. Those remain required under the existing acceptance criteria. Native VM coverage of the coordinated producer graph is required before claiming runtime acceptance. Current inventory: 1 Cargo target (1 bin); manifests: `Cargo.toml`. Include explicit and automatically discovered targets, supported features and target-specific configurations. Inventory every startup/runtime grant and authenticated peer, then success, denial, cancellation, failed transfer, restart and teardown. Trace callers and downstream providers so names, numeric identities and retained aliases never become implicit authority. ## Authority, security and reliability Record each finding's affected revision, invariant, reproduction, owner, regression coverage and resolution. Report suspected vulnerabilities through SECURITY.md and keep sensitive details private. Record a result and rationale for each audit criterion, including caller responsibilities when this component has no process or Rust target. ## Acceptance criteria <details> <summary>Checklist</summary> - [ ] Record origin, recipient, object, operations, delegation ceiling, lifetime and aliases for each relevant capability or caller-supplied authority-bearing value. - [ ] Audit ambient discovery/selectors, cwd/PATH/environment, numeric identities, inherited routes and host fallbacks; require explicit authorized intake. - [ ] Account for residual authority after success, error, cancellation, timeout, restart, failed transfer and teardown, including fork/exec where implemented. - [ ] Remove unnecessary endpoints, broad rights, duplicate aliases, provider/admin grants and debug routes. - [ ] Exercise stale generations, replay, pending replies, forged descriptive identity and object/path resolution races at the owned boundary. - [ ] Prove independent cleanup attempts and caller-specific error precedence; quarantine or terminate when retained authority cannot be accounted for. - [ ] Review unsafe/FFI/parser/arithmetic/lifetime/lock/publication invariants and add adversarial coverage where practical. - [ ] Inventory obsolete APIs, wrappers, fallback/dead paths and duplicate validators with their maintained callers. - [ ] Migrate callers and delete deprecated contracts/shims in a coherent signed revision graph; reject retired input versions where relevant. - [ ] Classify each size/count/depth/time bound as ABI, hardware, explicit resource policy or accidental limitation. - [ ] Test beyond removed boundaries and at allocation/ABI limits while preserving exhaustion errors, denial-of-service controls and bounded waits. - [ ] Keep every tracked authored code/test/script/workflow file below 1000 physical lines through thematic refactoring. - [ ] Run the deterministic tracked-source size gate, covering executable fixtures/generators and excluding only genuine non-code data or external payloads. - [ ] Audit production/test feature and symbol separation, including this repository's effect on rootd test orchestration. - [ ] Supply changes affecting rootd semantic surface to the maintained same-toolchain baseline; record a justified component-specific applicability result. - [ ] Check bootstrap ownership and development/release authority parity at this repository's producer/consumer boundary. - [ ] Use maintained [integration#3](https://git.erikinkinen.fi/erix/integration/issues/3) profiler evidence before optimizing; preserve live access checks, ownership and success criteria. - [ ] Audit build/CI inputs, secret handling, private outputs, symlink containment, deletion, subprocess bounds, warnings and host dependencies. - [ ] meaningful public/private inline documentation, crate/target `missing_docs` enforcement without blanket allowances or hidden-API escapes, warning-denied private-item rustdoc and an undocumented-public-API negative gate. - [ ] Validation: Run `cargo fmt --all -- --check`, strict Clippy, unit/doctests and warning-denied builds/rustdoc for every owned crate/target under default and all valid feature, freestanding/host, SMP and profile combinations; test mutually exclusive combinations separately. Add focused VM regressions for runtime behavior and observe the older catalog and unit tests at the exact published heads. - [ ] Documentation: update applicable README/ARCHITECTURE/ROADMAP in meta's canonical format and affected technical-manual TeX/API references; keep README evergreen and shared governance byte-identical to meta. - [ ] Evidence: record exact source/dependency revisions, commands, configurations, real exit status, CI run URLs and results; repeat the audit on final heads and obtain independent review of security closures. No skipped/pending/predecessor result counts as a pass. </details> ## Alternatives and tradeoffs Refactor within the component unless shared semantics justify extracting common code. Preserve regression coverage before deleting superseded paths. Profile before optimizing, and document ABI limits, hardware limits and explicit quotas. Preserve security and reliability requirements. The mediator class cannot use ordinary start, immediate commit, TTY provisioning, powerbox installation or automatic restart. Procd has forty native binary builds and six new mediator refusal/cleanup regressions. No Posixd executable or coordinated realm VM acceptance is claimed. Actual grant-return provisioning, authenticated caller ownership, typed startup memory/inventory, readiness, configuration/seal, client I/O, fair retirement, complete consumer image adoption and both full guest build generations remain open. ### Native bootstrap destination correction — 15 September 2026 The temporary endpoint destination is now child-local slot 4, after the mandatory CSpace, VSpace and TCB roots in slots 1–3. This proves the constructor boundary; coordinated mediator startup, seal, client I/O, retirement and full guest builds remain open. Actual grant-return provisioning, authenticated receiver readiness, configuration/seal, client I/O, fair retirement, whole-codebase authority/documentation closure and both complete guest build generations remain required. No runnable Posixd realm or guest-build acceptance is claimed. Procd's existing transaction remains the sole owner of privileged construction writes and final mappings; no new control endpoint, capability, lookup root or wire operation is introduced. Rounded protection must neither leave a declared byte writable nor silently remove write permission from unrelated mutable data. Transaction tests must preserve original relocation ranges while emitting final read-only permissions, apply construction relocations successfully and retain failure/abort behavior. This checkpoint does not establish complete runtime permission, frame, authority, realm or guest-build acceptance. Full frame proof, whole-codebase authority/documentation review, runnable realms and both complete guest build generations remain open. An earlier image is rejected by the maintained observer. The command's image CI gate awaits adoption of a coherent product catalog containing both required component fixes. Current Integration CI, complete frame proof, whole-codebase authority/documentation closure, runnable realms and both guest-build generations remain open. Both are nonzero only for the realm mediator role; both must be zero for every other role. Reject the obsolete 56-byte shape. The pair describes delegated lifecycle responsibility; numbers alone never confer creation, installation or rollback authority. Guard admission must match the original supervisor, never replace it with a later claimant. Caller RELEASE initiates cancellation and must precede any ordinary abort request that could wait behind Procd delivery retirement. Actual Launchd runtime preparation and scheduler adoption, deployment-sized ownership storage, adversarial host controls and real producer/consumer VM execution remain required. Ordinary roles require zeros. Actual Launchd owned producer/runtime adoption, coordinated consumer VM execution, complete fairness, configuration/readiness/seal and both full guest builds remain open. Matching catalog adoption and real consumer VMs remain requirements; complete realm and full in-guest build acceptance remain open. Available original test logs pass without warnings, but the missing terminal output prevents complete CI acceptance or source-level diagnosis. ## Tracking and rollout Legacy destinations, exact source/rights/caller/relation checks, native empty-slot and capacity enforcement, and acknowledged disposal remain required. Signed [Docs ee08bab6](https://git.erikinkinen.fi/erix/docs/commit/ee08bab65e29dd6c3c3781f1b361070a99d7325b) documents the contract. All 45 document tests pass, the full 2,653-page manual builds without final warnings, all 491,233 word bounds pass and three affected/adjacent pages are visually reviewed. Its original CI1083/1084 is under observation. Signed [Integration 04bff04f](https://git.erikinkinen.fi/erix/integration/commit/04bff04f4328676ba8205f7ac2b0df64213698a0) adopts those two original image sources. Both catalog policies, all 76 original signatures and complete transitive closure pass. The Cargo catalog contains neither changed component and remains unchanged. All helper, Rust, profiler and CI source bytes retain their previous validation; fresh formatting, source policy and Markdown pass. Original CI1799/1800 is queued. Fresh configured-client and older preparation/startup VM execution on this successor remains required by [Loaderd issue 5](https://git.erikinkinen.fi/erix/loaderd/issues/5); the previous two prerequisite passes and subsequent client failure remain retained. Original Exsh CI281/282 now have complete failure logs: unit suites pass 507/478/1 and all 355 frame-checker controls pass, but both runtime profiles reach 256 functions with 101 unresolved observations and both all-feature profiles reach 286 with 68 unresolved observations. All four logs total 322,830 bytes with zero warning candidates. [Exsh frame issue 4](https://git.erikinkinen.fi/erix/exsh/issues/4) and [compiler issue 9](https://git.erikinkinen.fi/erix/exsh/issues/9) remain open. No unchanged CI was restarted and no acceptance bound was relaxed. These repairs add no checklist credit; native configured-client acceptance, managed-row reuse, profiling, complete authority closure and both full guest-build requirements remain open. Guarded preparation uses the actual Posixd root with its required immutable layout, and actual private mediators reach readiness and retire independently. The configured-client VM now passes all three inherited markers, then its first PREPARE_REALM_CLIENT request 34 (opcode 0x6d7) returns INTERNAL (5). The original failed run retains 109 artifacts and 56,226 serial bytes, with zero build-warning candidates and no process-owner cleanup failure. [Loaderd issue 5](https://git.erikinkinen.fi/erix/loaderd/issues/5) records the separate defect: the counted Launchd client producer selects its own grant column, while Loaderd's intake, handler and reply retain legacy fixed destination 645. Two independent actual-code tests reproduce intake refusal and reply redirection. A correction must preserve the exact original client destination while retaining legacy destination, source receipt, actual caller, relation and cleanup gates. The mediator-fixture correction is demonstrated in both prerequisite VMs; [Exsh issue 10](https://git.erikinkinen.fi/erix/exsh/issues/10) remains linked to full configured-client validation. No client execution, configuration/seal/byte-I/O acceptance, managed-row reuse, profiler observation or full guest build is claimed. Original Exsh CI281/282 is running, and original Integration CI1797/1798 is queued; earlier original Integration cohorts remain under observation. Exsh compiler/frame gates remain open, and no unchanged CI was restarted. These repairs add no canonical checklist credit. No unchanged job was rerun; coordinated runtime acceptance remains separate. Coordinated Procd/Launchd adoption and four-client native VM acceptance remain open in [Loaderd PR2](https://git.erikinkinen.fi/erix/loaderd/pulls/2). Complete client admission/lifecycle design — 25 September 2026: the [shared codec design](https://git.erikinkinen.fi/erix/lib-ipc/issues/1) now defines public Launchd operations6D5–6DD using only original owned realm/client handles; private Procd provisioning43D–441; distinct authenticated never-started client disposal messages; and LCH1v4 counted client-row/plan-byte storage. No public caller nominates a native process or capability identity. Freeze verifies the complete canonical plan before effects; private provisioning preserves grant MOVE, receiver COPY and independent source/caller retirement. Client Start follows the two-sided seal, and exact terminal outcomes remain in counted storage until realm retirement. The first immutable byte cohort is explicitly scoped; it is no permanent POSIX process ceiling. A dedicated rootless byte-client binary will use RCS1 and its own ingress only. Implementation, strict validation and the real four-client VM witness remain open. Retained cleanup design — 25 September 2026: lifecycle failures must return the exact original materialization and linker transaction owners to a cleanup-only boundary. Each owner advances independently and is removed only after correlated acknowledged disposition; ordinary request serving remains unavailable while either is unresolved. Complete linker cleanup precedes process commit. An idempotent Abort confirms an already idle peer, while a different active transaction remains refused and a new Begin preserves any live predecessor. Procd must retain and advance failed cleanup before it can acknowledge absence. Existing operation widths and authority routes remain unchanged. Source implementation, whole-graph fault controls, coherent dependency validation and native evidence are required before acceptance. Native consumer development — 24 September 2026: authenticated target-layout extraction and original-transaction binding are under implementation. The consumer checks complete file-backed table extent, uniqueness, target identity and final RO/NX page permissions before effects. The original materialization owner is no longer copyable. Independent review also identified [malformed reply error classification](https://git.erikinkinen.fi/erix/loaderd/issues/4); its correction and whole-graph short/oversized response cleanup controls await full validation on the coherent successor dependencies. The distinct private-client staging contract above is being implemented with exact realm/mediator correlation before creation. [Implementation review](https://git.erikinkinen.fi/erix/loaderd/pulls/2) remains WIP. No new native image or guest-build acceptance is added. Private client materialization contract — 24 September 2026: the existing materialization-begin frame carries only the supervisor pair. Role recognition alone cannot bind an actual client to its intended mediator before native creation. Use distinct private operations with explicit descriptive correlation, authenticated through the existing Loaderd and Launchd routes; no new capability or ordinary-launch fallback is introduced. Loader `PREPARE_REALM_CLIENT` (`0x655`) is exactly 340 bytes: retain the existing 316-byte exact-executable selection offsets, then realm ID/generation u64 at 316/324 and native mediator process/generation u32 at 332/336. Its distinct 176-byte reply retains the existing 152-byte result/grant/digest fields, then echoes the complete relation at 152/160/168/172 on both success and refusal. Existing failure-zero rules still apply to staged/grant IDs and digest evidence. The old 316/152-byte parsers reject this selector. The exact executable SEND retains COPY semantics and independent source disposal; the staged install grant retains MOVE semantics. Procd `BEGIN_REALM_CLIENT_MATERIALIZATION` (`0x43C`) is exactly 88 bytes: existing 64-byte begin field offsets, then realm ID/generation at 64/72 and native mediator process/generation at 80/84. Require private role `0x449`, the original nonzero Launchd pair, and nonzero relation scalars. Generic Begin64 must reject role `0x449`; mediator Begin64 remains unchanged. The existing 36-byte noncommit reply recognizes the new selector and echoes request, operation and original transaction, with zero materialization and staged IDs. Encoding preflights the complete request; neither decoding nor scalar correlation authenticates the native origin. Before client CREATE, Procd authenticates actual Loaderd and the retained running Launchd, resolves the exact original Guarded and unstarted mediator, and checks the same supervisor. Because the final plan digest includes actual client generations, the first admitted client request may bind a previously unbound mediator to that realm pair before creation. Retain this first binding even if client creation later fails. All later client requests and counted Provision must match it. Reject the same realm pair on any other retained mediator belonging to that supervisor, including retirement or uncertain cleanup. Bootstrap-only Provision can still perform the first binding when there are no clients. Preserve the actual parent/mediator/client relationship through active materialization, staged commit, rollback and terminal custody; numeric realm metadata grants no authority. Client startup, ingress installation, complete configuration, authenticated seal, source disposal and native caller retirement remain separate gates. Clients cannot start until committed seal and its caller retirement are proved. The required two-realm/four-client byte-I/O and cross-realm refusal witness remains open. This is the implementation contract; it adds no native or phase acceptance. Counted client configuration continuation — 24 September 2026: Proposed coordinated continuation: configure each private Posixd instance with two actual staged clients and mediator-owned bounded byte channels. Preserve the existing startup/control handshake and native identity checks. Configuration is canonical, counted and digest-bound; labels select already held owners and never confer authority. This is a first nonblocking byte-I/O slice. Full filesystem/TTY configuration, complete POSIX semantics, libc, all resource-retirement criteria, rebuilding Rust/LLVM inside EriX and both complete EriX guest builds remain required later work. Extend the private exact-image path for the new RealmClient class. Authenticate the scoped executable bytes and original stage/grant independently of ordinary launch manifests or TTY/stream installers. Return only the exact prepared client identity to the retained owner; keep client image preparation distinct from later digest-bound startup provisioning, so all client pairs can be frozen before the plan is hashed. Authenticate the target layout descriptor/version through this same selected-image path before Procd allocates it, using the exact binding below. Do not accept public-supplied widths, host layout assumptions, path labels as authority or a second fallback executable route. Preserve partial mapping/grant ownership and exact cleanup after malformed image/layout or lost completion. Authenticate target geometry through the existing selected-image path. Posixd exports one immutable 96-byte target-generated descriptor in read-only file-backed ELF load storage: magic16 `ERIXPXSCAPLAY001`, then ten little-endian u64 words for version1, total size96, ELF machine, pointer bits, and client/descriptor/channel row size/alignment pairs. Sizes are nonzero and alignments powers of two; target fields match the selected executable. Loaderd extracts exactly one complete descriptor from its already authenticated root ELF bytes, refusing missing, duplicate, malformed or writable records. No host-derived type size or reopened pathname supplies geometry. An exact 144-byte BindRealmLayout request uses the existing authenticated LoaderMaterialization route: request/op u32, original active transaction u64, root ELF SHA-25632 and descriptor96. Its response uses the existing 36-byte materialization shape with zero noncommit materialization/staged fields. Procd accepts it only from actual Loaderd for that original active mediator transaction, retains the description through staged commit/rollback, and requires it before mediator commit. The startup carries the descriptor SHA-256, which Posixd compares against its own compiled descriptor before any typed arena borrow. Canonical checked sizing partitions client rows, descriptor rows, channel rows, plan bytes, ring bytes, retained per-client results and immediate packet storage; every multiplication, alignment, address and page round must fit. This grants no additional endpoint or allocation authority. Ordinary endpoint transfer copies authority. Every source and possible receive destination remains owned across submission, collection and native retirement, including ambiguous results. Reserve each prospective receive slot before COLLECT; validate its normalized receipt and actual Generic kind/rights, then independently reconcile its disposal before reuse. Unique InstallGrant and RevocationGrant transfers keep MOVE semantics. Do not infer source deletion from successful copy or use deletion to manufacture successful unique-grant movement. Track this continuation with [Posixd realm lifecycle](https://git.erikinkinen.fi/erix/posixd/issues/1), [POSIX ABI](https://git.erikinkinen.fi/erix/lib-posixabi/issues/1) and [Phase 6 completion](https://git.erikinkinen.fi/erix/integration/issues/65). This is a proposed contract; no runtime or implementation acceptance is claimed. **Counted private startup dependency adoption — 24 September 2026.** These host/build results do not establish actual running mediator readiness or retirement, a complete service-image pass, configuration/seal, client I/O, or either required guest rebuild. Tracking: [owning issue](https://git.erikinkinen.fi/erix/loaderd/issues/1), [WIP PR](https://git.erikinkinen.fi/erix/loaderd/pulls/2) and [Phase 6 acceptance](https://git.erikinkinen.fi/erix/integration/issues/65). <details> <summary>Detailed scope and contracts</summary> ### Runtime consumer dependency alignment — 15 September 2026 The product catalog, product VM acceptance and guest build remain pending. Signed commit [cdf08f8e5f2cf208390099598f86ccfaa7cc96eb](https://git.erikinkinen.fi/erix/loaderd/commit/cdf08f8e5f2cf208390099598f86ccfaa7cc96eb) requires exact GRANT-only final installer receipts and selects the original shared dependency graph. Lifetime now exercises 27 ordinary CPL3 grant-right controls and requires INSTALL_GRANT_RIGHTS_OK before its existing cleanup assertions. These minimal native scenarios establish neither full service-image acceptance nor a guest build. Full coordinated consumer acceptance remains open under [Kernel design 19](https://git.erikinkinen.fi/erix/kernel/issues/19) and [phase completion](https://git.erikinkinen.fi/erix/integration/issues/65). Full service CPU/profiler VM acceptance and guest builds remain open in [Phase 6 completion](https://git.erikinkinen.fi/erix/integration/issues/65). ### Digest-selected exact executable preparation Retire the fixed-path private Loaderd preparation family after migrating Launchd and all native consumers. Add V2 operations 0x718 (ordinary executable), 0x719 (realm mediator) and 0x71A (realm client). Their 104-byte base request retains request/opcode, transaction, install destination, actual executable SEND source/staging, mode, size and original object identity. Replace pathname fields with the nonzero command-entry digest already defined as SHA-256(domain V1 || u64 little-endian raw entry length || exact authenticated entry bytes). Realm clients append the unchanged 24-byte original relation, for 128 bytes total. The 184-byte base response preserves original preparation measurements and appends that command-entry correlation; clients append the relation for 208 bytes. Refusal echoes the original entry and relation while withholding success evidence. Old operations and codecs are removed without a fallback. Launchd derives the digest only from existing Vfsd-authenticated executable evidence, never argv[0], a caller selector or optional display labels. Loaderd compares that digest against entries of the complete runtime graph after authenticating its configured digest. Require exactly one matching executable root, then materialize the actual received executable endpoint with existing exact size, manifest and content measurement checks. The selector digest is data and cannot acquire a filesystem object, bypass runtime-graph integrity, select a service role or start a process. Separate graph-root selection explicitly: authenticated bootstrap/service pathname selection remains on its own native lifecycle; exact executable/realm/client preparation accepts only the digest selector with actual executable SEND custody. Do not copy a graph source path into another fixed buffer, synthesize a pathname or reopen the selected executable. Preserve graph closure/cycle checks, native caller/realm relation, unique install-grant MOVE, uncertain cleanup and original rollback obligations. Both success and refusal must correlate the requested command entry before Launchd accepts returned evidence. This completes Loaderd selection within the ongoing native launch migration. Vfsd executable/sidecar framing, counted authenticated entry evidence, retained program display, provider adapter retirement and coherent runtime adoption remain required. Author literal wire, wrong/zero digest, same-content distinct entries, long names, retired frames, native authority and cleanup controls; keep tests/builds/checks/CI deferred under the current waiver. Publish immutable dependencies bottom-up and update the manual and affected tracking records. Native SEND and entry-digest validation return a borrowed complete raw label; ordinary preparation copies it before transport reuse and admits the sidecar in the remaining exact scratch. Labels create no capability or replacement authority. Seven new controls cover long raw preparation, reused caller scratch, original job ownership, capacity/identity refusal, compaction, stale generations, successor transfer, literal startup geometry and missing/unaddressable budgets. The containing native migration remains open for remaining provider/name adapters, complete cross-provider lifetime/refusal controls and coherent runtime catalog adoption. Existing broad acceptance remains unchanged. Full EriX guest build generations, external Rust/LLVM rebuilding inside EriX and profiler evidence remain required and unperformed. </details> <details> <summary>Related records and contracts</summary> | Repository | Links | | --- | --- | | docs | [issue 1](https://git.erikinkinen.fi/erix/docs/issues/1), [PR 4](https://git.erikinkinen.fi/erix/docs/pulls/4) | | integration | [issue 101](https://git.erikinkinen.fi/erix/integration/issues/101), [issue 2](https://git.erikinkinen.fi/erix/integration/issues/2), [PR 12](https://git.erikinkinen.fi/erix/integration/pulls/12) | | kernel | [issue 20](https://git.erikinkinen.fi/erix/kernel/issues/20) | | launchd | [issue 1](https://git.erikinkinen.fi/erix/launchd/issues/1), [PR 2](https://git.erikinkinen.fi/erix/launchd/pulls/2) | | lib-bootstrap | [issue 1](https://git.erikinkinen.fi/erix/lib-bootstrap/issues/1), [PR 2](https://git.erikinkinen.fi/erix/lib-bootstrap/pulls/2) | | lib-capabi | [issue 3](https://git.erikinkinen.fi/erix/lib-capabi/issues/3) | | lib-ipc | [PR 2](https://git.erikinkinen.fi/erix/lib-ipc/pulls/2) | | loaderd | [issue 3](https://git.erikinkinen.fi/erix/loaderd/issues/3) | | powerboxd | [PR 2](https://git.erikinkinen.fi/erix/powerboxd/pulls/2) | | refspecs.linuxfoundation.org | [progheader.html](https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/progheader.html) | | rootd | [PR 2](https://git.erikinkinen.fi/erix/rootd/pulls/2) | | sourceware.org | [Options.html](https://sourceware.org/binutils/docs/ld/Options.html) | | ttyd | [PR 3](https://git.erikinkinen.fi/erix/ttyd/pulls/3) | </details>
erikinkinen changed title from [FEATURE] [P02.R57] Audit authority, code quality and documentation in loaderd to [FEATURE] Audit authority, code quality and documentation in loaderd 2026-09-12 08:02:34 +02:00
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:35:00 +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/loaderd#1
No description provided.