web/src/customer-grid/folders.ts

// ---------------------------------------------------------------------------
// customer-grid / folders.ts
// Wave-8 I11c (contract C4) — the folder MODEL for the Views and Cohorts rails,
// pure and React-free so verify_folders.py can run it under node.
//
// One level, deliberately. Nesting brings cycle-checking, move-into-your-own-
// descendant, and recursive delete semantics with it; the owner asked for
// folders you can drag things into, and a flat model is the whole of that.
//
// THE PART THAT IS EASY TO GET WRONG — the echo. Folder operations ride the
// same once-by-id event log as everything else, so between the emit and the
// host's echo there is a window where the payload still describes the world as
// it was BEFORE the click. Render that naively and a just-deleted folder
// reappears for one round trip (the "delete blip"), a rename flickers back to
// the old name, and a dragged view jumps home. So this module reconciles the
// host's copy against this browser's own recent stamps, exactly as
// optimism.ts::reconcileFields does for fields — same ECHO_RECENT_MS window,
// same rule that a STALE stamp yields to the host (divergence is not an echo).
// ---------------------------------------------------------------------------

import { ECHO_RECENT_MS } from "./viewEcho";
import type { GridFolder } from "./types";

/** What this browser did recently, by folder id / item id. Values are epoch ms
 *  from THIS machine's clock — both sides of every comparison are local, so
 *  this is not the tenant-day rule (that one is about two ENGINES agreeing). */
export interface FolderStamps {
  created?: Record<string, number>;
  renamed?: Record<string, { at: number; name: string }>;
  deleted?: Record<string, number>;
  /** itemId -> {at, folderId} for a drag this browser just performed. */
  moved?: Record<string, { at: number; folderId: string | null }>;
  /**
   * WAVE 20 item 19 (C-FOLDER-REORDER) — the FULL folder order this browser just set.
   *
   * ONE stamp, not one per folder, because a reorder is one decision about a list: the
   * order the user dropped into is the order they want, and reconstructing it from N
   * per-folder stamps would let two of them age out at different moments and leave a
   * sequence nobody ever chose. The host answers with `order` NUMBERS on each folder
   * (that is the durable form); this is what to render until it does.
   */
  ordered?: { at: number; order: string[] };
  /**
   * ⭐ WAVE 27 · OWNER ITEM 5 (contract C7) — the FULL VIEW order this browser just set.
   *
   * A separate stamp from `ordered` above, deliberately, even though both are "a list this
   * browser dragged into shape": they age independently and they are different decisions. One
   * stamp holding both would make reordering a folder revive a view order the user had already
   * let go of, and vice versa — the exact "a sequence nobody ever chose" failure `ordered`'s own
   * note refuses one level down.
   */
  orderedViews?: { at: number; order: string[] };
}

export const FOLDER_STAMP_MAX = 64;

const isRecent = (t: number | undefined, now: number): boolean =>
  typeof t === "number" && now - t <= ECHO_RECENT_MS;

/** Drop stamps past the echo window so the map cannot grow without bound and a
 *  long-lived tab cannot keep asserting an edit nobody remembers. */
export function pruneFolderStamps(stamps: FolderStamps | undefined, now: number): FolderStamps {
  const out: FolderStamps = {};
  const keepNum = (rec: Record<string, number> | undefined) => {
    if (!rec) return undefined;
    const kept = Object.entries(rec).filter(([, t]) => isRecent(t, now));
    return kept.length ? Object.fromEntries(kept.slice(-FOLDER_STAMP_MAX)) : undefined;
  };
  const keepObj = <T extends { at: number }>(rec: Record<string, T> | undefined) => {
    if (!rec) return undefined;
    const kept = Object.entries(rec).filter(([, v]) => isRecent(v.at, now));
    return kept.length ? Object.fromEntries(kept.slice(-FOLDER_STAMP_MAX)) : undefined;
  };
  const created = keepNum(stamps?.created);
  const renamed = keepObj(stamps?.renamed);
  const deleted = keepNum(stamps?.deleted);
  const moved = keepObj(stamps?.moved);
  if (created) out.created = created;
  if (renamed) out.renamed = renamed;
  if (deleted) out.deleted = deleted;
  if (moved) out.moved = moved;
  // Item 19: a single stamp, so it is kept or dropped whole — pruning it by halves is
  // exactly the partial sequence the field's own note refuses.
  if (isRecent(stamps?.ordered?.at, now) && stamps?.ordered) out.ordered = stamps.ordered;
  // Item 5 (C7): the same rule for the VIEW order, kept or dropped whole for the same reason.
  if (isRecent(stamps?.orderedViews?.at, now) && stamps?.orderedViews)
    out.orderedViews = stamps.orderedViews;
  return out;
}

/**
 * ⭐ WAVE 27 · OWNER ITEM 5 (contract C7) — the rail's view order, as this browser last set it.
 *
 * ⛔ WHY IT IS NEEDED AT ALL: the server assembles view order (`aios_grid.py:1602-1647`) and the
 * echo is one round trip behind the drop. Without this the row springs back to its old place the
 * instant the workspace refreshes, which reads as "the drag did not work" — the NO-BLIP law's
 * subject, applied to a sequence instead of to a value.
 *
 * ⚠ PAST THE ECHO WINDOW THE SERVER WINS, unconditionally. That asymmetry is the whole design of
 * this module: inside the window a local drag is newer truth; outside it, a difference between
 * the copies is divergence between SESSIONS, and the durable store decides.
 *
 * ⛔ IDS THE STAMP DOES NOT NAME KEEP THEIR SERVER ORDER, appended after the named ones — the
 * same rule the host applies to a `folder_reorder` payload. A view created in another tab since
 * the drop is not evidence that the drop was wrong; dropping it would be this function deleting
 * a view from the rail to defend a sequence.
 */
export function applyViewOrder<T extends { id: string }>(
  views: T[],
  stamps: FolderStamps | undefined,
  now: number
): T[] {
  const stamp = stamps?.orderedViews;
  if (!stamp || !isRecent(stamp.at, now) || !Array.isArray(stamp.order)) return views;
  const byId = new Map(views.map((v) => [v.id, v]));
  const out: T[] = [];
  const placed = new Set<string>();
  for (const id of stamp.order) {
    const v = byId.get(id);
    if (!v || placed.has(id)) continue;
    placed.add(id);
    out.push(v);
  }
  for (const v of views) if (!placed.has(v.id)) out.push(v);
  return out;
}

/**
 * The host's folder list, corrected by what this browser just did.
 *
 *   deleted recently  -> DROP it, even though the echo still lists it
 *                        (the tombstone rule; without this a deleted folder
 *                        blinks back for one round trip)
 *   renamed recently  -> keep OUR name until the echo carries it
 *   created recently  -> keep OURS if the echo has not caught up yet
 *
 * Everything stale yields to the host: past the window, a difference between
 * the copies is divergence between sessions, and host state is the durable
 * truth. That asymmetry is the whole design.
 */
export function reconcileFolders(
  hostFolders: GridFolder[] | undefined,
  localFolders: GridFolder[] | undefined,
  stamps: FolderStamps | undefined,
  now: number
): GridFolder[] {
  const host = hostFolders ?? [];
  const out: GridFolder[] = [];
  const seen = new Set<string>();

  for (const f of host) {
    if (isRecent(stamps?.deleted?.[f.id], now)) continue; // tombstone
    seen.add(f.id);
    const rename = stamps?.renamed?.[f.id];
    out.push(isRecent(rename?.at, now) && rename ? { ...f, name: rename.name } : f);
  }

  // A folder this browser created that the echo has not yet returned. Skipped
  // when it was also deleted since — creating and deleting inside one window
  // must net to nothing, not to a ghost.
  for (const f of localFolders ?? []) {
    if (seen.has(f.id)) continue;
    if (!isRecent(stamps?.created?.[f.id], now)) continue;
    if (isRecent(stamps?.deleted?.[f.id], now)) continue;
    out.push(f);
  }

  out.sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.name.localeCompare(b.name));

  // ── WAVE 20 item 19 (C-FOLDER-REORDER): this browser's drag, until the echo carries it.
  //
  // Applied AFTER the host sort and as a SEPARATE pass, both deliberately:
  //   · the host's `order` numbers are the durable truth and stay the base sequence, so a
  //     folder the stamp never names keeps exactly the place the server gave it;
  //   · `Array.prototype.sort` is stable (ES2019), so every unnamed folder — one created in
  //     another tab between the drag and the echo, say — holds its relative position at the
  //     end instead of being flung to the front by a missing rank.
  // A stamped id that has since been DELETED needs no handling: the tombstone pass above
  // already dropped it, and `rank` is only ever consulted for folders that survived.
  const ordered = stamps?.ordered;
  if (isRecent(ordered?.at, now) && ordered) {
    const rank = new Map(ordered.order.map((id, i) => [id, i]));
    out.sort(
      (a, b) =>
        (rank.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
        (rank.get(b.id) ?? Number.MAX_SAFE_INTEGER)
    );
  }
  return out;
}

/**
 * Where an item actually belongs right now: this browser's recent drag wins
 * over the host's echo, and a folder that no longer exists resolves to ROOT.
 *
 * The second half matters as much as the first. `folder_delete` moves contents
 * to root host-side, but the client sees the folder vanish one render before
 * the items' `folderId` is rewritten — and an item pointing at a folder nobody
 * renders would simply not appear in any group. Resolving a dangling ref to
 * root is what stops a folder delete from making views look deleted too.
 */
export function resolveFolderId(
  itemId: string,
  hostFolderId: string | null | undefined,
  folders: GridFolder[],
  stamps: FolderStamps | undefined,
  now: number
): string | null {
  const moved = stamps?.moved?.[itemId];
  const id = isRecent(moved?.at, now) && moved ? moved.folderId : (hostFolderId ?? null);
  if (id == null) return null;
  // ⚠ W32-T27 — the RESERVED root placement is not a dangling reference. It names no folder by
  // design, so the `folders.some(...)` test below would null it and hand the item straight back
  // to the Shared bucket, re-creating item 20 one layer down from where it was fixed.
  if (id === ROOT_FOLDER_ID) return ROOT_FOLDER_ID;
  return folders.some((f) => f.id === id) ? id : null;
}

export interface FolderGroup<T> {
  folder: GridFolder | null; // null = the root group
  items: T[];
}

/**
 * WAVE 20 item 18 / WAVE 21 item 9 (ruling R12, contract C1) — the SYNTHETIC folder
 * that every view shared WITH you appears under.
 *
 * ⛔ IT IS NOT A STORED FOLDER, and nothing may ever write one with this id. It has no
 * record in `folders`, no `order`, no icon, and the rail refuses every action on it
 * (`ViewSidebar` suppresses the row menu for exactly this id): it cannot be renamed into
 * something else, duplicated into a second copy of other people's work, or deleted. It is a
 * READING of the view list — "these arrived by grant" — rendered as a group because that is
 * the only shape this rail has for "a set of views with something in common".
 *
 * Declared HERE rather than in the component (where it lived through wave 20) so the
 * synthesis below is pure, and `verify_folders.py` can run it under node like every other
 * rule in this file. A constant a gate cannot reach is a contract nobody checks.
 */
export const SHARED_FOLDER_ID = "__shared__";
export const SHARED_FOLDER_NAME = "Shared with me";

/**
 * ⭐⭐ WAVE 32 · T27 (owner item 20) — **"FILED AT ROOT", AS A VALUE.**
 *
 * Owner: *a shared View cannot be moved out of the Shared folder.* The cause is that **root was
 * represented by ABSENCE at every layer**, and absence cannot distinguish two different facts:
 *
 *   · `folderId == null` because the receiver never filed this view — it should show under
 *     "Shared with me", which is where a grant LANDS;
 *   · `folderId == null` because the receiver deliberately dragged it OUT of that group.
 *
 * `groupByFolder` had to guess, and it guessed "shared" — so filing a shared view at root put it
 * straight back where it came from. **The root bucket was unreachable for a shared view by
 * construction**, which is exactly why only folder→folder moves ever appeared to work.
 *
 * ⛔ THE SENTINEL IS STORED, NOT DERIVED, AND THAT IS THE WHOLE FIX. Both other layers wrote the
 * same absence and must both learn this value: `core/grid_events.py`'s `item_move` branch
 * (`if target is None: cur.pop(item_id, None)  # back to the root`) and
 * `aios_grid.clean_item_folders`, whose own docstring states the defect one level deeper —
 * *"nothing stores 'this item is in no folder'"*. A client-only fix is impossible; there is
 * nothing to read back.
 *
 * ⚠ It is a RESERVED id in the same namespace as real folder ids, so `resolveFolderId` must pass
 * it through rather than treating it as dangling, and `clean_item_folders` must admit it beside
 * `fid in fids`. It is deliberately NOT rendered as a group: {@link groupByFolder} maps it onto
 * the ordinary root bucket, so nothing in the rail ever shows the word.
 */
export const ROOT_FOLDER_ID = "__root__";

/**
 * Group items into folders + a root bucket, in folder order, root LAST.
 *
 * Root last because the rails are read top-down and folders are the structure
 * the user made; ungrouped items are the leftovers. Every item appears exactly
 * once — a grouping that can drop an item would make a view look deleted.
 *
 * ⭐ WAVE 21 item 9 (R12/C1) — `isShared` adds the synthetic "Shared with me" group,
 * AFTER root, and three things about it are deliberate:
 *
 *   · **After root, not before it.** C1 says LAST in as many words. It reads correctly
 *     too: the rail is "my folders, my loose views, and then other people's".
 *   · **A shared view the receiver has FILED still goes to their folder.** The `__shared__`
 *     group is where a grant LANDS, not a cage it stays in — the rail's own note calls
 *     moving out "per-receiver placement" and that must keep working. So the synthetic
 *     group collects only the shared views that resolved to ROOT.
 *   · **An empty group does not render.** A folder head with nothing under it says "here is
 *     something you cannot reach" — the same reason `foldNav` drops empty nav folders.
 *
 * Omitting `isShared` leaves the function byte-identical to the pre-wave-21 one, which is
 * what every existing caller (the cohort rail, the tests) still gets.
 */
export function groupByFolder<T>(
  items: T[],
  folders: GridFolder[],
  folderIdOf: (item: T) => string | null,
  isShared?: (item: T) => boolean
): FolderGroup<T>[] {
  const buckets = new Map<string, T[]>(folders.map((f) => [f.id, []]));
  const root: T[] = [];
  const shared: T[] = [];
  for (const item of items) {
    const id = folderIdOf(item);
    const bucket = id == null ? undefined : buckets.get(id);
    if (bucket) bucket.push(item);
    // ⭐⭐ W32-T27 (owner item 20) — THE ROOT BUCKET IS REACHABLE FOR A SHARED VIEW NOW.
    // `ROOT_FOLDER_ID` is the receiver saying "I filed this at the top level"; absence still
    // means "this arrived by grant and I have not filed it". Before this line the two were one
    // value, `isShared` won, and a shared view dragged to root returned to "Shared with me" on
    // the next render — the owner's item 20, in one branch.
    else if (id === ROOT_FOLDER_ID) root.push(item);
    else if (isShared?.(item)) shared.push(item);
    else root.push(item);
  }
  const out: FolderGroup<T>[] = folders.map((f) => ({ folder: f, items: buckets.get(f.id) ?? [] }));
  out.push({ folder: null, items: root });
  if (shared.length)
    out.push({ folder: { id: SHARED_FOLDER_ID, name: SHARED_FOLDER_NAME }, items: shared });
  return out;
}

/**
 * WAVE 20 item 19 (C-FOLDER-REORDER) — where a dragged folder lands: the full order with
 * `draggedId` moved to sit immediately BEFORE `beforeId`, or last when that is null (the
 * drop on the ungrouped section below every folder).
 *
 * Here rather than inside the rail because it is the only part of the drag a test can hold:
 * the drop handler is DOM, the emit is the caller's, and this is the arithmetic that decides
 * what the user sees. `null` means "emit nothing" — an unknown id, or a drop that changes
 * nothing. Returning the unchanged array instead would be worse than useless: the caller
 * cannot tell it apart from a real reorder, so every no-op drag would write the store, bump
 * every reader's payload, and reconcile to the identical list.
 *
 * ⚠ The dragged id is REMOVED BEFORE the target index is read. Taking the index first and
 * splicing after is the classic off-by-one here: dragging a folder DOWNWARD would land it one
 * place short of where it was dropped, and only in that direction — the shape of bug that
 * survives a demo and gets reported as "it sometimes doesn't move".
 */
export function reorderFolderIds(
  ids: string[],
  draggedId: string,
  beforeId: string | null
): string[] | null {
  if (!ids.includes(draggedId)) return null;
  // ⛔ DROPPED ON ITSELF. Without this the id is filtered out, `indexOf` cannot find its own
  // target, and the "not found" branch sends the folder to the END — so releasing a drag over
  // the folder you picked up would quietly move it to the bottom of the rail. Found by this
  // function's own gate the minute the arithmetic left the component; the drop handler's
  // indicator suppresses the same case visually, which is exactly why it would never have
  // been noticed there.
  if (beforeId === draggedId) return null;
  const rest = ids.filter((id) => id !== draggedId);
  const found = beforeId ? rest.indexOf(beforeId) : -1;
  const at = found < 0 ? rest.length : found;
  const next = [...rest.slice(0, at), draggedId, ...rest.slice(at)];
  if (next.length === ids.length && next.every((id, i) => id === ids[i])) return null;
  return next;
}

/** A fresh folder id. Client-generated, like every other id in this component. */
export function newFolderId(): string {
  const rand =
    typeof crypto !== "undefined" && "randomUUID" in crypto
      ? crypto.randomUUID().slice(0, 8)
      : Math.random().toString(36).slice(2, 10);
  return `fld_${rand}`;
}