@de./types 1.0.0

package/src/lsp/consolidation.ts

@@ -0,0 +1,420 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ContextSchema } from '../context'
+import { AgentSnapshotSchema } from '../aux/agents'
+import { ActionRecordSchema, DateTimeZoneSchema } from '../time'
+import { MoneySchema } from '../measure'
+import { AddressSchema, CoordinatesSchema } from '../geo'
+
+import {
+	APIErrorSchema,
+	APIHeadersSchema,
+	APIResponseBaseSchema,
+	APIResponseDataSchemaFactory
+} from '../api'
+
+export const CPointIdSchema = Type.Readonly(Type.String({ __brand: 'CPointId' as const }))
+export const OrderIdSchema = Type.Readonly(Type.String({ __brand: 'OrderId' as const }))
+export const AgentIdSchema = Type.Readonly(Type.String({ __brand: 'AgentId' as const }))
+export const OfferIdSchema = Type.Readonly(Type.String({ __brand: 'OfferId' as const }))
+export const ZoneIdSchema = Type.Readonly(Type.String({ __brand: 'ZoneId' as const }))
+export const PackageIdSchema = Type.Readonly(Type.String({ __brand: 'PackageId' as const }))
+
+export type AgentId = Static<typeof AgentIdSchema>
+export type OfferId = Static<typeof OfferIdSchema>
+export type OrderId = Static<typeof OrderIdSchema>
+export type CPointId = Static<typeof CPointIdSchema>
+export type ZoneId = Static<typeof ZoneIdSchema>
+export type PackageId = Static<typeof PackageIdSchema>
+
+// ── Consolidation Point ───────────────────────────────────────
+
+// Consolidation Point Type Schema
+export const ConsolidationPointTypeSchema = Type.Union([
+  Type.Literal('HUB'),              // Hub facility
+  Type.Literal('NODE'),             // Agent meetup node/hub
+  Type.Literal('POD'),              // Smart locker / drone-pad pod unit
+  Type.Literal('PICKUP_LOCATION'),  // Designated pickup spot
+  Type.Literal('DROPOFF_LOCATION')  // Designated dropoff spot
+])
+
+// Consolidation Point Schema
+export const ConsolidationPointStatusSchema = Type.Union([
+  Type.Literal('ACTIVE'),
+  Type.Literal('CONGESTED'),
+  Type.Literal('CLOSED')
+])
+export const ConsolidationPointSchema = Type.Object({
+  id: CPointIdSchema,
+  type: ConsolidationPointTypeSchema,
+  name: Type.String({ description: 'Name/description of consolidation point' }),
+  address: Type.Optional(AddressSchema),
+  coordinates: CoordinatesSchema,
+  status: ConsolidationPointStatusSchema,
+  
+  // Hub-specific
+  hubId: Type.Optional(Type.String({ description: 'Hub ID if type is HUB' })),
+
+  // Pod-specific
+  podId: Type.Optional(Type.String({ description: 'Pod ID if type is POD' })),
+  
+  // Agent meetup specific
+  radiusMeters: Type.Optional(Type.Number({ 
+    minimum: 0, 
+    description: 'Acceptable radius for agent meetup in meters' 
+  })),
+  
+  // Capacity and timing
+  maxCapacity: Type.Optional(Type.Number({
+    minimum: 1,
+    description: 'Max simultaneous consolidation ops'
+  })),
+  estimatedDuration: Type.Optional(Type.Number({ 
+    description: 'Estimated duration for consolidation in minutes' 
+  })),
+  fallbackPoints: Type.Array(CPointIdSchema),  // ordered by preference
+  adjacentZones: Type.Array(ZoneIdSchema),
+  // Availability
+  availability: Type.Optional(Type.Object({
+    daysOfWeek: Type.Array(Type.Union([
+      Type.Literal('MON'),
+      Type.Literal('TUE'),
+      Type.Literal('WED'),
+      Type.Literal('THU'),
+      Type.Literal('FRI'),
+      Type.Literal('SAT'),
+      Type.Literal('SUN')
+    ])),
+    startTime: Type.String({ description: 'HH:MM format' }),
+    endTime: Type.String({ description: 'HH:MM format' })
+  })),
+  avgWaitTimeS: Type.Number({
+    minimum: 1,
+    description: 'Rolling 24h average'
+  }),
+  
+  // Metadata
+  notes: Type.Optional(Type.String({ maxLength: 500 })),
+  context: ContextSchema,
+  created: ActionRecordSchema,
+  updated: Type.Optional(ActionRecordSchema)
+})
+
+// ── Package Custody ─────────────────────────────────────────
+
+export const ConsolidationCustodyStatusSchema = Type.Union([
+  Type.Literal('WITH_ORIGIN_AGENT'),
+  Type.Literal('IN_TRANSIT_TO_CONSOLIDATION_POINT'),
+  Type.Literal('HANDED_OFF'),
+  Type.Literal('WITH_CONSOLIDATING_AGENT'),
+  Type.Literal('DELIVERED'),
+  Type.Literal('UNCONFIRMED'),
+  Type.Literal('MANUAL_INTERVENTION')
+])
+
+export const ConsolidationPackageCustodySchema = Type.Object({
+  packageId: PackageIdSchema,
+  orderId: OrderIdSchema,
+  heldBy: AgentIdSchema,
+  status: ConsolidationCustodyStatusSchema,
+  handoffAt: Type.Optional(CPointIdSchema),
+  handoffTime: Type.Optional(DateTimeZoneSchema),
+  lastConfirmed: DateTimeZoneSchema
+})
+
+// ── Scorer Snapshot (audit trail) ────────────────────────────
+
+export const ConsolidationScorerSnapshotSchema = Type.Object({
+  evaluated: Type.Optional(ActionRecordSchema),
+  evaluationCycle: Type.Number(),
+  benefitScore: Type.Number({ minimum: 0, maximum: 1 }),  // 0–1, higher = better match
+  routeDeviationCost: Type.Number(),  // added km for A
+  slaFitScore: Type.Number(),  // how comfortably inside deadline
+  densityBonus: Type.Number(),  // zone order density multiplier
+  cpointProximityScore: Type.Number(),  // how well cpoint fits both routes
+  agentCapacityScore: Type.Number(),  // capacity headroom
+  alternativesCount: Type.Number()  // how many other matches were scored
+})
+
+// ── Trajectory Confirmation ───────────────────────────────────
+
+export const ConsolidationTrajectoryStatusSchema = Type.Union([
+  Type.Literal('CONVERGING'),
+  Type.Literal('DIVERGING'),
+  Type.Literal('STATIONARY'),
+  Type.Literal('ARRIVED')
+])
+
+export const ConsolidationTrajectoryCheckSchema = Type.Object({
+  checked: Type.Optional(ActionRecordSchema),
+  agent: AgentSnapshotSchema,
+  cpointPosition: CoordinatesSchema,
+  bearingToCpointDeg: Type.Number(),  // computed: true bearing agent→cpoint
+  angularDeltaDeg: Type.Number(),  // |heading - bearing_to_cpoint|, 0–180
+  distanceToCpointM: Type.Number(),
+  status: ConsolidationTrajectoryStatusSchema,
+  warningIssued: Type.Boolean()
+})
+
+// ── Consolidation Offer ───────────────────────────────────────
+
+export const ConsolidationNackReasonSchema = Type.Union([
+  Type.Literal('VEHICLE_FULL'),
+  Type.Literal('ROUTE_DEVIATION_TOO_FAR'),
+  Type.Literal('PERSONAL_EMERGENCY'),
+  Type.Literal('APP_NOT_RESPONDED'),
+  Type.Literal('AGENT_DECLINED'),
+  Type.Literal('SLA_TOO_TIGHT')
+])
+export const ConsolidationAckRecordSchema = Type.Object({
+  agentId: AgentIdSchema,
+  role: Type.Union([
+    Type.Literal('consolidating'),
+    Type.Literal('handingOff')
+  ]),
+  acked: Type.Optional(ActionRecordSchema),
+  nacked: Type.Optional(ActionRecordSchema),
+  nackReason: Type.Optional(ConsolidationNackReasonSchema),
+  timedOut: Type.Boolean()
+})
+
+export const ConsolidationOfferStateSchema = Type.Union([
+  Type.Literal('PROPOSED'),
+  Type.Literal('SCHEDULED'),
+  Type.Literal('PENDING_ACKS'),
+  Type.Literal('COMMITTED'),
+  Type.Literal('IN_PROGRESS'),
+  Type.Literal('COMPLETED'),
+  Type.Literal('TIMED_OUT'),
+  Type.Literal('NACK_RECEIVED'),
+  Type.Literal('RENDEZVOUS_MISSED'),
+  Type.Literal('AGENT_OFFLINE'),
+  Type.Literal('SLA_ESCALATED'),
+  Type.Literal('CANCELLED')
+])
+export const ConsolidationOfferPurposeSchema = Type.Union([
+  Type.Literal('TRANSFER'),
+  Type.Literal('BATCH'),
+  Type.Literal('RETURN'),
+  Type.Literal('REROUTE'),
+  Type.Literal('RELAY'), // two-leg cross-zone handoff arranged by Rally Dispatch
+])
+export const ConsolidationOfferPrioritySchema = Type.Union([
+  Type.Literal('LOW'),
+  Type.Literal('NORMAL'),
+  Type.Literal('HIGH'),
+  Type.Literal('URGENT')
+])
+
+export const ConsolidationOfferSchema = Type.Object({
+  id: OfferIdSchema,
+  context: ContextSchema,
+  state: ConsolidationOfferStateSchema,
+  purpose: ConsolidationOfferPurposeSchema,
+  priority: ConsolidationOfferPrioritySchema,
+
+  // Participants
+  consolidatingAgentId: AgentIdSchema,  // Agent A
+  handingOffAgentIds: Type.Array(AgentIdSchema), // Agents B, C, ...
+  orderIds: Type.Array(OrderIdSchema), // orders being consolidated
+  notes: Type.Optional(Type.String()),
+
+  // Relay-only — absent on proactive offers
+  handoffCode: Type.Optional( Type.Number({ description: '4-digit PIN exchanged physically at the cpoint; set only for RELAY offers' }) ),
+
+  // Schedule tracking
+  scheduledTime: Type.Optional(Type.Number()),
+  actualStartTime: Type.Optional(Type.Number()),
+  actualEndTime: Type.Optional(Type.Number()),
+
+  // Rendezvous
+  cpointId: CPointIdSchema,
+  fallbackCPointId: Type.Optional(CPointIdSchema),
+  rendezvousEta: DateTimeZoneSchema, // when A arrives at cpoint
+  acceptDeadline: DateTimeZoneSchema, // latest B/C can ACK
+  waitBudgetMs: Type.Number({ minimum: 1 }), // how long A will wait at cpoint
+
+  // Financials
+  consolidationFee: MoneySchema,  // added to A's earnings
+
+  // ACK tracking
+  ackRecords: Type.Array(ConsolidationAckRecordSchema),
+
+  // Trajectory monitoring
+  trajectoryChecks: Type.Array(ConsolidationTrajectoryCheckSchema),
+  lastTrajectoryOk: Type.Boolean(),
+  adherenceWarnings: Type.Number({ minimum: 0 }), // count this session
+
+  // Timing
+  proposed: ActionRecordSchema,
+  committed: Type.Optional(ActionRecordSchema),
+  arrivedAtCpoint: Type.Optional(ActionRecordSchema), // when agent A first reached the cpoint; drives wait budget
+  rendezvousConfirmed: Type.Optional(ActionRecordSchema),
+  completed: Type.Optional(ActionRecordSchema),
+  failed: Type.Optional(ActionRecordSchema),
+  updated: Type.Optional(ActionRecordSchema),
+
+  // Audit
+  scorerSnapshot: ConsolidationScorerSnapshotSchema, // why this match was proposed
+  failureReason: Type.Optional(Type.String()),
+  reEvaluationCount: Type.Number({ minimum: 0 }),
+  excludedPairs: Type.Array(Type.Object({
+    agentId: AgentIdSchema,
+    untilCycle: Type.Number()
+  }))
+})
+
+export type ConsolidationPointType = Static<typeof ConsolidationPointTypeSchema>
+export type ConsolidationPointStatus = Static<typeof ConsolidationPointStatusSchema>
+export type ConsolidationPoint = Static<typeof ConsolidationPointSchema>
+
+export type ConsolidationAckRecord = Static<typeof ConsolidationAckRecordSchema>
+export type ConsolidationNackReason = Static<typeof ConsolidationNackReasonSchema>
+export type ConsolidationCustodyStatus = Static<typeof ConsolidationCustodyStatusSchema>
+export type ConsolidationPackageCustody = Static<typeof ConsolidationPackageCustodySchema>
+export type ConsolidationScorerSnapshot = Static<typeof ConsolidationScorerSnapshotSchema>
+export type ConsolidationTrajectoryStatus = Static<typeof ConsolidationTrajectoryStatusSchema>
+export type ConsolidationTrajectoryCheck = Static<typeof ConsolidationTrajectoryCheckSchema>
+
+export type ConsolidationOfferState = Static<typeof ConsolidationOfferStateSchema>
+export type ConsolidationOfferPurpose = Static<typeof ConsolidationOfferPurposeSchema>
+export type ConsolidationOfferPriority = Static<typeof ConsolidationOfferPrioritySchema>
+export type ConsolidationOffer = Static<typeof ConsolidationOfferSchema>
+
+// ── Manual Schedule Request ───────────────────────────────────
+// Purposes available to LSP coordinators — RELAY is reserved for Rally Dispatch.
+
+export const ConsolidationManualPurposeSchema = Type.Union([
+  Type.Literal('TRANSFER'),
+  Type.Literal('BATCH'),
+  Type.Literal('RETURN'),
+  Type.Literal('REROUTE'),
+])
+
+export const ConsolidationScheduleBodySchema = Type.Object({
+  consolidatingAgentId: Type.String({ description: 'Agent who holds the packages and arrives first' }),
+  receivingAgentIds: Type.Array( Type.String(), { minItems: 1, description: 'Agents receiving the packages' }),
+  orderReferences: Type.Array( Type.String() ),
+  purpose: ConsolidationManualPurposeSchema,
+  priority: ConsolidationOfferPrioritySchema,
+  scheduledTime: Type.Number({ description: 'Unix ms timestamp for the meetup' }),
+  waitBudgetMs: Type.Optional( Type.Number({ minimum: 30_000, maximum: 3_600_000 }) ),
+  notes: Type.Optional( Type.String({ maxLength: 500 }) ),
+  cpointId: Type.Optional( Type.String({ description: 'Existing consolidation point ID' }) ),
+  meetupLocation: Type.Optional( Type.Object({
+    name: Type.String(),
+    coordinates: CoordinatesSchema,
+    radiusMeters: Type.Optional( Type.Number({ minimum: 10, maximum: 500 }) ),
+    notes: Type.Optional( Type.String({ maxLength: 500 }) ),
+  })),
+})
+
+export type ConsolidationManualPurpose = Static<typeof ConsolidationManualPurposeSchema>
+export type ConsolidationScheduleBody = Static<typeof ConsolidationScheduleBodySchema>
+
+// ─── Request Validation Schemas ───────────────────────────────────────────────
+
+export const LSPConsolidationScheduleRVS = {
+	headers:  APIHeadersSchema,
+	body:     ConsolidationScheduleBodySchema,
+	response: {
+		201:   APIResponseDataSchemaFactory({ consolidation: ConsolidationOfferSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPConsolidationFetchRVS = {
+	headers:     APIHeadersSchema,
+	querystring: Type.Object({
+		agentId:  Type.Optional(Type.String()),
+		state:    Type.Optional(Type.Array(Type.String())),
+		purpose:  Type.Optional(Type.String()),
+		fromDate: Type.Optional(Type.Number()),
+		toDate:   Type.Optional(Type.Number()),
+		limit:    Type.Optional(Type.Number()),
+		offset:   Type.Optional(Type.Number())
+	}),
+	response: {
+		200:   APIResponseDataSchemaFactory({ consolidations: Type.Array(ConsolidationOfferSchema), total: Type.Number() }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPConsolidationGetRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ consolidationId: Type.String() }),
+	response: {
+		200:   APIResponseDataSchemaFactory({ consolidation: ConsolidationOfferSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPConsolidationUpdateStateRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ consolidationId: Type.String() }),
+	body:     Type.Object({
+		state: Type.Union([
+			Type.Literal('SCHEDULED'),
+			Type.Literal('IN_PROGRESS'),
+			Type.Literal('COMPLETED'),
+			Type.Literal('CANCELLED')
+		]),
+		actualStartTime: Type.Optional(Type.Number()),
+		actualEndTime:   Type.Optional(Type.Number()),
+		notes:           Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: {
+		200:   APIResponseDataSchemaFactory({ consolidation: ConsolidationOfferSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPConsolidationCreatePointRVS = {
+	headers:  APIHeadersSchema,
+	body:     Type.Object({
+		type: Type.Union([
+			Type.Literal('HUB'),
+			Type.Literal('NODE'),
+			Type.Literal('PICKUP_LOCATION'),
+			Type.Literal('DROPOFF_LOCATION')
+		]),
+		name:               Type.String(),
+		coordinates:        CoordinatesSchema,
+		address:            Type.Optional(Type.Any()),
+		hubId:              Type.Optional(Type.String()),
+		radiusMeters:       Type.Optional(Type.Number({ minimum: 0 })),
+		maxCapacity:        Type.Optional(Type.Number({ minimum: 1 })),
+		estimatedDuration:  Type.Optional(Type.Number()),
+		avgWaitTimeS:       Type.Optional(Type.Number({ minimum: 1 })),
+		fallbackPoints:     Type.Optional(Type.Array(Type.String())),
+		intersectionZones:  Type.Optional(Type.Array(Type.String())),
+		availability:       Type.Optional(Type.Any()),
+		notes:              Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: {
+		201:   APIResponseDataSchemaFactory({ point: ConsolidationPointSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPConsolidationFetchPointsRVS = {
+	headers:     APIHeadersSchema,
+	querystring: Type.Object({
+		type:     Type.Optional(Type.String()),
+		nearLat:  Type.Optional(Type.Number()),
+		nearLng:  Type.Optional(Type.Number()),
+		radiusKm: Type.Optional(Type.Number()),
+		limit:    Type.Optional(Type.Number())
+	}),
+	response: {
+		200:   APIResponseDataSchemaFactory({ points: Type.Array(ConsolidationPointSchema), total: Type.Number() }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export type LSPConsolidationScheduleValidation    = { body: Static<typeof LSPConsolidationScheduleRVS.body>, response: Static<(typeof LSPConsolidationScheduleRVS.response)[201]> }
+export type LSPConsolidationFetchValidation       = { querystring: Static<typeof LSPConsolidationFetchRVS.querystring>, response: Static<(typeof LSPConsolidationFetchRVS.response)[200]> }
+export type LSPConsolidationGetValidation         = { params: Static<typeof LSPConsolidationGetRVS.params>, response: Static<(typeof LSPConsolidationGetRVS.response)[200]> }
+export type LSPConsolidationUpdateStateValidation = { params: Static<typeof LSPConsolidationUpdateStateRVS.params>, body: Static<typeof LSPConsolidationUpdateStateRVS.body>, response: Static<(typeof LSPConsolidationUpdateStateRVS.response)[200]> }
+export type LSPConsolidationCreatePointValidation = { body: Static<typeof LSPConsolidationCreatePointRVS.body>, response: Static<(typeof LSPConsolidationCreatePointRVS.response)[201]> }
+export type LSPConsolidationFetchPointsValidation = { querystring: Static<typeof LSPConsolidationFetchPointsRVS.querystring>, response: Static<(typeof LSPConsolidationFetchPointsRVS.response)[200]> }
+