Crate louke 

漏刻 (Lòukè) — the runtime observation dimension of Tianheng.

Where 圭表 reads imports and 渾儀 reads the AST — both at CI time — 漏刻 reacts at runtime, in your binary, against live objects: it sees the concrete type behind a dyn Trait crossing an architectural seam, which static and semantic analysis structurally cannot.

Two faces:

• Prod face. Declare RuntimeBoundary::at("seam").only_origins([…]) and install it once at startup. Probes read live type origins and react fail-closed.
• CI face (the non-default audit feature). Audits workspace source for assert_boundary! probes to guarantee every declared seam has a probe and every probe a declared seam.

Govern by reaction, not instruction.

Macros

assert_boundary

Probe a runtime seam: assert_boundary!("domain-entry", obj) reads obj’s concrete origin (via the Tracked supertrait on its trait) and reacts fail-closed against the seam’s allowlist. obj must be a reference to a dyn Trait whose trait carries : louke::Tracked.

register_origin

Register a type’s observed origin: register_origin!(PostgresRepo) captures module_path!() at the call site (so the origin is where the type is registered, not a self-asserted label) and yields an OriginEntry to pass to install. Declarative — no proc-macro, no syn.

Structs

Finding

Pair human-readable finding text with stable structured identity.

FindingKey

A dimension-agnostic identity for one observed fact.

OriginEntry

An origin registration produced by crate::register_origin! — a TypeId, the observed origin (module_path!() at the registration site), and the type’s name (for findings). Pass these to crate::install.

Report

All violations from one evaluation.

RuntimeBoundary

A runtime boundary: only the declared origins may cross the named seam. Declared in Rust (the single source of truth) and installed once at startup; a probe references the seam by name, so the policy lives in this declaration, not at the call site.

Violation

One violated boundary.

ViolationId

A violation’s baseline identity and human finding text.

Enums

BoundaryKind

Which kind of boundary produced a violation.

Outcome

The reaction’s outcome.

Polarity

The repair direction a boundary-drift violation points to.

Posture

How a violated boundary reacts in production. Event (the default) emits a structured Violation; Panic additionally aborts — opt-in only, never the default.

Severity

How strongly a boundary reacts.

Constants

RUNTIME_SEAM_RULE

The canonical runtime seam-origin rule label — written once here and referenced by both the prod reaction (the crate’s internal check_crossing) and the 天衡 shell’s list projection (tianheng depends on louke, so importing this is the allowed direction). Editing it in one place updates every projection. The specific allowed-origin set is a per-boundary detail layered on at each site, not part of this rule-family label.

Traits

Tracked

The supertrait a governed trait carries so a probe can recover the concrete type behind a dyn Trait without trait upcasting (rust 1.85). Write trait DomainPort: louke::Tracked; the blanket impl supplies as_any for every 'static type, so no per-type boilerplate is needed. A &dyn Trait over borrowed (non-'static) data cannot be probed — Any requires 'static (a stated bound).

Functions

audit_probe_coverage

CI face. Audit probe coverage against the declared RuntimeBoundary objects (the authoritative seam set — the constitution, not a source scan for declarations) by scanning the workspace’s source inputs for assert_boundary! probes. A file input is treated as an exact Cargo target root and walked through reachable modules; a directory input retains the legacy recursive corpus for source compatibility. Reacts, with the static dimensions’ exit-code contract, in both directions plus an un-auditable case:

install

Install the runtime constitution once at startup: the declared boundaries and the origin registrations (crate::register_origin!). The registry is write-once so the probe hot path reads it without a lock; calling install a second time is a constitution error (it fails loud rather than silently replacing the law).

runtime_seam_rule_line

The full runtime seam rule line — the canonical RUNTIME_SEAM_RULE label with the per-boundary allowed-origin set folded in (… (only origins: A, B)). Written once here and shared by the prod reaction (check_crossing’s violation rule) and the 天衡 shell’s list --format text projection, so the human-readable line the two render never drifts. The JSON projection deliberately keeps the label bare and carries the origins as a separate field, so it does not use this.

set_sink

Install the sink that receives runtime Violation events (a logger, an audit pipeline). Set once at startup; the default sink (used if none is installed) prints the violation as JSON to stderr.