Module subcontext 

SRD-67 — 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 subcontext_construction.md:

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

Phase scope

SRD-67’s five phases have all landed: the typed surface (Phase 1), the Rule 2 write-through rewrite in SubcontextBuilder::finalize (Phase 2), the synthesiser migrations (Phase 3), the pub(crate) seal on the legacy construction primitives (Phase 4), and SubcontextBuilder::add_result_bindings (Phase 5). The design document is the implemented specification; “Phase N” in this module’s comments names the push that landed a piece, not pending work.

Cross-binding rules from SRD-67 §“Cross-binding rules” are enforced at SubcontextBuilder::finalize and ScopeKernel::spawn:

• Rule 1 — import resolution at finalize.
• Rule 2 — export collision with final parent surfaces as ContractViolation::FinalShadow; collision with shared parent rewrites the body’s X := <expr> into extern X: <type> + __write_X := <expr> and records a WriteThroughBinding on the artifact. Per-cycle eval calls ScopeKernel::commit_write_throughs to fan values through the parent’s SharedCell.
• Rule 4 — coordinate routing handled by materialize_wiring_from_outer’s IterationExtern input-kind.
• Rule 5 — closure-binding economy: unused imports surface as finalize diagnostics rather than errors.

Cross-crate boundary

PullConsumer is defined as a trait so that nbrs-runtime’s ScopeFixture can implement it without polydat depending on nbrs-runtime (the crate dependency runs the other way). Phase 1 ships a minimal trait shape — the names a consumer wants to pull at cycle time — sufficient for the activity-side ScopeFixture::register_consumer adapter to absorb. The eventual seal of the SRD-32 PullPlan happens on the activity side; the artifact only carries the requested names.

Walled-off invariant (SRD-67 Phase 4)

Per SRD-67 §“Walled-off invariant”, the legacy cross-binding primitives PolydatKernel::materialize_wiring_from_outer and PolydatKernel::from_program are pub(crate) after Phase 4. External consumers must go through the typed surface: SubcontextBuilder / ScopeKernel::spawn for child construction, instance_program for parentless re-instancing of a compiled program, chain_kernel_under_parent for top- level kernel chaining.

The compile-fail cases under 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 and a Phase 4 invariant has regressed.

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 (per SRD-67 §“Decision 6”).

ChildName

Hierarchical identifier for a spawned sub-context.

CompileOptions

Optional compile-time configuration passed through to compile_polydat_with_libs when finalize compiles the body. When every field is at its default, finalize falls back to the minimal compile_ast_with_options path used by the do-loop bridge — no behaviour change for the simplest synthesisers.

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 Phase 1 tests can exercise the builder + spawn path without importing the activity crate.

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 (per SRD-13e §1.2).

ScopeKernel

Typed wrapper around an Arc<PolydatKernel>.

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 ScopeKernel::subcontext_builder — the parent is the only way in.

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 — taxonomically what SRD-13e §1.2 specifies. Drives the spawn-time validation decisions per SRD-67 Rule 1.

Traits

PullConsumer

Anything that wants to pull Polydat values at cycle time.