/**
 * Reference-transfer contract — a PURE, deterministic role-separation emitter +
 * advisory. No I/O, no Date, no Math.random.
 *
 * Reference channels bleed (model-mechanics #6: "references bleed; always state
 * what must NOT transfer"; failure-atlas row 11: "Reference roles contaminate —
 * transfer/ignore clauses were absent"). A multi-reference packet should state,
 * per reference, what it CONTROLS and what must NOT transfer. This emits that
 * canonical clause and warns when a multi-domain packet lacks it.
 *
 * Harvested from the MIT `Emily2040/seedance-2.0` reference-transfer-contract
 * (@63b32dc). Advisory by construction — nothing here mutates a live payload.
 */

export type ReferenceTransferRole =
  | 'character-sheet'
  | 'storyboard-grid'
  | 'start-frame'
  | 'end-frame'
  | 'reference-image'
  | 'background-plate';

export interface ReferenceTransferInput {
  role: ReferenceTransferRole;
  label: string;
}

export interface ReferenceTransferAdvisory {
  code: 'reference-transfer';
  severity: 'warning';
  message: string;
}

/** Bleed-relevant domain per role. `storyboard-grid` -> 'layout' (excluded: it
 *  has the single-full-frame guard and is never an identity/motion donor). */
const ROLE_DOMAIN: Record<ReferenceTransferRole, string> = {
  'character-sheet': 'identity',
  'start-frame': 'continuity',
  'end-frame': 'continuity',
  'background-plate': 'environment',
  'reference-image': 'appearance',
  'storyboard-grid': 'layout',
};

const LAYOUT_DOMAIN = 'layout';

/** What each domain controls and what must not transfer from it. */
const DOMAIN_CONTRACT: Record<string, { controls: string; ignore: string }> = {
  identity: {
    controls: 'face, hair, wardrobe, and silhouette',
    ignore: 'background, environment, camera, and lighting',
  },
  continuity: {
    controls: 'the opening state, pose, and framing',
    ignore: 'identity, wardrobe colour, and environment design',
  },
  environment: {
    controls: 'the location, set, and lighting plate',
    ignore: 'any people, identity, and wardrobe',
  },
  appearance: {
    controls: "the depicted subject's appearance",
    ignore: 'background, camera, and motion',
  },
};

function nonLayoutRefs(refs: ReferenceTransferInput[]): Array<ReferenceTransferInput & { domain: string }> {
  return refs
    .map((ref) => ({ ...ref, domain: ROLE_DOMAIN[ref.role] }))
    .filter((ref) => ref.domain !== LAYOUT_DOMAIN);
}

/** Distinct bleed-relevant domains present (layout excluded), first-appearance order. */
export function referenceDomains(refs: ReferenceTransferInput[]): string[] {
  const out: string[] = [];
  for (const ref of nonLayoutRefs(refs)) {
    if (!out.includes(ref.domain)) out.push(ref.domain);
  }
  return out;
}

/**
 * The canonical "REFERENCE ROLES:" block — one line per non-layout reference:
 * "<label> controls <domain controls> only; ignore <domain ignore> from that
 * reference." Returns '' when there are no non-layout references.
 */
export function referenceTransferClause(refs: ReferenceTransferInput[]): string {
  const lines = nonLayoutRefs(refs).map((ref) => {
    const contract = DOMAIN_CONTRACT[ref.domain];
    if (!contract) return `${ref.label} controls its ${ref.domain} role only; state what must not transfer.`;
    return `${ref.label} controls ${contract.controls} only; ignore ${contract.ignore} from that reference.`;
  });
  if (lines.length === 0) return '';
  return `REFERENCE ROLES:\n${lines.map((line) => `  ${line}`).join('\n')}`;
}

/** True when the prompt already carries a transfer/ignore (role-separation) clause. */
function hasTransferClause(promptText: string): boolean {
  return (
    /reference roles:/i.test(promptText)
    || /controls\b[^.]*\bonly;\s*ignore\b/i.test(promptText)
    || /(do not|don't|must not)\s+transfer/i.test(promptText)
  );
}

/**
 * Warn when a packet's references span ≥2 distinct bleed-relevant domains and the
 * prompt states no transfer/ignore contract. The message quotes the first
 * suggested clause line. Pure: depends only on its arguments.
 */
export function analyzeReferenceTransfer(
  refs: ReferenceTransferInput[],
  promptText: string,
): ReferenceTransferAdvisory[] {
  const domains = referenceDomains(refs);
  if (domains.length < 2) return [];
  if (hasTransferClause(promptText)) return [];

  const clause = referenceTransferClause(refs);
  const firstLine =
    clause
      .split('\n')
      .map((line) => line.trim())
      .find((line) => line && !/^REFERENCE ROLES:/i.test(line)) ?? '';
  return [
    {
      code: 'reference-transfer',
      severity: 'warning',
      message: `packet attaches references spanning ${domains.join(' + ')} but states no transfer/ignore contract — references bleed; add a role-separation clause, e.g. "${firstLine}".`,
    },
  ];
}