answer-graph-generation.ts

import type {
  AlertLevel,
  ClaimConfidenceLevel,
  CounterpointRelationKind,
  ClaimRecencyStatus,
  ClaimSupportKind,
  PropagationStepKind,
  SourceSnapshotType,
} from "@prisma/client";

import type { AnswerGraphJson } from "@/types/answer-graph";
import type { SourceCandidate } from "@/types/source-intake";
import type { InvestigationMode } from "@/server/analysis/investigation-limits";

/** Input for generating graph + evidence payload for a single analysis run. */
export type GenerateAnswerGraphInput = {
  question: string;
  sourceCandidates?: SourceCandidate[];
  mode?: InvestigationMode;
};

/** One source row to persist as `source_snapshots` (order preserved). */
export type GeneratedSourceSnapshot = {
  label: string;
  sourceType: SourceSnapshotType;
  url: string | null;
  excerpt: string | null;
  publishedAt?: Date | null;
};

export type GeneratedClaimSupportInput = {
  sourcePlaceholderId: string;
  supportKind: ClaimSupportKind;
  isPrimarySource?: boolean;
  supportingQuote?: string | null;
  contradictionNote?: string | null;
};

export type GeneratedClaimConfidenceInput = {
  score: number;
  level: ClaimConfidenceLevel;
  summary: string;
  hasPrimarySource: boolean;
  independentSourceCount: number;
  hasSupportingQuote: boolean;
  recencyStatus: ClaimRecencyStatus;
  hasContradiction: boolean;
};

export type GeneratedCounterpointInput = {
  summary: string;
  relationKind?: CounterpointRelationKind;
  graphNodeId?: string | null;
};

export type GeneratedPropagationChainStepInput = {
  stepKind: PropagationStepKind;
  order: number;
  label: string;
  detail?: string | null;
  sourcePlaceholderId?: string | null;
  claimGraphNodeId?: string | null;
  answerSegmentKey?: string | null;
};

/** One claim row + graph node id + source placeholders (`__src_0__`, …) before persist. */
export type GeneratedEvidenceClaimInput = {
  summary: string;
  graphNodeId: string | null;
  /** Legacy path; converted into direct supports when `supports` is omitted. */
  supportedSourcePlaceholderIds: string[];
  /** Preferred normalized support relations for this claim. */
  supports?: GeneratedClaimSupportInput[];
  /** Explainable confidence for this claim. */
  confidence?: GeneratedClaimConfidenceInput;
  /** When set, persisted as `counterpoints` rows for this claim. */
  counterpoints?: GeneratedCounterpointInput[];
  /** Ordered provenance/explanation chain for this claim. */
  propagationChain?: GeneratedPropagationChainStepInput[];
  /** When set, persisted as `alerts` rows with this claim's id. */
  alerts?: { level: AlertLevel; message: string }[];
};

/** Optional structured evidence rows; omit for minimal stub runs. */
export type GeneratedEvidenceBundle = {
  claims: GeneratedEvidenceClaimInput[];
  /**
   * Legacy: one counterargument applied to the first claim when that claim has no `counterpoints`.
   * Prefer per-claim `counterpoints` on each `claims[]` entry.
   */
  counterpoint?: {
    summary: string;
  };
  /**
   * Legacy: answer-scoped alert (`alerts.claim_id` null). Prefer per-claim `alerts` on `claims[]`.
   */
  alert?: {
    level: AlertLevel;
    message: string;
  };
};

/** Persistable result of a successful generation step (DB writer consumes this). */
/**
 * provider出力を永続化用へ正規化した中間payload。
 * graphJsonは描画スナップショットで、claim/source実体は別テーブルへ保存される。
 */
export type GeneratedAnswerGraphPayload = {
  answer: {
    title: string | null;
    model: string | null;
    content: string;
    graphJson: AnswerGraphJson;
  };
  sources: GeneratedSourceSnapshot[];
  evidence?: GeneratedEvidenceBundle;
};

export type GenerateAnswerGraphSuccess = {
  kind: "success";
  payload: GeneratedAnswerGraphPayload;
};

export type GenerateAnswerGraphFailure = {
  kind: "failure";
  /** Safe-for-UI message; also persisted on `analysis_runs.last_error_message` when the run fails. */
  errorMessage: string;
  /** Optional detail for server logs only (not stored by default). */
  cause?: unknown;
};

export type GenerateAnswerGraphResult =
  | GenerateAnswerGraphSuccess
  | GenerateAnswerGraphFailure;