/**
 * hasselink/tiling/prev-snapshot.ts
 * ------------------------------------------------------
 * A redundant Prev snapshot designed for sparse activity.
 *
 * User intent captured:
 * - `prev` should be "larger than needed" (purposeful redundancy).
 * - It should include a few layers (e.g. 4–5) of "echo of prev-in-prev".
 * - It should carry a bitmap-like projection that lets monitors learn
 *   *where* activity happened without ingesting full transactions.
 * - It should still be followed by a list of actual transactions/receipts
 *   for full verification / replay.
 */

import type { Coord5D } from "../genesis/genesis.ts";
import type { Receipt } from "../receipt.ts";
import type { Ray } from "../codec/ray.ts";
import type { TimeParity } from "../oracle.ts";
import type { ActivityBitmapSpec, BitsPerCell } from "./bitmap.ts";

/**
 * Default echo policy (normative recommendation):
 *
 * One `PrevSnapshot` should feel like "the last 5 frames":
 * - the snapshot itself (most recent) at full scale,
 * - plus 4 echoes (prev-in-prev) at increasingly smaller scales.
 */
export const DEFAULT_PREV_ECHO_LAYERS = 4 as const;

/**
 * A "transaction" at the tiling/projection level.
 *
 * Normative intent:
 * - It points at the touched address region (`anchor` + `ray`).
 * - It is accompanied by a Receipt (nonce-chain / identity proof) which can
 *   later be extended into full state-transition proofs.
 */
export interface ProjectionTx<T = unknown> {
  anchor: Coord5D;
  ray: Ray;
  receipt: Receipt<T>;
}

/**
 * One echo layer of history carried inside `PrevSnapshot`.
 *
 * Echo layers are redundant summaries intended for fast monitoring.
 * `depth=1` means "echo of prev" (i.e. prev^2), etc.
 */
export interface PrevEchoLayer<Bits extends BitsPerCell = 4> {
  /**
   * Echo depth relative to the snapshot:
   * - 1 means "echo of prev" (prev^2)
   * - 2 means prev^3
   * - 3 means prev^4
   * - 4 means prev^5
   */
  depth: 1 | 2 | 3 | 4;
  bitmap: ActivityBitmapSpec<Bits>;
}

/**
 * How the echoes are embedded into the painted bitmask.
 *
 * Normative intent:
 * - full-scale "bright fat pixel stars" hold the most recent summary,
 * - smaller echo summaries appear in the gaps/holes/ribs between them,
 *   like distant galaxies: still visible, but lower resolution.
 */
export interface PrevEchoEmbedding {
  kind: "galaxy";
}

/**
 * PrevSnapshot:
 * a protocol-level snapshot artifact, intentionally redundant.
 */
export interface PrevSnapshot<Bits extends BitsPerCell = 4, TxValue = unknown> {
  /**
   * The time parity of this snapshot (EvenData vs OddCode).
   * This matters for decoding parity-encoded visible bits.
   */
  parity: TimeParity;

  /**
   * Coarse activity overview for this snapshot window.
   * Typically a multi-level hierarchical bitmap.
   */
  bitmap: ActivityBitmapSpec<Bits>;

  /**
   * Echoes of earlier snapshots (prev-in-prev), intentionally redundant.
   *
   * Normative recommendation: exactly 4 layers (depth 1..4), so that one
   * PrevSnapshot carries a 5-frame feel (prev + 4 echoes).
   */
  echoes: readonly [
    PrevEchoLayer<Bits> & { depth: 1 },
    PrevEchoLayer<Bits> & { depth: 2 },
    PrevEchoLayer<Bits> & { depth: 3 },
    PrevEchoLayer<Bits> & { depth: 4 }
  ];

  /**
   * Embedding style for painting these echoes into the 2D substrate.
   * This is a semantic promise, not a concrete pixel layout.
   */
  echoEmbedding: PrevEchoEmbedding;

  /**
   * Sparse full-fidelity transaction list.
   * Normative intent:
   * - observers can choose to only ingest bitmap updates,
   * - while validators/replayers ingest the tx list.
   */
  transactions: readonly ProjectionTx<TxValue>[];
}