atomic-design-poc/src/app/brief/domain/brief.machine.ts

import { assertNever } from '@shared/kernel/fp';
import {
  Brief,
  BriefDecisions,
  BriefStatus,
  LetterBlock,
  LetterSection,
  LibraryPassage,
  allBlocks,
  canSubmit,
} from './brief';
import { RichTextBlock, deepCopyBlock, emptyBlock } from '@shared/kernel/rich-text';

/**
 * The letter composition state machine (Model + Msg + pure reduce), modeled on
 * `herregistratie/domain/intake.machine.ts`.
 *
 * Two invariants are enforced *here*, not in the UI:
 *  - Status transitions are total and guarded — an out-of-order transition Msg is a
 *    no-op (`draft→submitted→approved/rejected→draft`, `approved→sent`).
 *  - Edits are only possible in `draft`/`rejected`; editing a `rejected` letter flips
 *    it back to `draft`. Sections can never be added, removed, or reordered — there
 *    is no Msg for it, so it is unrepresentable.
 *
 * Authorization is NOT a reducer concern: `decisions` (canEdit/canApprove/canReject/
 * canSend) arrives from the server on every load and every status transition (PRD-0002
 * phase P1) and is carried through unchanged by the reducer — never recomputed here.
 * The reducer guards the status invariant; the server is the sole authority on who may
 * act on it.
 *
 * Note: there is no `PlaceholderInserted` Msg. The editor inserts a placeholder NODE
 * at the caret and emits the whole new block via `BlockContentEdited`; its insert menu
 * only offers keys from `brief.placeholders`, so inserting an unknown key is
 * structurally impossible (a pasted `{{…}}` is caught by the linter as `malformed`).
 */

export type BriefState =
  | { tag: 'loading' }
  | {
      tag: 'loaded';
      brief: Brief;
      availablePassages: readonly LibraryPassage[];
      decisions: BriefDecisions;
    }
  | { tag: 'failed'; reason: string };

export const initial: BriefState = { tag: 'loading' };

export type BriefMsg =
  | {
      tag: 'BriefLoaded';
      brief: Brief;
      availablePassages: readonly LibraryPassage[];
      decisions: BriefDecisions;
    }
  | { tag: 'BriefLoadFailed'; reason: string }
  | { tag: 'PassagesInserted'; sectionKey: string; passages: readonly LibraryPassage[] } // multi-select
  | { tag: 'FreeTextBlockAdded'; sectionKey: string }
  | { tag: 'BlockContentEdited'; blockId: string; content: RichTextBlock }
  | { tag: 'BlockRemoved'; blockId: string }
  | { tag: 'BlockMovedWithinSection'; blockId: string; toIndex: number }
  | { tag: 'Submitted'; by: string; at: string; decisions: BriefDecisions } // draft → submitted
  | { tag: 'Approved'; by: string; at: string; decisions: BriefDecisions } // submitted → approved
  | { tag: 'Rejected'; by: string; at: string; comments: string; decisions: BriefDecisions } // submitted → rejected
  | { tag: 'Sent'; at: string; decisions: BriefDecisions } // approved → sent
  | { tag: 'Seed'; state: BriefState };

/** Edits are allowed only in these statuses; editing a rejected letter reopens it. */
function isEditable(status: BriefStatus): boolean {
  return status.tag === 'draft' || status.tag === 'rejected';
}

/** Next `local-N` block id — DERIVED from existing ids (max + 1), not a stored counter. */
function nextLocalIndex(brief: Brief): number {
  let max = 0;
  for (const b of allBlocks(brief)) {
    const m = /^local-(\d+)$/.exec(b.blockId);
    if (m) max = Math.max(max, Number(m[1]));
  }
  return max + 1;
}

function mapSection(
  brief: Brief,
  sectionKey: string,
  f: (s: LetterSection) => LetterSection,
): Brief {
  return {
    ...brief,
    sections: brief.sections.map((s) => (s.sectionKey === sectionKey ? f(s) : s)),
  };
}

/** The section a block currently lives in, or undefined if the block is gone. */
function sectionKeyOfBlock(brief: Brief, blockId: string): string | undefined {
  return brief.sections.find((s) => s.blocks.some((b) => b.blockId === blockId))?.sectionKey;
}

/** A section accepts edits only when it is not a locked (predefined) template section. */
function isSectionEditable(brief: Brief, sectionKey: string | undefined): boolean {
  const section = brief.sections.find((s) => s.sectionKey === sectionKey);
  return !!section && !section.locked;
}

function mapBlocks(brief: Brief, f: (blocks: readonly LetterBlock[]) => LetterBlock[]): Brief {
  return { ...brief, sections: brief.sections.map((s) => ({ ...s, blocks: f(s.blocks) })) };
}

/** Apply an edit to the brief, guarded by status. A rejected letter reopens to draft. */
function withEdit(s: BriefState, f: (b: Brief) => Brief): BriefState {
  if (s.tag !== 'loaded' || !isEditable(s.brief.status)) return s;
  let brief = f(s.brief);
  if (brief.status.tag === 'rejected') brief = { ...brief, status: { tag: 'draft' } };
  return { ...s, brief };
}

function insertPassages(
  brief: Brief,
  sectionKey: string,
  passages: readonly LibraryPassage[],
): Brief {
  let idx = nextLocalIndex(brief);
  // The freeze happens HERE: each block gets a deep VALUE copy of the library content,
  // so later library edits can never mutate this letter (frozen snapshot).
  const newBlocks: LetterBlock[] = passages.map((p) => ({
    type: 'passage',
    blockId: `local-${idx++}`,
    sourcePassageId: p.passageId,
    sourceVersion: p.version,
    content: deepCopyBlock(p.content),
    edited: false,
  }));
  return mapSection(brief, sectionKey, (s) => ({ ...s, blocks: [...s.blocks, ...newBlocks] }));
}

function addFreeText(brief: Brief, sectionKey: string): Brief {
  const block: LetterBlock = {
    type: 'freeText',
    blockId: `local-${nextLocalIndex(brief)}`,
    content: emptyBlock(),
  };
  return mapSection(brief, sectionKey, (s) => ({ ...s, blocks: [...s.blocks, block] }));
}

function editBlockContent(brief: Brief, blockId: string, content: RichTextBlock): Brief {
  return mapBlocks(brief, (blocks) =>
    blocks.map((b) =>
      b.blockId !== blockId
        ? b
        : b.type === 'passage'
          ? { ...b, content, edited: true } // editing a snapshot marks it, keeps provenance
          : { ...b, content },
    ),
  );
}

function moveWithinSection(
  blocks: readonly LetterBlock[],
  blockId: string,
  toIndex: number,
): LetterBlock[] {
  const from = blocks.findIndex((b) => b.blockId === blockId);
  if (from === -1) return [...blocks];
  const clamped = Math.max(0, Math.min(toIndex, blocks.length - 1));
  const next = [...blocks];
  const [moved] = next.splice(from, 1);
  next.splice(clamped, 0, moved);
  return next;
}

export function reduce(s: BriefState, m: BriefMsg): BriefState {
  switch (m.tag) {
    case 'BriefLoaded':
      return {
        tag: 'loaded',
        brief: m.brief,
        availablePassages: m.availablePassages,
        decisions: m.decisions,
      };
    case 'BriefLoadFailed':
      return { tag: 'failed', reason: m.reason };
    case 'Seed':
      return m.state;

    // Section-level guard (defense-in-depth): locked sections never accept edits, even if a
    // Msg reaches the reducer. The UI already hides controls for locked sections.
    case 'PassagesInserted':
      return withEdit(s, (b) =>
        isSectionEditable(b, m.sectionKey) ? insertPassages(b, m.sectionKey, m.passages) : b,
      );
    case 'FreeTextBlockAdded':
      return withEdit(s, (b) =>
        isSectionEditable(b, m.sectionKey) ? addFreeText(b, m.sectionKey) : b,
      );
    case 'BlockContentEdited':
      return withEdit(s, (b) =>
        isSectionEditable(b, sectionKeyOfBlock(b, m.blockId))
          ? editBlockContent(b, m.blockId, m.content)
          : b,
      );
    case 'BlockRemoved':
      return withEdit(s, (b) =>
        isSectionEditable(b, sectionKeyOfBlock(b, m.blockId))
          ? mapBlocks(b, (blocks) => blocks.filter((x) => x.blockId !== m.blockId))
          : b,
      );
    case 'BlockMovedWithinSection':
      return withEdit(s, (b) =>
        isSectionEditable(b, sectionKeyOfBlock(b, m.blockId))
          ? mapBlocks(b, (blocks) =>
              blocks.some((x) => x.blockId === m.blockId)
                ? moveWithinSection(blocks, m.blockId, m.toIndex)
                : [...blocks],
            )
          : b,
      );

    case 'Submitted':
      // Guard the transition AND the completeness invariant.
      return transition(
        s,
        'draft',
        () => ({ tag: 'submitted', submittedBy: m.by, submittedAt: m.at }),
        m.decisions,
        canSubmit,
      );
    case 'Approved':
      return transition(
        s,
        'submitted',
        () => ({ tag: 'approved', approvedBy: m.by, approvedAt: m.at }),
        m.decisions,
      );
    case 'Rejected':
      return transition(
        s,
        'submitted',
        () => ({ tag: 'rejected', rejectedBy: m.by, rejectedAt: m.at, comments: m.comments }),
        m.decisions,
      );
    case 'Sent':
      return transition(s, 'approved', () => ({ tag: 'sent', sentAt: m.at }), m.decisions);

    default:
      return assertNever(m);
  }
}

/** A guarded status transition: only fires from `from`, and only if `guard` passes.
    `decisions` replaces the prior server-computed flags — always fresh from the
    same response that carried the new status. */
function transition(
  s: BriefState,
  from: BriefStatus['tag'],
  next: () => BriefStatus,
  decisions: BriefDecisions,
  guard: (b: Brief) => boolean = () => true,
): BriefState {
  if (s.tag !== 'loaded' || s.brief.status.tag !== from || !guard(s.brief)) return s;
  return { ...s, brief: { ...s.brief, status: next() }, decisions };
}