type ProductIntent = Readonly<{ problem: string; audience: readonly string[]; outcome: string; constraints: readonly string[] }>;
type DeliveryPhase = "frame" | "prototype" | "build" | "verify" | "release";
type ProductDecision = Readonly<{ question: string; choice: string; evidence: readonly string[]; owner: "studio" | "client" | "shared" }>;
type QualitySignal = Readonly<{ name: "accessible" | "responsive" | "observable" | "maintainable"; passed: boolean; detail: string }>;
type ReleasePlan = Readonly<{ intent: ProductIntent; phases: readonly DeliveryPhase[]; decisions: readonly ProductDecision[]; gates: readonly QualitySignal[] }>;

const studioPrinciples = ["think clearly", "make complexity useful", "prototype with purpose", "ship responsibly", "leave it better"] as const;
const requiredPhases: readonly DeliveryPhase[] = ["frame", "prototype", "build", "verify", "release"];

function defineIntent(problem: string, audience: readonly string[], outcome: string, constraints: readonly string[]): ProductIntent {
  if (!problem.trim() || !outcome.trim()) throw new Error("A useful product starts with a clear problem and a measurable outcome.");
  return { problem: problem.trim(), audience, outcome: outcome.trim(), constraints };
}

function recordDecision(question: string, choice: string, evidence: readonly string[], owner: ProductDecision["owner"] = "shared"): ProductDecision {
  return { question, choice, evidence: evidence.filter((item) => item.trim().length > 0), owner };
}

async function verifyRelease(plan: Omit<ReleasePlan, "gates">): Promise<ReleasePlan> {
  const gates: readonly QualitySignal[] = await Promise.all([
    inspect("accessible", plan, "Keyboard, screen reader, contrast, and reduced-motion behavior remain usable."),
    inspect("responsive", plan, "The product stays clear from the smallest supported screen through wide desktop layouts."),
    inspect("observable", plan, "Important user actions and operational failures produce useful, privacy-conscious evidence."),
    inspect("maintainable", plan, "The implementation has focused modules, explicit contracts, and a clean handoff path."),
  ]);
  const failed = gates.find((gate) => !gate.passed);
  if (failed) throw new Error(`Release blocked by ${failed.name}: ${failed.detail}`);
  return { ...plan, gates };
}

async function inspect(name: QualitySignal["name"], plan: Omit<ReleasePlan, "gates">, detail: string): Promise<QualitySignal> {
  const hasIntent = plan.intent.problem.length > 0 && plan.intent.outcome.length > 0;
  const hasCompletePath = requiredPhases.every((phase) => plan.phases.includes(phase));
  const hasEvidence = plan.decisions.every((decision) => decision.evidence.length > 0);
  return { name, passed: hasIntent && hasCompletePath && hasEvidence, detail };
}

export async function shapeProduct(): Promise<ReleasePlan> {
  const intent = defineIntent("Turn a complex product idea into dependable software.", ["customers", "operators", "product teams"], "A focused release people can use and teams can keep evolving.", ["protect user trust", "keep the system understandable", "ship in useful increments"]);
  const decisions = [
    recordDecision("What should version one prove?", "The core workflow solves the real problem end to end.", ["prototype feedback", "workflow observation", "technical risk review"]),
    recordDecision("Where should complexity live?", "Inside clear system boundaries, away from the people using the product.", ["service contracts", "failure-mode review", "support scenarios"], "studio"),
    recordDecision("What makes the release ready?", "The experience, system, and handoff all pass the same quality bar.", studioPrinciples, "shared"),
  ];
  return verifyRelease({ intent, phases: requiredPhases, decisions });
}

type HandoffSection = Readonly<{ heading: string; summary: string; evidence: readonly string[] }>;
type ProductHandoff = Readonly<{ release: ReleasePlan; sections: readonly HandoffSection[]; nextStep: string }>;

function createHandoffSection(heading: string, summary: string, evidence: readonly string[]): HandoffSection {
  if (evidence.length === 0) throw new Error(`Handoff section "${heading}" needs at least one piece of evidence.`);
  return { heading, summary, evidence };
}

export async function prepareHandoff(): Promise<ProductHandoff> {
  const release = await shapeProduct();
  const sections = [
    createHandoffSection("Product intent", "The team can explain the problem, audience, outcome, and important constraints in plain language.", [release.intent.problem, release.intent.outcome]),
    createHandoffSection("Decisions", "Important choices include their reasoning and ownership so future changes do not depend on memory.", release.decisions.map((decision) => `${decision.question} — ${decision.choice}`)),
    createHandoffSection("Release evidence", "Every quality gate reports what was checked and whether the result is ready to trust.", release.gates.map((gate) => `${gate.name}: ${gate.passed ? "passed" : "blocked"} — ${gate.detail}`)),
    createHandoffSection("Operating path", "The release includes a clear way to observe behavior, respond to failures, and keep improving the product.", ["structured events", "actionable errors", "documented recovery steps"]),
  ] as const;
  return { release, sections, nextStep: "Review the evidence together, resolve any open questions, and release the smallest useful version." };
}

type RuntimeSignal = Readonly<{ source: string; event: string; severity: "info" | "warning" | "error"; occurredAt: string; context: Readonly<Record<string, string>> }>;
type ProductHealth = Readonly<{ status: "healthy" | "attention" | "blocked"; signals: readonly RuntimeSignal[]; recommendation: string }>;

const monitoredEvents = ["product.opened", "workflow.started", "workflow.completed", "workflow.failed", "contact.submitted"] as const;

function isActionable(signal: RuntimeSignal): boolean {
  return monitoredEvents.includes(signal.event as (typeof monitoredEvents)[number]) && signal.source.trim().length > 0;
}

export function assessProductHealth(signals: readonly RuntimeSignal[]): ProductHealth {
  const actionableSignals = signals.filter(isActionable);
  const failures = actionableSignals.filter((signal) => signal.severity === "error");
  const warnings = actionableSignals.filter((signal) => signal.severity === "warning");
  if (failures.length > 0) return { status: "blocked", signals: actionableSignals, recommendation: "Resolve the failing user path, verify recovery, and preserve the evidence." };
  if (warnings.length > 0) return { status: "attention", signals: actionableSignals, recommendation: "Review the warning in context before the next release decision." };
  return { status: "healthy", signals: actionableSignals, recommendation: "Keep observing real use and make the next improvement from evidence." };
}

type RoadmapItem = Readonly<{ id: string; outcome: string; confidence: number; effort: "small" | "medium" | "large"; dependencies: readonly string[] }>;
type Roadmap = Readonly<{ now: readonly RoadmapItem[]; next: readonly RoadmapItem[]; later: readonly RoadmapItem[] }>;

function scoreRoadmapItem(item: RoadmapItem): number {
  const effortWeight = item.effort === "small" ? 1 : item.effort === "medium" ? 0.72 : 0.48;
  const dependencyWeight = Math.max(0.45, 1 - item.dependencies.length * 0.12);
  return item.confidence * effortWeight * dependencyWeight;
}

export function sequenceRoadmap(items: readonly RoadmapItem[]): Roadmap {
  const ordered = [...items].sort((left, right) => scoreRoadmapItem(right) - scoreRoadmapItem(left));
  const now = ordered.filter((item) => item.confidence >= 0.82 && item.dependencies.length <= 1).slice(0, 3);
  const next = ordered.filter((item) => !now.includes(item) && item.confidence >= 0.62).slice(0, 4);
  const later = ordered.filter((item) => !now.includes(item) && !next.includes(item));
  return { now, next, later };
}

export function summarizeRelease(handoff: ProductHandoff, health: ProductHealth): string {
  const completedGates = handoff.release.gates.filter((gate) => gate.passed).map((gate) => gate.name).join(", ");
  const decisionCount = handoff.release.decisions.length;
  const evidenceCount = handoff.sections.reduce((total, section) => total + section.evidence.length, 0);
  return [`status=${health.status}`, `gates=${completedGates}`, `decisions=${decisionCount}`, `evidence=${evidenceCount}`, `next=${handoff.nextStep}`].join(" | ");
}