[FEATURE] Audit authority, code quality and documentation in lib-posixabi #2

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

Problem and motivation

Audit lib-posixabi throughout Phase 6. Implement the planned POSIX wire and C ABI contracts, keeping compatibility identifiers and credentials separate from native grants.

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

Proposed behavior and scope

Current targets: none; scaffolded from meta. Add every future library, executable, build script, example and test target to this audit before implementation acceptance.

The repository currently contains the verified meta template and no Rust implementation. Audit the scaffold now, then every implemented compatibility boundary; absence of a current target does not close future implementation rows.

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.

Tracking and rollout

PR2 remains unfinished for its broader scope; full ABI, native client-lifecycle execution and both guest rebuilds remain required.

  • 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: 74ea167d14a7ad05bb436d47e9692122f640f5ee; 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.

No local API or capability policy changes. Actual service consumer and coherent full VM adoption remain open in phase completion.

Unused fields are canonical zero; names and symbolic targets carry no native authority.

Only the admitted prefix is staged; actual counted storage exhaustion refuses without silently shortening success. Final target bytes are never traversed, no content grant or fd is acquired, and all original callers, parents, links and expansion owners retire before delivery.

Complete mutation permission/effect mediation, two-path rename/link, legacy cwd migration and ext/FAT conditional transactions remain unfinished. Raw readlink is split from the previous combined two-path criterion to record one fully implemented operation boundary; the full namespace parent remains open. The existing native binding workload now requires seven raw-target observations/refusals per peer, including readlinkat and the read-only scope, without new authority or fixture budgets.

Both complete EriX guest generations and external Rust/LLVM rebuilding remain required and unperformed.

Original-entry namespace mutation mediation — 1 October 2026

Hardlink source requires parent search; changed directories require write/search.

Ordinary final-link/trailing-directory probes cannot substitute for entry evidence. Cleanup cannot undo a completed mutation.

The independent filesystem model keeps real initial directory entries, so a removed name cannot reappear from a fixture fallback.

They cover independent dirfds, link following, same-object rename, complete ACL/sticky policy, exact refusals, original detached content, cancellation and uncertain completion. The read-only peer requires all five mutation families to refuse.

The exact wire/migration, actual permission/effect mediation and two-path semantic criteria are source-accepted. The full namespace parent stays open: legacy cwd migration, required ext/FAT conditional transactions and cross-provider lifetime remain unfinished. Both complete EriX guest generations and external Rust/LLVM guest rebuilding remain required and unperformed.

Related records and contracts
Repository Links
docs PR 4
integration PR 12
kernel issue 20
lib-posixabi issue 5, issue 6, PR 3, namespace.md
posixd PR 5, namespace-mutations.md
rootd PR 2
## Problem and motivation Audit `lib-posixabi` throughout Phase 6. Implement the planned POSIX wire and C ABI contracts, keeping compatibility identifiers and credentials separate from native grants. Review each changed boundary at the final published revision. Prioritize security, reliability, then performance. ## Proposed behavior and scope Current targets: none; scaffolded from meta. Add every future library, executable, build script, example and test target to this audit before implementation acceptance. The repository currently contains the verified meta template and no Rust implementation. Audit the scaffold now, then every implemented compatibility boundary; absence of a current target does not close future implementation rows. ## 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. ## Tracking and rollout [PR2](https://git.erikinkinen.fi/erix/lib-posixabi/pulls/2) remains unfinished for its broader scope; full ABI, native client-lifecycle execution and both guest rebuilds remain required. - 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: `74ea167d14a7ad05bb436d47e9692122f640f5ee`; 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. No local API or capability policy changes. Actual service consumer and coherent full VM adoption remain open in [phase completion](https://git.erikinkinen.fi/erix/integration/issues/65). ### Counted namespace intents and original raw readlink — 1 October 2026 Unused fields are canonical zero; names and symbolic targets carry no native authority. Only the admitted prefix is staged; actual counted storage exhaustion refuses without silently shortening success. Final target bytes are never traversed, no content grant or fd is acquired, and all original callers, parents, links and expansion owners retire before delivery. Complete mutation permission/effect mediation, two-path rename/link, legacy cwd migration and ext/FAT conditional transactions remain unfinished. Raw readlink is split from the previous combined two-path criterion to record one fully implemented operation boundary; the full namespace parent remains open. The existing native binding workload now requires seven raw-target observations/refusals per peer, including readlinkat and the read-only scope, without new authority or fixture budgets. Both complete EriX guest generations and external Rust/LLVM rebuilding remain required and unperformed. ### Original-entry namespace mutation mediation — 1 October 2026 Hardlink source requires parent search; changed directories require write/search. Ordinary final-link/trailing-directory probes cannot substitute for entry evidence. Cleanup cannot undo a completed mutation. The independent filesystem model keeps real initial directory entries, so a removed name cannot reappear from a fixture fallback. They cover independent dirfds, link following, same-object rename, complete ACL/sticky policy, exact refusals, original detached content, cancellation and uncertain completion. The read-only peer requires all five mutation families to refuse. The exact wire/migration, actual permission/effect mediation and two-path semantic criteria are source-accepted. The full namespace parent stays open: legacy cwd migration, required ext/FAT conditional transactions and cross-provider lifetime remain unfinished. Both complete EriX guest generations and external Rust/LLVM guest rebuilding remain required and unperformed. <details> <summary>Related records and contracts</summary> | Repository | Links | | --- | --- | | docs | [PR 4](https://git.erikinkinen.fi/erix/docs/pulls/4) | | integration | [PR 12](https://git.erikinkinen.fi/erix/integration/pulls/12) | | kernel | [issue 20](https://git.erikinkinen.fi/erix/kernel/issues/20) | | lib-posixabi | [issue 5](https://git.erikinkinen.fi/erix/lib-posixabi/issues/5), [issue 6](https://git.erikinkinen.fi/erix/lib-posixabi/issues/6), [PR 3](https://git.erikinkinen.fi/erix/lib-posixabi/pulls/3), [namespace.md](https://git.erikinkinen.fi/erix/lib-posixabi/src/branch/feature/posix-compat/docs/namespace.md) | | posixd | [PR 5](https://git.erikinkinen.fi/erix/posixd/pulls/5), [namespace-mutations.md](https://git.erikinkinen.fi/erix/posixd/src/branch/feature/posix-compat/docs/namespace-mutations.md) | | rootd | [PR 2](https://git.erikinkinen.fi/erix/rootd/pulls/2) | </details>
erikinkinen changed title from [FEATURE] [P02.R74] Audit authority, code quality and documentation in lib-posixabi to [FEATURE] Audit authority, code quality and documentation in lib-posixabi 2026-09-12 08:02:42 +02:00
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:50 +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/lib-posixabi#2
No description provided.