Module join 

Pure hash-join logic for the topology join node (issue #72).

A HashJoin buffers one upstream (the build side) into an in-memory index keyed by a configurable dotted path, then enriches records streamed from the other upstream (the probe side) with projected fields looked up from the matching build record. This is the classic hash-join shape: the build side is fully materialized before the probe side starts emitting.

This module is pure data logic — no I/O, no channels, no async. The topology executor (crate::topology) owns the streaming/channel plumbing and calls HashJoin::add_build_page / HashJoin::probe_page as pages arrive. Keeping it pure makes every join semantic unit-testable in isolation (see the extensive tests at the bottom of this file).

Semantics

• inner drops probe records with no build-side match.
• left passes probe records through for non-matches, filling the projected fields with JoinConfig::on_missing.
• on_duplicate decides what happens when one probe key matches more than one build record: OnDuplicate::First keeps the first, and OnDuplicate::Cartesian emits one enriched record per match.
• on_collision decides what happens when a projected as name already exists on the probe record.
• key_normalize controls whether "42" (string) and 42 (number) are treated as the same key (KeyNormalize::Stringify) or as distinct keys (KeyNormalize::Preserve, the default — no coercion).

Structs

HashJoin

A hash join: build the index, then probe it.

JoinConfig

Compiled join configuration. Dotted key paths are pre-split at construction.

JoinStats

Running counters for a join, mirroring the faucet_join_* metrics.

Projection

A single field projection: copy from (a dotted path into the build record) onto the probe record under the name as_.

Enums

JoinMode

Join mode — how probe records with no build match are handled.

KeyNormalize

How to normalize keys before comparison.

OnCollision

What to do when a projected as name collides with an existing field on the probe record.

OnDuplicate

What to do when one probe key matches more than one build record.

Constants

DEFAULT_MAX_BUILD_RECORDS

Default safety cap on build-side records (10M).