mod host bridge - Verification and traceability

Platform spec article

mod host bridge - Verification and traceability

Back to Mod host bridge ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0001-feature-hub-authority Feature hub authority Accepted

   This feature hub owns normative MUST/SHOULD contract text for Mod host bridge.

   Context

   Sibling articles under this feature previously restated requirements in inconsistent forms.

   Decision

   This feature hub owns normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.

   Consequences

   Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

   Verification anchors

   • site/website/src/content/docs/platform-spec/compiler/compiler-mods/mod-host-bridge/index.mdx
   • article bundle under the same feature directory.

   Open full ADR page

2. 0002-spec-over-implementation-notes Specification over implementation notes Accepted

   Platform-spec text supersedes informal crate comments for Mod host bridge.

   Context

   Implementation crates accumulated informal notes that diverged from published contracts.

   Decision

   Normative platform-spec prose and ADRs under this feature supersede informal comments in implementation crates until explicitly migrated into spec text.

   Consequences

   Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

   Verification anchors

   • compiler/crates/beskid_analysis/
   • compiler/crates/beskid_codegen/
   • compiler/crates/beskid_analysis/src/services.rs

   Open full ADR page

3. 0003-mod-aot-only-registration Mod host AOT-only with descriptor registration Accepted

   Mods previously risked manifest attach lists for discovery.

   Context

   Mod packages must export public Beskid types implementing SDK contracts; host loads AOT artifacts and mod.descriptor.json registrations—not manifest attach metadata.

   Decision

   Contract discovery uses (contractId, typeId, entrySymbol) tuples; failures emit E1821–E1870 before mod.collect.

   Consequences

   JIT mod execution is not normative; rebuild uses beskid mod rebuild.

   Verification anchors

   • compiler/crates/beskid_analysis/
   • mod artifact store paths in analysis services.

   Open full ADR page

Articles

• Mod host bridge - AOT artifact contract On-disk mod artifact layout, cache keys, export descriptor schema, and load-failure diagnostics. article Standard Reviewed Wed May 20
• mod host bridge - Contracts and edge cases Reference compiler-owned execution, capability policy, and communication with compile-time Beskid modules. article Standard Reviewed Thu Apr 30
• mod host bridge - Design model Rust-side mod host execution, AOT artifact lifecycle, capability policy, and typed merge. article Standard Reviewed Wed May 20
• mod host bridge - Examples Reference compiler-owned execution, capability policy, and communication with compile-time Beskid modules. article Standard Reviewed Thu Apr 30
• mod host bridge - FAQ and troubleshooting Reference compiler-owned execution, capability policy, and communication with compile-time Beskid modules. article Standard Reviewed Thu Apr 30
• mod host bridge - Flow and algorithm Reference compiler-owned execution, capability policy, and communication with compile-time Beskid modules. article Standard Reviewed Thu Apr 30
• mod host bridge - Verification and traceability Reference compiler-owned execution, capability policy, and communication with compile-time Beskid modules. article Standard Reviewed Thu Apr 30

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Architecture

Compile-time mod execution flow

Reference ordering from parse through mod collection, generation, semantic analysis, rewrite, and lowering.

Completeness

OKfeature · 0 SpecSection(s) · 3 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  mod host bridge

  Parent feature hub

This article documents verification and traceability for mod host bridge.

Traceability matrix

Anchor	Role
compiler/crates/beskid_aot/src/mod_artifact.rs	Mod AOT artifact build, cache key tuple, descriptor emission.
compiler/crates/beskid_analysis/src/mod_host/	Reference mod host orchestration: discovery, capabilities, validation, contract dispatch, typed merge / reparse, analyze / rewrite.
compiler/crates/beskid_analysis/src/mod_host/diagnostics.rs	Structured ModHostIssue / ModHostDiagnostics with E1828, E1829, E1830, E1831, E1851, E1852, E1853, E1854, E1855.
compiler/crates/beskid_analysis/src/mod_host/validate.rs	Pre-mod.collect cross-artifact validation pass.
compiler/crates/beskid_analysis/src/mod_host/invoker.rs	ContractInvoker trait + StubContractInvoker / ScriptedContractInvoker test surfaces.
compiler/crates/beskid_analysis/src/services/front_end.rs	Front-end integration for run_through_generate before semantic diagnostics and run_analyze_rewrite after semantic work.
compiler/crates/beskid_codegen/src/services.rs	Lowering / codegen integration for mod host phases before lower.ready.
compiler/crates/beskid_pipeline/src/phases.rs	Literal mod.load, mod.collect, mod.generate, mod.analyze, mod.rewrite phase ids.

Test anchors

Anchor	Coverage
compiler/crates/beskid_analysis/src/mod_host/api.rs (unit tests)	Skip mod phases on no-mod plans, dispatch all four contract kinds through StubContractInvoker, abort on duplicate (contractId, typeId) registration with E1829.
compiler/crates/beskid_analysis/src/mod_host/validate.rs (unit tests)	Per-issue assertions for E1828, E1829, E1851, E1852, E1853, E1854, plus a clean-load pass.
compiler/crates/beskid_tests/src/mods/contract_dispatch.rs	End-to-end dispatch through every contract kind against the sample_mod fixture; canonical pipeline phase order.
compiler/crates/beskid_tests/src/mods/conflicts.rs	End-to-end E1828, E1829, E1853, E1854 scheduling abort tests against the sample_mod fixture.
compiler/crates/beskid_tests/fixtures/mods/sample_mod/	Reference compiler-mod fixture exercising Collector, Generator, AttributeGenerator, Analyzer, Rewriter.
compiler/crates/beskid_engine/tests/mod_host.rs	Engine-level integration: drives the full pipeline and JIT-compiles the lowered host program.
compiler/crates/beskid_tests/src/analysis/pipeline/mod_phases.rs	Pipeline-phase ordering subsequence assertions and FULL_BUILD_PHASE_ORDER regression.

Verification expectations

• Phase ids — Unit or integration tests must assert the literal strings from Compiler Mods / Mod projects and pipeline phase ids appear in beskid_pipeline observations (see Stage ordering / verification).
• Contract dispatch — ContractInvoker is dispatched once per scheduled (contractId, typeId, entrySymbol) tuple per phase, with Collector / Generator outcomes returned from run_through_generate and Analyzer / Rewriter outcomes returned from run_analyze_rewrite_with_invoker.
• Capabilities — Table-driven tests in compiler/crates/beskid_analysis/src/mod_host/capabilities.rs verify each capability grants / denies the documented effect and emits codes from the E1821–E1835 band on denial.
• AOT artifacts — Tests assert descriptor schema, cache key invalidation, and E1821–E1835 on deliberate load failures (AOT artifact contract).
• Scheduling conflicts — Tests assert E1828, E1829, E1851–E1855 short-circuit scheduling before mod.collect is observed (see compiler/crates/beskid_tests/src/mods/conflicts.rs and the scheduling-conflict band in AOT artifact contract).
• Merge — Tests assert atomic typed-emit commit at syntax.generation: partial emit never reaches lower.ready (pair with Typed emitter / verification once populated).
• Incremental traces — Optional goldens validate invalidation when syntax edits move spans tied to mod contract registrations (Incremental scheduling / verification).

Review cadence

• Update this bundle whenever public Beskid.Compiler.* shapes or host policies change.