[FEATURE] Define and enforce a versioned compatibility artifact contract #15

Open
opened 2026-11-07 18:10:35 +01:00 by erikinkinen · 1 comment
Owner

Problem and motivation

Imported userspace runtimes need an artifact contract distinct from the native abort-only policy. Native rejection of TLS, initializers and unwind metadata must remain explicit.

Proposed behavior and scope

Define a versioned, allocation-free compatibility record binding the complete original ELF length, SHA256, executable/shared-object role and x86-64 SysV target to declared runtime requirements. Use exact framing, reject unknown versions/fields and require canonical encoding.

Loaderd will bind the record to its original authenticated object bytes and validate the actual executable ELF. Its existing initial-TLS producer is the only supported additional mechanism. Ordered initialization/finalization, dynamic-module TLS, symbol versions and unwind requirements refuse until their runtime mechanisms exist.

Authority, security and reliability

Requirements describe the object; they grant no file, library, mapping or execution authority. Original graph/file provenance, closure validation, W^X, relocation checks and native artifact guards remain mandatory. No initializer is called by intake, and malformed input performs no native operation.

Acceptance criteria

  • Canonical record round trips; version, reserved-field, extent and original-byte substitutions refuse.
  • Real executable/shared ELF fixtures exercise positive intake, TLS geometry and unsupported-feature refusals.
  • Existing native rejection and authenticated materialization paths retain their contracts.
  • Document the stable format and its source/authority boundaries.

Alternatives and tradeoffs

A flag that relaxes the native artifact policy would blur the two contracts. A separate required-feature record keeps later runtime additions explicit without claiming their execution today.

Tracking and rollout

Extend LibDynlink's existing TLS foundations in #4, then wire the contract into Loaderd's authenticated initial-TLS intake. Constructors, dynamic-module lifetime and unwind execution remain separate runtime work.

## Problem and motivation Imported userspace runtimes need an artifact contract distinct from the native abort-only policy. Native rejection of TLS, initializers and unwind metadata must remain explicit. ## Proposed behavior and scope Define a versioned, allocation-free compatibility record binding the complete original ELF length, SHA256, executable/shared-object role and x86-64 SysV target to declared runtime requirements. Use exact framing, reject unknown versions/fields and require canonical encoding. Loaderd will bind the record to its original authenticated object bytes and validate the actual executable ELF. Its existing initial-TLS producer is the only supported additional mechanism. Ordered initialization/finalization, dynamic-module TLS, symbol versions and unwind requirements refuse until their runtime mechanisms exist. ## Authority, security and reliability Requirements describe the object; they grant no file, library, mapping or execution authority. Original graph/file provenance, closure validation, W^X, relocation checks and native artifact guards remain mandatory. No initializer is called by intake, and malformed input performs no native operation. ## Acceptance criteria - [x] Canonical record round trips; version, reserved-field, extent and original-byte substitutions refuse. - [x] Real executable/shared ELF fixtures exercise positive intake, TLS geometry and unsupported-feature refusals. - [x] Existing native rejection and authenticated materialization paths retain their contracts. - [x] Document the stable format and its source/authority boundaries. ## Alternatives and tradeoffs A flag that relaxes the native artifact policy would blur the two contracts. A separate required-feature record keeps later runtime additions explicit without claiming their execution today. ## Tracking and rollout Extend LibDynlink's existing TLS foundations in [#4](https://git.erikinkinen.fi/erix/lib-dynlink/issues/4), then wire the contract into Loaderd's authenticated initial-TLS intake. Constructors, dynamic-module lifetime and unwind execution remain separate runtime work.
erikinkinen added this to the Alpha 1 milestone 2026-11-07 18:10:35 +01:00
Author
Owner

The contract and its authenticated Loaderd intake are implemented in LibDynlink #16 and Loaderd #32. Docs #85 specifies the record and updates the library API reference. Native artifact rejection remains separate; unsupported initialization, unwind, symbol-version and dynamic-module requirements refuse before materialization.

The contract and its authenticated Loaderd intake are implemented in [LibDynlink #16](https://git.erikinkinen.fi/erix/lib-dynlink/pulls/16) and [Loaderd #32](https://git.erikinkinen.fi/erix/loaderd/pulls/32). [Docs #85](https://git.erikinkinen.fi/erix/docs/pulls/85) specifies the record and updates the library API reference. Native artifact rejection remains separate; unsupported initialization, unwind, symbol-version and dynamic-module requirements refuse before materialization.
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-dynlink#15
No description provided.