Module subcontext

Expand description

Parent-gated Polydat sub-context construction.

This module is the typed entry point for constructing a Polydat child kernel as a function of a parent kernel. It implements the protocol from crates/polydat/docs/design/subcontext_construction.md:

Parent yields a builder via ScopeKernel::subcontext_builder.
Builder accumulates module matter (imports, exports, body fragments, pull consumers) via SubcontextBuilder.
finalize closes the builder, validates imports against the parent’s exports, compiles the body into a ScopeModule with a typed ScopeContract.
Parent spawns the child via ScopeKernel::spawn — the single chokepoint where every cross-binding is resolved.

§Cross-binding rules

The comments in this module name the cross-binding rules by number. They are enforced at SubcontextBuilder::finalize and ScopeKernel::spawn:

Rule 1 — import resolution at finalize (subcontext_construction.md §2.2, SC4).
Rule 2 — export collision with a const parent output surfaces as ContractViolation::FinalShadow; collision with a shared cell visible at the parent rewrites the body’s X := <expr> into extern X: <type> + __write_X := <expr> and records a WriteThroughBinding on the artifact (§3.1). Per-cycle eval calls ScopeKernel::commit_write_throughs to fan values through the parent’s SharedCell (§5).
Rule 3 — the child is initialized after binding, so its consts see the bound inputs (§4, §9).
Rule 4 — coordinate routing handled by materialize_wiring_from_outer’s IterationExtern input-kind.
Rule 5 — closure-binding economy: magic externs are injected only when referenced (§3.2), and unused imports surface as finalize diagnostics rather than errors (§2.2).

§Cross-crate boundary

PullConsumer is defined as a trait so that nbrs-runtime’s ScopeFixture can implement it without polydat-core depending on nbrs-runtime (the crate dependency runs the other way). The trait carries a minimal shape — the names a consumer wants to pull at cycle time — sufficient for the activity-side ScopeFixture::register_consumer adapter to absorb. Sealing the host’s pull plan happens on the activity side; the artifact only carries the requested names (subcontext_construction.md §2.4).

§Walled-off invariant

The low-level cross-binding primitives are sealed (subcontext_construction.md §8, SC1): PolydatKernel::from_program is pub(crate) and materialize_wiring_from_outer is private to the kernel. External consumers must go through the typed surface: SubcontextBuilder / ScopeKernel::spawn or PolydatMatter::build_under for child construction, and Construction::root / KernelProgram::create_kernel for parentless re-instancing of a compiled program.

The compile-fail cases under the facade crate’s crates/polydat/tests/ui/seal/ guard the seal: one calls materialize_wiring_from_outer from outside the crate, one calls PolydatKernel::from_program, and neither may compile. If either starts compiling, the seal is broken.

Structs§

Child: Phantom-marker brand for “child of P”. spawn returns ScopeKernel<Child<P>>, distinct at the type level from a sibling’s Child<P> value but type-compatible at the module-identity level (subcontext_construction.md §1).
ChildName: Hierarchical identifier for a spawned sub-context.
CompileOptions: Optional compile-time configuration passed through to compile_ast_interpreter_with_options when finalize compiles the body. When every field is at its default, finalize compiles the statements under the default DSL options (subcontext_construction.md §2.3).
ExportSpec: Typed export declaration: a named value the child produces, available to its own descendants.
ImportSpec: Typed import declaration: a name the child’s body will reference, expecting the parent to export it.
NamedPullConsumer: Test-only / scratch consumer: holds a fixed list of names. Production consumers (validation / conditional / throttle / …) implement PullConsumer themselves on the activity side. This shape exists so tests can exercise the builder + spawn path without importing the activity crate.
ParentView: Everything a builder reads of the scope it builds under: the names the parent declares, the modifier on each output, the ledger the child’s compile is charged to, and the cells in scope there — each a live handle rather than a copy.
PolydatMatter: Typed Polydat matter accepted by both kernel-construction paths — root and subscope. Opaque externally: the only way to obtain a PolydatMatter value is via PolydatMatter::builder.
PolydatMatterBuilder: Builder for PolydatMatter. Configure exactly one input form (source, pre-parsed statements, or program), plus optional metadata, then call Self::build.
RegisteredPullConsumer: A consumer registration that has been recorded in a crate::kernel::subcontext::SubcontextBuilder.
RootMarker: Phantom-marker brand for the workload-root scope kernel — the top of any spawn type chain. Tests / examples that need a “starting” identity use this.
ScopeContract: Typed handle bundle (subcontext_construction.md §1).
ScopeKernel: Typed wrapper around a kernel of any engine.
ScopeModule: Closed, immutable module-matter artifact.
SharedCellInScope: One shared cell visible at a parent scope, reified for transitive cross-binding. Returned by ScopeKernel::shared_cells_in_scope.
SourceContext: Diagnostic context attached to a super::ScopeModule — where the module’s source came from. Used in error messages when a contract violation surfaces at spawn or finalize.
SubcontextBuilder: Module-matter accumulator. Construction is gated by a parent — ScopeKernel::subcontext_builder on the typed path, PolydatMatter::build_under on the untyped one — and both hand it the same ParentView.

Enums§

BodyFragment: Body fragment — what the builder accepts via super::SubcontextBuilder::body.
ContractViolation: Contract violation surfaced at finalize or spawn.
ExportClassification: Lifecycle classification for an export — what kind of downstream contract this export carries.
ImportClassification: Lifecycle classification for an import (scope_model.md §3). Carried into the module’s contract; finalize does not compare it against the parent (subcontext_construction.md §2.2).

Traits§

PullConsumer: Anything that wants to pull Polydat values at cycle time.

Functions§

wrap_root_kernel: Construct a workload-root ScopeKernel<RootMarker> from a compiled kernel of any engine: the door into the typed scope path, where a host spawns children it keeps and releases by name rather than dropping a kernel on the floor. Every child spawned under it runs on its engine.