@geastack/compiler 1.0.15

package/dist/ir/deferral.js

@@ -0,0 +1,409 @@
+import { representationKey } from '../representation/model.js';
+import { operandsOfIrOperation, resultOfIrOperation } from './queries.js';
+/**
+ * Which values render at their use instead of into a temporary of their own.
+ *
+ * A value with exactly one use, produced by an operation whose whole emitted
+ * form is one side-effect-free expression, does not need storage: the text can
+ * stand where the use stands. It lives here, beside the loop censuses, because
+ * it is a question about the IR -- what an operation reads and how many places
+ * read its result -- and not about C++.
+ */
+/**
+ * The operation kinds whose emitted statement is a side-effect-free
+ * expression.
+ *
+ * Not "cheap" and not "small": the question is whether moving the statement
+ * later, past other statements this census has also withheld, could be
+ * observed. A read of a cell, a formal, a literal, an arithmetic result, a
+ * conversion and a fresh Array are all answers about state nothing in the
+ * window changes. Every kind that writes -- `binding-write`, `set`,
+ * `define-own-property`, `delete` -- and every kind that can run a program's
+ * own code -- `call`, `construct`, `await`, `yield`, the iterator protocol,
+ * the JSX element builders -- is absent, so no deferred read is ever moved
+ * across an effect.
+ *
+ * `get` is the one kind decided per operation rather than by name, because it
+ * spells two different things: an index or `length` read off an Array or a
+ * string is a pure load, and a member read off anything else may reach a
+ * program-defined accessor. The narrow answer is the conservative one -- a
+ * receiver this census cannot prove pure simply keeps its temporary, which
+ * costs a copy and never correctness.
+ */
+const deferrableOperationKinds = new Set([
+    'constant',
+    'binding-read',
+    'parameter',
+    'receiver',
+    'compute',
+    'test',
+    'convert',
+    'has-property',
+    'allocate-array-object'
+]);
+/**
+ * The producers WITH effects whose result may still render inside the one
+ * operation that immediately consumes it.
+ *
+ * A call's result is an SSA temporary like any other, and where its single
+ * reader is the very next operation there is no window at all: nothing is
+ * crossed, so the call runs exactly where the IR placed it and only the
+ * temporary disappears. That temporary is not free the way a `double` is.
+ * `fns[slot] = makeKind(i % 4, i)` built a 32-byte `CallableObject` into a
+ * function-scope local, then copied it into the array cell -- two retains,
+ * two releases, and a store-forwarding stall on the 16-byte reload of what
+ * two 8-byte stores had just written. Rendered as the store's right-hand side
+ * the value is move-assigned straight from the call's return slot: the
+ * `closure` fixture went from 104 to 63 instructions per iteration.
+ *
+ * Unlike a pure deferral the producer is NOT marked withheld, so it goes on
+ * bounding every other value's window: a read defined before the call and
+ * used after it keeps its temporary, exactly as it does today, and C++'s
+ * unspecified operand order inside the consumer can never reorder it across
+ * the call.
+ */
+const forwardableProducerKinds = new Set(['call', 'construct', 'allocate-callable']);
+export const noForwarding = { forwardsCallInto: () => false, forwardsBinding: () => false };
+/**
+ * The positions a forwarded call result may occupy in its consumer, decided
+ * from the IR alone. An Array element store is admitted only for a stored
+ * value already carried as the element's own type: the renderer aligns any
+ * other value to the element first, and an alignment is a conversion whose
+ * spelling this census does not see.
+ */
+const callSinkOf = (consumer, value) => {
+    switch (consumer.kind) {
+        case 'call':
+        case 'construct': {
+            const operand = consumer.arguments.find((argument) => argument.value === value);
+            return operand === undefined ? null : { sink: consumer, operand };
+        }
+        case 'set': {
+            if (consumer.value.value !== value || consumer.typedComputedWrite !== undefined)
+                return null;
+            const receiver = consumer.receiver.representation;
+            if (receiver.kind !== 'array-object' || consumer.key.representation.kind !== 'scalar')
+                return null;
+            if (representationKey(receiver.element) !== representationKey(consumer.value.representation))
+                return null;
+            return { sink: consumer, operand: consumer.value };
+        }
+        case 'binding-write':
+            return consumer.value.value === value ? { sink: consumer, operand: consumer.value } : null;
+        case 'return':
+            return consumer.value !== null && consumer.value.value === value ? { sink: consumer, operand: consumer.value } : null;
+        default:
+            return null;
+    }
+};
+/** The carriers `gea::CallableObject` physically holds, whose every call path retains the environment it runs. */
+const callableObjectCarrierKinds = new Set([
+    'function',
+    'function-value-dispatch',
+    'function-and-constructor'
+]);
+/**
+ * Where a forwarded binding's one read may be consumed.
+ *
+ * The read no longer copies out of a cell that holds its own count, so a
+ * consumer that BORROWS the value for the duration of a call -- a receiver
+ * or argument passed by reference -- would borrow the array slot or field the
+ * written expression names, and the callee may overwrite that slot while the
+ * reference is live. Every admitted position either copies the value (a
+ * store, a return, a cell write), reads it before anything else runs (an
+ * arithmetic operand, a plain member load) or is the CALLEE of a call, where
+ * `CallableObject::call` retains the environment it is about to run for
+ * exactly this reason.
+ */
+const forwardedReadPositionAllowed = (consumer, read, representation, pureGet) => {
+    switch (consumer.kind) {
+        case 'call':
+            return consumer.callee.value === read && callableObjectCarrierKinds.has(representation.kind);
+        case 'compute':
+        case 'test':
+        case 'binding-write':
+        case 'return':
+            return true;
+        case 'get': {
+            if (consumer.key.value === read)
+                return true;
+            if (consumer.receiver.value !== read)
+                return false;
+            const receiver = consumer.receiver.representation.kind;
+            return receiver === 'array-object' || receiver === 'string' || pureGet(consumer);
+        }
+        case 'set':
+            return consumer.key.value === read || consumer.value.value === read;
+        default:
+            return false;
+    }
+};
+/** A conversion over alternatives can inspect its input once per arm. */
+const carriesAlternatives = (representation) => {
+    if (representation.kind === 'optional')
+        return carriesAlternatives(representation.payload);
+    if (representation.kind === 'borrowed-ref')
+        return carriesAlternatives(representation.referent);
+    return representation.kind === 'tagged-union';
+};
+const isDeferrableOperation = (operation, pureGet) => {
+    // One IR consumer is not necessarily one rendered evaluation. Sum
+    // projections may inspect several tags and rebuild a different set of
+    // alternatives; substituting one into another multiplies their expression
+    // trees. Preserve the SSA temporary at these boundaries, rather than making
+    // the target rediscover an expression-size limit after expanding the text.
+    if (operation.kind === 'convert' &&
+        (carriesAlternatives(operation.source.representation) || carriesAlternatives(operation.result.representation)))
+        return false;
+    if (operation.kind === 'get') {
+        const receiver = operation.receiver.representation.kind;
+        return receiver === 'array-object' || receiver === 'string' || pureGet(operation);
+    }
+    return deferrableOperationKinds.has(operation.kind);
+};
+/**
+ * Which values may render at their single use instead of into a temporary of
+ * their own.
+ *
+ * The IR is three-address form, and for a `double` that costs nothing: the C++
+ * compiler propagates the copy away. For a `std::shared_ptr` it is an atomic
+ * increment and a matching decrement, and for a `std::string` it is a heap
+ * allocation -- neither of which any optimizer may remove, because both are
+ * observable through the refcount and the allocator. An array indexed in a
+ * loop was paying one atomic pair per iteration purely to name the array the
+ * cell was already holding.
+ *
+ * Four conditions, and each one is load-bearing. Compound sum conversions
+ * additionally retain their named result to bound composition of projections:
+ *
+ * 1. exactly one use, so the expression is not evaluated twice;
+ * 2. that use in the same block, so no `goto` can reach the use without
+ *    passing the definition;
+ * 3. the defining operation side-effect-free (`isDeferrableOperation`); and
+ * 4. every operation between the two also deferred.
+ *
+ * (4) is what makes (3) sufficient. Everything between the definition and the
+ * use emitted no statement of its own, so the window contains no write at all
+ * -- which is why the order these reads end up in inside the use's own
+ * expression, which C++ leaves unspecified for most operators, cannot be
+ * observed by the program.
+ *
+ * Two forwardings ride on the same census, each with a narrower proof:
+ *
+ * - a `call`, `construct` or `allocate-callable` result whose single reader
+ *   is the IMMEDIATELY following operation (`forwardableProducerKinds`,
+ *   `callSinkOf`): no window, so nothing is crossed, and the producer keeps
+ *   bounding everyone else's windows;
+ * - a cell written once and read once in one block, the read itself
+ *   deferrable, every operation between the two effect-free, and the read
+ *   consumed where it is copied or called rather than borrowed
+ *   (`forwardedReadPositionAllowed`): the write renders nothing and the read
+ *   spells the written value (`forwardedBindings`).
+ *
+ * The target's `ForwardingPolicy` has the last word on both, because both
+ * depend on how a renderer spells its operand and on whose storage a cell is.
+ *
+ * A use recorded for a merge (`phi`) belongs to the PREDECESSOR block at the
+ * position `emitBody` writes merges at -- after that block's operations and
+ * before its terminator -- not to the block the phi is written in. Recording
+ * it where the phi sits would let a value move across the whole block.
+ */
+/**
+ * `pureGet` widens the `get` rule past Arrays and strings to whatever the
+ * emitter can prove is a plain field load (`emit-properties.ts`'s
+ * `isPlainMemberRead`): `v20 = gea_this->cities; if (b0 < v20->length())`
+ * is a `Ref` copy -- an atomic pair -- made only to name the field once, and
+ * with the read deferred the comparison spells the field itself. The default
+ * refuses every such read, which is the answer the census gave before it was
+ * asked.
+ */
+export const deferrableValuesOf = (body, pureGet = () => false, forwarding = noForwarding) => {
+    const uses = new Map();
+    const record = (value, block, index) => {
+        const sites = uses.get(value);
+        if (sites)
+            sites.push({ block, index });
+        else
+            uses.set(value, [{ block, index }]);
+    };
+    // A block that writes merges renders statements between its last operation
+    // and its terminator, so a call there is not adjacent to a `return` after it.
+    const mergeBlocks = new Set();
+    const producers = new Map();
+    const bindingWriteCounts = new Map();
+    const bindingReads = new Map();
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        block.operations.forEach((operation, index) => {
+            if (operation.kind === 'phi') {
+                for (const edge of operation.incoming) {
+                    mergeBlocks.add(edge.block);
+                    record(edge.value.value, edge.block, body.blocks.get(edge.block)?.operations.length ?? 0);
+                }
+                return;
+            }
+            const result = resultOfIrOperation(operation);
+            if (result !== null)
+                producers.set(result.id, operation);
+            if (operation.kind === 'binding-write')
+                bindingWriteCounts.set(operation.declaration, (bindingWriteCounts.get(operation.declaration) ?? 0) + 1);
+            if (operation.kind === 'binding-read') {
+                const reads = bindingReads.get(operation.declaration);
+                const site = { block: blockId, index, operation };
+                if (reads)
+                    reads.push(site);
+                else
+                    bindingReads.set(operation.declaration, [site]);
+            }
+            for (const operand of operandsOfIrOperation(operation))
+                record(operand.value, blockId, index);
+        });
+        for (const operand of operandsOfIrOperation(block.terminator))
+            record(operand.value, blockId, block.operations.length + 1);
+    }
+    for (const region of body.iteratorCloseRegions ?? [])
+        record(region.iterator.value, region.entry, 0);
+    const deferrable = new Set();
+    const forwardedBindings = new Map();
+    // A candidate is complete only once the whole body is censused: whether the
+    // written value itself defers is decided at its producer, which the
+    // descending walk reaches AFTER the write that reads it.
+    const bindingCandidates = [];
+    // Which withheld values a CALL is the single reader of. An array literal
+    // withheld whole has no statement to move -- it materializes from its own
+    // elements wherever its text lands (`EmitContext.pendingPacks`) -- so a
+    // renderer that spells one operand twice would build two objects where the
+    // program wrote one. Every renderer that does spell an operand twice spells
+    // its RECEIVER, and a call argument is never that, so restricting the
+    // withholding to call arguments is what makes the one-object rule hold
+    // without asking each renderer to promise it.
+    const consumedByCall = new Set();
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        // Descending, because whether an operation may be deferred depends on
+        // whether every LATER operation up to its use already was.
+        const withheld = new Set();
+        for (let index = block.operations.length - 1; index >= 0; index -= 1) {
+            const operation = block.operations[index];
+            if (!operation)
+                continue;
+            // A merge publishes its name before any block renders and emits no
+            // statement where it is written, so it never breaks a window.
+            if (operation.kind === 'phi') {
+                withheld.add(index);
+                continue;
+            }
+            if (forwardableProducerKinds.has(operation.kind)) {
+                const result = resultOfIrOperation(operation);
+                const sites = result === null ? undefined : uses.get(result.id);
+                const site = sites?.length === 1 ? sites[0] : undefined;
+                if (result === null || !site || site.block !== blockId)
+                    continue;
+                // Adjacent means the next operation, or the terminator of a block
+                // that writes no merges in front of it.
+                const consumer = site.index === index + 1 && site.index < block.operations.length
+                    ? block.operations[site.index]
+                    : index === block.operations.length - 1 && site.index === block.operations.length + 1 && !mergeBlocks.has(blockId)
+                        ? block.terminator
+                        : undefined;
+                if (consumer === undefined)
+                    continue;
+                const sink = callSinkOf(consumer, result.id);
+                if (sink === null || !forwarding.forwardsCallInto(sink.sink, sink.operand))
+                    continue;
+                deferrable.add(result.id);
+                continue;
+            }
+            if (operation.kind === 'binding-write') {
+                if (bindingWriteCounts.get(operation.declaration) !== 1)
+                    continue;
+                const reads = bindingReads.get(operation.declaration);
+                const read = reads?.length === 1 ? reads[0] : undefined;
+                if (!read || read.block !== blockId || read.index <= index || !deferrable.has(read.operation.result.id))
+                    continue;
+                const readSites = uses.get(read.operation.result.id);
+                const readSite = readSites?.length === 1 ? readSites[0] : undefined;
+                if (!readSite || readSite.block !== blockId)
+                    continue;
+                const consumer = readSite.index < block.operations.length
+                    ? block.operations[readSite.index]
+                    : readSite.index === block.operations.length + 1
+                        ? block.terminator
+                        : undefined;
+                if (consumer === undefined)
+                    continue;
+                if (!forwardedReadPositionAllowed(consumer, read.operation.result.id, read.operation.result.representation, pureGet))
+                    continue;
+                // Effect-free is the condition here, not withheld: a pure read that
+                // kept its temporary because ITS use lies past some later call still
+                // writes nothing, and the written expression only has to reach the
+                // read without anything changing what it names. From the read to its
+                // use the read's own deferral has already proved the window clear.
+                let clear = true;
+                for (let between = index + 1; between < read.index; between += 1) {
+                    const crossed = block.operations[between];
+                    if (!crossed || (crossed.kind !== 'phi' && !isDeferrableOperation(crossed, pureGet)))
+                        clear = false;
+                }
+                if (!clear)
+                    continue;
+                if (!forwarding.forwardsBinding(operation, read.operation))
+                    continue;
+                bindingCandidates.push({
+                    declaration: operation.declaration,
+                    value: operation.value,
+                    read: read.operation.result.id,
+                    write: index,
+                    readAt: read.index,
+                    use: readSite.index
+                });
+                continue;
+            }
+            if (!isDeferrableOperation(operation, pureGet))
+                continue;
+            const result = resultOfIrOperation(operation);
+            if (result === null)
+                continue;
+            const sites = uses.get(result.id);
+            const site = sites?.length === 1 ? sites[0] : undefined;
+            if (!site || site.block !== blockId || site.index <= index)
+                continue;
+            const limit = Math.min(site.index, block.operations.length);
+            let clear = true;
+            for (let between = index + 1; between < limit; between += 1)
+                if (!withheld.has(between))
+                    clear = false;
+            if (!clear)
+                continue;
+            withheld.add(index);
+            deferrable.add(result.id);
+            const reader = block.operations[site.index];
+            if (reader && (reader.kind === 'call' || reader.kind === 'construct' || reader.kind === 'super-initialize')) {
+                if (!reader.arguments.some((argument) => argument.value === result.id))
+                    continue;
+                consumedByCall.add(result.id);
+            }
+        }
+    }
+    for (const candidate of bindingCandidates) {
+        if (!deferrable.has(candidate.value.value))
+            continue;
+        const producer = producers.get(candidate.value.value);
+        // A formal reaches its reads by name already (`emit-bindings.ts`'s
+        // `collectFormalCells`), and that decision stays where it is.
+        if (producer === undefined || producer.kind === 'parameter' || producer.kind === 'receiver')
+            continue;
+        // A forwarded CALL moves to the read's use, so it may cross nothing at all
+        // -- not even a withheld read, whose place inside the use's expression C++
+        // orders however it likes.
+        if (forwardableProducerKinds.has(producer.kind) &&
+            !(candidate.readAt === candidate.write + 1 && candidate.use === candidate.readAt + 1))
+            continue;
+        forwardedBindings.set(candidate.declaration, { value: candidate.value, read: candidate.read });
+    }
+    return { values: deferrable, consumedByCall, forwardedBindings };
+};

package/dist/ir/dense-loops.d.ts

@@ -0,0 +1,230 @@
+import type { DeclarationId, IrValueId } from '../identity/ids.js';
+import type { Representation, TypedArrayElementDomain } from '../representation/model.js';
+import type { IrBlockId, IrBody, IrNonTerminatorOperation, IrOperand } from './model.js';
+/**
+ * Loops whose Array accesses can run against a raw element pointer, and the
+ * one loop-invariant condition that makes that sound.
+ *
+ * `c[i * N + j] += a_ik * b_kj` compiles to a load and a store through
+ * `ArrayObject`, and both of them can GROW the array -- a store past the end
+ * appends, which is what `a[a.length] = x` means in JavaScript. clang has to
+ * assume the storage may be reallocated on every iteration, so it reloads the
+ * base pointer each time and cannot vectorize anything. Measured on
+ * `bench/comparison`'s matrix_multiply: 35.5 ms, against 4.9 ms for the
+ * hand-written C++ that indexes a `std::vector` it knows nobody resizes.
+ *
+ * Hoisting the base pointer alone does not fix it, and neither does a
+ * per-access bounds check -- both measured 35 ms, because the branch that
+ * could still reallocate is inside the loop either way. What does fix it is a
+ * condition computed ONCE, before the loop:
+ *
+ *     geaFast = arr->holes.empty() && lower >= 0 && upper <= arr->size()
+ *
+ * and an access written `geaFast ? base[i].value : <the general form>`. The
+ * flag is loop-invariant, so clang's own loop unswitching produces the two
+ * loop bodies, and in the fast one nothing can resize: 7.9 ms, same answer.
+ * That is why this is a flag rather than a duplicated block -- the versioning
+ * already exists in the backend, and it only needed something invariant to
+ * version on.
+ *
+ * The proof this computes is that the loop's own test bounds every index:
+ *
+ *   - the loop is ascending (`i < B` / `i <= B`) with the counter on the left,
+ *     and the counter advances by a loop-invariant step, so inside the body
+ *     `i` never exceeds `B`;
+ *   - every index is the counter, or a loop-invariant base plus the counter,
+ *     so the highest index the loop can reach is `base + B`;
+ *   - and every use of the array inside the loop is one of those accesses --
+ *     one `push`, one call taking the array, one write of the cell, and the
+ *     window is no longer a window.
+ *
+ * The bound itself, the base and the counter's seed are all read at the
+ * preheader and checked there. Nothing here assumes a length.
+ */
+export interface DenseArray {
+    /** Distinguishes this window's pointer name within one body. */
+    readonly ordinal: number;
+    /** The loop this window belongs to. One flag per loop, not per array: two invariant flags would ask the backend for four loop versions where one condition covers every window. */
+    readonly group: number;
+    /** The array, as the emitter already knows how to spell it. */
+    readonly reference: DenseReference;
+    /** The element carrier, for the pointer's own type. */
+    readonly element: Representation;
+    /** Typed-array storage has no Cell wrapper or holes. */
+    readonly typed: TypedArrayElementDomain | null;
+    /** The block the flag and the pointer are computed in. */
+    readonly preheader: IrBlockId;
+    /** Every invariant addend used by an access, with `null` for the bare counter. All ranges must fit before any access is unchecked. */
+    readonly bases: readonly (IrOperand | null)[];
+    /** The counter cell, read at the preheader for the lowest index the loop can touch. */
+    readonly counter: DeclarationId;
+    /** The loop's own bound. */
+    readonly bound: IrOperand;
+    /** Whether the test admits the bound itself (`<=`), so the window is one wider. */
+    readonly inclusive: boolean;
+    /** The counter's step, checked non-negative at the preheader. */
+    readonly step: IrOperand | null;
+    /**
+     * Whether this window's indices are REMAINDERS by the array's own length
+     * rather than the loop's counter -- `ring[i % ring.length]`, the shape every
+     * ring buffer and hash bucket is written in.
+     *
+     * A different proof, and a simpler one: `x % n` lies in `[0, n)` for every
+     * dividend whenever `n > 0`, so the window needs no bound, no base and no
+     * counter -- only that the array is non-empty and has no holes, which is what
+     * the preheader checks. `bases`, `bound`, `inclusive`, `step` and `widened`
+     * carry no meaning for one of these.
+     *
+     * Worth its own shape because the ordinary bounds test is not cheap enough to
+     * leave in the loop. Measured on `bench/comparison/fixtures/object_create.ts`:
+     * 11.3ms as emitted, 11.8ms with a per-access `key < size()` guard (no better
+     * than doing nothing at all), 10.1ms with an unsigned integer one, and 7.9ms
+     * with the bound gone. A per-access size read is what stops clang keeping the
+     * base pointer in a register, so the bound has to leave the loop entirely.
+     */
+    readonly wrapped: boolean;
+    /**
+     * What a wrapped window's indices are taken modulo: `null` for the array's
+     * own `length`, a positive integer for a CONSTANT divisor.
+     *
+     * `x % n` lies in `[0, n)` either way, so the proof is the same one; what
+     * differs is what the preheader has to check. The array's own length needs
+     * only `size() > 0`, because an index below the length is inside the storage
+     * by definition. A constant needs `size() >= n`, because nothing ties the two
+     * together -- and that check is what makes `table[i % 16]` a window, which is
+     * how every fixed-capacity ring buffer, hash bucket and dispatch table is
+     * written.
+     *
+     * Meaningless when `wrapped` is false.
+     */
+    readonly modulus: number | null;
+    /**
+     * Whether an access can see the counter AFTER this turn's advance.
+     *
+     * The loop's test bounds the counter at the top of the body; a body that
+     * advances the counter and THEN reads reaches one step further, and the
+     * window has to be that much wider. A latch that advances and jumps straight
+     * back to the header -- which is what every `for` loop compiles to -- reaches
+     * nothing, and widening it there would cost the window outright: an array of
+     * exactly `bound` elements would fail `bound + 1 <= size` on every turn.
+     */
+    readonly widened: boolean;
+}
+export type DenseReference = {
+    readonly kind: 'cell';
+    readonly declaration: DeclarationId;
+    readonly representation: Representation;
+} | {
+    readonly kind: 'value';
+    readonly operand: IrOperand;
+    readonly storage: Representation;
+}
+/**
+ * A ROW of another array: `grid[i]` read inside the `j` loop.
+ *
+ * The receiver of `grid[i][j]` is loop-invariant and yet defined inside the
+ * loop -- the row load is one of the loop's own operations -- so neither of
+ * the two references above names it. `holder` is the array the row comes out
+ * of and `key` the invariant index; the emitter re-reads the row at the
+ * preheader, behind the condition that says the read is in range, and takes
+ * the pointer from there. `operand` is the row value itself, whose every
+ * other use inside the loop the window still has to account for.
+ */
+ | {
+    readonly kind: 'element';
+    readonly holder: DenseReference;
+    readonly key: IrOperand;
+    readonly operand: IrOperand;
+};
+/**
+ * One loop's condition.
+ *
+ * The flag is per LOOP and CUMULATIVE -- it ands its enclosing loop's flag --
+ * because the backend's loop unswitching is what turns the ternary into two
+ * loop bodies, and it versions on one invariant condition, not on several. An
+ * inner body that named three flags measured 62 ms against 7.9 for the same
+ * body behind one (`bench/comparison`'s matrix_multiply): clang gave up rather
+ * than emit eight versions. Anding outward is also what lets an access reached
+ * inside a nested loop cite the innermost flag -- the only one that loop's own
+ * unswitching can see -- and still stand for its own window's proof.
+ */
+export interface DenseGroup {
+    readonly ordinal: number;
+    /** The enclosing loop's group, whose flag this one ands. */
+    readonly parent: number | null;
+    readonly preheader: IrBlockId;
+}
+export interface DenseAccess {
+    /** The window whose pointer this access indexes. */
+    readonly array: number;
+    /** The flag it renders behind: the innermost enclosing loop's, which implies the window's own. */
+    readonly flag: number;
+}
+export interface DenseLoopPlan {
+    readonly arrays: readonly DenseArray[];
+    readonly groups: readonly DenseGroup[];
+    /** Which window each access renders against. */
+    readonly accesses: ReadonlyMap<IrNonTerminatorOperation, DenseAccess>;
+    /**
+     * Every read of a WRAPPED window's own `length`, and the window it belongs to.
+     *
+     * The divisor of `i % ring.length` is loop-invariant by the same admission
+     * that made the window dense -- nothing in the loop resizes the array -- but
+     * clang will not hoist the load: the element stores go through a pointer it
+     * cannot prove disjoint from the vector's own header, so the length is
+     * re-read on every turn and the base pointer never stays in a register.
+     * Measured on `object_create.ts`: 11.5ms as emitted, 10.3ms with only the
+     * length hoisted, 10.1ms with only the guard branch gone, 8.1ms with both.
+     */
+    readonly lengths: ReadonlyMap<IrValueId, number>;
+}
+export declare const emptyDenseLoopPlan: DenseLoopPlan;
+/**
+ * The plan a body can actually RENDER, once the target has answered the one
+ * question that is genuinely about its own storage.
+ *
+ * `denseLoopsOf` states what the loop's own control flow proves; it cannot
+ * say whether THIS backend already has a plain name for a window's array or
+ * counter cell to dereference through -- a local this body owns outright,
+ * unboxed, or a global -- because that is the target's own placement, capture
+ * and boxing decision, not a fact of the program. `admitsCell` is that one
+ * hook (`emit-arrays.ts`'s `denseCellName` is its sole implementation).
+ */
+export type DenseCellPolicy = (declaration: DeclarationId) => boolean;
+/** The windows a body ends up able to render, once `admittedDenseLoopPlanOf` has trimmed the raw plan. */
+export interface AdmittedDenseLoopPlan {
+    readonly arrays: readonly DenseArray[];
+    readonly groups: ReadonlyMap<number, DenseGroup>;
+    readonly accesses: ReadonlyMap<IrNonTerminatorOperation, DenseAccess>;
+    readonly lengths: ReadonlyMap<IrValueId, number>;
+}
+/**
+ * Narrows `denseLoopsOf`'s raw plan to the windows this body may actually
+ * render.
+ *
+ * A window not admitted here is never a refusal: the array still renders
+ * through the ordinary indexed path, which is always correct, and this only
+ * decides which windows get the additional fast one. Three things a plan
+ * built from the IR alone cannot settle are decided here, and only the first
+ * is about this backend's own storage rather than about the program:
+ *
+ * - whether this body already has a plain name for the cells a window
+ *   reaches through (`admitsCell`);
+ * - whether the integer census narrowed every index a window's accesses
+ *   read -- an un-narrowed `number` key is not an element access at all --
+ *   except a WRAPPED window, which is exempt: its own admission already
+ *   proves the array non-empty and hole-free (`DenseArray.wrapped`), so a
+ *   remainder by that length or by a literal modulus needs no narrowed index
+ *   to be a real one; one un-narrowed access anywhere in an ordinary window
+ *   takes the WHOLE window down, since every access shares the one pointer
+ *   the narrowing proof is about;
+ * - and, once the two above have dropped some accesses, whether anything is
+ *   left of a window at all: an array with no surviving access has no
+ *   pointer worth materializing, and a flag chain with no claimed window
+ *   below it has nothing to compute either -- a flag ands its enclosing
+ *   loop's, so every group on a claimed window's chain has to exist even
+ *   when nothing indexes anything in that loop, and no group outside that
+ *   chain is needed at all.
+ */
+export declare const admittedDenseLoopPlanOf: (plan: DenseLoopPlan, integerValues: ReadonlySet<IrValueId>, admitsCell: DenseCellPolicy) => AdmittedDenseLoopPlan;
+export declare const denseLoopsOf: (body: IrBody) => DenseLoopPlan;