[FEATURE] Audit authority, code quality and documentation in rootd #1
Labels
No labels
alpha-1
bug
ci
docs
duplicate
enhancement
help wanted
invalid
performance
phase-6
question
refactor
security
wontfix
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
erix/rootd#1
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Problem and motivation
Audit
rootdthroughout Phase 6. Own initial root-task bootstrap, minimal service startup policy and retirement of temporary bootstrap grants.Review each changed boundary at the final published revision. Prioritize security, reliability, then performance.
Proposed behavior and scope
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.
Planned native terminal-generation contract — 17 September 2026: Introduce operation 55 for exact native process/staging-generation/event-kind/status observations. The request has zero flags and arguments; malformed requests fail before dequeue. Successful responses preserve all four 32-bit fields, captured with the actual native terminal transition and retained after destruction. Empty queues return RETRY with zero values. These records constrain existing authority and confer no process-control capability.
Kernel, shared IPC, Procd and Rootd migrate together. Procd must match the native process/generation pair before cleanup, CPU-time observation, restart or service-event publication. Remove the superseded identity-free native selector after all maintained consumers migrate, with no fallback on unsupported kernels. Preserve queue reservation, ordering, wake and failure semantics. Validate actual exit/kill, generation reuse, empty/malformed input and cleanup failure, then strict component checks and original bounded native VMs on a coherent immutable revision graph.
This is the terminal-observation prerequisite for typed mediator bootstrap. The actual returned install grant already has a generation-checked endpoint-attenuation primitive for the first bootstrap effect. Guard custody, final receiver readiness, sealed publication, two mediators with real client I/O and both full guest builds remain separate mandatory work; this planned contract implements none of those by itself.
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
missing_docsenforcement without blanket allowances or hidden-API escapes, warning-denied private-item rustdoc and an undocumented-public-API negative gate.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.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.
Four new real-checker regressions cover early/late forbidden markers, extraction and scan failures, cleanup and extraction reuse; the existing stale-object regression builds actual baseline and product objects. Complete corrected CI is required.
Signed Rootd
c458c155ef5403fbedff625672be79017d0c9afbselects helpercdf15c52f24bd463dcabdddb945f779fff4ab367in its workflow and denies Rust, rustdoc and Python diagnostics. Runtime sources and dependency pins are byte-identical to scanner checkpoint3bf295a05b587970bcd96f307c194c85caff85e0. The repeated default/all development/release Rust matrix and all 62 Python/bootstrap checks pass; the earlier twelve native configurations retain their unchanged inputs. Rootd CI 1023/1024 passes at the corrected head with all four complete classified logs and no warnings; the original shallow dependency preparation now completes, all 62 Python checks run, and the actual artifact/semantic boundary gates pass. The original failed 1021/1022 logs remain retained under Integration issue #51.Typed mediator bootstrap, ordinary service-image adoption and both complete EriX builds inside EriX remain open.
Ordinary service-image adoption remains open.
Audit regression: #4.
Planned exact-generation native cleanup — 17 September 2026: Define distinct native terminal-destruction and
staged-abort operations 56 and 57. A checked request carries the nonzero original
process/generation pair in the low/high 32-bit halves of arg0; flags and all other
arguments are zero. Retire selectors 8 and 35 without reinterpreting them or
adding a compatibility fallback. The existing held Process or Root route remains
required; descriptive identities do not grant authority.
Match the exact pair under the same TCB record lock that enters retained cleanup.
Preserve terminal-versus-Created eligibility, partial disposal and retry custody.
An absent or different generation acknowledges absence of only the requested
instance, with zero response values; it cannot mutate a replacement. Migrate
every native caller and carry creation/event generation through deferred retries.
Account for processes created before a service's own managed ledger without
reconstructing historical identity from the current record. Maintain separate
terminal observation, cleanup custody, provider completion and native absence.
Required evidence includes exact wire and reserved-field controls, actual-object
generation/reuse and failed-release controls, consumer cleanup tests, and bounded
CPL3 native coverage. Update all operation inventories, Rootd's measured audit
contracts, canonical documentation and manual/API references. Validate coherent
original commit dependencies, complete strict component matrices and repository
CI checks, then monitor original workflows. Ordinary mediator start, whole-image
admission and both complete builds inside EriX remain separate open gates.
Original
1025/1026 stays failed; ordinary image and realm execution remain open.
Generation-bound cleanup consumer acceptance — 18 September 2026: Signed revision
fc898a7f4020757b2571647641ca096f66c31b6fis pushed. Bootstrap abort/destruction retains the original generation and requires complete correlated native receipts. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain open.Caller-bound realm admission and retained storage contract — 18 September 2026
Use distinct Launchd operations BEGIN_REALM 0x6D0, PREPARE_REALM 0x6D1,
ABORT_REALM 0x6D2 and READ_REALM 0x6D3. The existing 0x6B0–0x6BF range belongs
to filesystem providers and is not reused. Little-endian bodies are exact, with
nonzero request correlation and no fallback to ordinary launch transactions.
BEGIN_REALM is an authority-free 8-byte request (request ID, operation). Derive
session, authority realm, original process/generation and Running job from the
actual native pending caller. Reserve an independently budgeted realm record,
a nonwrapping generation and one disjoint executable-scope receipt slot before
replying. Client numeric identities or a bearer sender cannot select ownership.
PREPARE_REALM has a 32-byte prefix: request ID and operation (u32), realm record
ID and generation (u64 each), and selector byte length (u64), followed by exactly
that nonempty UTF-8 selector without NUL. Parsing adds no pathname or packet-size
ceiling. The request carries exactly one actual SEND-only directory endpoint to
the reserved receipt slot. Verify the original caller/job/session/authority realm
again and retire every unretained received capability on refusal. Resolve only
inside this explicit directory, authenticate the exact executable and manifest,
and call Loaderd's existing private PREPARE_REALM. Never imply a Posixd pathname,
Named route, root, cwd, TTY stream, ordinary job or public PreparedProcess input.
ABORT_REALM and READ_REALM are authority-free 24-byte requests: request ID,
operation and complete realm-record ID/generation. They require the same original
Running native owner. READ observes retained state only; ABORT must complete
independent source, invocation and exact-child retirement before its successful
acknowledgment. Parent terminality initiates the same retained cleanup internally.
All four operations have an exact 40-byte capability-free response: request ID,
operation, raw result and state (u32 each), record ID and generation (u64 each),
receipt slot and zero reserved word (u32 each). States are Unconfirmed=0,
Reserved=1, Preparing=2, Guarded=3, Retiring=4 and Retired=5. Success at BEGIN
requires Reserved, a nonzero complete handle and receipt slot. PREPARE success
requires Guarded; ABORT success requires Retired. READ returns an authenticated
nonzero state. Only successful BEGIN returns a receipt slot; every other result
has zero there. Failure always has Unconfirmed state; failed BEGIN has a zero
handle while other failures echo the original complete request handle. Unknown
nonzero result codes remain full-width. Unconfirmed proves no resource absence.
Correlate the complete response with the original request before using evidence.
Replace obsolete LCH1 v2 with exact 72-byte version3 startup policy. Preserve the
first 68-byte field order and append realm_capacity (u32 at offset68). Require an
explicit deployment value: zero disables new realm reservations, and nonzero
values allocate that many retained records and disjoint receipt slots. Validate
checked job-route + stream-route + realm-receipt arithmetic before leaving any
ordinary transaction receipt storage. No default or incidental fixed array sets
realm count. Coordinate shared startup codecs, Rootd payloads, Launchd arena and
Integration policy/packaging; old version/width must reject. Extend the native
capacity descriptor with the realm record's size/alignment and a new layout
version; do not assume ordinary reply records survive long enough for realms.
Keep original child, local scope/grant obligations and native invocation owners
independent. Actual scheduler progress must exclude ordinary and indirect blocking
peer calls while any native invocation needs progress. A permanently discharged
source slot is never revisited after reuse. Native release precedes ordinary
exact-child abort; preserve first errors and exhaust independent cleanup without
returning uncertain state to normal operation. Guarded staging remains private
and unstarted, without exported SEND or a Running job. This initial admission
interface does not define configuration, readiness, sealing or publication.
Coordinated host negatives, strict source-bound build matrices and real consumer
VM execution are required. Two mediator processes, two clients per realm with
actual mediated I/O, complete fair progress, source/effect/frame admission and
both full builds inside EriX remain separate open acceptance requirements.
Explicit realm startup consumer checkpoint — 18 September 2026: Signed
3babf21e4531f563559e0eda05378a7e69f8c3c2consumes exact 72-byte LCH1 version 3, preserves explicit zero or positive realm capacity and rejects legacy/truncated payloads without adding to the seven peer routes. Matched image publication and actual consumer VMs remain required; no runnable realm or complete guest build is claimed.Original coherent realm source CI acceptance — 18 September 2026: Signed
3babf21e4531f563559e0eda05378a7e69f8c3c2passes CI 1034 and CI 1033. Coherent catalog publication, actual consumer VMs and full guest-build acceptance remain separate open requirements.Coherent startup consumer acceptance — 18 September 2026: Signed Integration
8b1c037aed2503e1f2a4b17c8a8be0666d62a305adopts exact 72-byte LCH1 version 3, explicit realm capacity and version-6 compiler-derived arena geometry across runtime profiles, wire/configuration boundaries and image packaging. Full source/effect/frame admission, complete realm operation and both full builds inside EriX remain required.Tracking and rollout
Counted-client startup adoption — 25 September 2026: signed Rootd 59a05634 admits exact 88-byte LCH1 V4 client/plan storage while preserving the seven-route envelope and refusing legacy, truncated or unpaired disabled dimensions.
Original CI1045 and CI1046 pass. All four complete logs independently verify 222,958 bytes and zero warning candidates. Native configured-client acceptance, managed-row reuse, profiling and both complete guest-build requirements remain open.
Launchd startup capacity now validates four disjoint capability slots per realm and preserves ordinary intake through checked arithmetic; numeric storage counts add no authority.
Eight strict default, all-feature, runtime and production configurations pass 429 or 430 tests each, plus eight physical-console controls in both profiles. Ten native builds, host/native Clippy, private rustdoc, formatting and all 64 Python tests pass with zero warnings. Production-boundary, baseline, threat, phase, operation-ownership and dependency policies pass. The reviewed Rust 1.97.1 binary baseline changes only from 265,728 to 265,992 bytes: the startup decoder adds 37 instruction bytes plus 11 alignment bytes within existing segment padding, while dependency symbol metadata accounts for the on-disk increase. Exact size checking remains enabled; production source remains 15,293 lines with the same eight authority families and direct syscall inventory. The original size-check failure is retained as evidence of the detected change.
README and ARCHITECTURE describe the checked geometry, and ROADMAP records current validation. CI for this checkpoint awaits observation. Native acceptance of the complete producer graph, complete authority closure and both external-toolchain and EriX rebuilds inside EriX remain open under Phase 6 completion. No earlier CI or VM result is attributed to this revision.
feature/posix-compat; update linked WIP PRs after coherent signed checkpoints using canonical CONTRIBUTING.md messages.ac3c1847af9915164d4a819f5f15e1827884e8b1; refresh component/dependency heads and their own CI evidence as implementation advances.Verified grant-rights checkpoint — 20 September 2026:
Signed commit 87a9f38bfbcf18828a9c03b0c229696aa997d970 requires exact GRANT-only final installer receipts and selects the original shared dependency graph. Four strict 428/429-unit configurations, four native builds with the maintained linker layout, host/native Clippy, formatting and private rustdoc pass without warnings. Original CI 1037/1038 passes from four complete hashed logs (222,588 bytes), with zero warning candidates. Corrective audit commit 0890d3285d1e9efe5d701043f930e172971a0354 updates the independently reviewed bootstrap baseline to 15,247 active production lines and 265,872 linked bytes under Rust 1.97.1. All 64 Python tests and production, baseline, threat, phase and ownership audits pass. Authority inventory, direct syscalls, dependency names and eight unsafe sites are unchanged. Bug 6 retains original 1035/1036 failures.
Both maintained isolated native scenarios pass on their first attempts under the unchanged 60-second scenario limits, with no build warnings and empty QEMU stderr. Lifetime now exercises 27 ordinary CPL3 grant-right controls and requires INSTALL_GRANT_RIGHTS_OK before its existing cleanup assertions. Its 2,025-byte serial stream has SHA256
6c685f1ceaf9080bf0bec628a4fac512bf9049d0fbcfe2b3737666adf414ca3a; owned invocation retains 1,587 bytes. Normal stripping exactly matches both packaged kernels to retained original artifacts. All fifteen selected original source signatures and clean trees verify. 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.
Committed terminal-accounting consumers — 21 September 2026:
Procd 66934642c4464fc738152a9e60790914ba27dd1c in WIP PR 2 reserves notification/crash/cleanup storage before effects, obtains exact final CPU evidence, commits local status and cleanup obligations, then acknowledges on every actual event polling path. Lost acknowledgement replies preserve the local result without duplicate counters or notifications. Mediators retain only scalar counters and the original authenticated supervisor identity after disposing all capability columns; supervisor death discharges the pending scalar observation and a replacement cannot inherit it. Four strict 299/305-test configurations, native builds, Clippy and private rustdoc pass. Original CI 298/299 passes from four complete hashed logs, 347,245 bytes, zero warnings. Bug 5 remains open for actual service acceptance.
Rootd 64c97b13c450003d9c2b6bd9ed2a627088684b46 in WIP PR 2 acknowledges bootstrap evidence only after exact native destruction and local endpoint absence; both operations remain unavailable after temporary Process custody transfers to Procd. Four strict 430/429-test configurations, native builds, Clippy and private rustdoc pass. Original 1039/1040 exposed bug 7: a stale source-call inventory and its matching semantic operation declarations. The correction explicitly inventories acknowledgement consumers and preserves the same temporary route and eventual Procd owner. All 64 Python controls, production-boundary, semantic baseline, threat model, phase contract and operation-ownership gates pass. Corrected original CI 1041/1042 passes from four complete verified logs, 222,969 bytes, zero warnings. Bug 7 is corrected; failed original runs remain retained without reruns or weaker gates.
Docs e4525848ad4462901c9a6794ef1794cf85ea9e6b updates the native contract, Procd/Rootd consumer custody and original signed IPC API references. Selector 55 is retired in both the detailed contract and summary; 58/59/60 are cross-checked against the shared registry. All 45 documentation tests and generated-reference checks pass. The complete 2,431-page manual builds without warnings; changed prose, selector and API pages pass visual review. Original documentation CI 995/996 and corrected-table 997/998 passes from eight complete logs, 1,549,628 bytes, with zero warnings in the final LaTeX passes. The 37 earlier convergence candidates per manual log are retained and resolved.
The separate Integration orchestration library checkpoint b06dfad00202765491a64552dde29eaca1c24838 passes four strict 320/321-test host/native configurations. Full service catalogs remain on their prior coherent graph while 35 remaining application/service repositories adopt the original shared revisions. Integration 1697/1698 remains running, and 1699/1700 plus 1701/1702 waits at the latest bounded observations. These are pending full regressions, not successful runtime acceptance.
No new canonical acceptance leaf is closed: 15/460 and 3.48% weighted. Ordinary Launchd metric-consumer restart/disposal semantics, coherent service CPU/profiler VMs, complete realm/provider authority and I/O, source/effect/frame proof, Pagerd, native external Rust/LLVM/runtime rebuilding and both full EriX-in-EriX build generations remain required. The static audit finds 3,162 authored code files below 1,000 lines, 74 manifests, 259 original Git pins, 173 direct missing-docs gates and 92 conventional crate roots; this does not establish semantic authority or complete private-documentation closure.
Detailed scope and contracts
Original native stream identities — 30 September 2026
Ordinary namespace and executable routes cannot allocate one.
Original event times remain Unknown; this scalar metadata cannot turn an incomplete observation into successful compatibility status.
They cover literal wire rejection, atomic encoding, administrator isolation, lost-delivery allocation, binding refusal, exhaustion, directional lifetime, teardown/reuse, original ownership, malformed observations and receipt cleanup.
The full status/directory feature remains open for original native event-time capture, complete FAT metadata and whole-feature integration. Both full EriX guest build generations and external Rust/LLVM rebuilding inside EriX remain required and unperformed.
Original native stream event times — 30 September 2026
Alias creation, metadata queries, empty or refused operations and terminal device progress do not query a historical clock.
Ttyd receives an exact authenticated SEND-only Timed endpoint for this source purpose; Launchd uses its already admitted endpoint. Clean refusal remains Unknown.
The seeded boundary control retains the whole original object and proves the intended no-clock refusal contract when executed; no runtime reproduction or practical path to 2^64 bytes is claimed.
They cover source-event independence, unknown evidence, full-range dates, malformed replies, receipt cleanup, exact SEND-only admission, alias/retirement/reuse and overflow refusal. The existing realm workload now requires successful inherited fstat and original PTY clock evidence with stable birth before and after realm retirement; its independent transcript remains 385 calls.
The full status/directory feature remains open for complete FAT metadata and whole-feature integration. Both full EriX guest build generations and external Rust/LLVM rebuilding inside EriX remain required and unperformed.
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
[FEATURE] [P02.R67] Audit authority, code quality and documentation in rootdto [FEATURE] Audit authority, code quality and documentation in rootderikinkinen referenced this issue2026-09-12 14:20:30 +02:00
erikinkinen referenced this issue2026-10-30 17:08:22 +01:00
erikinkinen referenced this issue2026-10-30 17:09:10 +01:00