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 each binder slot’s rvalue (wire) type against its declared lvalue type, using the lookup closure to resolve wire names to their PortType. The closure returns None for unknown wires.

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.