/**
 * hasselink/tiling/bitmap.ts
 * ------------------------------------------------------
 * Sparse-monitoring bitmap vocabulary.
 *
 * Goal:
 * - Represent a HUGE logical address space (e.g. 48-bit) with a small,
 *   hierarchical bitmap that observers can scan efficiently.
 * - Spend MORE bits per coarse cell than strictly necessary (redundancy)
 *   so observers can cheaply estimate activity density and where to drill.
 * - Follow the bitmap with a transaction list that carries full details.
 *
 * This is spec vocabulary only; concrete layouts (texture dimensions,
 * packing, endianness, etc.) belong in a runtime package.
 */

import type { Bit } from "../bit/bit.ts";
import type { NatLadderBase } from "../program/nat-ladder.ts";

/** 3-bit saturating counter (0..7) represented as bits. */
export type Counter3 = readonly [Bit, Bit, Bit];

/** 4-bit saturating counter (0..15) represented as bits. */
export type Counter4 = readonly [Bit, Bit, Bit, Bit];

export type BitsPerCell = 1 | 2 | 3 | 4;

/**
 * A coarse cell in the monitoring bitmap.
 *
 * Normative intent:
 * - `count` approximates "how many events touched this region" during a window.
 * - Counter is allowed to be saturating (overflow sticks at all-1s).
 * - `hot` is an optional single-bit fast path for "nonzero".
 */
export interface ActivityCell<Bits extends BitsPerCell = 4> {
  bitsPerCell: Bits;
  hot?: Bit;
  count: Bits extends 4
    ? Counter4
    : Bits extends 3
      ? Counter3
      : readonly Bit[];
}

/**
 * A single resolution level of the bitmap.
 *
 * `level` is semantic, not necessarily a power-of-two.
 * Typical intent:
 * - lower level => coarser view (fewer cells)
 * - higher level => finer view (more cells)
 */
export interface ActivityBitmapLevel<Bits extends BitsPerCell = 4> {
  level: number;
  cell: ActivityCell<Bits>;
}

/**
 * A hierarchical activity bitmap.
 *
 * Normative intent:
 * - Level 0 might cover the whole address space (very coarse).
 * - Each higher level refines into smaller regions ("fat pixels" -> subpixels).
 * - Observers can scan coarse levels first, then drill only into hot regions.
 */
export interface ActivityBitmapSpec<Bits extends BitsPerCell = 4> {
  bitsPerCell: Bits;
  levels: number;
  /**
   * Refinement policy.
   *
   * Normative intent (Hasselink): refinement follows the Nat prime-ladder arities,
   * not base-2 quad/oct trees.
   *
   * Think: 7-tree, 31-tree, 127-tree, ... (Mersenne prime ladder).
   *
   * This matches the same recursion intuition used by `NatAtom` digit bases:
   * a small, stable ladder with a deterministic tail rule.
   */
  refinement: PrimeLadderRefinement;
}

/**
 * PrimeLadderRefinement:
 * hierarchical fanout driven by the Nat ladder bases.
 */
export interface PrimeLadderRefinement {
  kind: "prime-ladder";
  /**
   * Fanout arities (typically a prefix of the Nat ladder, e.g. [7, 31, 127]).
   *
   * Tail rule should be consistent with `natBaseAt`:
   * for all deeper levels, the last arity may repeat.
   */
  arities: readonly NatLadderBase[];
  tail?: "repeat-last";
}