effect-dynamodb 1.36.0 → 1.37.0

package/dist/internal/RangePlanner.js

@@ -0,0 +1,1296 @@
+/**
+ * @internal RangePlanner — the pure half of a planned query (#171, design §9).
+ *
+ * A planner never sends a request. It turns a plan and each response into the
+ * next *step* — a `Read` of one key range, a `Probe` that locates where to read
+ * next, or `Done` — and the terminal's loop (`Query.ts`) sends every request,
+ * so every request counts against `maxPages`, is observed by `onRequest` and
+ * is never sent once the call is about to return.
+ *
+ * Plans over a composite sort key (§7):
+ *
+ * - `key` — the bounds reach the key condition directly: one range.
+ * - `skip-scan` — composites left of the first bound have no bound (the
+ *   *skip tuple*): a probe (`Limit: 1`) finds each distinct tuple `T`, then
+ *   `T`'s own range is read, then a probe from just past `T`, and so on.
+ * - `filter` — one range over everything under the pinned prefix, every bound
+ *   checked per row: when skip-scan is not sound (§7.3), after the probe budget
+ *   is spent (§7.4) or at a key the tuple parse can't read.
+ *
+ * Plans over a Z-order sort key (§5): inside each prefix tuple, `naive` reads
+ * the box's hull, `jump` follows the last examined key to the next in-box
+ * address, `precise` reads a capped range plan; a missing prefix composite is
+ * walked by a binary skip-scan (§7.5).
+ *
+ * Positions are what a cursor records (§10): what has been **completed**, never
+ * a range to trust. Resume recomputes the plan and places the position in it.
+ */
+import { KEY_DELIMITER } from "@effect-dynamodb/schema/DynamoSchema.js";
+import { ValidationError } from "@effect-dynamodb/schema/Errors.js";
+import { bigmin, concatBytes, corners, fromBytes, inBox, litmax, nextInBox, prevInBox, REFINE_FACTOR, succ, toBytes, } from "@effect-dynamodb/schema/internal/ZOrderCurve.js";
+import * as Cursor from "./Cursor.js";
+import { compileExpr } from "./Expr.js";
+/** Default skip-scan probe budget per terminal call (§7.4). */
+export const DEFAULT_MAX_SKIPS = 32;
+/** Default range cap of a Z-order `precise` plan and of `auto`'s choice (§3.4). */
+export const DEFAULT_MAX_RANGES = 16;
+/** A jump run's first `Limit`, and what it resets to after a jump (§8.5). */
+export const JUMP_INITIAL = 16;
+/** The largest `Limit` a jump run grows to (§8.5). */
+export const JUMP_MAX_LIMIT = 1_000;
+// ---------------------------------------------------------------------------
+// Key values: order, display, conditions
+// ---------------------------------------------------------------------------
+/**
+ * `SK_MAX_SENTINEL` (`DynamoClient.ts`): above every character key
+ * composition emits, so `prefix + MAX` bounds every key under `prefix`.
+ */
+export const KEY_MAX = "￿";
+const encoder = new TextEncoder();
+const compareBytes = (a, b) => {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    }
+    return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+};
+/**
+ * Order two key values as DynamoDB does: by UTF-8 bytes. For text that is
+ * code point order, which JS string comparison (UTF-16 code units) is not
+ * above U+FFFF — so it is never used for keys.
+ */
+export const compareUtf8 = (a, b) => {
+    if (typeof a !== "string" || typeof b !== "string") {
+        return compareBytes(typeof a === "string" ? encoder.encode(a) : a, typeof b === "string" ? encoder.encode(b) : b);
+    }
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        const x = a.codePointAt(i);
+        const y = b.codePointAt(j);
+        if (x !== y)
+            return x < y ? -1 : 1;
+        i += x > 0xffff ? 2 : 1;
+        j += y > 0xffff ? 2 : 1;
+    }
+    return i < a.length ? 1 : j < b.length ? -1 : 0;
+};
+/**
+ * The highest code point: above every character a key can hold but itself.
+ * Where the text after a prefix is a value's own (no label precedes it),
+ * `prefix + KEY_TOP` bounds every key under the prefix; {@link KEY_MAX} does
+ * not, since an emoji (UTF-8 `F0 …`) outsorts it.
+ */
+export const KEY_TOP = String.fromCodePoint(0x10ffff);
+/**
+ * An inclusive high end for a strict `<` on key text: below `key`, and at or
+ * above every key below `key` that does not hold U+10FFFF. Its last code
+ * point is stepped down one (past the surrogates) and followed by U+10FFFF: a
+ * key below `key` either stops short of it — a prefix, which the bound keeps —
+ * or is smaller at some character, and from there sorts under the bound. A
+ * last code point of U+0000 has no predecessor; `key` without it is then the
+ * bound. (U+10FFFF rather than {@link KEY_MAX}, which an emoji outsorts.)
+ */
+export const keyJustBelow = (key) => {
+    const width = key.length > 1 && key.codePointAt(key.length - 2) > 0xffff ? 2 : 1;
+    const head = key.slice(0, key.length - width);
+    const last = key.codePointAt(key.length - width);
+    if (last === undefined || last === 0)
+        return head;
+    const previous = last - 1 >= 0xd800 && last - 1 <= 0xdfff ? 0xd7ff : last - 1;
+    return `${head}${String.fromCodePoint(previous)}${KEY_TOP}`;
+};
+const startsWithKey = (value, prefix) => {
+    if (typeof value === "string" && typeof prefix === "string")
+        return value.startsWith(prefix);
+    const v = typeof value === "string" ? encoder.encode(value) : value;
+    const p = typeof prefix === "string" ? encoder.encode(prefix) : prefix;
+    return p.length <= v.length && compareBytes(v.subarray(0, p.length), p) === 0;
+};
+/** Does `value` satisfy a sort key condition, as DynamoDB evaluates it? */
+export const keyConditionHolds = (condition, value) => {
+    if ("eq" in condition)
+        return compareUtf8(value, condition.eq) === 0;
+    if ("lt" in condition)
+        return compareUtf8(value, condition.lt) < 0;
+    if ("lte" in condition)
+        return compareUtf8(value, condition.lte) <= 0;
+    if ("gt" in condition)
+        return compareUtf8(value, condition.gt) > 0;
+    if ("gte" in condition)
+        return compareUtf8(value, condition.gte) >= 0;
+    if ("between" in condition) {
+        return (compareUtf8(value, condition.between[0]) >= 0 && compareUtf8(value, condition.between[1]) <= 0);
+    }
+    return startsWithKey(value, condition.beginsWith);
+};
+const isEmptyKey = (value) => value.length === 0;
+/**
+ * The key condition a read of `range` sends; `undefined` reads the whole
+ * partition. A zero-length operand is a defect: DynamoDB rejects it, and no
+ * plan should ever compose one.
+ */
+export const toKeyCondition = (range) => {
+    const condition = range.beginsWith !== undefined
+        ? { beginsWith: range.beginsWith }
+        : range.lower !== undefined && range.upper !== undefined
+            ? compareUtf8(range.lower, range.upper) === 0
+                ? { eq: range.lower }
+                : { between: [range.lower, range.upper] }
+            : range.lower !== undefined
+                ? { gte: range.lower }
+                : range.upper !== undefined
+                    ? { lte: range.upper }
+                    : undefined;
+    const operands = condition === undefined
+        ? []
+        : "between" in condition
+            ? condition.between
+            : [Object.values(condition)[0]];
+    if (operands.some(isEmptyKey)) {
+        throw new Error("[internal] A planned key condition has a zero-length operand, which DynamoDB rejects.");
+    }
+    return condition;
+};
+/** Is `value` inside `range` (as its key condition selects)? */
+export const rangeContains = (range, value) => {
+    const condition = toKeyCondition(range);
+    return condition === undefined || keyConditionHolds(condition, value);
+};
+/** A key value as `explain` and `onRequest` show it: text as is, bytes as `0x…` hex. */
+export const displayKeyValue = (value) => {
+    if (typeof value === "string")
+        return value;
+    let hex = "0x";
+    for (const byte of value)
+        hex += byte.toString(16).padStart(2, "0");
+    return hex;
+};
+/**
+ * The display bounds of a sort key condition: `eq` as `[v, v]`, `between` as
+ * `[a, b]`, one-sided operators open on the other side, `begins_with` as
+ * `[prefix, undefined]`, none as `[undefined, undefined]`.
+ */
+export const displayKeyCondition = (condition) => {
+    if (condition === undefined)
+        return [undefined, undefined];
+    const show = displayKeyValue;
+    if ("eq" in condition)
+        return [show(condition.eq), show(condition.eq)];
+    if ("between" in condition)
+        return [show(condition.between[0]), show(condition.between[1])];
+    if ("gt" in condition)
+        return [show(condition.gt), undefined];
+    if ("gte" in condition)
+        return [show(condition.gte), undefined];
+    if ("lt" in condition)
+        return [undefined, show(condition.lt)];
+    if ("lte" in condition)
+        return [undefined, show(condition.lte)];
+    return [show(condition.beginsWith), undefined];
+};
+// ---------------------------------------------------------------------------
+// Fingerprint (§10.3)
+// ---------------------------------------------------------------------------
+/** JSON with every object's keys sorted, so equal inputs give equal text. */
+export const canonicalJson = (value) => {
+    if (value instanceof Uint8Array)
+        return JSON.stringify(displayKeyValue(value));
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+    }
+    if (typeof value === "bigint")
+        return JSON.stringify(value.toString());
+    return JSON.stringify(value) ?? "null";
+};
+/**
+ * An expression as `explain` shows it: its compiled text with every name and
+ * value placeholder replaced by what it stands for.
+ */
+export const displayExpr = (expr) => {
+    const compiled = compileExpr(expr);
+    const shown = (value) => value.S !== undefined
+        ? JSON.stringify(value.S)
+        : value.N !== undefined
+            ? value.N
+            : value.BOOL !== undefined
+                ? String(value.BOOL)
+                : JSON.stringify(value);
+    return compiled.expression.replace(/[#:]e\d+/g, (placeholder) => placeholder.startsWith("#")
+        ? (compiled.names[placeholder] ?? placeholder)
+        : compiled.values[placeholder] === undefined
+            ? placeholder
+            : shown(compiled.values[placeholder]));
+};
+/** FNV-1a (32-bit) of `text`'s UTF-8 bytes, as 8 hex digits. */
+export const fnv1a32 = (text) => {
+    let hash = 0x811c9dc5;
+    for (const byte of encoder.encode(text)) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+};
+// ---------------------------------------------------------------------------
+// Step helpers
+// ---------------------------------------------------------------------------
+/**
+ * `[EDD-9094]`: a cursor that doesn't belong to the query it was given to —
+ * malformed, from another query, or a position outside the recomputed plan.
+ * Raised by the terminal (cursors are decoded there), never by `startFrom`.
+ */
+export const cursorRefusal = (entityType, why) => new ValidationError({
+    entityType,
+    operation: "query.startFrom",
+    cause: `[EDD-9094] The cursor does not belong to this query: ${why}. A cursor resumes only ` +
+        `the query that returned it — the same index, pinned composites, .within() bounds ` +
+        `and direction.`,
+});
+/**
+ * `step` resumed after `startKey`: what a read that returned a
+ * `LastEvaluatedKey`, or stopped inside its page, continues with. A filter
+ * read's position drops its tuple — `ExclusiveStartKey` alone places it.
+ */
+export const readFrom = (step, startKey) => ({
+    ...step,
+    startKey,
+    at: {
+        ...step.at,
+        tuple: step.at.mode === "filter" ? undefined : step.at.tuple,
+        boundary: { _tag: "At", startKey },
+    },
+});
+const done = { _tag: "Done" };
+const estimator = { _tag: "estimator" };
+/** The cursor of a plan with this fingerprint at `step` (§10.1): its position, or `null` once done. */
+const positionCursor = (fingerprint, step) => {
+    if (step._tag === "Done")
+        return null;
+    const at = step.at;
+    const boundary = at.boundary;
+    return {
+        v: 2,
+        f: fingerprint,
+        s: at.mode,
+        ...(at.tuple === undefined ? {} : { t: Cursor.keyValueToWire(at.tuple) }),
+        ...(boundary._tag === "At"
+            ? { k: Cursor.keyToWire(boundary.startKey) ?? {} }
+            : boundary._tag === "Through"
+                ? { a: Cursor.keyValueToWire(boundary.through) }
+                : boundary._tag === "TupleDone"
+                    ? { d: 1 }
+                    : {}),
+        ...(at.pass === undefined ? {} : { p: at.pass }),
+    };
+};
+/** A planned range as `explain` shows it. */
+const shownRange = (range) => {
+    const [lower, upper] = displayKeyCondition(toKeyCondition(range));
+    return { lower, upper, exact: range.exact };
+};
+/**
+ * A planner for a composite sort key plan. `start` places a cursor in the
+ * recomputed plan (§10.3): string ranges are kept or dropped whole, never cut.
+ */
+export const compositePlanner = (spec) => ({ reverse, maxSkips }) => {
+    const space = spec.space;
+    const fingerprint = fnv1a32(canonicalJson({ plan: spec.fingerprint, reverse }));
+    const P = spec.filterPlan.prefix;
+    const UPPER = `${P}${KEY_MAX}`;
+    const tupled = space._tag === "string";
+    const mode = spec.inner.empty
+        ? "empty"
+        : !tupled
+            ? "key"
+            : spec.ineligible !== undefined || maxSkips === 0
+                ? "filter"
+                : "skip-scan";
+    const reason = spec.inner.empty
+        ? "the bounds admit no value"
+        : space._tag === "none"
+            ? "leading composites bounded"
+            : (spec.ineligible ??
+                (maxSkips === 0 ? "maxSkips: 0" : `skip tuple: ${space.fields.join(", ")}`));
+    const refuse = (why) => cursorRefusal(spec.entityType, why);
+    // -- tuples (§7.2) --
+    const tupleOf = (key) => {
+        if (space._tag !== "string" || !key.startsWith(space.prefix))
+            return undefined;
+        let pos = space.prefix.length;
+        for (const label of space.labels) {
+            if (!key.startsWith(label, pos))
+                return undefined;
+            const end = key.indexOf(KEY_DELIMITER, pos + label.length);
+            if (end < 0)
+                return undefined;
+            pos = end + 1;
+        }
+        return key.startsWith(space.next, pos) ? key.slice(0, pos) : undefined;
+    };
+    /** Just above every key under `tuple`: its delimiter (`#`) bumped to the next character. */
+    const successor = (tuple) => `${tuple.slice(0, -1)}${String.fromCharCode(KEY_DELIMITER.charCodeAt(0) + 1)}`;
+    // -- steps --
+    const read = (at, range, startKey, rowCheck) => ({
+        _tag: "Read",
+        at: startKey === undefined ? at : { ...at, boundary: { _tag: "At", startKey } },
+        range,
+        startKey,
+        planIndex: undefined,
+        sizing: estimator,
+        rowCheck,
+    });
+    const keyRead = (boundary, startKey) => read({ mode: "key", tuple: undefined, boundary, skips: 0 }, spec.inner.conditionFor(undefined), startKey, spec.inner.rowCheck);
+    const tupleRead = (tuple, boundary, skips, startKey) => read({ mode: "skip-scan", tuple, boundary, skips }, spec.inner.conditionFor(tuple), startKey, spec.inner.rowCheck);
+    /** The filter range from a position: past its finished tuple, or all of `P`. */
+    const filterRange = (tuple) => {
+        const after = typeof tuple === "string" ? tuple : undefined;
+        return reverse
+            ? { lower: P, upper: after ?? UPPER, exact: spec.filterPlan.rowCheck === undefined }
+            : {
+                lower: after === undefined ? P : successor(after),
+                upper: UPPER,
+                exact: spec.filterPlan.rowCheck === undefined,
+            };
+    };
+    const filterRead = (from, startKey) => read({ ...from, mode: "filter", tuple: startKey === undefined ? from.tuple : undefined }, startKey === undefined ? filterRange(from.tuple) : filterRange(undefined), startKey, spec.filterPlan.rowCheck);
+    /** The next probe from `from` — or, once the budget is spent, the filter plan (§7.4). */
+    const probeFrom = (from) => {
+        if (from.skips >= maxSkips)
+            return filterRead(from);
+        const tuple = typeof from.tuple === "string" ? from.tuple : undefined;
+        return {
+            _tag: "Probe",
+            at: { ...from, mode: "skip-scan", skips: from.skips + 1 },
+            lower: reverse ? P : tuple === undefined ? P : successor(tuple),
+            upper: reverse ? (tuple ?? UPPER) : UPPER,
+        };
+    };
+    const fresh = (tuple, boundary) => ({
+        mode,
+        tuple,
+        boundary,
+        skips: 0,
+    });
+    const initial = () => mode === "empty"
+        ? done
+        : mode === "key"
+            ? keyRead({ _tag: "Start" })
+            : mode === "filter"
+                ? filterRead(fresh(undefined, { _tag: "Start" }))
+                : probeFrom(fresh(undefined, { _tag: "Start" }));
+    // -- resume (§10.3) --
+    /** `k` as a start key, when it lies in `range` under this partition. */
+    const startKeyIn = (key, range) => {
+        const pk = key[spec.pkField];
+        const sk = key[spec.skField];
+        if (pk === undefined || !("S" in pk) || pk.S !== spec.pkValue) {
+            return refuse("its key is in another partition");
+        }
+        const skValue = sk === undefined ? undefined : Cursor.wireToKeyValue(sk);
+        if (skValue === undefined || !rangeContains(range, skValue)) {
+            return refuse("its key is outside the recomputed plan");
+        }
+        return Cursor.keyFromWire(key);
+    };
+    /**
+     * Where `through` leaves a string range: entirely before it (`dropped`),
+     * entirely after it (`kept`), or across it, which no string plan's cursor
+     * can be (§10.3).
+     */
+    const clip = (range, through) => {
+        const p = range.beginsWith;
+        const before = (value) => compareUtf8(through, value) < 0;
+        const after = (value) => compareUtf8(through, value) > 0;
+        // Every key in the range is past `through` in scan direction?
+        const allPast = p !== undefined
+            ? reverse
+                ? after(p) && !startsWithKey(through, p)
+                : before(p)
+            : reverse
+                ? range.upper !== undefined && after(range.upper)
+                : range.lower !== undefined && before(range.lower);
+        if (allPast)
+            return "kept";
+        // …or none of them is?
+        const nonePast = p !== undefined
+            ? reverse
+                ? !after(p)
+                : after(p) && !startsWithKey(through, p)
+            : reverse
+                ? range.lower !== undefined && !after(range.lower)
+                : range.upper !== undefined && !before(range.upper);
+        return nonePast ? "dropped" : "straddle";
+    };
+    const start = (cursor) => {
+        if (cursor === undefined)
+            return initial();
+        if (cursor.f === undefined) {
+            // A legacy cursor, or a plain query's `{ k }`: a position inside a single range.
+            if (mode !== "key") {
+                return refuse(`it comes from a query without .within(), and this plan is ${mode}`);
+            }
+            if (cursor.k === undefined || cursor.s !== undefined || cursor.t !== undefined) {
+                return refuse("it carries no position in this plan");
+            }
+            const startKey = startKeyIn(cursor.k, spec.inner.conditionFor(undefined));
+            return startKey instanceof ValidationError
+                ? startKey
+                : keyRead({ _tag: "At", startKey }, startKey);
+        }
+        if (cursor.f !== fingerprint)
+            return refuse("its plan fingerprint differs");
+        // Nothing to resume: no cursor of an empty plan is ever handed out.
+        if (mode === "empty")
+            return done;
+        const s = cursor.s;
+        if (s === undefined ||
+            !(s === "key"
+                ? !tupled
+                : s === "filter"
+                    ? tupled
+                    : s === "skip-scan" && tupled && spec.ineligible === undefined)) {
+            return refuse(`its plan (${s ?? "none"}) can't continue as ${mode}`);
+        }
+        let tuple;
+        if (cursor.t !== undefined) {
+            const t = "S" in cursor.t ? cursor.t.S : undefined;
+            if (t === undefined || space._tag !== "string" || tupleOf(`${t}${space.next}`) !== t) {
+                return refuse("its skip tuple is not one of this plan's");
+            }
+            tuple = t;
+        }
+        const position = (boundary) => ({
+            mode: s,
+            tuple,
+            boundary,
+            skips: 0,
+        });
+        if (cursor.k !== undefined) {
+            if (s === "filter") {
+                if (tuple !== undefined)
+                    return refuse("a filter position inside a tuple");
+                const startKey = startKeyIn(cursor.k, filterRange(undefined));
+                return startKey instanceof ValidationError
+                    ? startKey
+                    : filterRead(position({ _tag: "At", startKey }), startKey);
+            }
+            if (s === "skip-scan" && tuple === undefined)
+                return refuse("a key outside any tuple");
+            const range = spec.inner.conditionFor(tuple);
+            const startKey = startKeyIn(cursor.k, range);
+            if (startKey instanceof ValidationError)
+                return startKey;
+            return s === "key"
+                ? keyRead({ _tag: "At", startKey }, startKey)
+                : tupleRead(tuple, { _tag: "At", startKey }, 0, startKey);
+        }
+        if (cursor.a !== undefined) {
+            const through = Cursor.wireToKeyValue(cursor.a);
+            if (through === undefined || s === "filter" || (s === "skip-scan" && tuple === undefined)) {
+                return refuse("its 'through' position is not one of this plan's");
+            }
+            const clipped = clip(spec.inner.conditionFor(tuple), through);
+            if (clipped === "straddle")
+                return refuse("its position cuts a range of this plan");
+            const boundary = { _tag: "Through", through };
+            if (s === "key")
+                return clipped === "kept" ? keyRead(boundary) : done;
+            return clipped === "kept"
+                ? tupleRead(tuple, boundary, 0)
+                : probeFrom(position({ _tag: "TupleDone" }));
+        }
+        if (cursor.d !== undefined) {
+            if (tuple === undefined)
+                return refuse("a finished tuple without the tuple");
+            return s === "filter"
+                ? filterRead(position({ _tag: "TupleDone" }))
+                : probeFrom(position({ _tag: "TupleDone" }));
+        }
+        // Start: of tuple `t`, or of the plan.
+        if (tuple !== undefined) {
+            return s === "skip-scan"
+                ? tupleRead(tuple, { _tag: "Start" }, 0)
+                : refuse("a filter position at the start of a tuple");
+        }
+        return s === "key"
+            ? keyRead({ _tag: "Start" })
+            : s === "filter"
+                ? filterRead(position({ _tag: "Start" }))
+                : probeFrom(position({ _tag: "Start" }));
+    };
+    // -- transitions --
+    const afterRead = (step, lastEvaluatedKey) => {
+        if (lastEvaluatedKey !== undefined)
+            return readFrom(step, lastEvaluatedKey);
+        return step.at.mode === "skip-scan"
+            ? probeFrom({ ...step.at, boundary: { _tag: "TupleDone" } })
+            : done;
+    };
+    const afterProbe = (step, key) => {
+        if (key === undefined)
+            return done;
+        const tuple = typeof key === "string" ? tupleOf(key) : undefined;
+        const previous = typeof step.at.tuple === "string" ? step.at.tuple : undefined;
+        // A key the parse can't read — or, defensively, a tuple that doesn't
+        // advance — leaves the rest to the filter plan, from where the probe began.
+        if (tuple === undefined ||
+            (previous !== undefined &&
+                (reverse ? compareUtf8(tuple, previous) >= 0 : compareUtf8(tuple, previous) <= 0))) {
+            return filterRead(step.at);
+        }
+        return tupleRead(tuple, { _tag: "Start" }, step.at.skips);
+    };
+    // -- cursors and explain --
+    const cursor = (step) => positionCursor(fingerprint, step);
+    const rowCheck = mode === "filter" ? spec.filterPlan.rowCheck : spec.inner.rowCheck;
+    const explain = (sizing) => ({
+        index: spec.index,
+        plan: mode,
+        reason,
+        // The ranges known before anything is read: the key plan's one range,
+        // or the span the probes (or the filter read) walk.
+        keyConditions: mode === "empty"
+            ? []
+            : mode === "key"
+                ? [shownRange(spec.inner.conditionFor(undefined))]
+                : [{ lower: P, upper: UPPER, exact: false }],
+        filter: undefined,
+        rowChecks: rowCheck?.fields ?? [],
+        sizing,
+        ...(mode === "skip-scan" ? { maxSkips } : {}),
+    });
+    return {
+        fingerprint,
+        mode,
+        filter: undefined,
+        rowCheck,
+        start,
+        afterRead,
+        afterProbe,
+        following: () => [],
+        cursor,
+        explain,
+    };
+};
+/** The key range of a pass's condition: its inclusive forms. */
+const passRange = (condition) => {
+    if (condition === undefined)
+        return { lower: undefined, upper: undefined, exact: true };
+    if ("beginsWith" in condition) {
+        return { lower: undefined, upper: undefined, beginsWith: condition.beginsWith, exact: true };
+    }
+    if ("eq" in condition)
+        return { lower: condition.eq, upper: condition.eq, exact: true };
+    if ("between" in condition) {
+        return { lower: condition.between[0], upper: condition.between[1], exact: true };
+    }
+    if ("gte" in condition)
+        return { lower: condition.gte, upper: undefined, exact: true };
+    if ("lte" in condition)
+        return { lower: undefined, upper: condition.lte, exact: true };
+    throw new Error("[internal] A key pass reads its pins: a strict bound has no 1.36 pass.");
+};
+/**
+ * A planner reading a query's own key and the key 1.36 composed for the same
+ * pins, one after the other (#171): rows 1.36 wrote whose key text changed
+ * stay under the 1.36 key until they are written again or `rekey` moves
+ * them. Those are the older rows, so a forward read takes the 1.36 key first
+ * and `.reverse()` takes it last; each key is read in the query's direction.
+ * The plan is `key`. When both keys are in one partition, a read of the 1.36
+ * key drops the rows the current key selects too (a value whose 1.36 text
+ * prefixes its escaped text: `50%` of `50%25`), so no row is read twice.
+ *
+ * A position is the start of a pass or a key inside one; its cursor names the
+ * pass in `p`. A cursor without a fingerprint (a plain query's `{ k }`, from
+ * before the fallback had anything to read, or from 1.36) is placed by its
+ * key: in the 1.36 pass when the key lies under the 1.36 key and not the
+ * current one.
+ */
+export const keyPassesPlanner = (spec) => ({ reverse }) => {
+    const keyOf = (pass) => ({ pkValue: pass.pkValue, condition: pass.condition });
+    const fingerprint = fnv1a32(canonicalJson({
+        passes: { current: keyOf(spec.current), legacy: keyOf(spec.legacy) },
+        reverse,
+    }));
+    const order = reverse ? [0, 1] : [1, 0];
+    const passOf = (pass) => (pass === 1 ? spec.legacy : spec.current);
+    const refuse = (why) => cursorRefusal(spec.entityType, why);
+    const skField = spec.skField;
+    const currentCondition = spec.current.condition;
+    const samePartition = spec.legacy.pkValue === spec.current.pkValue;
+    /** Does a sort key lie under the current pass's condition? */
+    const inCurrent = (key) => currentCondition === undefined || keyConditionHolds(currentCondition, key);
+    /** In one partition: the 1.36 read leaves the current key's rows to the current read. */
+    const dedupe = samePartition && skField !== undefined
+        ? {
+            fields: [],
+            reads: [skField],
+            accepts: (row) => {
+                const value = row[skField];
+                const key = value?.S ?? value?.B;
+                if (key === undefined)
+                    return true;
+                return currentCondition !== undefined && !keyConditionHolds(currentCondition, key);
+            },
+        }
+        : undefined;
+    const rows = spec.legacy.rows;
+    const reads = rows === undefined
+        ? []
+        : [...new Set([spec.pkField, ...(skField === undefined ? [] : [skField]), ...rows.reads])];
+    /** Is the row stored at this key? */
+    const storedAt = (row, key) => row[spec.pkField]?.S === key.pk && (skField === undefined || row[skField]?.S === key.sk);
+    /** A row the current read keeps: stored at its key now, or at no value's 1.36 text. */
+    const currentAccepts = (rows, row) => {
+        const composed = rows.composed(row);
+        if (composed === undefined || storedAt(row, composed))
+            return true;
+        if (rows.composed136 === undefined)
+            return false;
+        const own136 = rows.composed136(row);
+        return own136 === undefined || !storedAt(row, own136);
+    };
+    /** Does this row's stored sort key lie under the current pass's condition? */
+    const inCurrentRange = (row) => {
+        const value = skField === undefined ? undefined : row[skField];
+        const key = value?.S ?? value?.B;
+        return key !== undefined && inCurrent(key);
+    };
+    /** The current read's row check: not another value's row under the current key. */
+    const currentCheck = rows === undefined
+        ? undefined
+        : { fields: [], reads, accepts: (row) => currentAccepts(rows, row) };
+    /** The 1.36 read's row check: a row stored elsewhere whose key now the current read selects. */
+    const legacyCheck = rows === undefined
+        ? dedupe
+        : {
+            fields: [],
+            reads,
+            accepts: (row) => {
+                const composed = rows.composed(row);
+                if (composed === undefined)
+                    return dedupe === undefined || dedupe.accepts(row);
+                if (storedAt(row, composed))
+                    return false;
+                // Both ranges hold it, in one partition: the current read returned it.
+                if (samePartition && inCurrentRange(row) && currentAccepts(rows, row))
+                    return false;
+                if (composed.pk !== spec.current.pkValue)
+                    return false;
+                return composed.sk === undefined || inCurrent(composed.sk);
+            },
+        };
+    const checkOf = (pass) => (pass === 1 ? legacyCheck : currentCheck);
+    const read = (pass, boundary, startKey) => ({
+        _tag: "Read",
+        at: {
+            mode: "key",
+            tuple: undefined,
+            boundary: startKey === undefined ? boundary : { _tag: "At", startKey },
+            skips: 0,
+            pass,
+        },
+        range: passRange(passOf(pass).condition),
+        pkValue: pass === 1 ? spec.legacy.pkValue : undefined,
+        startKey,
+        planIndex: undefined,
+        sizing: estimator,
+        rowCheck: checkOf(pass),
+    });
+    /** Does `key` lie in `pass` — its partition, and the range its condition selects? */
+    const inPass = (key, pass) => {
+        const pk = key[spec.pkField];
+        if (pk === undefined || !("S" in pk) || pk.S !== passOf(pass).pkValue)
+            return false;
+        if (skField === undefined)
+            return true;
+        const sk = key[skField];
+        const value = sk === undefined ? undefined : Cursor.wireToKeyValue(sk);
+        if (value === undefined)
+            return false;
+        const condition = passOf(pass).condition;
+        return condition === undefined || keyConditionHolds(condition, value);
+    };
+    const start = (cursor) => {
+        if (cursor === undefined)
+            return read(order[0], { _tag: "Start" });
+        if (cursor.f === undefined) {
+            // A plain query's `{ k }`, or 1.36's: placed by its key.
+            if (cursor.k === undefined || cursor.s !== undefined || cursor.t !== undefined) {
+                return refuse("it carries no position in this plan");
+            }
+            // Under both keys (one partition): the current pass's.
+            const pass = inPass(cursor.k, 1) && !(samePartition && inPass(cursor.k, 0))
+                ? 1
+                : inPass(cursor.k, 0)
+                    ? 0
+                    : undefined;
+            if (pass === undefined)
+                return refuse("its key is outside the recomputed plan");
+            const startKey = Cursor.keyFromWire(cursor.k);
+            return read(pass, { _tag: "At", startKey }, startKey);
+        }
+        if (cursor.f !== fingerprint)
+            return refuse("its plan fingerprint differs");
+        if (cursor.s !== "key" || cursor.t !== undefined || cursor.a !== undefined) {
+            return refuse("its position is not one of this plan's");
+        }
+        if (cursor.d !== undefined)
+            return refuse("its position is not one of this plan's");
+        const pass = cursor.p ?? order[0];
+        if (cursor.k === undefined)
+            return read(pass, { _tag: "Start" });
+        if (!inPass(cursor.k, pass))
+            return refuse("its key is outside the recomputed plan");
+        const startKey = Cursor.keyFromWire(cursor.k);
+        return read(pass, { _tag: "At", startKey }, startKey);
+    };
+    const afterRead = (step, lastEvaluatedKey) => {
+        if (lastEvaluatedKey !== undefined)
+            return readFrom(step, lastEvaluatedKey);
+        const next = order[order.indexOf(step.at.pass ?? 0) + 1];
+        return next === undefined ? done : read(next, { _tag: "Start" });
+    };
+    const explain = (sizing) => ({
+        index: spec.index,
+        plan: "key",
+        reason: "one key condition, and the 1.36 key of rows not yet moved",
+        keyConditions: order.map((pass) => ({
+            ...shownRange(passRange(passOf(pass).condition)),
+            exact: checkOf(pass) === undefined,
+        })),
+        filter: undefined,
+        rowChecks: [],
+        sizing,
+    });
+    return {
+        fingerprint,
+        mode: "key",
+        filter: undefined,
+        rowCheck: checkOf(order[0]),
+        start,
+        afterRead,
+        afterProbe: () => done,
+        following: () => [],
+        cursor: (step) => positionCursor(fingerprint, step),
+        explain,
+    };
+};
+/** `bytes`, unless empty: DynamoDB rejects a zero-length key operand (`EmptyKeyBound`). */
+const nonEmpty = (bytes) => bytes === undefined || bytes.length === 0 ? undefined : bytes;
+const startsWithBytes = (value, prefix) => prefix.length <= value.length && compareBytes(value.subarray(0, prefix.length), prefix) === 0;
+/**
+ * A planner for a Z-order sort key plan. Inside each tuple `T` (the given
+ * prefix, or each one a binary skip-scan finds), a range `[lo, hi]` of
+ * addresses is read as `BETWEEN T‖lo AND T‖hi`; the strategy decides which
+ * ranges (§5.5). `start` places a cursor by clipping the recomputed plan at
+ * its address (§10.3), so a cursor resumes under any `maxRanges` or
+ * strategy.
+ */
+export const zorderPlanner = (spec) => ({ reverse, maxSkips, zorder }) => {
+    const { layout, box } = spec;
+    const W = layout.bytes;
+    const MAXZ = (1n << BigInt(layout.bits)) - 1n;
+    const P = spec.prefix;
+    const succP = succ(P);
+    const tupled = spec.tuple.length > 0;
+    const maxRanges = zorder?.maxRanges ?? DEFAULT_MAX_RANGES;
+    const fingerprint = fnv1a32(canonicalJson({ plan: spec.fingerprint, reverse }));
+    const refuse = (why) => cursorRefusal(spec.entityType, why);
+    // -- the strategy (§5.6) --
+    const [strategy, why] = box === "empty"
+        ? ["empty", "empty box"]
+        : !spec.bounded
+            ? ["key", "no dimension bounded"]
+            : zorder?.strategy !== undefined && zorder.strategy !== "auto"
+                ? [zorder.strategy, "explicit strategy"]
+                : spec.ranges(maxRanges, 1).exact
+                    ? ["precise", "exact plan fits maxRanges"]
+                    : ["jump", "exact plan over maxRanges"];
+    const mode = strategy === "empty" ? "empty" : !tupled ? strategy : maxSkips === 0 ? "filter" : "skip-scan";
+    const reason = !tupled || strategy === "empty"
+        ? why
+        : maxSkips === 0
+            ? "maxSkips: 0"
+            : `skip tuple: ${spec.tuple.map((segment) => segment.field).join(", ")}; ${strategy} ` +
+                `inside each tuple (${why})`;
+    /** The mode a read inside a tuple (or the whole plan) records. */
+    const readMode = tupled ? "skip-scan" : strategy;
+    // -- addresses (§5.2, §5.3) --
+    const full = box === "empty" ? undefined : box;
+    const { zmin, zmax } = full === undefined ? { zmin: 0n, zmax: 0n } : corners(layout, full);
+    const single = full?.every((intervals) => intervals.length === 1) === true;
+    const contains = (z) => full !== undefined && inBox(layout, full, z);
+    /** The first in-box address at or after `z`. */
+    const nextIn = (z) => {
+        if (full === undefined || z > zmax)
+            return undefined;
+        if (z <= zmin)
+            return zmin;
+        return single ? bigmin(layout, z, zmin, zmax) : nextInBox(layout, full, z);
+    };
+    /** The last in-box address at or before `z`. */
+    const prevIn = (z) => {
+        if (full === undefined || z < zmin)
+            return undefined;
+        if (z >= zmax)
+            return zmax;
+        return single ? litmax(layout, z, zmin, zmax) : prevInBox(layout, full, z);
+    };
+    /** The ranges each tuple reads, in scan direction (`jump`: its first). */
+    const planned = full === undefined
+        ? []
+        : strategy === "key"
+            ? [{ lo: 0n, hi: MAXZ, exact: true }]
+            : strategy === "precise"
+                ? spec.ranges(maxRanges, REFINE_FACTOR).ranges
+                : [{ lo: zmin, hi: zmax, exact: false }];
+    const ordered = reverse ? [...planned].reverse() : planned;
+    /** Where a range ends, in scan direction. */
+    const end = (r) => (reverse ? r.lo : r.hi);
+    /** `[lo, hi]` under `T`: a whole subtree as `begins_with T` (no condition when `T` is empty). */
+    const keyRange = (T, r) => r.lo === 0n && r.hi === MAXZ
+        ? {
+            lower: undefined,
+            upper: undefined,
+            ...(T.length > 0 ? { beginsWith: T } : {}),
+            exact: r.exact,
+        }
+        : {
+            lower: concatBytes([T, toBytes(r.lo, W)]),
+            upper: concatBytes([T, toBytes(r.hi, W)]),
+            exact: r.exact,
+        };
+    const tupleOf = (at) => (at.tuple instanceof Uint8Array ? at.tuple : P);
+    /** The address of a sort key under `T`, or `undefined` when it isn't one. */
+    const addressOf = (T, key) => key instanceof Uint8Array && key.length === T.length + W && startsWithBytes(key, T)
+        ? fromBytes(key.subarray(T.length))
+        : undefined;
+    /** The addresses a read covers. */
+    const spanOf = (step) => {
+        const T = tupleOf(step.at);
+        return {
+            lo: addressOf(T, step.range.lower) ?? 0n,
+            hi: addressOf(T, step.range.upper) ?? MAXZ,
+            exact: step.range.exact,
+        };
+    };
+    // -- steps --
+    const position = (tuple, boundary, skips) => ({ mode: readMode, tuple, boundary, skips });
+    const read = (at, T, r, planIndex, startKey, run = JUMP_INITIAL) => ({
+        _tag: "Read",
+        at: startKey === undefined ? at : { ...at, boundary: { _tag: "At", startKey } },
+        range: keyRange(T, r),
+        startKey,
+        planIndex,
+        sizing: strategy === "jump" ? { _tag: "jump", run } : estimator,
+        rowCheck: spec.rowCheck,
+    });
+    /** Everything up to address `z` of tuple `T` is done. */
+    const through = (T, z) => ({
+        _tag: "Through",
+        through: concatBytes([T, toBytes(z, W)]),
+    });
+    /** Tuple `at` is finished: the next probe, or the end of the plan. */
+    const tupleDone = (at) => tupled ? probeFrom({ ...at, boundary: { _tag: "TupleDone" } }) : done;
+    /** The first read of tuple `T` (or of the plan, `tuple` absent). */
+    const firstRead = (T, tuple, skips) => {
+        const at = position(tuple, { _tag: "Start" }, skips);
+        const first = ordered[0];
+        return first === undefined
+            ? tupleDone(at)
+            : read(at, T, first, strategy === "precise" ? 0 : undefined, undefined);
+    };
+    /** The filter range from a position: past its finished tuple, or all of `P` (§7.4). */
+    const filterRange = (tuple) => {
+        const exact = !spec.bounded && spec.filterRowCheck === undefined;
+        if (reverse)
+            return { lower: nonEmpty(P), upper: tuple ?? succP, exact };
+        if (tuple === undefined)
+            return { lower: nonEmpty(P), upper: succP, exact };
+        const lower = succ(tuple);
+        return lower === undefined ? undefined : { lower, upper: succP, exact };
+    };
+    const filterRead = (from, startKey) => {
+        const tuple = startKey === undefined && from.tuple instanceof Uint8Array ? from.tuple : undefined;
+        const range = filterRange(tuple);
+        if (range === undefined)
+            return done;
+        return {
+            _tag: "Read",
+            at: {
+                ...from,
+                mode: "filter",
+                tuple,
+                boundary: startKey === undefined ? from.boundary : { _tag: "At", startKey },
+            },
+            range,
+            startKey,
+            planIndex: undefined,
+            sizing: estimator,
+            rowCheck: spec.filterRowCheck,
+        };
+    };
+    // -- the binary skip-scan (§7.5) --
+    /** A probe from `at` (lower and upper inclusive; never a zero-length operand). */
+    const probe = (at, lower, upper) => ({
+        _tag: "Probe",
+        at: { ...at, mode: "skip-scan", skips: at.skips + 1 },
+        lower: nonEmpty(lower),
+        upper: nonEmpty(upper),
+    });
+    /**
+     * The next probe from `from` — or, once the budget is spent, the filter
+     * plan (§7.4). No stored key equals `succ(P)` or a tuple `T` (each is
+     * followed by at least the address), so the inclusive bounds read as the
+     * exclusive ones of §7.5.
+     */
+    const probeFrom = (from) => {
+        if (from.skips >= maxSkips)
+            return filterRead(from);
+        const T = from.tuple instanceof Uint8Array ? from.tuple : undefined;
+        if (reverse)
+            return probe(from, P, T ?? succP);
+        if (T === undefined)
+            return probe(from, P, succP);
+        const lower = succ(T);
+        return lower === undefined ? done : probe(from, lower, succP);
+    };
+    /**
+     * A probed key's skip tuple (§7.5): every prefix segment after `P`, each
+     * given one compared with its value in the (length, bytes) order keys sort
+     * in. A given segment below its value SEEKs to it; one above SKIPs past
+     * the missing segments before it (mirrored in reverse: `to` is then the
+     * next probe's upper bound). `undefined` for a key the parse can't read.
+     */
+    const parse = (key) => {
+        if (!startsWithBytes(key, P))
+            return undefined;
+        let pos = P.length;
+        let missingEnd = P.length;
+        for (const segment of spec.tuple) {
+            const start = pos;
+            const stop = segment.hash !== undefined
+                ? start + segment.hash
+                : start + 2 > key.length
+                    ? -1
+                    : start + 2 + ((key[start] << 8) | key[start + 1]);
+            if (stop < 0 || stop > key.length)
+                return undefined;
+            if (segment.given === undefined) {
+                missingEnd = stop;
+            }
+            else {
+                const order = compareBytes(key.subarray(start, stop), segment.given);
+                if (order !== 0) {
+                    const seek = concatBytes([key.subarray(0, start), segment.given]);
+                    const missing = key.slice(0, missingEnd);
+                    return reverse
+                        ? { _tag: "move", to: order > 0 ? (succ(seek) ?? succP) : missing }
+                        : { _tag: "move", to: order < 0 ? seek : succ(missing) };
+                }
+            }
+            pos = stop;
+        }
+        return key.length - pos === W ? { _tag: "tuple", tuple: key.slice(0, pos) } : undefined;
+    };
+    const initial = () => {
+        const fresh = position(undefined, { _tag: "Start" }, 0);
+        return mode === "empty"
+            ? done
+            : mode === "filter"
+                ? filterRead(fresh)
+                : tupled
+                    ? probeFrom(fresh)
+                    : firstRead(P, undefined, 0);
+    };
+    // -- resume (§10.3) --
+    /** Everything up to address `a` (in scan direction) is done: clip the plan there. */
+    const resumeThrough = (tuple, sk, a) => {
+        const T = tuple ?? P;
+        const at = position(tuple, { _tag: "Through", through: sk }, 0);
+        if (strategy === "jump") {
+            const n = reverse
+                ? a === 0n
+                    ? undefined
+                    : prevIn(a - 1n)
+                : a === MAXZ
+                    ? undefined
+                    : nextIn(a + 1n);
+            if (n === undefined)
+                return tupleDone(at);
+            return read(at, T, reverse ? { lo: zmin, hi: n, exact: false } : { lo: n, hi: zmax, exact: false }, undefined, undefined);
+        }
+        for (let i = 0; i < ordered.length; i++) {
+            const r = ordered[i];
+            if (reverse ? r.lo < a : r.hi > a) {
+                const clipped = reverse
+                    ? { lo: r.lo, hi: r.hi < a ? r.hi : a - 1n, exact: r.exact }
+                    : { lo: r.lo > a ? r.lo : a + 1n, hi: r.hi, exact: r.exact };
+                return read(at, T, clipped, strategy === "precise" ? i : undefined, undefined);
+            }
+        }
+        return tupleDone(at);
+    };
+    /** `k` as a start key: in this partition, its sort key an address under `T`. */
+    const placeKey = (key, T) => {
+        const pk = key[spec.pkField];
+        if (pk === undefined || !("S" in pk) || pk.S !== spec.pkValue) {
+            return refuse("its key is in another partition");
+        }
+        const wire = key[spec.skField];
+        const sk = wire === undefined ? undefined : Cursor.wireToKeyValue(wire);
+        const address = addressOf(T, sk);
+        if (address === undefined || !(sk instanceof Uint8Array)) {
+            return refuse("its key is outside the recomputed plan");
+        }
+        return { startKey: Cursor.keyFromWire(key), sk, address };
+    };
+    /**
+     * Resume inside the range holding `k`'s address, clipped to start there.
+     * An address no range holds is out of the box — the rows at it were never
+     * results — so the position reads as everything up to it being done.
+     */
+    const resumeAt = (tuple, key) => {
+        const T = tuple ?? P;
+        const placed = placeKey(key, T);
+        if (placed instanceof ValidationError)
+            return placed;
+        const { startKey, sk, address: a } = placed;
+        const at = position(tuple, { _tag: "At", startKey }, 0);
+        if (strategy === "jump") {
+            if (!contains(a))
+                return resumeThrough(tuple, sk, a);
+            return read(at, T, reverse ? { lo: zmin, hi: a, exact: false } : { lo: a, hi: zmax, exact: false }, undefined, startKey);
+        }
+        const i = ordered.findIndex((r) => r.lo <= a && a <= r.hi);
+        if (i < 0)
+            return resumeThrough(tuple, sk, a);
+        const r = ordered[i];
+        return read(at, T, reverse ? { lo: r.lo, hi: a, exact: r.exact } : { lo: a, hi: r.hi, exact: r.exact }, strategy === "precise" ? i : undefined, startKey);
+    };
+    const start = (cursor) => {
+        if (cursor?.f !== undefined && cursor.f !== fingerprint) {
+            return refuse("its plan fingerprint differs");
+        }
+        if (cursor === undefined)
+            return initial();
+        if (strategy === "empty") {
+            return cursor.f === undefined
+                ? refuse("it comes from a query without .within(), and this plan is empty")
+                : done;
+        }
+        if (cursor.f === undefined) {
+            // A legacy cursor, or a plain query's `{ k }`: a position in a single-range plan.
+            if (tupled || !(strategy === "key" || strategy === "naive")) {
+                return refuse(`it comes from a query without .within(), and this plan is ${mode}`);
+            }
+            if (cursor.k === undefined || cursor.s !== undefined || cursor.t !== undefined) {
+                return refuse("it carries no position in this plan");
+            }
+            return resumeAt(undefined, cursor.k);
+        }
+        // Any strategy continues any other: positions are addresses, never ranges.
+        const s = cursor.s;
+        const fits = s !== undefined &&
+            (tupled
+                ? s === "skip-scan" || s === "filter"
+                : s === "key" || s === "naive" || s === "jump" || s === "precise");
+        if (!fits)
+            return refuse(`its plan (${s ?? "none"}) can't continue as ${mode}`);
+        let tuple;
+        if (cursor.t !== undefined) {
+            const t = Cursor.wireToKeyValue(cursor.t);
+            const parsed = tupled && t instanceof Uint8Array ? parse(concatBytes([t, new Uint8Array(W)])) : undefined;
+            if (parsed?._tag !== "tuple" ||
+                !(t instanceof Uint8Array) ||
+                compareBytes(parsed.tuple, t) !== 0) {
+                return refuse("its skip tuple is not one of this plan's");
+            }
+            tuple = t;
+        }
+        const at = (boundary) => ({ mode: s, tuple, boundary, skips: 0 });
+        if (cursor.k !== undefined) {
+            if (s === "filter") {
+                if (tuple !== undefined)
+                    return refuse("a filter position inside a tuple");
+                const pk = cursor.k[spec.pkField];
+                const wire = cursor.k[spec.skField];
+                const sk = wire === undefined ? undefined : Cursor.wireToKeyValue(wire);
+                if (pk === undefined || !("S" in pk) || pk.S !== spec.pkValue) {
+                    return refuse("its key is in another partition");
+                }
+                const range = filterRange(undefined);
+                if (!(sk instanceof Uint8Array) || range === undefined || !rangeContains(range, sk)) {
+                    return refuse("its key is outside the recomputed plan");
+                }
+                const startKey = Cursor.keyFromWire(cursor.k);
+                return filterRead(at({ _tag: "At", startKey }), startKey);
+            }
+            if (tupled && tuple === undefined)
+                return refuse("a key outside any tuple");
+            return resumeAt(tuple, cursor.k);
+        }
+        if (cursor.a !== undefined) {
+            const sk = Cursor.wireToKeyValue(cursor.a);
+            const a = addressOf(tuple ?? P, sk);
+            if (a === undefined ||
+                !(sk instanceof Uint8Array) ||
+                s === "filter" ||
+                (tupled && tuple === undefined)) {
+                return refuse("its 'through' position is not one of this plan's");
+            }
+            return resumeThrough(tuple, sk, a);
+        }
+        if (cursor.d !== undefined) {
+            if (tuple === undefined)
+                return refuse("a finished tuple without the tuple");
+            return s === "filter"
+                ? filterRead(at({ _tag: "TupleDone" }))
+                : probeFrom(at({ _tag: "TupleDone" }));
+        }
+        // Start: of tuple `t`, or of the plan.
+        if (tuple !== undefined) {
+            return s === "skip-scan"
+                ? firstRead(tuple, tuple, 0)
+                : refuse("a filter position at the start of a tuple");
+        }
+        return s === "filter"
+            ? filterRead(at({ _tag: "Start" }))
+            : tupled
+                ? probeFrom(at({ _tag: "Start" }))
+                : initial();
+    };
+    // -- transitions --
+    const afterRead = (step, lastEvaluatedKey) => {
+        if (step.at.mode === "filter") {
+            return lastEvaluatedKey === undefined ? done : readFrom(step, lastEvaluatedKey);
+        }
+        const T = tupleOf(step.at);
+        if (lastEvaluatedKey !== undefined) {
+            if (step.sizing._tag !== "jump")
+                return readFrom(step, lastEvaluatedKey);
+            // `jump` (§5.5): the last row examined — not the last returned, which
+            // the filter may have dropped — decides whether the run goes on.
+            const run = step.sizing.run;
+            const sk = lastEvaluatedKey[spec.skField]?.B;
+            const a = addressOf(T, sk);
+            if (a === undefined || contains(a)) {
+                // In the box: rows may follow at the same address. The next page doubles (§8.5).
+                return {
+                    ...readFrom(step, lastEvaluatedKey),
+                    sizing: { _tag: "jump", run: Math.min(run * 2, JUMP_MAX_LIMIT) },
+                };
+            }
+            // Out of the box: a new key condition from the next in-box address —
+            // never a fabricated start key (a GSI start key needs the table key).
+            const span = spanOf(step);
+            const n = reverse ? (a === 0n ? undefined : prevIn(a - 1n)) : nextIn(a + 1n);
+            if (n === undefined || (reverse ? n < span.lo : n > span.hi))
+                return tupleDone(step.at);
+            return read({ ...step.at, boundary: { _tag: "Through", through: sk } }, T, reverse ? { lo: span.lo, hi: n, exact: false } : { lo: n, hi: span.hi, exact: false }, undefined, undefined);
+        }
+        // The range is finished: the next planned one, or the tuple is.
+        const i = step.planIndex;
+        if (i !== undefined && i + 1 < ordered.length) {
+            return read({ ...step.at, boundary: through(T, end(spanOf(step))) }, T, ordered[i + 1], i + 1, undefined);
+        }
+        return tupleDone(step.at);
+    };
+    const afterProbe = (step, key) => {
+        if (key === undefined)
+            return done;
+        const parsed = key instanceof Uint8Array ? parse(key) : undefined;
+        // A key the parse can't read leaves the rest to the filter plan.
+        if (parsed === undefined)
+            return filterRead(step.at);
+        if (parsed._tag === "tuple") {
+            const previous = step.at.tuple instanceof Uint8Array ? step.at.tuple : undefined;
+            const order = previous === undefined ? undefined : compareBytes(parsed.tuple, previous);
+            // Defensively: a tuple that doesn't advance.
+            if (order !== undefined && (reverse ? order >= 0 : order <= 0)) {
+                return filterRead(step.at);
+            }
+            return firstRead(parsed.tuple, parsed.tuple, step.at.skips);
+        }
+        // SEEK / SKIP: probe again from where the given segment says.
+        const to = parsed.to;
+        if (to === undefined)
+            return reverse ? filterRead(step.at) : done;
+        const from = reverse ? step.upper : step.lower;
+        const advances = from === undefined || (reverse ? compareUtf8(to, from) < 0 : compareUtf8(to, from) > 0);
+        if (!advances || step.at.skips >= maxSkips)
+            return filterRead(step.at);
+        return reverse ? probe(step.at, P, to) : probe(step.at, to, succP);
+    };
+    /** The precise ranges after `step` in its tuple, not started (§9.2). */
+    const following = (step, n) => {
+        const i = step.planIndex;
+        if (i === undefined || step.at.mode === "filter" || n <= 0)
+            return [];
+        const T = tupleOf(step.at);
+        const out = [];
+        let previous = spanOf(step);
+        for (let j = i + 1; j < ordered.length && out.length < n; j++) {
+            const r = ordered[j];
+            out.push(read({ ...step.at, boundary: through(T, end(previous)) }, T, r, j, undefined));
+            previous = r;
+        }
+        return out;
+    };
+    // -- cursors and explain --
+    const rowCheck = mode === "filter" ? spec.filterRowCheck : spec.rowCheck;
+    const explain = (sizing) => {
+        const exactPlan = full === undefined ? undefined : spec.ranges(maxRanges, 1);
+        const volume = full === undefined
+            ? 0n
+            : full.reduce((product, intervals) => product * intervals.reduce((n, [lo, hi]) => n + (hi - lo + 1n), 0n), 1n);
+        return {
+            index: spec.index,
+            plan: mode,
+            reason,
+            // The ranges known before anything is read: each tuple's plan, or —
+            // with a skip tuple — the span the probes (or the filter read) walk.
+            keyConditions: mode === "empty"
+                ? []
+                : tupled
+                    ? [shownRange({ ...filterRange(undefined), exact: false })]
+                    : ordered.map((r) => shownRange(keyRange(P, r))),
+            filter: spec.filter === undefined ? undefined : displayExpr(spec.filter),
+            rowChecks: rowCheck?.fields ?? [],
+            sizing,
+            zorder: {
+                bits: layout.bits,
+                box: layout.dimensions.map((dimension, i) => ({
+                    field: dimension.field,
+                    bits: dimension.bits,
+                    levels: full === undefined
+                        ? []
+                        : full[i].map(([lo, hi]) => [lo.toString(), hi.toString()]),
+                })),
+                fill: full === undefined ? 0 : Number(volume) / Number(zmax - zmin + 1n),
+                exactRanges: exactPlan === undefined ? 0 : exactPlan.exact ? exactPlan.ranges.length : "over-cap",
+            },
+            ...(mode === "skip-scan" ? { maxSkips } : {}),
+        };
+    };
+    return {
+        fingerprint,
+        mode,
+        filter: spec.filter,
+        rowCheck,
+        start,
+        afterRead,
+        afterProbe,
+        following,
+        cursor: (step) => positionCursor(fingerprint, step),
+        explain,
+    };
+};
+//# sourceMappingURL=RangePlanner.js.map