polydat_core/kernel/subcontext/
mod.rs

1// Copyright 2024-2026 Jonathan Shook
2// SPDX-License-Identifier: Apache-2.0
3
4//! SRD-67 — parent-gated Polydat sub-context construction.
5//!
6//! This module is the typed entry point for constructing a Polydat
7//! child kernel as a function of a parent kernel. It implements
8//! the protocol from
9//! [subcontext_construction.md](../../../docs/design/subcontext_construction.md):
10//!
11//! 1. Parent yields a builder via [`ScopeKernel::subcontext_builder`].
12//! 2. Builder accumulates module matter (imports, exports, body
13//!    fragments, pull consumers) via [`SubcontextBuilder`].
14//! 3. `finalize` closes the builder, validates imports against the
15//!    parent's exports, compiles the body into a [`ScopeModule`] with
16//!    a typed [`ScopeContract`].
17//! 4. Parent spawns the child via [`ScopeKernel::spawn`] — the single
18//!    chokepoint where every cross-binding is resolved.
19//!
20//! ## Phase scope
21//!
22//! SRD-67's five phases have all landed: the typed surface
23//! (Phase 1), the Rule 2 write-through rewrite in
24//! [`SubcontextBuilder::finalize`] (Phase 2), the synthesiser
25//! migrations (Phase 3), the `pub(crate)` seal on the legacy
26//! construction primitives (Phase 4), and
27//! [`SubcontextBuilder::add_result_bindings`] (Phase 5). The
28//! design document is the implemented specification; "Phase N"
29//! in this module's comments names the push that landed a piece,
30//! not pending work.
31//!
32//! Cross-binding rules from SRD-67 §"Cross-binding rules" are
33//! enforced at [`SubcontextBuilder::finalize`] and
34//! [`ScopeKernel::spawn`]:
35//!
36//! * Rule 1 — import resolution at finalize.
37//! * Rule 2 — export collision with `final` parent surfaces as
38//!   [`ContractViolation::FinalShadow`]; collision with `shared`
39//!   parent rewrites the body's `X := <expr>` into
40//!   `extern X: <type>` + `__write_X := <expr>` and records a
41//!   `WriteThroughBinding` on the artifact. Per-cycle eval
42//!   calls [`ScopeKernel::commit_write_throughs`] to fan values
43//!   through the parent's `SharedCell`.
44//! * Rule 4 — coordinate routing handled by `materialize_wiring_from_outer`'s
45//!   IterationExtern input-kind.
46//! * Rule 5 — closure-binding economy: unused imports surface as
47//!   finalize diagnostics rather than errors.
48//!
49//! ## Cross-crate boundary
50//!
51//! [`PullConsumer`] is defined as a trait so that `nbrs-runtime`'s
52//! `ScopeFixture` can implement it without `polydat`
53//! depending on `nbrs-runtime` (the crate dependency runs the
54//! other way). Phase 1 ships a minimal trait shape — the names a
55//! consumer wants to pull at cycle time — sufficient for the
56//! activity-side `ScopeFixture::register_consumer` adapter to
57//! absorb. The eventual seal of the SRD-32 `PullPlan` happens on
58//! the activity side; the artifact only carries the requested
59//! names.
60//!
61//! ## Walled-off invariant (SRD-67 Phase 4)
62//!
63//! Per SRD-67 §"Walled-off invariant", the legacy
64//! cross-binding primitives `PolydatKernel::materialize_wiring_from_outer` and
65//! `PolydatKernel::from_program` are `pub(crate)` after Phase 4.
66//! External consumers must go through the typed surface:
67//! [`SubcontextBuilder`] / [`ScopeKernel::spawn`] for child
68//! construction, `instance_program` for parentless re-instancing
69//! of a compiled program, `chain_kernel_under_parent` for top-
70//! level kernel chaining.
71//!
72//! The compile-fail cases under `tests/ui/seal/` guard the seal: one
73//! calls `materialize_wiring_from_outer` from outside the crate, one
74//! calls `PolydatKernel::from_program`, and neither may compile. If
75//! either starts compiling, the seal is broken and a Phase 4
76//! invariant has regressed.
77
78mod builder;
79mod error;
80mod kernel;
81mod module;
82mod name;
83mod pull;
84mod spec;
85
86#[cfg(test)]
87mod tests;
88
89pub use builder::{CompileOptions, SubcontextBuilder};
90pub use error::{ContractViolation, SourceContext};
91pub(crate) use kernel::PolydatMatterInner;
92pub use kernel::{Child, PolydatMatter, PolydatMatterBuilder, RootMarker};
93pub use kernel::{ScopeKernel, SharedCellInScope};
94pub use module::{BodyFragment, ScopeContract, ScopeModule};
95pub use name::ChildName;
96pub use pull::{NamedPullConsumer, PullConsumer, RegisteredPullConsumer};
97pub use spec::{ExportClassification, ExportSpec, ImportClassification, ImportSpec};
polydat_core/kernel/subcontext/mod.rs

polydat_core/kernel/subcontext/
mod.rs
