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

New issue

Open

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

erikinkinen commented

2026-09-12 07:57:46 +02:00

Owner

Problem and motivation

This issue tracks continuous Phase 6 audit closure for lib-dynlink. Parse supported native dynamic metadata and produce deterministic dependency, symbol and relocation plans without process-memory mutation.

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.

Symbol-only relocation correction — 16 September 2026: signed lib-dynlink abd5153adf994ca40753f9650a675940a228e1d3 calculates GLOB_DAT and eager JUMP_SLOT as S, while retaining checked S+A and B+A, original provider selection and writable target ownership. The canonical defect report is #2 and review is #3. Four default/all-feature dev/release configurations pass 47 tests each, host/native strict Clippy, private rustdoc and four native builds without warnings. Of nine new independent controls, five fail and four pass against the original implementation; all nine pass after correction.

Original dynlinkd, loaderd and bootloader source candidates, each changing only the library's full commit selector in an isolated exact-commit worktree, pass four strict configurations: 13/105/41 tests respectively, with twelve native builds and private rustdoc, zero warnings. Published consumer commits remain unchanged pending coherent adoption.

The retained Exsh executable and six explicit libraries yield 1,608 independently expected relocation writes under caller-selected hypothetical load biases. Both original and corrected planners match those original zero-addend inputs. All 107 symbol-only writes remain identical under positive, negative and extreme unused-addend variants with the fix; the original planner fails the addend-16 control (actual Cargo exit 101). The original/packaged dynamic tables are byte-identical and all artifact/manifest hashes are retained. This host metadata replay performs no target mapping or execution and does not admit native frame paths.

Signed Docs 214b08666b8b36ad4270bcfee3b3379d8dc08a79 documents the expressions and regenerates only the library's 103-route API reference from exact signed-source rustdoc JSON. All 45 documentation tests, Markdown and canonical checks pass. The full manual has 2,383 pages, 436,424 in-bounds word boxes, zero final warnings and four visually reviewed changed pages. All 3,696 inventoried code/configuration files remain below 1,000 lines; complete semantic authority and private documentation closure remains open.

Matching library CI 30/31 passes with four complete logs (36,856 bytes), 47 tests per run, strict builds/rustdoc and zero warnings. Docs CI 913/914 passes with four complete logs (763,872 bytes), 45 tests and 2,383-page renders, zero final warnings. Coherent catalog adoption, complete native source/frame evidence, runnable realms and both full guest build generations remain open.

Tracking and rollout

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: fac981fa2e5aa6b0eb8e526fcd3acbd2785d251d; 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.

## Problem and motivation This issue tracks continuous Phase 6 audit closure for `lib-dynlink`. Parse supported native dynamic metadata and produce deterministic dependency, symbol and relocation plans without process-memory mutation. 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. Symbol-only relocation correction — 16 September 2026: signed lib-dynlink `abd5153adf994ca40753f9650a675940a228e1d3` calculates GLOB_DAT and eager JUMP_SLOT as S, while retaining checked S+A and B+A, original provider selection and writable target ownership. The canonical defect report is https://git.erikinkinen.fi/erix/lib-dynlink/issues/2 and review is https://git.erikinkinen.fi/erix/lib-dynlink/pulls/3. Four default/all-feature dev/release configurations pass 47 tests each, host/native strict Clippy, private rustdoc and four native builds without warnings. Of nine new independent controls, five fail and four pass against the original implementation; all nine pass after correction. Original dynlinkd, loaderd and bootloader source candidates, each changing only the library's full commit selector in an isolated exact-commit worktree, pass four strict configurations: 13/105/41 tests respectively, with twelve native builds and private rustdoc, zero warnings. Published consumer commits remain unchanged pending coherent adoption. The retained Exsh executable and six explicit libraries yield 1,608 independently expected relocation writes under caller-selected hypothetical load biases. Both original and corrected planners match those original zero-addend inputs. All 107 symbol-only writes remain identical under positive, negative and extreme unused-addend variants with the fix; the original planner fails the addend-16 control (actual Cargo exit 101). The original/packaged dynamic tables are byte-identical and all artifact/manifest hashes are retained. This host metadata replay performs no target mapping or execution and does not admit native frame paths. Signed Docs `214b08666b8b36ad4270bcfee3b3379d8dc08a79` documents the expressions and regenerates only the library's 103-route API reference from exact signed-source rustdoc JSON. All 45 documentation tests, Markdown and canonical checks pass. The full manual has 2,383 pages, 436,424 in-bounds word boxes, zero final warnings and four visually reviewed changed pages. All 3,696 inventoried code/configuration files remain below 1,000 lines; complete semantic authority and private documentation closure remains open. Matching library CI [30](https://git.erikinkinen.fi/erix/lib-dynlink/actions/runs/30)/[31](https://git.erikinkinen.fi/erix/lib-dynlink/actions/runs/31) passes with four complete logs (36,856 bytes), 47 tests per run, strict builds/rustdoc and zero warnings. Docs CI [913](https://git.erikinkinen.fi/erix/docs/actions/runs/913)/[914](https://git.erikinkinen.fi/erix/docs/actions/runs/914) passes with four complete logs (763,872 bytes), 45 tests and 2,383-page renders, zero final warnings. Coherent catalog adoption, complete native source/frame evidence, runnable realms and both full guest build generations remain open. ## Tracking and rollout - 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: `fac981fa2e5aa6b0eb8e526fcd3acbd2785d251d`; 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.

erikinkinen added the

labels

2026-09-12 07:57:46 +02:00

erikinkinen referenced this issue from erix/integration

2026-09-12 08:02:00 +02:00

[FEATURE] Audit and refactor authority, lifecycle and code quality across every repository #2

erikinkinen changed title from ~~[FEATURE] [P02.R40] Audit authority, code quality and documentation in lib-dynlink~~ to [FEATURE] Audit authority, code quality and documentation in lib-dynlink

2026-09-12 08:02:27 +02:00

erikinkinen referenced this issue

2026-09-16 06:34:09 +02:00

[BUG] Symbol-only relocations incorrectly apply the RELA addend #2

erikinkinen referenced this issue

2026-09-16 06:52:27 +02:00

WIP: Correct symbol-only relocation values #3

erikinkinen referenced this issue from erix/integration

2026-09-19 11:36:52 +02:00

[FEATURE] Track Phase 6 POSIX compatibility and full EriX self-hosting #65