@rise-maritime/keelson-js 0.6.0-pre.14 → 0.6.0-pre.16

package/dist/index.d.ts

@@ -216,6 +216,14 @@ export declare function getInterfaceDefinition(interfaceAndVersion: string): {
     readonly name: "ScenarioControl";
     readonly fullName: "keelson.interfaces.scenario_control.ScenarioControl";
     readonly methods: {
+        readonly list_scenarios: {
+            readonly name: "list_scenarios";
+            readonly requestType: import("./interfaces/ScenarioControl").MessageFns<import("./interfaces/ScenarioControl").ListScenariosRequest>;
+            readonly requestStream: false;
+            readonly responseType: import("./interfaces/ScenarioControl").MessageFns<import("./interfaces/ScenarioControl").ListScenariosResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         readonly load: {
             readonly name: "load";
             readonly requestType: import("./interfaces/ScenarioControl").MessageFns<import("./interfaces/ScenarioControl").LoadRequest>;

package/dist/interfaces/Route.d.ts

@@ -88,6 +88,36 @@ export declare enum GeometryType {
 }
 export declare function geometryTypeFromJSON(object: any): GeometryType;
 export declare function geometryTypeToJSON(object: GeometryType): 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
@@ -108,6 +138,30 @@ export declare enum RouteStatus {
 }
 export declare function routeStatusFromJSON(object: any): RouteStatus;
 export declare function routeStatusToJSON(object: RouteStatus): string;
+/**
+ * Which side of an operational limit counts as a breach.
+ *
+ * RouteInfo's own limit block carries both directions — max_wind_gust_mps is
+ * breached above, min_visibility_m below — so nothing about a limit's identity
+ * says which way it fails. Consumers of an exceedance record need it: "the most
+ * extreme value reached" is undefined without it, and deriving the direction
+ * from a `max_` / `min_` name prefix is a string match that fails silently the
+ * first time a limit is named anything else.
+ *
+ * Lives here rather than beside either consumer because it is a property of the
+ * limit as authored, not of the monitoring. Read by keelson.EnvelopeExceedance
+ * and keelson.EnvelopeLimitState.
+ */
+export declare enum EnvelopeBound {
+    ENVELOPE_BOUND_UNSPECIFIED = 0,
+    /** ENVELOPE_BOUND_UPPER - Breached by going ABOVE the limit value (max_wind_gust_mps, max_roll_deg). */
+    ENVELOPE_BOUND_UPPER = 1,
+    /** ENVELOPE_BOUND_LOWER - Breached by going BELOW it (min_visibility_m, min_speed_knots). */
+    ENVELOPE_BOUND_LOWER = 2,
+    UNRECOGNIZED = -1
+}
+export declare function envelopeBoundFromJSON(object: any): EnvelopeBound;
+export declare function envelopeBoundToJSON(object: EnvelopeBound): string;
 /** Required action for an ActionPoint. */
 export declare enum ActionPointRequiredAction {
     ACTION_POINT_REQUIRED_ACTION_UNSPECIFIED = 0,
@@ -272,6 +326,19 @@ export interface RouteInfo {
     maxWindSpeedMps?: number | undefined;
     minSpeedKnots?: number | undefined;
     maxSpeedKnots?: number | undefined;
+    /**
+     * Minimum visibility the route is valid above. `visibility_range_m` is
+     * published, so without this the measurement exists and the limit it should
+     * be checked against does not.
+     */
+    minVisibilityM?: number | undefined;
+    /**
+     * Gust limit, distinct from the mean-wind limit above. Gust is what governs
+     * small-craft operations: 12 m/s mean with 20 m/s gusts is a different
+     * proposition from a steady 12 m/s, and only the mean can be constrained
+     * today. Checked against the windowed `true_wind_speed_max_mps`.
+     */
+    maxWindGustMps?: number | undefined;
     /**
      * -- Optimization & autonomy ------------------------------------------------
      * Free-form optimization method label (e.g. "fuel-min", "eta-min", "weather-routed").
@@ -286,10 +353,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
@@ -327,8 +402,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.
      */
@@ -352,12 +428,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.
@@ -452,7 +539,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;

package/dist/interfaces/Route.js

@@ -5,8 +5,8 @@
 //   protoc               v6.30.2
 // source: Route.proto
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RouteIssue = exports.RouteChallenge = exports.HazardZone = exports.ActionPoint = exports.ActionPoints = exports.ScheduleElement = exports.Schedule = exports.Schedules = exports.Leg = exports.Waypoint = exports.DefaultWaypoint = exports.Waypoints = exports.RouteInfo = exports.Route = exports.Extensions_Entry_AttributesEntry = exports.Extensions_Entry = exports.Extensions = exports.CircleGeometry = exports.RouteRef = exports.schedule_OriginToJSON = exports.schedule_OriginFromJSON = exports.Schedule_Origin = exports.actionPointRequiredActionToJSON = exports.actionPointRequiredActionFromJSON = exports.ActionPointRequiredAction = exports.routeStatusToJSON = exports.routeStatusFromJSON = exports.RouteStatus = exports.geometryTypeToJSON = exports.geometryTypeFromJSON = exports.GeometryType = exports.colregTrafficIntensityToJSON = exports.colregTrafficIntensityFromJSON = exports.ColregTrafficIntensity = exports.colregSituationToJSON = exports.colregSituationFromJSON = exports.ColregSituation = exports.hazardZoneTypeToJSON = exports.hazardZoneTypeFromJSON = exports.HazardZoneType = exports.routeChallengeTypeToJSON = exports.routeChallengeTypeFromJSON = exports.RouteChallengeType = exports.operationalContextToJSON = exports.operationalContextFromJSON = exports.OperationalContext = exports.autonomyLevelToJSON = exports.autonomyLevelFromJSON = exports.AutonomyLevel = exports.protobufPackage = void 0;
-exports.RouteStatusUpdate = exports.RouteSignature = exports.RouteSignatures = void 0;
+exports.Schedule = exports.Schedules = exports.Leg = exports.Waypoint = exports.DefaultWaypoint = exports.Waypoints = exports.RouteInfo = exports.Route = exports.Extensions_Entry_AttributesEntry = exports.Extensions_Entry = exports.Extensions = exports.CircleGeometry = exports.RouteRef = exports.schedule_OriginToJSON = exports.schedule_OriginFromJSON = exports.Schedule_Origin = exports.actionPointRequiredActionToJSON = exports.actionPointRequiredActionFromJSON = exports.ActionPointRequiredAction = exports.envelopeBoundToJSON = exports.envelopeBoundFromJSON = exports.EnvelopeBound = exports.routeStatusToJSON = exports.routeStatusFromJSON = exports.RouteStatus = exports.routeTopologyToJSON = exports.routeTopologyFromJSON = exports.RouteTopology = exports.geometryTypeToJSON = exports.geometryTypeFromJSON = exports.GeometryType = exports.colregTrafficIntensityToJSON = exports.colregTrafficIntensityFromJSON = exports.ColregTrafficIntensity = exports.colregSituationToJSON = exports.colregSituationFromJSON = exports.ColregSituation = exports.hazardZoneTypeToJSON = exports.hazardZoneTypeFromJSON = exports.HazardZoneType = exports.routeChallengeTypeToJSON = exports.routeChallengeTypeFromJSON = exports.RouteChallengeType = exports.operationalContextToJSON = exports.operationalContextFromJSON = exports.OperationalContext = exports.autonomyLevelToJSON = exports.autonomyLevelFromJSON = exports.AutonomyLevel = exports.protobufPackage = void 0;
+exports.RouteStatusUpdate = exports.RouteSignature = exports.RouteSignatures = exports.RouteIssue = exports.RouteChallenge = exports.HazardZone = exports.ActionPoint = exports.ActionPoints = exports.ScheduleElement = void 0;
 /* eslint-disable */
 const wire_1 = require("@bufbuild/protobuf/wire");
 const Coordinate_1 = require("./Coordinate");
@@ -411,6 +411,67 @@ function geometryTypeToJSON(object) {
     }
 }
 exports.geometryTypeToJSON = geometryTypeToJSON;
+/**
+ * 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.
+ */
+var RouteTopology;
+(function (RouteTopology) {
+    RouteTopology[RouteTopology["ROUTE_TOPOLOGY_UNSPECIFIED"] = 0] = "ROUTE_TOPOLOGY_UNSPECIFIED";
+    /**
+     * ROUTE_TOPOLOGY_OPEN - Runs from the first waypoint to the last and ends there. The last
+     * waypoint has no outgoing leg.
+     */
+    RouteTopology[RouteTopology["ROUTE_TOPOLOGY_OPEN"] = 1] = "ROUTE_TOPOLOGY_OPEN";
+    /**
+     * 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.
+     */
+    RouteTopology[RouteTopology["ROUTE_TOPOLOGY_CLOSED"] = 2] = "ROUTE_TOPOLOGY_CLOSED";
+    RouteTopology[RouteTopology["UNRECOGNIZED"] = -1] = "UNRECOGNIZED";
+})(RouteTopology || (exports.RouteTopology = RouteTopology = {}));
+function routeTopologyFromJSON(object) {
+    switch (object) {
+        case 0:
+        case "ROUTE_TOPOLOGY_UNSPECIFIED":
+            return RouteTopology.ROUTE_TOPOLOGY_UNSPECIFIED;
+        case 1:
+        case "ROUTE_TOPOLOGY_OPEN":
+            return RouteTopology.ROUTE_TOPOLOGY_OPEN;
+        case 2:
+        case "ROUTE_TOPOLOGY_CLOSED":
+            return RouteTopology.ROUTE_TOPOLOGY_CLOSED;
+        case -1:
+        case "UNRECOGNIZED":
+        default:
+            return RouteTopology.UNRECOGNIZED;
+    }
+}
+exports.routeTopologyFromJSON = routeTopologyFromJSON;
+function routeTopologyToJSON(object) {
+    switch (object) {
+        case RouteTopology.ROUTE_TOPOLOGY_UNSPECIFIED:
+            return "ROUTE_TOPOLOGY_UNSPECIFIED";
+        case RouteTopology.ROUTE_TOPOLOGY_OPEN:
+            return "ROUTE_TOPOLOGY_OPEN";
+        case RouteTopology.ROUTE_TOPOLOGY_CLOSED:
+            return "ROUTE_TOPOLOGY_CLOSED";
+        case RouteTopology.UNRECOGNIZED:
+        default:
+            return "UNRECOGNIZED";
+    }
+}
+exports.routeTopologyToJSON = routeTopologyToJSON;
 /**
  * Lifecycle status for the route artifact (authoring + quality).
  * Execution-side state (vessel sailing, paused, completed) lives on
@@ -492,6 +553,61 @@ function routeStatusToJSON(object) {
     }
 }
 exports.routeStatusToJSON = routeStatusToJSON;
+/**
+ * Which side of an operational limit counts as a breach.
+ *
+ * RouteInfo's own limit block carries both directions — max_wind_gust_mps is
+ * breached above, min_visibility_m below — so nothing about a limit's identity
+ * says which way it fails. Consumers of an exceedance record need it: "the most
+ * extreme value reached" is undefined without it, and deriving the direction
+ * from a `max_` / `min_` name prefix is a string match that fails silently the
+ * first time a limit is named anything else.
+ *
+ * Lives here rather than beside either consumer because it is a property of the
+ * limit as authored, not of the monitoring. Read by keelson.EnvelopeExceedance
+ * and keelson.EnvelopeLimitState.
+ */
+var EnvelopeBound;
+(function (EnvelopeBound) {
+    EnvelopeBound[EnvelopeBound["ENVELOPE_BOUND_UNSPECIFIED"] = 0] = "ENVELOPE_BOUND_UNSPECIFIED";
+    /** ENVELOPE_BOUND_UPPER - Breached by going ABOVE the limit value (max_wind_gust_mps, max_roll_deg). */
+    EnvelopeBound[EnvelopeBound["ENVELOPE_BOUND_UPPER"] = 1] = "ENVELOPE_BOUND_UPPER";
+    /** ENVELOPE_BOUND_LOWER - Breached by going BELOW it (min_visibility_m, min_speed_knots). */
+    EnvelopeBound[EnvelopeBound["ENVELOPE_BOUND_LOWER"] = 2] = "ENVELOPE_BOUND_LOWER";
+    EnvelopeBound[EnvelopeBound["UNRECOGNIZED"] = -1] = "UNRECOGNIZED";
+})(EnvelopeBound || (exports.EnvelopeBound = EnvelopeBound = {}));
+function envelopeBoundFromJSON(object) {
+    switch (object) {
+        case 0:
+        case "ENVELOPE_BOUND_UNSPECIFIED":
+            return EnvelopeBound.ENVELOPE_BOUND_UNSPECIFIED;
+        case 1:
+        case "ENVELOPE_BOUND_UPPER":
+            return EnvelopeBound.ENVELOPE_BOUND_UPPER;
+        case 2:
+        case "ENVELOPE_BOUND_LOWER":
+            return EnvelopeBound.ENVELOPE_BOUND_LOWER;
+        case -1:
+        case "UNRECOGNIZED":
+        default:
+            return EnvelopeBound.UNRECOGNIZED;
+    }
+}
+exports.envelopeBoundFromJSON = envelopeBoundFromJSON;
+function envelopeBoundToJSON(object) {
+    switch (object) {
+        case EnvelopeBound.ENVELOPE_BOUND_UNSPECIFIED:
+            return "ENVELOPE_BOUND_UNSPECIFIED";
+        case EnvelopeBound.ENVELOPE_BOUND_UPPER:
+            return "ENVELOPE_BOUND_UPPER";
+        case EnvelopeBound.ENVELOPE_BOUND_LOWER:
+            return "ENVELOPE_BOUND_LOWER";
+        case EnvelopeBound.UNRECOGNIZED:
+        default:
+            return "UNRECOGNIZED";
+    }
+}
+exports.envelopeBoundToJSON = envelopeBoundToJSON;
 /** Required action for an ActionPoint. */
 var ActionPointRequiredAction;
 (function (ActionPointRequiredAction) {
@@ -1311,6 +1427,8 @@ function createBaseRouteInfo() {
         maxWindSpeedMps: undefined,
         minSpeedKnots: undefined,
         maxSpeedKnots: undefined,
+        minVisibilityM: undefined,
+        maxWindGustMps: undefined,
         optimizationMethod: "",
         autonomyLevel: 0,
         extensions: undefined,
@@ -1360,6 +1478,12 @@ exports.RouteInfo = {
         if (message.maxSpeedKnots !== undefined) {
             writer.uint32(277).float(message.maxSpeedKnots);
         }
+        if (message.minVisibilityM !== undefined) {
+            writer.uint32(285).float(message.minVisibilityM);
+        }
+        if (message.maxWindGustMps !== undefined) {
+            writer.uint32(293).float(message.maxWindGustMps);
+        }
         if (message.optimizationMethod !== "") {
             writer.uint32(402).string(message.optimizationMethod);
         }
@@ -1476,6 +1600,20 @@ exports.RouteInfo = {
                     message.maxSpeedKnots = reader.float();
                     continue;
                 }
+                case 35: {
+                    if (tag !== 285) {
+                        break;
+                    }
+                    message.minVisibilityM = reader.float();
+                    continue;
+                }
+                case 36: {
+                    if (tag !== 293) {
+                        break;
+                    }
+                    message.maxWindGustMps = reader.float();
+                    continue;
+                }
                 case 50: {
                     if (tag !== 402) {
                         break;
@@ -1521,6 +1659,8 @@ exports.RouteInfo = {
             maxWindSpeedMps: isSet(object.maxWindSpeedMps) ? globalThis.Number(object.maxWindSpeedMps) : undefined,
             minSpeedKnots: isSet(object.minSpeedKnots) ? globalThis.Number(object.minSpeedKnots) : undefined,
             maxSpeedKnots: isSet(object.maxSpeedKnots) ? globalThis.Number(object.maxSpeedKnots) : undefined,
+            minVisibilityM: isSet(object.minVisibilityM) ? globalThis.Number(object.minVisibilityM) : undefined,
+            maxWindGustMps: isSet(object.maxWindGustMps) ? globalThis.Number(object.maxWindGustMps) : undefined,
             optimizationMethod: isSet(object.optimizationMethod) ? globalThis.String(object.optimizationMethod) : "",
             autonomyLevel: isSet(object.autonomyLevel) ? autonomyLevelFromJSON(object.autonomyLevel) : 0,
             extensions: isSet(object.extensions) ? exports.Extensions.fromJSON(object.extensions) : undefined,
@@ -1570,6 +1710,12 @@ exports.RouteInfo = {
         if (message.maxSpeedKnots !== undefined) {
             obj.maxSpeedKnots = message.maxSpeedKnots;
         }
+        if (message.minVisibilityM !== undefined) {
+            obj.minVisibilityM = message.minVisibilityM;
+        }
+        if (message.maxWindGustMps !== undefined) {
+            obj.maxWindGustMps = message.maxWindGustMps;
+        }
         if (message.optimizationMethod !== "") {
             obj.optimizationMethod = message.optimizationMethod;
         }
@@ -1600,6 +1746,8 @@ exports.RouteInfo = {
         message.maxWindSpeedMps = object.maxWindSpeedMps ?? undefined;
         message.minSpeedKnots = object.minSpeedKnots ?? undefined;
         message.maxSpeedKnots = object.maxSpeedKnots ?? undefined;
+        message.minVisibilityM = object.minVisibilityM ?? undefined;
+        message.maxWindGustMps = object.maxWindGustMps ?? undefined;
         message.optimizationMethod = object.optimizationMethod ?? "";
         message.autonomyLevel = object.autonomyLevel ?? 0;
         message.extensions = (object.extensions !== undefined && object.extensions !== null)
@@ -1609,7 +1757,7 @@ exports.RouteInfo = {
     },
 };
 function createBaseWaypoints() {
-    return { defaults: undefined, waypoint: [], extensions: undefined };
+    return { defaults: undefined, waypoint: [], topology: 0, extensions: undefined };
 }
 exports.Waypoints = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -1619,6 +1767,9 @@ exports.Waypoints = {
         for (const v of message.waypoint) {
             exports.Waypoint.encode(v, writer.uint32(18).fork()).join();
         }
+        if (message.topology !== 0) {
+            writer.uint32(24).int32(message.topology);
+        }
         if (message.extensions !== undefined) {
             exports.Extensions.encode(message.extensions, writer.uint32(794).fork()).join();
         }
@@ -1645,6 +1796,13 @@ exports.Waypoints = {
                     message.waypoint.push(exports.Waypoint.decode(reader, reader.uint32()));
                     continue;
                 }
+                case 3: {
+                    if (tag !== 24) {
+                        break;
+                    }
+                    message.topology = reader.int32();
+                    continue;
+                }
                 case 99: {
                     if (tag !== 794) {
                         break;
@@ -1664,6 +1822,7 @@ exports.Waypoints = {
         return {
             defaults: isSet(object.defaults) ? exports.DefaultWaypoint.fromJSON(object.defaults) : undefined,
             waypoint: globalThis.Array.isArray(object?.waypoint) ? object.waypoint.map((e) => exports.Waypoint.fromJSON(e)) : [],
+            topology: isSet(object.topology) ? routeTopologyFromJSON(object.topology) : 0,
             extensions: isSet(object.extensions) ? exports.Extensions.fromJSON(object.extensions) : undefined,
         };
     },
@@ -1675,6 +1834,9 @@ exports.Waypoints = {
         if (message.waypoint?.length) {
             obj.waypoint = message.waypoint.map((e) => exports.Waypoint.toJSON(e));
         }
+        if (message.topology !== 0) {
+            obj.topology = routeTopologyToJSON(message.topology);
+        }
         if (message.extensions !== undefined) {
             obj.extensions = exports.Extensions.toJSON(message.extensions);
         }
@@ -1689,6 +1851,7 @@ exports.Waypoints = {
             ? exports.DefaultWaypoint.fromPartial(object.defaults)
             : undefined;
         message.waypoint = object.waypoint?.map((e) => exports.Waypoint.fromPartial(e)) || [];
+        message.topology = object.topology ?? 0;
         message.extensions = (object.extensions !== undefined && object.extensions !== null)
             ? exports.Extensions.fromPartial(object.extensions)
             : undefined;

package/dist/interfaces/RoutePlanner.d.ts

@@ -1,6 +1,6 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
 import { Coordinate } from "./Coordinate";
-import { Extensions, Route, RouteInfo, RouteRef } from "./Route";
+import { Extensions, Route, RouteInfo, RouteRef, RouteTopology } from "./Route";
 export declare const protobufPackage = "keelson.interfaces.route_planner";
 /**
  * What the planner should optimise for. A closed set, not the free-form
@@ -46,6 +46,8 @@ export interface PlanRouteRequest {
      * `Coordinate`, not `Waypoint` — these are the positions the route must
      * touch, not planned waypoints with turn radii and speeds. Those are the
      * planner's output, not its input.
+     * Under `topology = CLOSED` this list is the circuit's via-points: the first
+     * is both departure and final arrival, and it is NOT repeated at the end.
      */
     waypoints: Coordinate[];
     /**
@@ -64,6 +66,15 @@ export interface PlanRouteRequest {
      * reply with more.
      */
     maxAlternatives: number;
+    /**
+     * Whether the caller wants a point-to-point route or a circuit. Without it
+     * a circuit is unrequestable and the planner's own convention becomes the
+     * new implicit rule, one layer up from where it was just removed. Under
+     * CLOSED the planner MUST set `Waypoints.topology` on every alternative and
+     * close it with a leg on the last waypoint, never by appending a copy of
+     * `waypoints[0]`. See protocol-specification.md §6.2.1.
+     */
+    topology: RouteTopology;
     /**
      * Vendor-specific planning inputs — deployment tunings, experimental cost
      * profiles. Anything that becomes generally useful should graduate to a
@@ -94,6 +105,13 @@ export declare const RoutePlannerDefinition: {
          * Re-run navigability and validation against a (possibly hand-edited)
          * route, replying it annotated with `challenges`, `issues` and `status`.
          * Takes a whole `keelson.Route` because that is genuinely the input.
+         *
+         * The closure invariants of §6.2.1 are part of what is validated, and a
+         * breach is a `RouteIssue`: the last waypoint carries a `leg` if and only if
+         * the topology is CLOSED, the first waypoint is not repeated at the end,
+         * waypoint ids are unique, and a CLOSED route has at least two waypoints.
+         * Exactly two is legal but coincident out-and-back geometry — a
+         * `RouteChallenge`, not an error.
          */
         readonly validate_route: {
             readonly name: "validate_route";

package/dist/interfaces/RoutePlanner.js

@@ -87,7 +87,7 @@ function optimizationGoalToJSON(object) {
 }
 exports.optimizationGoalToJSON = optimizationGoalToJSON;
 function createBasePlanRouteRequest() {
-    return { waypoints: [], constraints: undefined, goal: 0, maxAlternatives: 0, extensions: undefined };
+    return { waypoints: [], constraints: undefined, goal: 0, maxAlternatives: 0, topology: 0, extensions: undefined };
 }
 exports.PlanRouteRequest = {
     encode(message, writer = new wire_1.BinaryWriter()) {
@@ -103,6 +103,9 @@ exports.PlanRouteRequest = {
         if (message.maxAlternatives !== 0) {
             writer.uint32(32).uint32(message.maxAlternatives);
         }
+        if (message.topology !== 0) {
+            writer.uint32(40).int32(message.topology);
+        }
         if (message.extensions !== undefined) {
             Route_1.Extensions.encode(message.extensions, writer.uint32(794).fork()).join();
         }
@@ -143,6 +146,13 @@ exports.PlanRouteRequest = {
                     message.maxAlternatives = reader.uint32();
                     continue;
                 }
+                case 5: {
+                    if (tag !== 40) {
+                        break;
+                    }
+                    message.topology = reader.int32();
+                    continue;
+                }
                 case 99: {
                     if (tag !== 794) {
                         break;
@@ -166,6 +176,7 @@ exports.PlanRouteRequest = {
             constraints: isSet(object.constraints) ? Route_1.RouteInfo.fromJSON(object.constraints) : undefined,
             goal: isSet(object.goal) ? optimizationGoalFromJSON(object.goal) : 0,
             maxAlternatives: isSet(object.maxAlternatives) ? globalThis.Number(object.maxAlternatives) : 0,
+            topology: isSet(object.topology) ? (0, Route_1.routeTopologyFromJSON)(object.topology) : 0,
             extensions: isSet(object.extensions) ? Route_1.Extensions.fromJSON(object.extensions) : undefined,
         };
     },
@@ -183,6 +194,9 @@ exports.PlanRouteRequest = {
         if (message.maxAlternatives !== 0) {
             obj.maxAlternatives = Math.round(message.maxAlternatives);
         }
+        if (message.topology !== 0) {
+            obj.topology = (0, Route_1.routeTopologyToJSON)(message.topology);
+        }
         if (message.extensions !== undefined) {
             obj.extensions = Route_1.Extensions.toJSON(message.extensions);
         }
@@ -199,6 +213,7 @@ exports.PlanRouteRequest = {
             : undefined;
         message.goal = object.goal ?? 0;
         message.maxAlternatives = object.maxAlternatives ?? 0;
+        message.topology = object.topology ?? 0;
         message.extensions = (object.extensions !== undefined && object.extensions !== null)
             ? Route_1.Extensions.fromPartial(object.extensions)
             : undefined;
@@ -226,6 +241,13 @@ exports.RoutePlannerDefinition = {
          * Re-run navigability and validation against a (possibly hand-edited)
          * route, replying it annotated with `challenges`, `issues` and `status`.
          * Takes a whole `keelson.Route` because that is genuinely the input.
+         *
+         * The closure invariants of §6.2.1 are part of what is validated, and a
+         * breach is a `RouteIssue`: the last waypoint carries a `leg` if and only if
+         * the topology is CLOSED, the first waypoint is not repeated at the end,
+         * waypoint ids are unique, and a CLOSED route has at least two waypoints.
+         * Exactly two is legal but coincident out-and-back geometry — a
+         * `RouteChallenge`, not an error.
          */
         validate_route: {
             name: "validate_route",