@peopl-health/nexus 6.0.0-dev.466 → 6.0.0-dev.611

package/lib/shared/dtos/ClinicalFact.js

@@ -0,0 +1,85 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+const dateOrDateTime = z.union([z.iso.date(), dateTime]);
+
+const interpretationSchema = z.strictObject({
+  negated: z.boolean().default(false),
+  hedged: z.boolean().default(false),
+  experiencer: z.enum(['patient', 'family', 'other']).default('patient'),
+  temporal: z.enum(['current', 'historical', 'hypothetical']).default('current'),
+});
+
+const baseFields = {
+  id: z.string(),
+  code: z.string(),
+  effective: dateTime,
+  category: z.string(),
+  interpretation: interpretationSchema.default(() => interpretationSchema.parse({})),
+  notes: z.array(z.string()).default([]),
+  confidence: z.number().nullable().default(null),
+};
+
+const observationFact = z.strictObject({
+  ...baseFields,
+  kind: z.literal('observation'),
+  codeCtcae: z.string().nullable().default(null),
+  value: z.record(z.string(), z.unknown()).default({}),
+});
+
+const medicationFact = z.strictObject({
+  ...baseFields,
+  kind: z.literal('medication'),
+  dose: z.string().nullable().default(null),
+  route: z.string().nullable().default(null),
+  frequency: z.string().nullable().default(null),
+  adherenceStatus: z.enum([
+    'started', 'ongoing', 'completed', 'stopped',
+    'skipping_doses', 'non_adherent', 'as_needed', 'unknown',
+  ]).default('unknown'),
+});
+
+const conditionFact = z.strictObject({
+  ...baseFields,
+  kind: z.literal('condition'),
+  clinicalStatus: z.enum([
+    'active', 'recurrence', 'relapse', 'inactive', 'remission', 'resolved', 'unknown',
+  ]).default('unknown'),
+  onset: dateOrDateTime.nullable().default(null),
+});
+
+const procedureFact = z.strictObject({
+  ...baseFields,
+  kind: z.literal('procedure'),
+  venue: z.string().nullable().default(null),
+  outcome: z.string().nullable().default(null),
+});
+
+const appointmentFact = z.strictObject({
+  ...baseFields,
+  kind: z.literal('appointment'),
+  scheduledFor: dateOrDateTime.nullable().default(null),
+  purpose: z.string().nullable().default(null),
+});
+
+const allergyFact = z.strictObject({
+  ...baseFields,
+  kind: z.literal('allergy'),
+  clinicalStatus: z.enum(['active', 'inactive', 'resolved', 'unknown']).default('active'),
+  verificationStatus: z.enum(['unconfirmed', 'presumed', 'confirmed', 'refuted', 'unknown']).default('unconfirmed'),
+  allergenCategory: z.enum(['food', 'medication', 'environment', 'biologic', 'unknown']).default('unknown'),
+  criticality: z.enum(['low', 'high', 'unable_to_assess', 'unknown']).default('unknown'),
+  reaction: z.string().nullable().default(null),
+});
+
+const schema = z.discriminatedUnion('kind', [
+  observationFact, medicationFact, conditionFact, procedureFact, appointmentFact, allergyFact,
+]);
+
+class ClinicalFact extends BaseDto {}
+
+ClinicalFact.schema = schema;
+
+module.exports = { ClinicalFact };

package/lib/shared/dtos/ClinicalMention.js

@@ -0,0 +1,53 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const CATEGORY = [
+  'symptom', 'emotion', 'lab_value', 'medication', 'adherence',
+  'treatment', 'appointment', 'indication', 'diagnosis',
+  'allergy', 'comorbidity', 'performance_status',
+];
+
+const assertionSchema = z.object({
+  negated: z.boolean().default(false),
+  hedged: z.boolean().default(false),
+  experiencer: z.enum(['patient', 'family', 'other']).default('patient'),
+  temporal: z.enum(['current', 'historical', 'hypothetical']).default('current'),
+  confidence: z.number().default(1),
+});
+
+const factSchema = z.object({
+  mentionId: z.string(),
+  patientId: z.string(),
+  category: z.enum(CATEGORY),
+  canonicalTerm: z.string(),
+  reportedAt: dateTime,
+  assertion: assertionSchema.default(() => assertionSchema.parse({})),
+  ctcaeTerm: z.string().nullable().default(null),
+  temporality: z.string().nullable().default(null),
+  observedFields: z.record(z.string(), z.unknown()).default({}),
+});
+
+const provenanceSchema = z.object({
+  mentionId: z.string(), // mentionId/patientId also on fact; repeated for FHIR compatibility (separate resources)
+  patientId: z.string(),
+  turnId: z.string(),
+  recordedAt: dateTime,
+  source: z.string(),
+  verbatimQuotes: z.array(z.string()).default([]),
+  extractorConfidence: z.number().default(1),
+});
+
+const schema = z.object({
+  schemaVersion: z.string().default('1'),
+  fact: factSchema,
+  provenance: provenanceSchema,
+});
+
+class ClinicalMention extends BaseDto {}
+
+ClinicalMention.schema = schema;
+
+module.exports = { ClinicalMention };

package/lib/shared/dtos/ClusterHistoryRecord.js

@@ -0,0 +1,21 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  clusterId: z.string(),
+  turnId: z.string(),
+  action: z.string(),
+  changes: z.record(z.string(), z.unknown()).default({}),
+  transitionReason: z.string().nullable().default(null),
+  recordedAt: dateTime,
+});
+
+class ClusterHistoryRecord extends BaseDto {}
+
+ClusterHistoryRecord.schema = schema;
+
+module.exports = { ClusterHistoryRecord };

package/lib/shared/dtos/ClusterImpression.js

@@ -0,0 +1,40 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  clusterId: z.string(),
+  patientId: z.string(),
+  label: z.string(),
+  hypothesisType: z.enum(['ae_profile', 'symptom_syndrome', 'disease_complication', 'relational_causal']),
+  status: z.enum(['active', 'dissolved']).default('active'),
+  confidence: z.enum(['speculative', 'moderate', 'strong']),
+  clinicalSignificance: z.enum(['benign', 'moderate', 'safety_relevant', 'emergency']),
+  memberCaseIds: z.array(z.string()).min(1),
+  consultationId: z.string().nullable().default(null),
+  relationshipModel: z.string(),
+  strengthensIf: z.array(z.string()).default([]),
+  weakensIf: z.array(z.string()).default([]),
+  openingReasoning: z.string(),
+  openedAt: dateTime,
+  dissolvedAt: dateTime.nullable().default(null),
+  dissolveReason: z.string().nullable().default(null),
+  dissolveCategory: z.enum([
+    'linked_case_closed', 'confidence_dropped', 'superseded_by_other_cluster', 'evidence_insufficient', 'other',
+  ]).nullable().default(null),
+})
+  .refine((d) => (!d.dissolveReason && !d.dissolveCategory) || d.dissolvedAt !== null, {
+    message: 'dissolveReason/dissolveCategory require dissolvedAt',
+  })
+  .refine((d) => (d.status === 'dissolved') === (d.dissolvedAt !== null), {
+    message: 'status is dissolved iff dissolvedAt is set',
+  });
+
+class ClusterImpression extends BaseDto {}
+
+ClusterImpression.schema = schema;
+
+module.exports = { ClusterImpression };

package/lib/shared/dtos/ContingencySafetyNet.js

@@ -0,0 +1,47 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const escalationStepSchema = z.strictObject({
+  recipient: z.enum(['patient', 'care_team']),
+  message: z.string(),
+  priority: z.enum(['critical', 'high', 'medium', 'low', 'routine', 'urgent', 'asap', 'stat']).nullable().default(null),
+  actionRequested: z.string().nullable().default(null),
+  firesAfterSilenceMinutes: z.number().int().nonnegative().nullable().default(null),
+});
+
+const carePlanSchema = z.strictObject({
+  planId: z.string(),
+  patientId: z.string(),
+  relatedCaseId: z.string().nullable().default(null),
+  relatedClusterId: z.string().nullable().default(null),
+  concern: z.string(),
+  awaitingCharacterization: z.string(),
+  whyThisMatters: z.string(),
+  creationReasoning: z.string(),
+  status: z.enum(['armed', 'fired_reminder', 'fired_team', 'auto_resolved', 'cancelled']).default('armed'),
+  createdAt: dateTime,
+  resolvedAt: dateTime.nullable().default(null),
+  resolvedReason: z.string().nullable().default(null),
+})
+  .refine((c) => !['auto_resolved', 'cancelled'].includes(c.status) || c.resolvedAt !== null, {
+    message: 'a resolved/cancelled carePlan requires resolvedAt',
+  })
+  .refine((c) => !c.resolvedReason || c.resolvedAt !== null, {
+    message: 'resolvedReason requires resolvedAt',
+  });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  carePlan: carePlanSchema,
+  teamEscalation: escalationStepSchema,
+  patientReminder: escalationStepSchema.nullable().default(null),
+});
+
+class ContingencySafetyNet extends BaseDto {}
+
+ContingencySafetyNet.schema = schema;
+
+module.exports = { ContingencySafetyNet };

package/lib/shared/dtos/DispatchedEscalation.js

@@ -0,0 +1,44 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const baseFields = {
+  schemaVersion: z.string().default('1'),
+  eventId: z.string(),
+  patientId: z.string(),
+  severity: z.enum(['critical', 'high', 'medium', 'low']),
+  createdAt: dateTime,
+  status: z.enum(['queued', 'sent', 'acknowledged', 'failed']).default('queued'),
+  reason: z.string().nullable().default(null),
+};
+
+const notifyEscalation = z.strictObject({
+  ...baseFields,
+  kind: z.enum(['page_navigator', 'page_oncologist', 'notify_911_guidance']),
+  recipient: z.string().nullable().default(null),
+  requiresAck: z.boolean().default(false),
+});
+
+const followupEscalation = z.strictObject({
+  ...baseFields,
+  kind: z.literal('schedule_followup'),
+  fireAt: dateTime,
+  followupPurpose: z.string().nullable().default(null),
+});
+
+const ticketEscalation = z.strictObject({
+  ...baseFields,
+  kind: z.literal('open_ticket'),
+  title: z.string(),
+  slaMinutes: z.number().int().nullable().default(null),
+});
+
+const schema = z.discriminatedUnion('kind', [notifyEscalation, followupEscalation, ticketEscalation]);
+
+class DispatchedEscalation extends BaseDto {}
+
+DispatchedEscalation.schema = schema;
+
+module.exports = { DispatchedEscalation };

package/lib/shared/dtos/Intervention.js

@@ -0,0 +1,29 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  kind: z.enum(['otc', 'self_care', 'other', 'education', 'team_escalation', 'follow_up_check']),
+  interventionId: z.string(),
+  patientId: z.string(),
+  caseId: z.string(),
+  interventionLabel: z.string(),
+  rationale: z.string().nullable().default(null),
+  deliveredAt: dateTime,
+  outcome: z.enum(['pending', 'improved', 'no_relief', 'side_effects', 'worsened', 'unknown']).default('pending'),
+  outcomeNotes: z.string().nullable().default(null),
+  recipientKind: z.enum(['patient', 'related_person']).default('patient'),
+  recipientRefId: z.string().nullable().default(null),
+})
+  .refine((d) => d.recipientKind !== 'related_person' || d.recipientRefId !== null, {
+    message: 'a related_person recipient requires recipientRefId',
+  });
+
+class Intervention extends BaseDto {}
+
+Intervention.schema = schema;
+
+module.exports = { Intervention };

package/lib/shared/dtos/ManagedSymptom.js

@@ -0,0 +1,75 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const gradeEstimateSchema = z.strictObject({
+  bestEstimate: z.number().int().min(1).max(5).nullable().default(null),
+  confidence: z.enum(['low', 'moderate', 'high']).nullable().default(null),
+  possibleRange: z.tuple([z.number().int().min(1).max(5), z.number().int().min(1).max(5)]).nullable().default(null),
+  reasoning: z.string().default(''),
+})
+  .refine((g) => g.possibleRange === null || g.possibleRange[0] <= g.possibleRange[1], {
+    message: 'possibleRange must be ordered [min, max]',
+  })
+  .refine(
+    (g) => g.bestEstimate === null || g.possibleRange === null
+      || (g.bestEstimate >= g.possibleRange[0] && g.bestEstimate <= g.possibleRange[1]),
+    { message: 'bestEstimate must fall within possibleRange' },
+  );
+
+const symptomConditionSchema = z.strictObject({
+  conditionId: z.string(),
+  patientId: z.string(),
+  ctcaeTerm: z.string(),
+  clinicalStatus: z.enum(['characterizing', 'monitoring', 'resolved', 'inactive', 'closed']).default('characterizing'),
+  onsetAt: dateTime,
+  abatementAt: dateTime.nullable().default(null),
+  closeReason: z.string().nullable().default(null),
+  temporality: z.string().nullable().default(null),
+  evidenceEpisodeIds: z.array(z.string()).default([]),
+  currentEpisodeId: z.string().nullable().default(null),
+  evidenceMentionIds: z.array(z.string()).default([]),
+  lastTransitionReason: z.string().nullable().default(null),
+  recurrenceCount: z.number().int().nonnegative().default(0),
+  reactivatedAt: dateTime.nullable().default(null),
+})
+  .refine((c) => !c.closeReason || c.abatementAt !== null, {
+    message: 'closeReason requires abatementAt',
+  })
+  .refine((c) => c.abatementAt === null || ['resolved', 'inactive', 'closed'].includes(c.clinicalStatus), {
+    message: 'abatementAt requires a terminal clinicalStatus (resolved/inactive/closed)',
+  })
+  .refine((c) => c.abatementAt === null || new Date(c.abatementAt) >= new Date(c.onsetAt), {
+    message: 'abatementAt must be >= onsetAt',
+  });
+
+const symptomAssessmentSchema = z.strictObject({
+  assessmentId: z.string(),
+  conditionId: z.string(),
+  patientId: z.string(),
+  performedAt: dateTime,
+  previousId: z.string().nullable().default(null),
+  grade: gradeEstimateSchema,
+  trajectory: z.string().nullable().default(null),
+  decisionPosture: z.string().nullable().default(null),
+  gradeVerification: z.string().default('provisional'),
+  reasoning: z.string().nullable().default(null),
+  postureReason: z.string().nullable().default(null),
+  problemRepresentation: z.string().nullable().default(null),
+  gradeThresholdClause: z.string().nullable().default(null),
+});
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  condition: symptomConditionSchema,
+  latestAssessment: symptomAssessmentSchema,
+  priorAssessments: z.array(symptomAssessmentSchema).default([]),
+});
+
+class ManagedSymptom extends BaseDto {}
+
+ManagedSymptom.schema = schema;
+
+module.exports = { ManagedSymptom };

package/lib/shared/dtos/MonitoringEpisode.js

@@ -0,0 +1,25 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  episodeId: z.string(),
+  patientId: z.string(),
+  managingOrgId: z.string(),
+  episodeType: z.literal('home-monitoring-programme').default('home-monitoring-programme'),
+  status: z.enum(['planned', 'waitlist', 'active', 'onhold', 'finished', 'cancelled', 'entered-in-error']),
+  periodStart: dateTime,
+  periodEnd: dateTime.nullable().default(null),
+})
+  .refine((d) => d.periodEnd === null || new Date(d.periodEnd) >= new Date(d.periodStart), {
+    message: 'periodEnd must be >= periodStart',
+  });
+
+class MonitoringEpisode extends BaseDto {}
+
+MonitoringEpisode.schema = schema;
+
+module.exports = { MonitoringEpisode };

package/lib/shared/dtos/PatientContext.js

@@ -0,0 +1,22 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  patientId: z.string(),
+  assembledAt: dateTime,
+  activeRegimen: z.string().nullable().default(null),
+  activePhase: z.string().nullable().default(null),
+  profileMedications: z.array(z.string()).default([]),
+  profileAllergies: z.array(z.string()).default([]),
+  profileComorbidities: z.array(z.string()).default([]),
+});
+
+class PatientContext extends BaseDto {}
+
+PatientContext.schema = schema;
+
+module.exports = { PatientContext };

package/lib/shared/dtos/PatientRiskAssessment.js

@@ -0,0 +1,46 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const predictedAeSchema = z.strictObject({
+  aeName: z.string(),
+  severityIfConfirmed: z.enum(['emergency', 'safety_relevant', 'moderate']),
+  minimumSymptomSet: z.array(z.string()).default([]),
+  why: z.string().nullable().default(null),
+});
+
+const predictedDiseaseRiskSchema = z.strictObject({
+  bodySite: z.string(),
+  complications: z.array(z.string()).default([]),
+  warningSymptoms: z.array(z.string()).default([]),
+  amplifierComorbidities: z.array(z.string()).default([]),
+});
+
+const predictedComorbidityAmplifierSchema = z.strictObject({
+  comorbidity: z.string(),
+  interaction: z.string(),
+  clinicalNote: z.string().nullable().default(null),
+});
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  assessmentId: z.string(),
+  patientId: z.string(),
+  status: z.literal('final').default('final'),
+  sourceRegimen: z.string().nullable().default(null),
+  sourceDiagnosis: z.string().nullable().default(null),
+  sourcePhase: z.string().nullable().default(null),
+  predictedAes: z.array(predictedAeSchema).default([]),
+  diseaseRisks: z.array(predictedDiseaseRiskSchema).default([]),
+  comorbidityAmplifiers: z.array(predictedComorbidityAmplifierSchema).default([]),
+  assessedAt: dateTime,
+  assessedByModel: z.string().nullable().default(null),
+});
+
+class PatientRiskAssessment extends BaseDto {}
+
+PatientRiskAssessment.schema = schema;
+
+module.exports = { PatientRiskAssessment };

package/lib/shared/dtos/Reminder.js

@@ -0,0 +1,32 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  reminderId: z.string(),
+  patientId: z.string(),
+  kind: z.enum(['medication', 'appointment', 'exam', 'self_care_action', 'check_in', 'other']),
+  message: z.string(),
+  fireAt: dateTime,
+  channel: z.string().default('whatsapp'),
+  status: z.enum(['scheduled', 'cancelled', 'expired']).default('scheduled'),
+  authoredAt: dateTime,
+  cancelReason: z.string().nullable().default(null),
+  recipientKind: z.enum(['patient', 'related_person']).default('patient'),
+  recipientRefId: z.string().nullable().default(null),
+})
+  .refine((d) => (d.status === 'cancelled') === (d.cancelReason !== null), {
+    message: 'cancelReason is set iff status is cancelled',
+  })
+  .refine((d) => d.recipientKind !== 'related_person' || d.recipientRefId !== null, {
+    message: 'a related_person recipient requires recipientRefId',
+  });
+
+class Reminder extends BaseDto {}
+
+Reminder.schema = schema;
+
+module.exports = { Reminder };

package/lib/shared/dtos/RoutingDecision.js

@@ -0,0 +1,68 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const mentionFindingSchema = z.strictObject({
+  caseId: z.string(),
+  clinicalReasoning: z.string(),
+  decisionAction: z.string(),
+});
+
+const secondaryActionSchema = z.strictObject({
+  action: z.string(),
+  composeAs: z.string(),
+});
+
+const deferredItemSchema = z.strictObject({
+  item: z.string(),
+  deferReason: z.string(),
+});
+
+// patientId/turnId also on root — repeated per subrecord for FHIR compatibility (each projects a separate resource)
+const assessmentSchema = z.strictObject({
+  assessmentId: z.string(),
+  patientId: z.string(),
+  turnId: z.string(),
+  performedAt: dateTime,
+  previousId: z.string().nullable().default(null),
+  summary: z.string(),
+  notes: z.array(z.string()).default([]),
+  findings: z.array(mentionFindingSchema).default([]),
+});
+
+const dispositionSchema = z.strictObject({
+  dispositionId: z.string(),
+  patientId: z.string(),
+  kind: z.string(),
+  primaryAction: z.string(),
+  primaryReason: z.string(),
+  primaryCaseId: z.string().nullable().default(null),
+  secondaryActions: z.array(secondaryActionSchema).default([]),
+  deferredItems: z.array(deferredItemSchema).default([]),
+  authoredAt: dateTime,
+});
+
+const provenanceSchema = z.strictObject({
+  agentDevice: z.string(),
+  onBehalfOf: z.string(),
+  recordedAt: dateTime,
+});
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  decisionId: z.string(),
+  patientId: z.string(),
+  turnId: z.string(),
+  committedAt: dateTime,
+  assessment: assessmentSchema,
+  disposition: dispositionSchema,
+  provenance: provenanceSchema,
+});
+
+class RoutingDecision extends BaseDto {}
+
+RoutingDecision.schema = schema;
+
+module.exports = { RoutingDecision };

package/lib/shared/dtos/SymptomEpisode.js

@@ -0,0 +1,41 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateTime = z.iso.datetime({ offset: true });
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  episodeId: z.string(),
+  patientId: z.string(),
+  canonicalTerm: z.string(),
+  openedAt: dateTime,
+  lastMentionAt: dateTime,
+  closedAt: dateTime.nullable().default(null),
+  closeReason: z.string().nullable().default(null),
+  evidenceMentionIds: z.array(z.string()).default([]),
+  firstIntensity: z.number().nullable().default(null),
+  lastIntensity: z.number().nullable().default(null),
+  maxIntensity: z.number().nullable().default(null),
+})
+  .refine((d) => !d.closeReason || d.closedAt !== null, {
+    message: 'closeReason requires closedAt',
+  })
+  .refine(
+    (d) => d.maxIntensity === null
+      || ((d.firstIntensity === null || d.maxIntensity >= d.firstIntensity)
+        && (d.lastIntensity === null || d.maxIntensity >= d.lastIntensity)),
+    { message: 'maxIntensity must be >= firstIntensity and lastIntensity' },
+  )
+  .refine((d) => new Date(d.lastMentionAt) >= new Date(d.openedAt), {
+    message: 'lastMentionAt must be >= openedAt',
+  })
+  .refine((d) => d.closedAt === null || new Date(d.closedAt) >= new Date(d.openedAt), {
+    message: 'closedAt must be >= openedAt',
+  });
+
+class SymptomEpisode extends BaseDto {}
+
+SymptomEpisode.schema = schema;
+
+module.exports = { SymptomEpisode };

package/lib/shared/dtos/TreatmentEpisode.js

@@ -0,0 +1,31 @@
+const { z } = require('zod');
+
+const { BaseDto } = require('./BaseDto');
+
+const dateOnly = z.iso.date();
+
+const schema = z.strictObject({
+  schemaVersion: z.string().default('1'),
+  episodeId: z.string(),
+  patientId: z.string(),
+  cancerConditionId: z.string(),
+  regimenName: z.string(),
+  phase: z.enum(['diagnosis', 'active_curative', 'active_palliative', 'remission', 'advanced']),
+  periodStart: dateOnly,
+  periodEnd: dateOnly.nullable().default(null),
+  currentCycle: z.number().int().nonnegative(),
+  currentWeek: z.number().int().nonnegative(),
+  plannedCycles: z.number().int().positive(),
+})
+  .refine((d) => d.currentCycle <= d.plannedCycles, {
+    message: 'currentCycle must be <= plannedCycles',
+  })
+  .refine((d) => d.periodEnd === null || new Date(d.periodEnd) >= new Date(d.periodStart), {
+    message: 'periodEnd must be >= periodStart',
+  });
+
+class TreatmentEpisode extends BaseDto {}
+
+TreatmentEpisode.schema = schema;
+
+module.exports = { TreatmentEpisode };