// Construction
//
// `new` is a [transform]: at each call site it chooses the allocation strategy
// (escape-driven — the first GENERAL local optimization done as a per-module
// transform, per the castles plan). INCREMENT 1: it routes every site to the
// heap constructor `new-heap`, byte-equivalent to the old behavior — proving the
// transform conversion is transparent. INCREMENT 2 adds the stack lowering for
// proven-local, comptime-sized fields. Mirrors std/list:new's
// route-and-preserve-continuations shape (the `| field` / `| err` match carries
// over to `new-heap` unchanged).
~[comptime|transform] pub tor new {
    invocation: *const Invocation,
    item: *const Item,
    allocator: std.mem.Allocator
} -> SiteResult

// Heap constructor — the concrete runtime allocation. `new` routes here unless
// the escape pass proves the field local (then it's stack-built at the call
// site). The Field carries its allocator, so `free` is allocator-agnostic.
~pub tor new-heap { bits: usize }
| field *Field<field!>
| err string

// EXPLICIT stack constructor (Brick 1 of escape-driven allocation). Places the
// Field and its word buffer in the CALLER's frame — no heap, no per-pass page
// fault. Bare-return (`-> *Field`, no `err`: a stack buffer can't OOM). Must be a
// [transform]: stack memory cannot be returned from a callee, so the construction
// is inlined at the call site. `bits` must be comptime (Zig errors otherwise —
// the array size is comptime). `free` rides the no-op allocator, unchanged.
// Brick 2 will route a provably-local `new` here automatically.
~[comptime|transform] pub tor new.on-stack {
    bits: usize,
    reporter: std/compiler:*ErrorReporter
} -> *Field<field!>

// Concrete stack-wiring constructor for `new.on-stack`. The transform's preamble
// declares a caller-frame word buffer + Field slot and passes them here; this
// zeroes the buffer and wires the Field with the no-op allocator (so `free` is a
// safe no-op — no free-site rewrite). Carries <field!> so the obligation survives
// the transform. Not meant to be called directly.
~pub tor new-instack { buf: []u64, slot: *Field, bits: usize } -> *Field<field!>

// Mutation (borrow — obligation untouched)
//
// Set bit i to 1. Void, chains with `|>`. The irreducible per-cell poke.
~pub tor set { f: *Field<field>, i: usize }

// Set every bit in the arithmetic progression {from, from+stride, ...} <= limit.
// The IR's AP-write access pattern, fused: one tight strided bit-fill instead of a
// per-cell `set` call through the flow. Word-blocking (precomputed per-stride
// patterns) is a later refinement; this is the simple fused loop.
~pub tor strike { f: *Field<field>, from: usize, stride: usize, limit: usize }

// Wheel-strided strike: for a prime `p`, set every bit `p*w` where `w` is a wheel
// position (the residues in `wheel`, repeated every `period`) with `w >= p` and
// `p*w <= limit`. The composite wheel positions of `p` are exactly `p * (wheel
// positions >= p)`, so this marks only coprime-to-period multiples — `period/φ`
// fewer strikes than the full `strike`. Assumes `wheel[0] == 1` (the unit residue),
// used for the cheap per-block early-out.
~pub tor strike-wheel {
    f: *Field<field>,
    p: usize,
    wheel: []const usize,
    period: usize,
    limit: usize
}

// Mark every multiple of `stride` in [from, limit] — set the whole strided
// residue class. Unlike `strike` (an arbitrary AP from `from`), this is a
// [transform]: the COMPILER GENERATES a specialized, fully-unrolled marker per
// stride and dispatches at runtime. Same move as regex->DFA, kernel->SIMD: a
// restricted access pattern compiled to specialized native code. (v1: plumbing
// proof — emits one simple correct marker; the per-stride unrolled codegen lands
// next.)
~[comptime|transform] pub tor mark-multiples {
    f: *Field<field>,
    from: usize,
    stride: usize,
    limit: usize,
    reporter: std/compiler:*ErrorReporter
}

// Zero every bit — reset a field for reuse without reallocating. The lever for
// alloc-once sieve loops: `new` once, `clear` each pass instead of new/free per
// pass (the per-pass allocation/page-fault tax is the dominant cost once marking
// is wheel-strided).
~pub tor clear { f: *Field<field> }

// Read (borrow)
//
// 1 if bit i is set, else 0.
~pub tor test { f: *Field<field>, i: usize } -> i64

// Count of UNSET bits in [lo, hi). Word-wise @popCount over the aligned middle —
// the IR's "1-bit (+,0) reduction recognized as popcount", made real.
~pub tor count-zeros { f: *Field<field>, lo: usize, hi: usize } -> i64

// Teardown (consume — discharges <!field>)
~pub tor free { f: *Field<!field> }