Crate hunyi 

渾儀 (Húnyí) — the semantic observation dimension of Tianheng.

Where the gnomon 圭表 observes imports (does domain import infra?), 渾儀 observes meaning via the AST (syn): does a module’s public API expose a forbidden type? That is the complement of import-governance — a type imported for internal use is fine; a type named in a pub signature is a leak, and one named via a fully-qualified path with no use is invisible to a token scanner but caught here.

Declare a SemanticBoundary in Rust, check it against a Cargo workspace, and get an Outcome with the same exit-code contract (0/1/2) and reaction model as the static dimension — both express findings in the shared 璇璣 (xuanji) crate. The heavy syn dependency is quarantined to this crate, never the core (self_governance.rs).

Observed surface and its honest bounds. The exposed surface of a module anchor is its pub free functions (params/returns), pub struct/enum/union field types, pub type-alias targets, pub const/static types, pub trait method signatures and associated-type bounds (and supertraits), the generic bounds / where-clauses of those items, and the pub methods of inherent impl blocks. Out of scope (stated bounds, not silent passes): trait impl blocks (their shape is dictated by the trait, not the impl site); a type reachable only through a glob import or a macro; and a type knowable only through inference (a return-position impl Trait that hides a concrete type, or an alias chain). Within the resolved scope there is no false negative: a forbidden type that is resolvable always reacts.

Govern by reaction, not instruction.

Structs

Baseline

A recorded set of accepted violations — a generated observation snapshot, not policy. The gate fails only on violations absent from it.

ForbiddenMarkerBoundary

A forbidden-marker boundary: types defined in a module subtree must not acquire a forbidden trait — by #[derive(T)] or a hand-written impl T for <a subtree type>. Declared in Rust and composed at the gate. The complement to exposure, impl-locality, and visibility; it delivers the “this layer is not T-able” intent.

ForbiddenMarkerBoundaryDraft

A boundary awaiting more forbidden traits (optional), severity (optional), and a reason.

ForbiddenMarkerCrateDraft

A forbidden-marker boundary awaiting its module-subtree anchor.

ForbiddenMarkerModuleDraft

A subtree-anchored boundary awaiting its first forbidden trait.

Report

All violations from one evaluation.

SemanticBoundaries

The 渾儀 (semantic) dimension’s boundaries, gathered so the shell takes the dimension as one unit rather than one parameter per capability. Each field is one capability’s boundaries; check_all evaluates them all with a single cargo metadata read.

SemanticBoundary

A semantic boundary: the public API of a module must not expose any forbidden type. Declared in Rust (the single source of truth), alongside — and composed with — the static constitution at the gate. Each dimension owns its own declaration DSL and expresses findings in the shared 璇璣 model; the shell merges them into one reaction.

SemanticBoundaryDraft

A boundary awaiting severity (optional) and its reason.

SemanticCrateDraft

A semantic boundary awaiting its module anchor.

SemanticModuleDraft

A module-anchored boundary awaiting the forbidden set.

TraitImplBoundary

A trait-impl-locality boundary: within a target crate, the named trait may be implemented only inside the declared allowed module location(s). An impl <Trait> for <Type> block outside them is a violation. Declared in Rust (the single source of truth) and composed with the other dimensions at the gate. This governs impl locality — the complement of exposure (SemanticBoundary) and of the static import boundary. It governs only the target crate’s own impl sites; it makes no claim about downstream crates (that would be external trait sealing, an essential gap).

TraitImplBoundaryDraft

A boundary awaiting more allowed locations (optional), severity (optional), and reason.

TraitImplCrateDraft

A trait-impl-locality boundary awaiting its trait anchor.

TraitImplTraitDraft

A trait-anchored boundary awaiting its first allowed location.

Violation

One violated boundary. severity is the producing boundary’s severity, so the exit-code decision and the report can treat enforce and warn findings apart. baselined is set when baseline gating records the violation in a baseline; a baselined violation does not fail the reaction.

ViolationId

A violation’s identity for baseline matching: (target, rule, finding). Reason and severity are excluded so editing them does not turn a known violation new.

VisibilityBoundary

A visibility boundary: a governed module must not declare any bare-pub items — a declared-visibility hygiene rule for an internal / impl-detail layer. The rule is syntactic (the pub keyword on the module’s own direct items), not crate- reachability: pub(crate)/pub(super)/pub(in …)/private are allowed, and attribute- derived public surface (#[macro_export], #[no_mangle]) is out of scope (the deferred attribute capability’s domain). Declared in Rust and composed with the other dimensions at the gate.

VisibilityBoundaryDraft

A boundary awaiting severity (optional) and its reason.

VisibilityCrateDraft

A visibility boundary awaiting its module anchor.

VisibilityModuleDraft

A module-anchored boundary awaiting the rule.

Enums

BoundaryKind

Which kind of boundary produced a violation — surfaced in the JSON report so a consumer need not reverse-engineer the rule string. Not part of the baseline identity (ViolationId), so adding it does not invalidate existing baselines. #[non_exhaustive]: a further dimension (e.g. runtime) adds its own kind without breaking consumers.

Outcome

The reaction’s outcome. Exit codes separate architectural drift (1) from a misconfiguration (2), so a mistyped target is not reported as drift.

Severity

How strongly a boundary reacts. Enforce fails the reaction (exit 1); Warn reports the violation as advisory without failing — the first rung of adoption, so a dirty project can observe a boundary before enforcing it.

Functions

apply_baseline

Mark each violation the baseline records as baselined, so it no longer fails the reaction; violations absent from the baseline are left as new.

check

Run the semantic boundaries against the Cargo workspace at manifest_path.

check_all

Evaluate every declared semantic boundary against the workspace with a single cargo metadata read, merging all findings into one outcome. A constitution error on any boundary supersedes (exit 2). The per-capability check/check_trait_impl_locality/ check_visibility entries remain for direct use; the shell composes via this.

check_forbidden_marker

Run the forbidden-marker boundaries against the Cargo workspace at manifest_path.

check_trait_impl_locality

Run the trait-impl-locality boundaries against the Cargo workspace at manifest_path.

check_visibility

Run the visibility boundaries against the Cargo workspace at manifest_path.