[FEATURE] Audit authority, code quality and documentation in lib-block #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/lib-block#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
lib-blockthroughout Phase 6. Define block I/O data contracts, geometry and validation helpers without acquiring device authority.Review each changed boundary at the final published revision. Prioritize 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 inputs through callers and public APIs. Confirm that the library acquires no service, hardware or host authority implicitly. Review startup, teardown and Rootd parity at the caller boundary when this crate owns no process, and justify each applicability decision.
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.
Native producer/consumer migration, matching VM execution and full guest builds remain separate acceptance gates.
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
edace7b98081afa46e087391d5ce8f52fce4bf3fis 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.Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.
Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.
Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.
Runnable mediator bootstrap, fair retirement and both complete builds inside EriX remain separate open acceptance requirements.
Actual admission dispatch, coordinated consumer VMs, runnable mediators and both full builds inside EriX remain separate open acceptance requirements.
Tracking and rollout
No unchanged job was rerun; coordinated runtime acceptance remains separate.
Coordinated native consumer acceptance remains separate in PR2.
Each of the four default/all-feature development/release selections passes 22 tests/doctests. Formatting, strict host/native Clippy, warning-denied builds, private rustdoc, Markdown and exact original dependency checks pass with zero warnings.
Actual running mediator readiness/retirement, complete service-image acceptance, configuration/seal, client I/O and both required guest rebuilds remain open.
Tracking: owning issue, WIP PR and Phase 6 acceptance.
Detailed scope and contracts
Coordinated library dependency update — 15 September 2026
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.
No local API or capability policy changes. Actual service consumer and coherent full VM adoption remain open in phase completion.
Explicit original-device durability barriers — 30 September 2026
LibBlock defines exact receipt-free 16/24-byte flush framing (
0x704), full request/device correlation, atomic encoding, a descriptive support flag and a refusal default. Its client uses only supplied transport and never replays an accepted request. Blockd forwards one admitted whole-disk or partition barrier to its original provider, preserving read-only/unsupported refusal and existing provider-binding retirement. No new capability or data-access route is added.Unknown guarantees refuse.
They cover independent wire evidence, atomic refusal, miscorrelation, no replay, original partition selection, negotiated-feature proof, witness order and failed persistence. Two native VM scenarios exercise the original mounted FAT partition: writable media rewrites original boot bytes, completes the barrier and compares a fresh read; read-only media must refuse without data I/O.
The full status/directory feature remains open for complete FAT metadata and integration; the wider durability item remains open for filesystem recovery, truncate/sparse growth and compatibility fsync/fdatasync. Both full EriX guest build generations and external Rust/LLVM rebuilding inside EriX remain required and unperformed.
Persistent FAT metadata recovery design — 30 September 2026
Complete original FAT metadata needs one durable update boundary joining original media changes and its retained identity/owner/mode/time records. The completed device barrier is a prerequisite, not a transaction implementation. Introduce a reusable, allocation-free original-device undo journal in LibBlock, followed by explicit FAT metadata-format and mount integration in the same full status/directory work.
The caller supplies the original device, an allowed target prefix and a disjoint journal extent. The library neither discovers an extent nor reads policy from an ambient path. On-media selectors cannot choose another device or escape those regions. The original device metadata must agree with logical block size and bounds; writable transaction/recovery requires explicit flush support and refuses read-only media. Caller-owned two-block scratch supplies all working storage; journal capacity derives from the selected actual extent rather than a compiled record count.
Use a checksummed versioned header and two-block undo records: a descriptor binding transaction sequence, record index, original target LBA and before-image CRC, followed by the original complete block. Header and descriptor checksums cover the full block with canonical zero padding. CRC detects corruption, not authentication. No atomic-sector-write assumption or fallback to a plausible older header is allowed. Corrupt or torn headers/records refuse recovery instead of silently initializing storage or publishing metadata.
Before each target write, persist the complete before-images, then the header's counted prefix, with a durability barrier before the first target effect. Repeated writes to one target have separate records and recover in reverse order, avoiding a quadratic duplicate search. Commit persists target changes before clearing and persisting the active header. Semantic refusal can restore a fully known journal. Any storage/transport uncertainty poisons the current adapter; it cannot resume ordinary I/O or retry through another source. Dropping an active owner does no hidden I/O: the original active header remains for explicit recovery by a later owner.
Recovery validates the entire original counted journal before its first target write, checks every original geometry/sequence/index/checksum and restores in reverse order. A crash during restoration leaves the active journal available for another idempotent recovery. Clear it only after restored targets are durable. Malformed late records must cause zero restore writes. Distinguish successful recovery, clean semantic refusal, capacity exhaustion and uncertainty; a caller cannot swallow a failed block operation and then obtain a successful commit.
The subsequent FAT metadata format will explicitly reserve this extent within its original mounted block authority, outside normal file-data access. Its records retain allocated object serials and authenticated administrative ownership/mode, independent event times and exact original-media binding. Mount/status clocks must not replace missing history. Complete permission/status integration, rename/reuse consistency, native VM fixtures and recovery remain part of the same feature; the journal core alone does not complete FAT metadata or compatibility fsync.
Author independent literal format, hostile extent, wrong-device, late-corruption, repeated-write, capacity, semantic-abort, swallowed-error and interrupted-storage controls. Tests/builds/lints/generated docs/VM/profiler/CI execution remain deferred. Keep original authority and error precedence, document all new APIs, retain strict missing_docs and files below 1000 lines, and publish coherent signed revisions. No power-loss or runtime pass is claimed from authored controls.
Explicit original-device undo journal — 30 September 2026
Corrupt or torn evidence refuses without automatic formatting or older-header fallback.
Swallowed block failures cannot commit. Uncertain storage poisons the owner and prevents further I/O; a later owner must reopen the original journal for explicit recovery. Device selectors and log records cannot discover another route or escape the original extents. Filesystem callers must separately restore or retire their volatile state and serialize other writers.
16 new tests are authored and unrun, with independently encoded media and checksums, separate volatile/stable device images, failure before/after every transaction and recovery call, hostile extents, wrong record bindings, late corruption, repeated writes, capacity/sequence refusal, swallowed errors and callback/backend unwinding.
The full status/directory feature remains open for mounted FAT metadata format, source identity/ownership/mode/event records, permissions/status, mutation/rename/reuse consistency and native integration. Both full EriX guest-build generations and external Rust/LLVM rebuilding inside EriX remain required and unperformed.
Related records and contracts
[FEATURE] [P02.R29] Audit authority, code quality and documentation in lib-blockto [FEATURE] Audit authority, code quality and documentation in lib-blockerikinkinen referenced this issue from erix/integration2026-09-19 23:04:20 +02:00
The block-device client now pins LibIPC
61b43723in 9b335e80. This is part of the Vfsd dependency repair; the existing interfaces are unchanged, and Integration consumer adoption is in progress.