@golemio/pid 5.19.1-dev.2799089619 → 5.19.1-dev.2815853394

package/docs/processing/trip_context/index.md

@@ -0,0 +1,149 @@
+# Trip context (`IVPTripsLastPositionContext`)
+
+Per-trip state carried between consecutive vehicle position updates. It represents what is known
+about a trip's last processed position - id, coordinates, state, delay bookkeeping, cancellation
+and a small tracking snapshot. One context instance exists per `tripId` for the lifetime of the
+trip's real-time processing. Defined in
+`src/schema-definitions/vehicle-positions/models/interfaces/VPTripsLastPositionInterfaces.ts`.
+
+- **Created**: `TripContextHelper.createInitial(tripId)` when a trip is seen for the first time
+  in a processing run and has no persisted context yet.
+- **Updated**: mutated in place while positions for the trip are processed (see below).
+- **Persisted**: serialized to JSON and stored (Postgres); reloaded on the next run and merged back
+  into the working context.
+
+This document covers, in order:
+
+1. [Core lifecycle rules](#core-lifecycle-rules) - the write boundary and the timestamp rule that
+   apply to every context mutation.
+2. [Field-specific contracts](#field-specific-contracts) - quirks of individual fields
+   (cancellation, the before-track-delayed seed, the date/string duality, last-stop delay
+   bookkeeping, the at-stop streak's asymmetric clear).
+3. [Fallback behavior](#fallback-behavior) - what happens when the incoming GPS position is
+   invalid, and the lean shape used to persist tracking snapshots.
+
+## Core lifecycle rules
+
+### Helper write boundary
+
+- [`TripContextHelper.ts`](../../../src/integration-engine/vehicle-positions/workers/vehicle-positions/helpers/trip-context/TripContextHelper.ts)
+  is the only module allowed to mutate `IVPTripsLastPositionContext` fields.
+- Callers (`PositionsManager`, `RegionalBusPositionsManager`, `ComputeDelayHelper`,
+  delay-propagation tasks, ...) always go through one of its exported functions instead of writing
+  to the context object directly.
+- New processing logic that needs to change the context must add or reuse a function here rather
+  than mutating the context inline.
+
+### Timestamp rule (`transitionState`)
+
+- `transitionState(context, state, options?)` stamps `lastPositionStateChange` (ISO string,
+  `new Date().toISOString()`) only when `state` actually differs from `context.lastPositionState`
+  - a state that repeats across consecutive positions does not re-stamp the timestamp.
+- The one exception is `options.forceTimestamp`, used by delay propagation
+  (`TripContextHelper.recordPropagatedDelay`) to force a fresh `BEFORE_TRACK_DELAYED` transition and
+  timestamp even when the state did not change, since the propagated delay itself is new information.
+
+## Field-specific contracts
+
+### Cancellation: sticky vs. plain
+
+`lastPositionCanceled` means different things depending on which manager writes it, both via the same
+`TripContextHelper.commitValidPosition(context, position, positionToUpdate, canceled)` call:
+
+- **`PositionsManager`** treats it as a sticky accumulator: once a position sets it (via
+  `lastPositionStaysCanceled`, driven by `hasTcpEventOrCancel`), later positions keep it canceled
+  even if they themselves are not canceled (`lastPositionStaysCanceled || position.is_canceled`).
+  - A trip cannot un-cancel itself here.
+- **`RegionalBusPositionsManager`** passes the plain per-position `position.is_canceled` with no
+  stickiness - the flag reflects only the current position.
+- Do not assume `lastPositionCanceled` is sticky across all managers; check which manager owns the trip.
+
+### Sticky seed: `lastPositionBeforeTrackDelayed`
+
+- `context.lastPositionBeforeTrackDelayed` stores `{ delay, origin_timestamp }` for the last
+  `BEFORE_TRACK_DELAYED` position, written by `TripContextHelper.recordBeforeTrackDelayed` and
+  `TripContextHelper.recordPropagatedDelay`.
+- The timestamp is stored as-is (`Date` or whatever was passed in) - it is never re-derived by
+  calling `.getTime()` on an already-stored value.
+- Treat it as an opaque, already-resolved snapshot rather than something to recompute from.
+
+### Date/string contract on `origin_timestamp`-family fields
+
+- `lastPositionBeforeTrackDelayed.origin_timestamp` is typed `string | Date | null`.
+- A context persisted to Postgres round-trips through `JSON.stringify`/`JSON.parse`, which
+  serializes a `Date` to an ISO string - so a freshly created context in memory holds a `Date`,
+  while one reloaded from storage holds a `string`.
+- Both must be handled on read.
+- Because of this, and because `null` is a valid value distinct from "not a Date/string", consumers
+  must never narrow with `=== null` (or `!== null`) alone - use `??`/`== null` so both `null` and
+  `undefined` are treated consistently.
+
+### Last-stop delay bookkeeping: `lastPositionLastStop`
+
+- `context.lastPositionLastStop` holds `{ sequence, arrival_delay, departure_delay }` for the last
+  stop the trip was at.
+- `TripContextHelper.resetLastStopDelay` clears all three fields to `null` together.
+- `TripContextHelper.updateLastStopSequenceIfUnset` only writes `sequence` when it is currently
+  `null` - it never overwrites an already-set sequence.
+- `TripContextHelper.setLastStopArrivalDelay`/`setLastStopDepartureDelay` are verbatim
+  pass-throughs: `undefined` must remain `undefined` (dropped by `JSON.stringify`) rather than
+  being coerced to `null`, since that would change the persisted bytes.
+
+### Asymmetric clear: `atStopStreak`
+
+- `context.atStopStreak` holds `{ stop_sequence, firstPositionTimestamp, firstPositionDelay }`,
+  tracking how long a trip has stayed at the same stop.
+- `TripContextHelper.clearAtStopStreak` zeroes **only** `stop_sequence` to `null`.
+  - `firstPositionTimestamp` and `firstPositionDelay` are intentionally left untouched, persisted
+    as-is.
+- Do not assume clearing the streak resets the whole object; check `stop_sequence` specifically
+  when deciding whether a streak is active.
+
+## Fallback behavior
+
+### Invalid GPS coordinates: stop-based fallback
+
+`BasePositionsManager.resolveTrackingPosition` - guard before `lat`/`lng` feed into `turf.point`.
+
+- Trigger: `VPUtils.hasValidCoordinates` fails (null, non-finite, outside `(0, 100)` on either axis).
+- Step 1: `VPUtils.findStopCoordinatesForFallback` - look up `this_stop_id` (preferred) or
+  `last_stop_id` in trip's loaded GTFS `stop_times`. Covers: GPS dead, onboard stop-matching
+  (CIS/ASW) still correct.
+- Step 2, match found: use stop's coords instead of raw GPS, build `turf` point, run normal
+  `getEstimatedPoint`/delay pipeline - real `AT_STOP`/`ON_TRACK` + delay, not frozen stale state.
+  Stop's own coords re-checked via `hasValidCoordinates` too - bad GTFS stop data falls through
+  to step 3, not trusted.
+- Step 3, no match (no stop id, or id not in trip schedule): `buildInvalidCoordinatesFallback`.
+  - `lat`/`lng`: `position.lat`/`lng` re-checked via `hasValidCoordinates` (not plain `??`, since a
+    `NaN` from a bad upstream parse is not `null`/`undefined` and would otherwise pass through
+    unchanged); only on failure falls back to `context.lastPositionLat`/`Lng`, then `0` as last
+    resort.
+  - `state_position` from `context.lastPositionState`.
+  - `last_stop_id`/`last_stop_sequence`: current position's own fields first
+    (`this_stop_sequence ?? last_stop_sequence`), stale `context.lastPositionTracking` snapshot
+    only as last resort - avoids sticking at old sequence once GPS recovers.
+- All branches: `state_process = PROCESSED` unconditionally. Why: pre-fix, crash on invalid
+  coords left row unprocessed - same bad row re-fetched + re-crashed worker every run (one bad
+  GPS event → hundreds of crashes/hour). Unconditional PROCESSED breaks that loop.
+- Shared via base class by `PositionsManager` + `RegionalBusPositionsManager` - don't reimplement
+  inline in either subclass.
+
+### Lean tracking shape: `lastPositionTracking`
+
+`context.lastPositionTracking` is a GeoJSON `Feature<Point, IVPTripsTrackingProperties>` written by
+`TripContextHelper.recordTracking`, only for positions in `AT_STOP` or `ON_TRACK` state.
+`IVPTripsTrackingProperties` (`VPTripsLastPositionInterfaces.ts`) is a `Pick` limited to exactly the
+7 fields actually read downstream:
+
+- `bearing`
+- `shape_dist_traveled`
+- `tcp_event`
+- `last_stop_sequence`
+- `last_stop_id`
+- `last_stop_arrival_time`
+- `last_stop_departure_time`
+
+This replaces a wider legacy shape that carried unused fields. Each field is written as an explicit
+`?? null` literal, so a missing value persists as `null` (kept by `JSON.stringify`) rather than
+`undefined` (dropped) - do not add new fields to this shape without confirming they are actually
+consumed elsewhere.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/pid",
-    "version": "5.19.1-dev.2799089619",
+    "version": "5.19.1-dev.2815853394",
     "description": "Golemio PID Module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",