@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7001.1.03608ab252

package/src/modules/warranty_claims/lib/stateMachine.ts

@@ -0,0 +1,130 @@
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { CLAIM_STATUS_TRANSITIONS } from '../data/constants'
+import type { WarrantyClaimLineStatus, WarrantyClaimStatus } from '../data/validators'
+import { claimTypeAllowsLineFinancialAdjustments } from './claimTypeConfig'
+
+type AmountValue = number | string | null | undefined
+
+export type ClaimLineRollupInput = {
+  creditAmount?: AmountValue
+  credit_amount?: AmountValue
+  restockingFee?: AmountValue
+  restocking_fee?: AmountValue
+  coreCreditAmount?: AmountValue
+  core_credit_amount?: AmountValue
+  lineStatus?: WarrantyClaimLineStatus | null
+  line_status?: WarrantyClaimLineStatus | null
+  deletedAt?: Date | string | null
+  deleted_at?: Date | string | null
+}
+
+export const lineStatusGuards: Record<WarrantyClaimLineStatus, readonly WarrantyClaimLineStatus[]> = {
+  // `approved -> resolved` supports the credit-only / field-destroy flow where no
+  // physical return is received (the line is resolved without the goods lifecycle).
+  pending: ['approved', 'rejected'],
+  approved: ['received', 'resolved'],
+  rejected: [],
+  received: ['inspected'],
+  inspected: ['resolved'],
+  resolved: [],
+}
+
+const approvedRollupStatuses = new Set<WarrantyClaimLineStatus>(['approved', 'received', 'inspected', 'resolved'])
+const resolvedHeaderLineStatuses = new Set<WarrantyClaimLineStatus>(['rejected', 'resolved'])
+const terminalStatuses = new Set<WarrantyClaimStatus>(['closed', 'cancelled'])
+
+function amount(value: AmountValue): number {
+  if (value === null || value === undefined) return 0
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+function lineCreditAmount(line: ClaimLineRollupInput): number {
+  return amount(line.creditAmount ?? line.credit_amount)
+}
+
+function lineRestockingFee(line: ClaimLineRollupInput): number {
+  return amount(line.restockingFee ?? line.restocking_fee)
+}
+
+function lineCoreCreditAmount(line: ClaimLineRollupInput): number {
+  return amount(line.coreCreditAmount ?? line.core_credit_amount)
+}
+
+function lineStatus(line: ClaimLineRollupInput): WarrantyClaimLineStatus | null {
+  return line.lineStatus ?? line.line_status ?? null
+}
+
+function isDeleted(line: ClaimLineRollupInput): boolean {
+  return Boolean(line.deletedAt ?? line.deleted_at ?? null)
+}
+
+export function nextStatuses(status: WarrantyClaimStatus): WarrantyClaimStatus[] {
+  return [...(CLAIM_STATUS_TRANSITIONS[status] ?? [])]
+}
+
+export function canTransition(from: WarrantyClaimStatus, to: WarrantyClaimStatus): boolean {
+  return nextStatuses(from).includes(to)
+}
+
+export function assertTransition(from: WarrantyClaimStatus, to: WarrantyClaimStatus): void {
+  if (canTransition(from, to)) return
+  throw new CrudHttpError(400, { error: 'warranty_claims.errors.invalidTransition' })
+}
+
+export function isTerminal(status: string): boolean {
+  return (terminalStatuses as Set<string>).has(status)
+}
+
+export function canResolveWithLineStatuses(lines: readonly ClaimLineRollupInput[]): boolean {
+  return lines.every((line) => {
+    if (isDeleted(line)) return true
+    const status = lineStatus(line)
+    return Boolean(status && resolvedHeaderLineStatuses.has(status))
+  })
+}
+
+// Matches the numeric(18,4) scale of the warranty_claims total columns so the
+// float sums serialize without artifacts like "0.30000000000000004".
+const ROLLUP_AMOUNT_SCALE = 10_000
+
+function roundRollupAmount(value: number): number {
+  return Math.round((value + Number.EPSILON) * ROLLUP_AMOUNT_SCALE) / ROLLUP_AMOUNT_SCALE
+}
+
+export function computeHeaderRollups(
+  lines: readonly ClaimLineRollupInput[],
+  options?: { claimType?: string | null },
+): {
+  totalClaimedAmount: number
+  totalApprovedAmount: number
+} {
+  // Restocking / core adjustments only belong to return-family claims. When a claimType is
+  // supplied, warranty and vendor-recovery claims roll up the credit amount alone so they can
+  // never inherit a return's restock/core math (LINE-05). When omitted, behavior is unchanged.
+  const applyFinancialAdjustments = options?.claimType === undefined
+    ? true
+    : claimTypeAllowsLineFinancialAdjustments(options.claimType)
+  let totalClaimedAmount = 0
+  let totalApprovedAmount = 0
+
+  for (const line of lines) {
+    if (isDeleted(line)) continue
+    const creditAmount = lineCreditAmount(line)
+    totalClaimedAmount += creditAmount
+
+    const status = lineStatus(line)
+    if (status && approvedRollupStatuses.has(status)) {
+      // A restocking fee larger than the line's credit must not drag the
+      // approved header total negative — clamp the line contribution at zero.
+      totalApprovedAmount += applyFinancialAdjustments
+        ? Math.max(0, creditAmount - lineRestockingFee(line) + lineCoreCreditAmount(line))
+        : Math.max(0, creditAmount)
+    }
+  }
+
+  return {
+    totalClaimedAmount: roundRollupAmount(totalClaimedAmount),
+    totalApprovedAmount: roundRollupAmount(totalApprovedAmount),
+  }
+}

package/src/modules/warranty_claims/lib/timelineFilters.ts

@@ -0,0 +1,22 @@
+export const TIMELINE_FILTERS = ['all', 'comments', 'status_changes', 'customer_visible'] as const
+
+export type TimelineFilterId = (typeof TIMELINE_FILTERS)[number]
+
+export type TimelineFilterableEvent = {
+  kind: string
+  visibility: string
+}
+
+export function isTimelineFilterId(value: string): value is TimelineFilterId {
+  return (TIMELINE_FILTERS as readonly string[]).includes(value)
+}
+
+export function filterTimelineEvents<TEvent extends TimelineFilterableEvent>(
+  events: TEvent[],
+  filter: TimelineFilterId,
+): TEvent[] {
+  if (filter === 'comments') return events.filter((event) => event.kind === 'comment')
+  if (filter === 'status_changes') return events.filter((event) => event.kind === 'status_changed')
+  if (filter === 'customer_visible') return events.filter((event) => event.visibility === 'customer')
+  return events
+}

package/src/modules/warranty_claims/lib/triage.ts

@@ -0,0 +1,366 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { WarrantyClaim, WarrantyClaimLine } from '../data/entities'
+import { evaluateClaimRisk, type ClaimRiskAssessment } from './risk'
+import { addWarrantyMonths } from './warrantyPreview'
+import type {
+  WarrantyClaimDisposition,
+  WarrantyClaimPriority,
+  WarrantyClaimType,
+  WarrantyClaimWarrantyStatus,
+} from '../data/validators'
+
+export type WarrantyClaimTriageScope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type WarrantyClaimTriageReason = {
+  messageKey: string
+  params?: Record<string, string | number>
+}
+
+export type WarrantyEligibilitySuggestion = {
+  status: WarrantyClaimWarrantyStatus
+  purchaseDate: string | null
+  warrantyMonths: number | null
+  warrantyExpiresAt: string | null
+  reason: WarrantyClaimTriageReason
+}
+
+export type WarrantyClaimLineTriageSuggestion = {
+  lineId: string
+  lineNo: number
+  sku: string | null
+  productName: string | null
+  serialNumber: string | null
+  qtyClaimed: number
+  eligibility: WarrantyEligibilitySuggestion
+  suggestedDisposition: WarrantyClaimDisposition
+  suggestedPath: 'replace' | 'repair_review' | 'deny' | 'credit_with_restocking_fee' | 'core_accept'
+  reason: WarrantyClaimTriageReason
+  restockingFeePercent: number | null
+}
+
+export type WarrantyClaimPrioritySuggestion = {
+  currentPriority: WarrantyClaimPriority
+  suggestedPriority: WarrantyClaimPriority
+  ageHours: number | null
+  slaDueAt: string | null
+  overdue: boolean
+  reason: WarrantyClaimTriageReason
+}
+
+export type WarrantyClaimReviewEligibility = {
+  status: 'fast_track_candidate' | 'review_required'
+  reason: WarrantyClaimTriageReason
+}
+
+export type WarrantyClaimTriageSuggestion = {
+  claim: {
+    id: string
+    claimNumber: string
+    claimType: WarrantyClaimType
+    status: string
+    customerName: string | null
+    submittedAt: string | null
+    slaDueAt: string | null
+  }
+  eligibility: WarrantyClaimReviewEligibility
+  priority: WarrantyClaimPrioritySuggestion
+  lines: WarrantyClaimLineTriageSuggestion[]
+  risk: ClaimRiskAssessment
+  generatedAt: string
+}
+
+function toIso(value: Date | string | null | undefined): string | null {
+  if (!value) return null
+  const date = value instanceof Date ? value : new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date.toISOString()
+}
+
+function toDateOnlyIso(value: Date | string | null | undefined): string | null {
+  const iso = toIso(value)
+  return iso ? iso.slice(0, 10) : null
+}
+
+
+function reason(messageKey: string, params?: Record<string, string | number>): WarrantyClaimTriageReason {
+  return params ? { messageKey, params } : { messageKey }
+}
+
+function parseAmount(value: string | number | null | undefined, fallback: number): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim().length) {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return fallback
+}
+
+function resolveEligibility(line: WarrantyClaimLine, now: Date): WarrantyEligibilitySuggestion {
+  // An unparseable purchase date is missing data, not an expired warranty — a
+  // truthy Invalid Date would otherwise fall through and be denied as
+  // out_of_warranty. Mirrors computeWarrantyEntitlementPreview.
+  if (
+    !line.purchaseDate
+    || Number.isNaN(line.purchaseDate.getTime())
+    || line.warrantyMonths === null
+    || line.warrantyMonths === undefined
+    || !Number.isFinite(line.warrantyMonths)
+  ) {
+    return {
+      status: 'unknown',
+      purchaseDate: toDateOnlyIso(line.purchaseDate),
+      warrantyMonths: line.warrantyMonths ?? null,
+      warrantyExpiresAt: toDateOnlyIso(line.warrantyExpiresAt),
+      reason: reason('warranty_claims.triage.reason.missingWarrantyData'),
+    }
+  }
+
+  const expiresAt = addWarrantyMonths(line.purchaseDate, line.warrantyMonths)
+  const status: WarrantyClaimWarrantyStatus = expiresAt.getTime() >= now.getTime() ? 'in_warranty' : 'out_of_warranty'
+  return {
+    status,
+    purchaseDate: toDateOnlyIso(line.purchaseDate),
+    warrantyMonths: line.warrantyMonths,
+    warrantyExpiresAt: toDateOnlyIso(expiresAt),
+    reason: status === 'in_warranty'
+      ? reason('warranty_claims.triage.reason.warrantyStillValid')
+      : reason('warranty_claims.triage.reason.warrantyExpired'),
+  }
+}
+
+function suggestLineDisposition(
+  claimType: WarrantyClaimType,
+  qtyClaimed: number,
+  eligibility: WarrantyEligibilitySuggestion,
+): Pick<WarrantyClaimLineTriageSuggestion, 'suggestedDisposition' | 'suggestedPath' | 'reason' | 'restockingFeePercent'> {
+  if (claimType === 'core_return') {
+    return {
+      suggestedDisposition: 'credit',
+      suggestedPath: 'core_accept',
+      reason: reason('warranty_claims.triage.reason.coreAcceptancePath'),
+      restockingFeePercent: null,
+    }
+  }
+
+  if (eligibility.status === 'in_warranty') {
+    if (qtyClaimed <= 1) {
+      return {
+        suggestedDisposition: 'replace',
+        suggestedPath: 'replace',
+        reason: reason('warranty_claims.triage.reason.inWarrantyLowQuantity'),
+        restockingFeePercent: null,
+      }
+    }
+    return {
+      suggestedDisposition: 'repair',
+      suggestedPath: 'repair_review',
+      reason: reason('warranty_claims.triage.reason.inWarrantyInspection'),
+      restockingFeePercent: null,
+    }
+  }
+
+  if (eligibility.status === 'out_of_warranty' && claimType === 'return') {
+    return {
+      suggestedDisposition: 'credit',
+      suggestedPath: 'credit_with_restocking_fee',
+      reason: reason('warranty_claims.triage.reason.outOfWarrantyReturnRestocking'),
+      restockingFeePercent: 15,
+    }
+  }
+
+  if (eligibility.status === 'out_of_warranty') {
+    return {
+      suggestedDisposition: 'deny',
+      suggestedPath: 'deny',
+      reason: reason('warranty_claims.triage.reason.outsideWarrantyWindow'),
+      restockingFeePercent: null,
+    }
+  }
+
+  return {
+    suggestedDisposition: 'repair',
+    suggestedPath: 'repair_review',
+    reason: reason('warranty_claims.triage.reason.unknownEligibilityInspection'),
+    restockingFeePercent: null,
+  }
+}
+
+function hoursBetween(from: Date | null | undefined, to: Date): number | null {
+  if (!from) return null
+  return Math.max(0, Math.round(((to.getTime() - from.getTime()) / 3_600_000) * 10) / 10)
+}
+
+const priorityRank: Record<WarrantyClaimPriority, number> = {
+  low: 0,
+  normal: 1,
+  high: 2,
+  urgent: 3,
+}
+
+function atLeastPriority(priority: WarrantyClaimPriority, minimum: WarrantyClaimPriority): WarrantyClaimPriority {
+  return priorityRank[priority] >= priorityRank[minimum] ? priority : minimum
+}
+
+function suggestPriority(claim: WarrantyClaim, now: Date, risk: ClaimRiskAssessment): WarrantyClaimPrioritySuggestion {
+  const ageHours = hoursBetween(claim.submittedAt ?? claim.createdAt, now)
+  const slaDueAt = toIso(claim.slaDueAt)
+  const overdue = claim.slaDueAt ? claim.slaDueAt.getTime() < now.getTime() : false
+  const highRisk = risk.signals.some((signal) => signal.level === 'high')
+  if (overdue) {
+    return {
+      currentPriority: claim.priority,
+      suggestedPriority: 'urgent',
+      ageHours,
+      slaDueAt,
+      overdue,
+      reason: highRisk
+        ? reason('warranty_claims.triage.reason.highRiskPriority')
+        : reason('warranty_claims.triage.reason.slaOverdue'),
+    }
+  }
+  if (highRisk) {
+    return {
+      currentPriority: claim.priority,
+      suggestedPriority: atLeastPriority(claim.priority, 'high'),
+      ageHours,
+      slaDueAt,
+      overdue,
+      reason: reason('warranty_claims.triage.reason.highRiskPriority'),
+    }
+  }
+  if (claim.slaDueAt && claim.slaDueAt.getTime() - now.getTime() <= 6 * 3_600_000) {
+    return {
+      currentPriority: claim.priority,
+      suggestedPriority: 'high',
+      ageHours,
+      slaDueAt,
+      overdue,
+      reason: reason('warranty_claims.triage.reason.slaDueSoon', { hours: 6 }),
+    }
+  }
+  if (ageHours !== null && ageHours >= 36) {
+    return {
+      currentPriority: claim.priority,
+      suggestedPriority: 'high',
+      ageHours,
+      slaDueAt,
+      overdue,
+      reason: reason('warranty_claims.triage.reason.openAtLeastHours', { hours: 36 }),
+    }
+  }
+  return {
+    currentPriority: claim.priority,
+    suggestedPriority: claim.priority === 'low' ? 'normal' : claim.priority,
+    ageHours,
+    slaDueAt,
+    overdue,
+    reason: claim.priority === 'low'
+      ? reason('warranty_claims.triage.reason.lowPriorityEscalation')
+      : reason('warranty_claims.triage.reason.priorityConsistent'),
+  }
+}
+
+function serializeLineSuggestion(
+  claimType: WarrantyClaimType,
+  line: WarrantyClaimLine,
+  now: Date,
+  risk: ClaimRiskAssessment,
+): WarrantyClaimLineTriageSuggestion {
+  const qtyClaimed = parseAmount(line.qtyClaimed, 1)
+  const eligibility = resolveEligibility(line, now)
+  const disposition = suggestLineDisposition(claimType, qtyClaimed, eligibility)
+  const riskAdjustedDisposition = risk.signals.length > 0 && disposition.suggestedPath === 'replace'
+    ? {
+        suggestedDisposition: 'repair' as const,
+        suggestedPath: 'repair_review' as const,
+        reason: reason('warranty_claims.triage.reason.riskSignalsRequireReview'),
+        restockingFeePercent: null,
+      }
+    : disposition
+  return {
+    lineId: line.id,
+    lineNo: line.lineNo,
+    sku: line.sku ?? null,
+    productName: line.productName ?? null,
+    serialNumber: line.serialNumber ?? null,
+    qtyClaimed,
+    eligibility,
+    ...riskAdjustedDisposition,
+  }
+}
+
+function resolveReviewEligibility(
+  lines: readonly WarrantyClaimLineTriageSuggestion[],
+  risk: ClaimRiskAssessment,
+): WarrantyClaimReviewEligibility {
+  if (risk.signals.length > 0) {
+    return {
+      status: 'review_required',
+      reason: reason('warranty_claims.triage.reason.riskSignalsReviewRequired', { count: risk.signals.length }),
+    }
+  }
+  // `every` is vacuously true for an empty list, which would fast-track a claim
+  // that has no lines at all — the one case that most needs a human.
+  if (
+    lines.length > 0
+    && lines.every((line) => line.eligibility.status === 'in_warranty' && line.suggestedPath === 'replace')
+  ) {
+    return {
+      status: 'fast_track_candidate',
+      reason: reason('warranty_claims.triage.reason.fastTrackCandidate'),
+    }
+  }
+  return {
+    status: 'review_required',
+    reason: reason('warranty_claims.triage.reason.lineReviewRequired'),
+  }
+}
+
+export async function buildWarrantyClaimTriageSuggestion(input: {
+  em: EntityManager
+  claimId: string
+  scope: WarrantyClaimTriageScope
+  now?: Date
+  risk?: ClaimRiskAssessment
+}): Promise<WarrantyClaimTriageSuggestion> {
+  const now = input.now ?? new Date()
+  const claim = await findOneWithDecryption(
+    input.em,
+    WarrantyClaim,
+    { id: input.claimId, tenantId: input.scope.tenantId, organizationId: input.scope.organizationId, deletedAt: null },
+    {},
+    input.scope,
+  )
+  if (!claim) {
+    throw new CrudHttpError(404, { error: 'warranty_claims.errors.notFound' })
+  }
+  const lines = await findWithDecryption(
+    input.em,
+    WarrantyClaimLine,
+    { claim: claim.id, tenantId: input.scope.tenantId, organizationId: input.scope.organizationId, deletedAt: null },
+    { orderBy: { lineNo: 'ASC' } },
+    input.scope,
+  )
+  const risk = input.risk ?? await evaluateClaimRisk(input.em, claim, lines)
+  const lineSuggestions = lines.map((line) => serializeLineSuggestion(claim.claimType, line, now, risk))
+  return {
+    claim: {
+      id: claim.id,
+      claimNumber: claim.claimNumber,
+      claimType: claim.claimType,
+      status: claim.status,
+      customerName: claim.customerName ?? null,
+      submittedAt: toIso(claim.submittedAt),
+      slaDueAt: toIso(claim.slaDueAt),
+    },
+    eligibility: resolveReviewEligibility(lineSuggestions, risk),
+    priority: suggestPriority(claim, now, risk),
+    lines: lineSuggestions,
+    risk,
+    generatedAt: now.toISOString(),
+  }
+}

package/src/modules/warranty_claims/lib/troubleshooting.ts

@@ -0,0 +1,157 @@
+export type TroubleshootingOption = {
+  label: string
+  next?: TroubleshootingNode
+  resolution?: string
+  reasonCode?: string
+}
+
+export type TroubleshootingNode = {
+  prompt: string
+  options: TroubleshootingOption[]
+}
+
+export type TroubleshootingGuideMatcher = {
+  claimType?: string | null
+  reasonCode?: string | null
+  isActive: boolean
+}
+
+const MAX_TREE_DEPTH = 50
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function requiredText(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : null
+}
+
+function optionalText(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  return requiredText(value) ?? undefined
+}
+
+function parseOption(raw: unknown, depth: number, seen: WeakSet<object>): TroubleshootingOption | null {
+  if (!isRecord(raw)) return null
+  const label = requiredText(raw.label)
+  if (!label) return null
+
+  const next = raw.next === undefined || raw.next === null
+    ? undefined
+    : parseNode(raw.next, depth + 1, seen) ?? null
+  if (next === null) return null
+
+  const resolution = optionalText(raw.resolution)
+  const reasonCode = optionalText(raw.reasonCode)
+  if (!next && resolution === undefined && reasonCode === undefined) return null
+
+  return {
+    label,
+    ...(next ? { next } : {}),
+    ...(resolution !== undefined ? { resolution } : {}),
+    ...(reasonCode !== undefined ? { reasonCode } : {}),
+  }
+}
+
+function parseNode(raw: unknown, depth: number, seen: WeakSet<object>): TroubleshootingNode | null {
+  if (depth > MAX_TREE_DEPTH || !isRecord(raw)) return null
+  if (seen.has(raw)) return null
+
+  seen.add(raw)
+  const prompt = requiredText(raw.prompt)
+  const optionsRaw = raw.options
+  if (!prompt || !Array.isArray(optionsRaw)) {
+    seen.delete(raw)
+    return null
+  }
+
+  const options: TroubleshootingOption[] = []
+  for (const optionRaw of optionsRaw) {
+    const option = parseOption(optionRaw, depth, seen)
+    if (!option) {
+      seen.delete(raw)
+      return null
+    }
+    options.push(option)
+  }
+
+  seen.delete(raw)
+  return { prompt, options }
+}
+
+export function parseGuideSteps(raw: unknown): TroubleshootingNode | null {
+  return parseNode(raw, 0, new WeakSet<object>())
+}
+
+export function walkGuide(
+  root: TroubleshootingNode | null,
+  path: number[],
+): { node: TroubleshootingNode | null; terminal: { resolution?: string; reasonCode?: string } | null } {
+  if (!root) return { node: null, terminal: null }
+
+  let node: TroubleshootingNode | null = root
+  for (let index = 0; index < path.length; index += 1) {
+    const optionIndex = path[index]
+    if (!node || !Number.isInteger(optionIndex) || optionIndex < 0 || optionIndex >= node.options.length) {
+      return { node: null, terminal: null }
+    }
+
+    const option: TroubleshootingOption = node.options[optionIndex]
+    if (option.next) {
+      node = option.next
+      continue
+    }
+
+    if (option.resolution !== undefined || option.reasonCode !== undefined) {
+      if (index !== path.length - 1) return { node: null, terminal: null }
+      return {
+        node: null,
+        terminal: {
+          ...(option.resolution !== undefined ? { resolution: option.resolution } : {}),
+          ...(option.reasonCode !== undefined ? { reasonCode: option.reasonCode } : {}),
+        },
+      }
+    }
+
+    return { node: null, terminal: null }
+  }
+
+  return { node, terminal: null }
+}
+
+export function guideMatches(
+  guide: TroubleshootingGuideMatcher,
+  claimType?: string | null,
+  reasonCode?: string | null,
+): boolean {
+  if (!guide.isActive) return false
+  if (guide.claimType !== null && guide.claimType !== undefined && guide.claimType !== claimType) return false
+  if (guide.reasonCode !== null && guide.reasonCode !== undefined && guide.reasonCode !== reasonCode) return false
+  return true
+}
+
+export function guideMatchSpecificity(guide: Pick<TroubleshootingGuideMatcher, 'claimType' | 'reasonCode'>): number {
+  return (guide.claimType ? 1 : 0) + (guide.reasonCode ? 1 : 0)
+}
+
+export function selectBestGuide<TGuide extends TroubleshootingGuideMatcher>(
+  guides: readonly TGuide[],
+  claimType?: string | null,
+  reasonCode?: string | null,
+): TGuide | null {
+  let best: TGuide | null = null
+  let bestScore = -1
+
+  for (const guide of guides) {
+    if (!guideMatches(guide, claimType, reasonCode)) continue
+    const score = guideMatchSpecificity(guide)
+    if (score > bestScore) {
+      best = guide
+      bestScore = score
+    }
+  }
+
+  return best
+}

package/src/modules/warranty_claims/lib/tryResolve.ts

@@ -0,0 +1,7 @@
+export function tryResolve<T>(resolver: { resolve: <R = unknown>(name: string) => R }, name: string): T | undefined {
+  try {
+    return resolver.resolve<T>(name)
+  } catch {
+    return undefined
+  }
+}