dynlinkd

dynlinkd is the EriX dynamic-linker service for supported native dynamic objects.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX dynamic-linker service. Its purpose in EriX is to receive explicit dynamic-link requests, validate supported object metadata, and prepare deterministic dependency, symbol, and relocation plans.

Functionally, it exposes a no_std service binary plus host-side unit tests for the startup and dispatch contracts. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• validate the dynlinkd startup envelope and capability intake contract
• serve the typed begin/submit/commit/read/abort complete-graph transaction
• retain caller-supplied object names, identities, mapped ranges, and table bytes only in a transaction-local startup-mapped arena
• compact each accepted variable record to the exact identity fields retained after validation, erasing its transient prefix immediately
• call lib-dynlink for supported ELF64 object and complete-graph planning
• stream authoritative relocation writes to the caller without independent object, graph, name, table, symbol, relocation, or dependency-path limits
• erase replaced, aborted, malformed, and failed transaction state

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Status

Implemented service baseline and dynamic startup:

• #![no_std], target-none service binary with a fixed linker base and a deployment-sized, page-aligned transaction arena whose exact target layouts are embedded in the ELF and consumed by image tooling; the arena remains below a terminal stack reserve that tooling moves when the arena grows
• true dynamic executable packaging through the signed boot dynamic catalog
• service startup validation for SERVICE_ROLE_DYNLINKD
• one required receive endpoint and no primary-control endpoint
• no VFS peer grant; callers with object-source authority submit every manifest-selected object
• typed begin, sequential fragment submission for arbitrarily sized records, complete-graph commit, streamed plan read, and abort dispatch
• exact package-version and full feature/manifest/object digest agreement across every submitted graph edge
• deterministic response bodies for success, malformed, unsupported, manifest, symbol, relocation, and actual storage-exhaustion classes
• exact per-object dependency, symbol, relocation, mapped-range, table, and graph traversal storage derived from submitted metadata
• arena sizing mirrors the real allocation/compaction sequence over the packaged runtime graph; no caller or service imposes a parallel product cap
• required startup and single-endpoint runtime intake have no service-local deadline, and replies retain the canonical transport buffer through transient kernel backpressure
• runtime operations admit no transferred authority; complete unwanted receipts are retired before rejection, while malformed receipt state, uncertain cleanup, or terminal transport loss fails stopped
• host unit tests for startup validation, in-place dispatch, arena rollback and erasure, complete two-object graph resolution, authoritative relocation writes, storage exhaustion, and incomplete-graph cleanup
• real-artifact host packaging verifies embedded layout discovery, terminal NOBITS growth, program-header growth, symbol updates, the authenticated runtime-read capacity word, and post-patch hashes
• Operator evidence documents dynlinkd as a self-hosted dynamic executable: its first dependency graph is resolved from the signed boot catalog through rootd/procd, and self-bootstrap failures are triaged with ERIX_ROOTD:DYNLINKD_DYNAMIC:* before the retained ERIX_ROOTD:READY:DYNLINKD launch proof
• CI test coverage for formatting, strict clippy, build, unit tests, and docs build, alongside Markdown linting

The service prepares immutable complete-graph plans. It does not discover filesystem dependencies, map process memory, apply relocations, create processes, or publish itself through named.

Dynamic Boot Artifact Evidence

The image build documents dynlinkd as a dynamic boot artifact and packages the dynamic-linker service as an ELF64 x86_64 ET_DYN executable with .erix_dynlink metadata in the signed dynlink-store and mirrors it under /lib/erix/dynlink with its required shared objects.

Startup remains rootd through procd staged dynamic creation after VFS readiness; its first-link graph comes from the boot catalog and cannot use dynlinkd's own service API. Dynamic packaging and filesystem mirror records are evidence and launch inputs only; they do not grant filesystem, loader, object-store, service-discovery, provider-bypass, block-device, or dynlinkd authority. dynlinkd receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

dynlinkd governance is scoped to dynamic-link service behavior shared by dependent repositories.

The scoped governance rules are:

• It must expose narrow, documented IPC rather than ambient filesystem search.
• It treats transport byte capacity and deployment-mapped arena storage as resource facts and does not turn them into independent linker policy.
• It must not continue after uncertain received-authority cleanup or terminal reply state; process exit requests teardown, with a stopped loop as the fallback quarantine.
• It preserves clean-room implementation boundaries and does not introduce external crate dependencies.
• Breaking IPC, startup, or authority changes require coordinated updates in lib-bootstrap, lib-capabi, lib-ipc, rootd, integration, and docs.

Service Boundaries

• dynlinkd carries only the capabilities delivered in its startup envelope.
• The startup path is linked from boot-catalog shared objects by rootd and procd before dynlinkd can serve its own API.
• Operator evidence must keep this self-host startup failure class distinct from bootloader kernel-link/catalog failures, kernel service-link failures, and ordinary service dynamic-link failures.
• The service receives only its local service endpoint.
• The service has no VFS, provider, process, frame, VSPACE, key, journal, or root-control authority.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.