Module binder 

Typed-binding contracts between adapters and the polydat runtime.

What a binder is

A Binder is an adapter’s declaration, at op-template construction time, of one typed-parameter binding shape it expects: which wires supply values, and what lvalue type each value will be assigned into at the wire-protocol layer (CQL column type, RPC parameter type, HTTP body schema, etc.).

Polydat consumes the binder to:

1. Verify wiring sanity at construction time — for each slot, check that the wire’s rvalue type satisfies the declared lvalue type. Concretely, the load-bearing rule is: a string detour (rvalue → to_display_string → bytes → cluster parser → typed wire form) is permitted only when the lvalue is itself a string-natural type. Anywhere else, text-rendering a typed wire to feed a typed parameter is the workload-shape defect the binder API exists to catch.

2. Plan typed pass-through at compile time — when the kernel knows a wire’s value will flow only into typed slots, it can skip string-form codegen entirely and materialise the value as the adapter’s expected lvalue type directly. (Compile-time use of binder metadata is a follow-on; for now polydat consumes the binder only for verification.)

What a binder is NOT

• It is not a workload-author syntax. Workload authors keep writing their adapter-native op templates (e.g. a CQL prepared: statement with {wire} references); the adapter constructs binders internally during its op-template processing (CQL: prepare the statement, read parameter metadata, build the binder from that).

• It is not compulsory for polydat callers in general. Polydat works without any binders submitted; the binder API is an opt-in surface for callers that have typed-parameter intent to declare.

• It IS compulsory for adapters via the DriverAdapter::binders_for trait method — every adapter has to either declare its binders or explicitly acknowledge it has none. Default no-op declarations are forbidden by trait design so the question can’t be skipped silently.

Pre-canned binder patterns

Three Binder variants cover the protocol shapes seen so far: positional (CQL ? placeholders, ordinal RPC params), named (CQL :name, JSON-RPC), and single-value (one whole field bound as one typed value).

Structs

BinderSlot

One slot in a binder.

BinderViolation

One wire-type-vs-lvalue-type mismatch found by verify_binders.

Enums

Binder

One adapter-declared binding shape for one op-template field.

Functions

verify_against_kernel

Verify binders against a crate::kernel::PolydatKernel directly, returning Ok(()) when every slot’s rvalue→lvalue check passes and Err(Vec<BinderViolation>) listing every failure otherwise.

verify_binders

Every slot whose wire type cannot satisfy its lvalue type, given a lookup from wire name to the program’s type for it.