[FEATURE] Make API reference conversion explicit and reproducible #14

Closed
opened 2026-10-14 09:10:51 +02:00 by erikinkinen · 1 comment
Owner

Problem and motivation

API references need a reproducible conversion request with clear tool inputs, resource budgets and diagnostic records. The interface should make those inputs reviewable alongside the selected Rustdoc source.

Proposed behavior and scope

Use one versioned request for the selected documentation procedures, manifest, genuine Rustdoc JSON, converter and original command owner. Include explicit environment, working directories, output and receipt roots, and finite input, output and time budgets. Invoke the selected Python with --contract, the complete request byte count and SHA-256, and optional --check. Require finite positive caller-selected budgets and supported single-leaf names; reject traversal and aliases without imposing an ASCII-only namespace. Replace the superseded selectors and split inventory, rendering, conversion and request validation into focused modules.

Docs owns the implementation and caller documentation; Integration records the complete procedure sources in its build inventory. Existing generated reference semantics remain the comparison baseline.

Authority, security and reliability

A request describes selected host inputs and output rights; it does not authorize native EriX execution or prove source, frame, runtime or guest admission. Preserve the original command owner's waits, cancellation and cleanup contract. Retain complete converter diagnostics, the exact first failure and independent cleanup errors. Finish the complete conversion cohort before writing references. A failed write may leave a partial cohort, which must be requalified before use.

Acceptance criteria

  • Implement the complete explicit request and migrate maintained callers.
  • Keep every authored module below 1,000 physical lines with useful inline documentation.
  • Cover real generation/check, changed or missing inputs, invalid budgets, diagnostics, cancellation and cleanup.
  • Preserve the semantic output of genuine selected API references.
  • Adopt the complete procedure inputs in Integration and update the tooling documentation.
  • Publish the coherent change and reconcile the phase checklist.

Alternatives and tradeoffs

One bound request avoids conflicting selectors and keeps the tool and source descriptions together. Separate inventory and conversion modules let the existing semantic controls remain independent of external tool execution.

Tracking and rollout

Documentation requirements, documentation audit, manual review, Integration review, and phase completion.

Update the converter, maintained callers and Integration source inventory together. Detailed private authority review remains separate from this interface proposal.

## Problem and motivation API references need a reproducible conversion request with clear tool inputs, resource budgets and diagnostic records. The interface should make those inputs reviewable alongside the selected Rustdoc source. ## Proposed behavior and scope Use one versioned request for the selected documentation procedures, manifest, genuine Rustdoc JSON, converter and original command owner. Include explicit environment, working directories, output and receipt roots, and finite input, output and time budgets. Invoke the selected Python with `--contract`, the complete request byte count and SHA-256, and optional `--check`. Require finite positive caller-selected budgets and supported single-leaf names; reject traversal and aliases without imposing an ASCII-only namespace. Replace the superseded selectors and split inventory, rendering, conversion and request validation into focused modules. Docs owns the implementation and caller documentation; Integration records the complete procedure sources in its build inventory. Existing generated reference semantics remain the comparison baseline. ## Authority, security and reliability A request describes selected host inputs and output rights; it does not authorize native EriX execution or prove source, frame, runtime or guest admission. Preserve the original command owner's waits, cancellation and cleanup contract. Retain complete converter diagnostics, the exact first failure and independent cleanup errors. Finish the complete conversion cohort before writing references. A failed write may leave a partial cohort, which must be requalified before use. ## Acceptance criteria - [x] Implement the complete explicit request and migrate maintained callers. - [x] Keep every authored module below 1,000 physical lines with useful inline documentation. - [x] Cover real generation/check, changed or missing inputs, invalid budgets, diagnostics, cancellation and cleanup. - [x] Preserve the semantic output of genuine selected API references. - [x] Adopt the complete procedure inputs in Integration and update the tooling documentation. - [x] Publish the coherent change and reconcile the phase checklist. ## Alternatives and tradeoffs One bound request avoids conflicting selectors and keeps the tool and source descriptions together. Separate inventory and conversion modules let the existing semantic controls remain independent of external tool execution. ## Tracking and rollout [Documentation requirements](https://git.erikinkinen.fi/erix/docs/issues/1), [documentation audit](https://git.erikinkinen.fi/erix/docs/issues/2), [manual review](https://git.erikinkinen.fi/erix/docs/pulls/4), [Integration review](https://git.erikinkinen.fi/erix/integration/pulls/12), and [phase completion](https://git.erikinkinen.fi/erix/integration/issues/65). Update the converter, maintained callers and Integration source inventory together. Detailed private authority review remains separate from this interface proposal.
Author
Owner

The explicit conversion request is complete in Docs 3fb1be80, with the complete converter inventory adopted by Integration 50b12fcc. Maintained callers use selected inputs and original process ownership, command streams and prepared references share one allowance, and the older selectors are removed. The separate Coreutils reference note and manual publisher remain open.

The explicit conversion request is complete in [Docs 3fb1be80](https://git.erikinkinen.fi/erix/docs/commit/3fb1be808d1cda25880489712d2e7198bf355eef), with the complete converter inventory adopted by [Integration 50b12fcc](https://git.erikinkinen.fi/erix/integration/commit/50b12fccb3d009044ed50f48a24b095b23fadf7d). Maintained callers use selected inputs and original process ownership, command streams and prepared references share one allowance, and the older selectors are removed. The separate [Coreutils reference note](https://git.erikinkinen.fi/erix/docs/issues/15) and [manual publisher](https://git.erikinkinen.fi/erix/docs/issues/16) remain open.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:33:40 +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/docs#14
No description provided.