@rise-maritime/keelson-js 0.6.0-alpha.255.dev.1 → 0.6.0-alpha.275.dev.1

package/dist/interfaces/ErrorResponse.d.ts

@@ -19,14 +19,19 @@ export declare enum ErrorResponse_Code {
     OUT_OF_RANGE = 3,
     /** INVALID_STATE - wrong state for the operation (e.g. pause when STOPPED) */
     INVALID_STATE = 4,
-    /** PERMISSION_DENIED - path escapes base directory, lock-down rules */
+    /** PERMISSION_DENIED - refused under current conditions: authorisation, */
     PERMISSION_DENIED = 5,
-    /** IO_FAILURE - read/write fault on disk, network, etc. */
+    /**
+     * IO_FAILURE - lock-down rules, policy. The answer MAY change;
+     * the ErrorResponse twin of COMMAND_RESULT_DENIED.
+     */
     IO_FAILURE = 6,
     /** UNAVAILABLE - backend / dependency not ready */
     UNAVAILABLE = 7,
     /** INTERNAL - unhandled exception */
     INTERNAL = 8,
+    /** UNSUPPORTED - structurally not implemented by this source; the */
+    UNSUPPORTED = 9,
     UNRECOGNIZED = -1
 }
 export declare function errorResponse_CodeFromJSON(object: any): ErrorResponse_Code;

package/dist/interfaces/ErrorResponse.js

@@ -25,14 +25,19 @@ var ErrorResponse_Code;
     ErrorResponse_Code[ErrorResponse_Code["OUT_OF_RANGE"] = 3] = "OUT_OF_RANGE";
     /** INVALID_STATE - wrong state for the operation (e.g. pause when STOPPED) */
     ErrorResponse_Code[ErrorResponse_Code["INVALID_STATE"] = 4] = "INVALID_STATE";
-    /** PERMISSION_DENIED - path escapes base directory, lock-down rules */
+    /** PERMISSION_DENIED - refused under current conditions: authorisation, */
     ErrorResponse_Code[ErrorResponse_Code["PERMISSION_DENIED"] = 5] = "PERMISSION_DENIED";
-    /** IO_FAILURE - read/write fault on disk, network, etc. */
+    /**
+     * IO_FAILURE - lock-down rules, policy. The answer MAY change;
+     * the ErrorResponse twin of COMMAND_RESULT_DENIED.
+     */
     ErrorResponse_Code[ErrorResponse_Code["IO_FAILURE"] = 6] = "IO_FAILURE";
     /** UNAVAILABLE - backend / dependency not ready */
     ErrorResponse_Code[ErrorResponse_Code["UNAVAILABLE"] = 7] = "UNAVAILABLE";
     /** INTERNAL - unhandled exception */
     ErrorResponse_Code[ErrorResponse_Code["INTERNAL"] = 8] = "INTERNAL";
+    /** UNSUPPORTED - structurally not implemented by this source; the */
+    ErrorResponse_Code[ErrorResponse_Code["UNSUPPORTED"] = 9] = "UNSUPPORTED";
     ErrorResponse_Code[ErrorResponse_Code["UNRECOGNIZED"] = -1] = "UNRECOGNIZED";
 })(ErrorResponse_Code || (exports.ErrorResponse_Code = ErrorResponse_Code = {}));
 function errorResponse_CodeFromJSON(object) {
@@ -64,6 +69,9 @@ function errorResponse_CodeFromJSON(object) {
         case 8:
         case "INTERNAL":
             return ErrorResponse_Code.INTERNAL;
+        case 9:
+        case "UNSUPPORTED":
+            return ErrorResponse_Code.UNSUPPORTED;
         case -1:
         case "UNRECOGNIZED":
         default:
@@ -91,6 +99,8 @@ function errorResponse_CodeToJSON(object) {
             return "UNAVAILABLE";
         case ErrorResponse_Code.INTERNAL:
             return "INTERNAL";
+        case ErrorResponse_Code.UNSUPPORTED:
+            return "UNSUPPORTED";
         case ErrorResponse_Code.UNRECOGNIZED:
         default:
             return "UNRECOGNIZED";

package/dist/interfaces/Route.d.ts

@@ -57,13 +57,24 @@ export declare enum HazardZoneType {
 }
 export declare function hazardZoneTypeFromJSON(object: any): HazardZoneType;
 export declare function hazardZoneTypeToJSON(object: HazardZoneType): string;
-/** COLREG encounter situation for an annotated leg. */
+/**
+ * COLREG encounter situation, from own ship's side. One vocabulary for the plan and the live
+ * picture: a Route leg is annotated with 1-4 only; Encounter.situation may also carry 5-6, which
+ * describe a live target and never a planned leg.
+ */
 export declare enum ColregSituation {
     COLREG_SITUATION_UNSPECIFIED = 0,
+    /** COLREG_SITUATION_OVERTAKING - own ship is overtaking */
     COLREG_SITUATION_OVERTAKING = 1,
+    /** COLREG_SITUATION_CROSSING_STBD - target crossing from own starboard */
     COLREG_SITUATION_CROSSING_STBD = 2,
+    /** COLREG_SITUATION_CROSSING_PORT - target crossing from own port */
     COLREG_SITUATION_CROSSING_PORT = 3,
     COLREG_SITUATION_HEAD_ON = 4,
+    /** COLREG_SITUATION_OVERTAKEN - target is overtaking own ship (Encounter only) */
+    COLREG_SITUATION_OVERTAKEN = 5,
+    /** COLREG_SITUATION_NONE - target not under way, or restricted visibility (Encounter only) */
+    COLREG_SITUATION_NONE = 6,
     UNRECOGNIZED = -1
 }
 export declare function colregSituationFromJSON(object: any): ColregSituation;
@@ -88,6 +99,58 @@ export declare enum GeometryType {
 }
 export declare function geometryTypeFromJSON(object: any): GeometryType;
 export declare function geometryTypeToJSON(object: GeometryType): string;
+/**
+ * How a leg's XTD corridor boundary is defined. UNSPECIFIED MUST be read as
+ * OFFSET: every leg published before this field existed is a constant-offset
+ * corridor, and reading it any other way would change routes nobody edited.
+ */
+export declare enum XtdCorridorMode {
+    XTD_CORRIDOR_MODE_UNSPECIFIED = 0,
+    /** XTD_CORRIDOR_MODE_OFFSET - Parallel lines at xtd_port_m / xtd_starboard_m either side of track. */
+    XTD_CORRIDOR_MODE_OFFSET = 1,
+    /**
+     * XTD_CORRIDOR_MODE_POLYLINE - A boundary drawn by the planner (Leg.xtd_port_boundary /
+     * xtd_starboard_boundary), e.g. a corridor that narrows past a shoal.
+     * xtd_port_m / xtd_starboard_m still carry a nominal limit for a monitor
+     * that does not evaluate polylines. That fallback is NOT conservative when
+     * the drawn corridor is narrower than the nominal one, which is why such a
+     * monitor SHOULD report the leg as monitored at reduced fidelity.
+     */
+    XTD_CORRIDOR_MODE_POLYLINE = 2,
+    UNRECOGNIZED = -1
+}
+export declare function xtdCorridorModeFromJSON(object: any): XtdCorridorMode;
+export declare function xtdCorridorModeToJSON(object: XtdCorridorMode): string;
+/**
+ * Whether a route's waypoint list closes back on itself. RTZ 1.2 has no such
+ * concept, so producers either repeated the first waypoint (breaking id
+ * uniqueness) or left closing to consumer convention (silently wrong the first
+ * time a consumer chooses not to loop). This field makes the author say.
+ *
+ * An enum rather than a bool, like every other classification in this file:
+ * OPEN says closure was considered and declined, and there is room for a
+ * third topology (out-and-back). UNSPECIFIED MUST be read as OPEN; that is
+ * the fail-safe direction, since sailing a point-to-point route as a circuit
+ * takes the vessel over unplanned water. Terminal behaviour (stop, hold, go
+ * round again) is execution policy and belongs on keelson.Voyage, not here.
+ * See protocol-specification.md §6.2.1.
+ */
+export declare enum RouteTopology {
+    ROUTE_TOPOLOGY_UNSPECIFIED = 0,
+    /**
+     * ROUTE_TOPOLOGY_OPEN - Runs from the first waypoint to the last and ends there. The last
+     * waypoint has no outgoing leg.
+     */
+    ROUTE_TOPOLOGY_OPEN = 1,
+    /**
+     * ROUTE_TOPOLOGY_CLOSED - A circuit: the last waypoint's outgoing leg terminates at the first
+     * waypoint, which is NOT repeated at the end of the list.
+     */
+    ROUTE_TOPOLOGY_CLOSED = 2,
+    UNRECOGNIZED = -1
+}
+export declare function routeTopologyFromJSON(object: any): RouteTopology;
+export declare function routeTopologyToJSON(object: RouteTopology): string;
 /**
  * Lifecycle status for the route artifact (authoring + quality).
  * Execution-side state (vessel sailing, paused, completed) lives on
@@ -323,10 +386,18 @@ export interface Waypoints {
     defaults: DefaultWaypoint | undefined;
     /** Ordered list of waypoints, in route order. */
     waypoint: Waypoint[];
+    /**
+     * Whether the list above closes back on itself. Lives here because it is a
+     * statement about this list. Unset reads as ROUTE_TOPOLOGY_OPEN (§6.2.1).
+     */
+    topology: RouteTopology;
     extensions: Extensions | undefined;
 }
 /**
- * Default values for waypoint/leg fields. RTZ-aligned.
+ * Default values for waypoint/leg fields. RTZ-aligned — the field set matches
+ * RTZ's own defaultWaypoint element, which is a separate question from where
+ * leg data hangs: a merged default inherits the departure convention of the
+ * field it backs, same as an explicit value (§6.2.1).
  *
  * The scalars are `optional` for the same reason as their `Waypoint`
  * counterparts, one level up: without presence there is no way to say "this
@@ -364,8 +435,9 @@ export interface Waypoint {
      */
     position: Coordinate | undefined;
     /**
-     * Planned speed over ground when leaving this waypoint. `optional` because
-     * `Waypoints.defaults` backs this field: without presence, "no override,
+     * Planned speed over ground when LEAVING this waypoint, i.e. on `leg`
+     * below. RTZ indexes this on the arrival waypoint instead (§6.2.1).
+     * `optional` because `Waypoints.defaults` backs this field: without presence, "no override,
      * use the default" and "hold zero speed here" are the same bytes, and 0.0
      * is the more dangerous reading of the pair.
      */
@@ -389,12 +461,23 @@ export interface Waypoint {
     lock: boolean;
     /** Operational context for this waypoint (open sea, port approach, lock, ...). */
     operationalContext: OperationalContext;
-    /** Outgoing leg from this waypoint to the next. The last waypoint has none. */
+    /**
+     * Outgoing leg from this waypoint to the next: `waypoint[i].leg` is the edge
+     * to `waypoint[i+1]`. In an OPEN route the last waypoint has none and a
+     * consumer MUST ignore one if present. In a CLOSED route the last waypoint's
+     * leg runs to `waypoint[0]`; that is how a circuit closes, never by
+     * repeating the first waypoint. RTZ hangs the leg on the ARRIVAL waypoint,
+     * so a converter shifts by one (§6.2.1).
+     */
     leg: Leg | undefined;
     /** Free-form notes attached to this waypoint. */
     note: string;
     extensions: Extensions | undefined;
 }
+/**
+ * Every field here describes the edge LEAVING the waypoint that carries it
+ * (see Waypoint.leg and §6.2.1 for the RTZ shift).
+ */
 export interface Leg {
     /**
      * Cross-track distance (XTD) limits and monitoring thresholds, in metres.
@@ -405,6 +488,19 @@ export interface Leg {
     xtdStarboardM?: number | undefined;
     xtdMonitoringPortM?: number | undefined;
     xtdMonitoringStarboardM?: number | undefined;
+    /**
+     * How this leg's XTD corridor boundary is shaped. See XtdCorridorMode and
+     * protocol-specification.md §6.2.2.
+     */
+    xtdCorridorMode: XtdCorridorMode;
+    /**
+     * POLYLINE only: the drawn corridor boundary on each side, vertices in
+     * along-track order, covering this leg and the turn at the waypoint it
+     * arrives at. A consumer MUST ignore both lists unless the mode is POLYLINE,
+     * so a stale shape left behind by a switch back to OFFSET is never sailed.
+     */
+    xtdPortBoundary: XtdBoundaryPoint[];
+    xtdStarboardBoundary: XtdBoundaryPoint[];
     /**
      * Safety contour (depth in metres below chart datum) below which the route
      * is considered unsafe.
@@ -453,6 +549,36 @@ export interface Leg {
     colregTrafficIntensity: ColregTrafficIntensity;
     extensions: Extensions | undefined;
 }
+/**
+ * One vertex of a drawn XTD corridor boundary (Leg.xtd_port_boundary /
+ * Leg.xtd_starboard_boundary).
+ */
+export interface XtdBoundaryPoint {
+    /**
+     * WGS-84 vertex. Authoritative: this is the boundary a monitor checks
+     * against, whatever the anchor below says.
+     */
+    position: Coordinate | undefined;
+    /**
+     * Editor anchor — where along the leg's straight the vertex was placed,
+     * 0 at the leg's start and 1 at its end, and how far off track. Lets an
+     * editor keep the vertex attached to the leg when a waypoint moves, instead
+     * of leaving it stranded at its old position. `optional` because a vertex
+     * placed freely (at a leg end or inside a turn) has no such anchor, and 0
+     * is a real fraction.
+     */
+    alongTrackFraction?: number | undefined;
+    /**
+     * Perpendicular distance from track for that anchor, metres, always
+     * positive: the side is given by which boundary list holds the vertex.
+     */
+    offsetM?: number | undefined;
+    /**
+     * True when the vertex lies on the turn at the leg's end rather than on the
+     * straight.
+     */
+    inTurn: boolean;
+}
 export interface Schedules {
     /** Multiple schedules can coexist (e.g. "manual", "weather-optimized"). */
     schedule: Schedule[];
@@ -489,7 +615,12 @@ export interface ScheduleElement {
     etdWindowEnd: Date | undefined;
     /** Planned duration of stay at this waypoint (port, anchorage, ...). */
     stay: Duration | undefined;
-    /** -- Environmental forecast for this leg ------------------------------------ */
+    /**
+     * -- Environmental forecast for this leg ------------------------------------
+     * The OUTGOING leg — the one leaving `waypoint_id`, matching `Waypoint.leg`
+     * and `planned_sog_knots`. The last waypoint of an OPEN route has no
+     * outgoing leg and so no forecast to carry (§6.2.1).
+     */
     windSpeedMps: number;
     windDirectionDeg: number;
     currentSpeedMps: number;
@@ -632,6 +763,7 @@ export declare const Waypoints: MessageFns<Waypoints>;
 export declare const DefaultWaypoint: MessageFns<DefaultWaypoint>;
 export declare const Waypoint: MessageFns<Waypoint>;
 export declare const Leg: MessageFns<Leg>;
+export declare const XtdBoundaryPoint: MessageFns<XtdBoundaryPoint>;
 export declare const Schedules: MessageFns<Schedules>;
 export declare const Schedule: MessageFns<Schedule>;
 export declare const ScheduleElement: MessageFns<ScheduleElement>;