[FEATURE] Audit authority, code quality and documentation in lib-block #1

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

Problem and motivation

This issue tracks continuous Phase 6 audit closure for lib-block. Define block I/O data contracts, geometry and validation helpers without acquiring device authority.

An initial inventory is not a security or documentation closure claim. Evidence must follow each changed boundary through final heads, with priority security, reliability, then performance.

Proposed behavior and scope

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

Trace authority-bearing values across callers and public APIs; prove that the library does not acquire hidden service, hardware or host authority. Treat startup/teardown and rootd parity dimensions as caller/consumer contracts where this crate owns no process, with a separate evidence-backed applicability decision per row.

Authority, security and reliability

Maintain a finding register with public finding references, exact revisions, invariants, reproduction, owners, regression tests and closure evidence. Publish only non-sensitive status here; suspected vulnerabilities follow SECURITY.md. Each dimension below needs its own result and rationale; an absent daemon or current Rust target is not a blanket exemption.

Acceptance criteria

  • 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

Use cohesive local refactoring or a justified shared extraction only after identifying real common semantics and authority boundaries. Remove superseded paths after preserving maintained coverage. Profile before optimization; document unavoidable ABI/hardware limits and explicit quotas rather than weakening security for speed.

Native terminal generation checkpoint — 17 September 2026: Signed revision 12259cc6a9eafd479248d45d8000bcaa0367d2a7 is pushed. The coherent immutable dependency graph now selects the generation-bearing operation 55 contract. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, freestanding builds, rustdoc, formatting and Markdown checks pass. Native producer/consumer migration, matching VM execution and full guest builds remain separate acceptance gates. Original automatic CI is being collected without retries.

Generation-bound native cleanup checkpoint — 18 September 2026: Signed revision 4e3c2504151ec265eb3db6362231fe22ba088092 is pushed. The coherent immutable dependency graph adopts the checked generation-bound cleanup ABI. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and rustdoc pass. Formatting and Markdown checks pass. Original CI 31 and CI 32 passes; all four terminal logs are complete (43,876 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.

Returned-grant shared contract checkpoint — 18 September 2026: Signed revision edace7b98081afa46e087391d5ce8f52fce4bf3f is pushed. The coherent immutable dependency graph adopts the checked returned-grant bootstrap contract. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original CI 33 and CI 34 passes; all four terminal logs are complete (43,874 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.

Caller-local grant relocation checkpoint — 18 September 2026: Signed revision 6503c3a959656f1755f517810a24ebab41e81fde is pushed. The coherent immutable dependency graph adopts the caller-local grant relocation ABI. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original CI 35 and CI 36 passes; all four terminal logs are complete (43,850 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.

Explicit receiver admission checkpoint — 18 September 2026: Signed revision c0894b261041d50aecaa750b81077e42d7001f72 is pushed. The coherent immutable dependency graph adopts explicit owned receiver request budgets. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original CI 37 and CI 38 passes; all four terminal logs are complete (43,822 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.

Owned bootstrap wire checkpoint — 18 September 2026: Signed revision cd9feadb72fffe6261c9fc61c7036031e4204fb0 is pushed. The coherent immutable dependency graph adopts the identity-only owned bootstrap request. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original CI 39 and CI 40 passes; all four terminal logs are complete (43,832 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.

Original supervisor wire checkpoint — 18 September 2026: Signed revision 81898aa46d8b1d4e25131607a7515831858066c3 is pushed. The coherent immutable dependency graph adopts the supervisor-aware materialization request. Local runtime policy is unchanged. Default/all development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original CI 41 and CI 42 passes; all four terminal logs are complete (43,852 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.

Caller-bound realm storage wire checkpoint — 18 September 2026: Signed revision 7433d8eba7b071da64519b16df813e8af6638bfd is pushed. The coherent immutable graph adopts caller-bound realm messages and, where used, explicit version-3 deployment storage. Local authority and runtime policy are unchanged. Default/all development and release tests, strict host/native Clippy, freestanding builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original CI 43 and CI 44 passes; all four terminal logs are complete (43,830 bytes), without warnings. Actual admission dispatch, coordinated consumer VMs, runnable mediators and both full builds inside EriX remain separate open acceptance requirements.

Tracking and rollout

Coordinated library dependency update — 15 September 2026

Signed d81abd049c566b1b9c9aaf732a7868861ff2db45 aligns existing dependency pins with the original foundation commits for coherent runtime adoption. This update changes Cargo selections and the roadmap; Rust implementation files in this repository are unchanged. All default/all-feature development/release configurations pass 22 tests each, strict host/native Clippy, formatting, four native builds and private rustdoc without warnings. Final canonical documentation checks pass. Push/review CI 27/28 passes with complete classified logs and no final warnings. The product catalog remains unchanged; this update does not establish a new runtime VM, authority-lifecycle closure, performance result or guest build. Review: #2.

  • Parent work: erix/integration#2 and erix/docs#1.
  • Branch: feature/posix-compat; update linked WIP PRs after coherent signed checkpoints using canonical CONTRIBUTING.md messages.
  • Baseline revision: 23e89b88ca25f7ea1b5a4972829812eb64e5b286; refresh component/dependency heads and their own CI evidence as implementation advances.
  • Cross-repository dependencies remain full lowercase commit hashes; update the selected graph deliberately. This issue does not authorize merges, release tags or replacement of published images.

Explicit install-grant library checkpoint — 19 September 2026: signed/pushed commit de5a6567fb8250e3ac9040fb23462e14b3ec3790. Original dependency pins now select the shared explicit grant-rights contract without mixed wire/capability revisions. The local API and authority policy are unchanged. Four host test matrices pass 22 tests each, alongside four native builds, strict host/native Clippy, formatting, private rustdoc and policy checks. Validation has no warnings. Original CI 45/46 passes with four complete hashed logs (43,822 bytes), zero warnings.

Coordinated actual consumers and matching native execution remain open under Kernel design 19. This dependency/wire checkpoint does not establish complete lifecycle acceptance or either full EriX build generation. Phase completion retains native external Rust/LLVM/runtime rebuilding as an independent requirement.

Acknowledged terminal consumer dependencies — 21 September 2026: signed commit 40fcbe0d568c54288b44c0c30034406279533168 aligns original shared revisions for repeatable terminal observation and exact acknowledgement under Kernel design 20. No local API or capability policy changes. Four strict 22-unit host configurations, four native builds, host/native Clippy, private rustdoc, formatting and dependency checks pass without warnings. Original CI 47, 48 passes; four complete logs total 43,852 bytes with verified hashes and zero warning candidates. Actual service consumer and coherent full VM adoption remain open in phase completion.

## Problem and motivation This issue tracks continuous Phase 6 audit closure for `lib-block`. Define block I/O data contracts, geometry and validation helpers without acquiring device authority. An initial inventory is not a security or documentation closure claim. Evidence must follow each changed boundary through final heads, with priority security, reliability, then performance. ## Proposed behavior and scope Current inventory: 1 Cargo target (1 lib); manifests: `Cargo.toml`. Include explicit and automatically discovered targets, supported features and target-specific configurations. Trace authority-bearing values across callers and public APIs; prove that the library does not acquire hidden service, hardware or host authority. Treat startup/teardown and rootd parity dimensions as caller/consumer contracts where this crate owns no process, with a separate evidence-backed applicability decision per row. ## Authority, security and reliability Maintain a finding register with public finding references, exact revisions, invariants, reproduction, owners, regression tests and closure evidence. Publish only non-sensitive status here; suspected vulnerabilities follow SECURITY.md. Each dimension below needs its own result and rationale; an absent daemon or current Rust target is not a blanket exemption. ## Acceptance criteria - [ ] 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. ## Alternatives and tradeoffs Use cohesive local refactoring or a justified shared extraction only after identifying real common semantics and authority boundaries. Remove superseded paths after preserving maintained coverage. Profile before optimization; document unavoidable ABI/hardware limits and explicit quotas rather than weakening security for speed. Native terminal generation checkpoint — 17 September 2026: Signed revision `12259cc6a9eafd479248d45d8000bcaa0367d2a7` is pushed. The coherent immutable dependency graph now selects the generation-bearing operation 55 contract. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, freestanding builds, rustdoc, formatting and Markdown checks pass. Native producer/consumer migration, matching VM execution and full guest builds remain separate acceptance gates. Original automatic CI is being collected without retries. Generation-bound native cleanup checkpoint — 18 September 2026: Signed revision `4e3c2504151ec265eb3db6362231fe22ba088092` is pushed. The coherent immutable dependency graph adopts the checked generation-bound cleanup ABI. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and rustdoc pass. Formatting and Markdown checks pass. Original [CI 31](https://git.erikinkinen.fi/erix/lib-block/actions/runs/31) and [CI 32](https://git.erikinkinen.fi/erix/lib-block/actions/runs/32) passes; all four terminal logs are complete (43,876 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements. Returned-grant shared contract checkpoint — 18 September 2026: Signed revision `edace7b98081afa46e087391d5ce8f52fce4bf3f` is pushed. The coherent immutable dependency graph adopts the checked returned-grant bootstrap contract. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original [CI 33](https://git.erikinkinen.fi/erix/lib-block/actions/runs/33) and [CI 34](https://git.erikinkinen.fi/erix/lib-block/actions/runs/34) passes; all four terminal logs are complete (43,874 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements. Caller-local grant relocation checkpoint — 18 September 2026: Signed revision `6503c3a959656f1755f517810a24ebab41e81fde` is pushed. The coherent immutable dependency graph adopts the caller-local grant relocation ABI. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original [CI 35](https://git.erikinkinen.fi/erix/lib-block/actions/runs/35) and [CI 36](https://git.erikinkinen.fi/erix/lib-block/actions/runs/36) passes; all four terminal logs are complete (43,850 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements. Explicit receiver admission checkpoint — 18 September 2026: Signed revision `c0894b261041d50aecaa750b81077e42d7001f72` is pushed. The coherent immutable dependency graph adopts explicit owned receiver request budgets. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original [CI 37](https://git.erikinkinen.fi/erix/lib-block/actions/runs/37) and [CI 38](https://git.erikinkinen.fi/erix/lib-block/actions/runs/38) passes; all four terminal logs are complete (43,822 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements. Owned bootstrap wire checkpoint — 18 September 2026: Signed revision `cd9feadb72fffe6261c9fc61c7036031e4204fb0` is pushed. The coherent immutable dependency graph adopts the identity-only owned bootstrap request. Local runtime policy is unchanged. Default/all-feature development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original [CI 39](https://git.erikinkinen.fi/erix/lib-block/actions/runs/39) and [CI 40](https://git.erikinkinen.fi/erix/lib-block/actions/runs/40) passes; all four terminal logs are complete (43,832 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements. Original supervisor wire checkpoint — 18 September 2026: Signed revision `81898aa46d8b1d4e25131607a7515831858066c3` is pushed. The coherent immutable dependency graph adopts the supervisor-aware materialization request. Local runtime policy is unchanged. Default/all development and release units, strict host/native Clippy, native builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original [CI 41](https://git.erikinkinen.fi/erix/lib-block/actions/runs/41) and [CI 42](https://git.erikinkinen.fi/erix/lib-block/actions/runs/42) passes; all four terminal logs are complete (43,852 bytes), without warnings. Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements. Caller-bound realm storage wire checkpoint — 18 September 2026: Signed revision `7433d8eba7b071da64519b16df813e8af6638bfd` is pushed. The coherent immutable graph adopts caller-bound realm messages and, where used, explicit version-3 deployment storage. Local authority and runtime policy are unchanged. Default/all development and release tests, strict host/native Clippy, freestanding builds and private-item rustdoc pass. Formatting and Markdown checks pass. Original [CI 43](https://git.erikinkinen.fi/erix/lib-block/actions/runs/43) and [CI 44](https://git.erikinkinen.fi/erix/lib-block/actions/runs/44) passes; all four terminal logs are complete (43,830 bytes), without warnings. Actual admission dispatch, coordinated consumer VMs, runnable mediators and both full builds inside EriX remain separate open acceptance requirements. ## Tracking and rollout ### Coordinated library dependency update — 15 September 2026 Signed `d81abd049c566b1b9c9aaf732a7868861ff2db45` aligns existing dependency pins with the original foundation commits for coherent runtime adoption. This update changes Cargo selections and the roadmap; Rust implementation files in this repository are unchanged. All default/all-feature development/release configurations pass 22 tests each, strict host/native Clippy, formatting, four native builds and private rustdoc without warnings. Final canonical documentation checks pass. Push/review CI 27/28 passes with complete classified logs and no final warnings. The product catalog remains unchanged; this update does not establish a new runtime VM, authority-lifecycle closure, performance result or guest build. Review: https://git.erikinkinen.fi/erix/lib-block/pulls/2. - Parent work: https://git.erikinkinen.fi/erix/integration/issues/2 and https://git.erikinkinen.fi/erix/docs/issues/1. - Branch: `feature/posix-compat`; update linked WIP PRs after coherent signed checkpoints using canonical CONTRIBUTING.md messages. - Baseline revision: `23e89b88ca25f7ea1b5a4972829812eb64e5b286`; refresh component/dependency heads and their own CI evidence as implementation advances. - Cross-repository dependencies remain full lowercase commit hashes; update the selected graph deliberately. This issue does not authorize merges, release tags or replacement of published images. Explicit install-grant library checkpoint — 19 September 2026: signed/pushed commit [de5a6567fb8250e3ac9040fb23462e14b3ec3790](https://git.erikinkinen.fi/erix/lib-block/commit/de5a6567fb8250e3ac9040fb23462e14b3ec3790). Original dependency pins now select the shared explicit grant-rights contract without mixed wire/capability revisions. The local API and authority policy are unchanged. Four host test matrices pass 22 tests each, alongside four native builds, strict host/native Clippy, formatting, private rustdoc and policy checks. Validation has no warnings. Original CI 45/46 passes with four complete hashed logs (43,822 bytes), zero warnings. Coordinated actual consumers and matching native execution remain open under [Kernel design 19](https://git.erikinkinen.fi/erix/kernel/issues/19). This dependency/wire checkpoint does not establish complete lifecycle acceptance or either full EriX build generation. [Phase completion](https://git.erikinkinen.fi/erix/integration/issues/65) retains native external Rust/LLVM/runtime rebuilding as an independent requirement. Acknowledged terminal consumer dependencies — 21 September 2026: signed commit [40fcbe0d568c54288b44c0c30034406279533168](https://git.erikinkinen.fi/erix/lib-block/commit/40fcbe0d568c54288b44c0c30034406279533168) aligns original shared revisions for repeatable terminal observation and exact acknowledgement under [Kernel design 20](https://git.erikinkinen.fi/erix/kernel/issues/20). No local API or capability policy changes. Four strict 22-unit host configurations, four native builds, host/native Clippy, private rustdoc, formatting and dependency checks pass without warnings. Original CI [47](https://git.erikinkinen.fi/erix/lib-block/actions/runs/47), [48](https://git.erikinkinen.fi/erix/lib-block/actions/runs/48) passes; four complete logs total 43,852 bytes with verified hashes and zero warning candidates. Actual service consumer and coherent full VM adoption remain open in [phase completion](https://git.erikinkinen.fi/erix/integration/issues/65).
erikinkinen changed title from [FEATURE] [P02.R29] Audit authority, code quality and documentation in lib-block to [FEATURE] Audit authority, code quality and documentation in lib-block 2026-09-12 08:02:22 +02:00
Sign in to join this conversation.
No description provided.