Module cursor_partition 

Cursor partition specs — SRD 71.

Value types and a small spec language following the token grammar chunking [in window] [order]:

• PartitionSpec — the parsed-but-unresolved form of a cursor=... argument: a Chunking (Form 1 single sub-range, Form 2 delta list, or Form 3 pre-baked recipe, as typed Bounds), an optional in start..end window, and a PartitionOrder.
• Partition — a single resolved partition with concrete absolute ordinals, computed by resolve from a PartitionSpec against a known base extent.

The parser and resolution math live here; the DSL over clause and cursor source factory integration live in their own modules. The Polydat Value integration rides on the existing Value::Ext / ReflectedValue mechanism — see the impls below.

Structs

Partition

A single resolved partition: an absolute ordinal range with derived percentage and index metadata.

PartitionList

A list of resolved partitions carried as a single Polydat value.

PartitionSpec

Parsed cursor=... argument:

Enums

Bound

One numeric boundary or list token inside a partition spec. The forms are distinguished syntactically at parse time:

Chunking

The chunking part of a spec — the shape that carves a domain into partitions. Two shapes:

PartitionOrder

Iteration order for a resolved partition list — the optional trailing keyword of a spec ("fib:5 largest_first").

Functions

cursor_extent

The extent a cursor resolves partitions against: the schema’s static extent when known, otherwise the difference of its extent outputs pulled from state.

cursor_extent_on

cursor_extent through the Kernel trait, for a kernel on any engine.

cursor_over_partitions

Resolve the partitions a cursor’s over clause denotes: the list the compiler resolved at build when the clause and the extent were constant, otherwise the raw over value pulled from state against the extent. Returns an empty list for a cursor without an over clause. The interpreter-state form of cursor_over_partitions_on, which does the same on a kernel of any engine.

cursor_over_partitions_on

cursor_over_partitions through the Kernel trait, for a kernel on any engine.

cursor_slot_writes

The inputs narrowing a cursor to one partition writes, by name: the <cursor>__cursor slot and its six scalar projections. This is what narrow_cursor writes on the interpreter and set_cursor on every compiled kernel.

narrow_cursor

Write one resolved partition into a cursor’s <cursor>__cursor slot and its six scalar projection slots. Slots the program does not declare are skipped. The interpreter-state form of set_cursor on the Kernel trait, which does the same on a kernel of any engine.

parse

Parse a cursor=... spec string into a PartitionSpec.

resolve

Resolve a PartitionSpec against a cursor’s base extent [base_start, base_end), producing a list of concrete Partitions with absolute ordinals.

resolve_over

Resolve the value of an over expression into the partitions it denotes, against a cursor of extent ordinals.

split_evenly

Split [start_ord, end_ord) into n contiguous half-open chunks whose sizes differ by at most one ordinal. Boundary i sits at start_ord + round(i * span / n), so the rounding slack is distributed across the chunks rather than accumulating in the last one. n must be >= 1.

subdivide_partition

Split a resolved Partition into n contiguous sub-partitions whose sizes differ by at most one ordinal — the value-level form of the */N spec token (identical boundary math via split_evenly). Indices restart at 0, count is n, base_extent propagates, and the pct fields interpolate the parent’s span.