fix(tours): checklist entries within their contract, whole locks and a leaner reading

A lock flight chained into one group of more than 30 parts broke the
checklist's contract and made every decision about it fail; an entry now
names its nearest part and the first others, a portage lists at most 30
obstacles and a checklist at most 100 own entries. Reading along a line
takes in the parts of a lock the corridor cut off, so its data basis no
longer depends on how the route runs. A line or an area stands at the
middle of its extent, so adding a node leaves it in place, and an earlier
decision is judged by where the obstacle was, not by the route point of its
passage. The cache keeps its readings without their lines, for one data
version at a time, and the data version is read without the region
boundaries.

shared/src/paddle/paddle-route-relation.ts

@@ -213,7 +213,7 @@ export function relateObstaclesToRoute(
   return related.sort((a, b) => a.alongM - b.alongM);
 }
 
-/** Two visits of the route closer than this along it are one passage (a bend that leaves the reach for a moment). */
+/** Two visits whose closest points lie closer than this along the route are one passage. */
 export const PASSAGE_GAP_M = 50;
 /** The most passages one object keeps: an out-and-back tour passes twice, a winding river a few times more. */
 export const MAX_PASSAGES = 4;
@@ -257,9 +257,12 @@ function segmentApproach(
 
 /**
  * Every separate time the route comes within `reachM` of an object, in route
- * order: a run of segments in reach is one visit, two runs closer than
- * PASSAGE_GAP_M along the route are one, and each visit is anchored where it
- * comes closest (the earlier point on a tie). An out-and-back tour passes an
+ * order: a run of segments in reach is one visit, anchored where it comes
+ * closest (the earlier point on a tie), and two visits whose anchors lie
+ * closer than PASSAGE_GAP_M along the route are one. Two runs whose anchors
+ * lie further apart stay two passages even when the route left the reach
+ * only briefly between them; that binds a decision to more of the route, so
+ * it errs towards asking for a look again. An out-and-back tour passes an
  * obstacle twice, so a change to its way back is not missed. At most
  * MAX_PASSAGES are kept, the closest ones.
  */

shared/src/tours/paddle-check.schema.ts

@@ -112,11 +112,15 @@ export type ObstacleDecisionRecord = z.infer<typeof obstacleDecisionRecordSchema
 
 /** The most entries one checklist carries; an area holding more answers as cut short. */
 export const PADDLE_CHECK_MAX_ENTRIES = 300;
+/** The most own portages and locks one checklist lists. */
+export const PADDLE_CHECK_MAX_OWN = 100;
+/** The most objects one entry names, and the most obstacles one portage lists as carried round. */
+export const OBSTACLE_REFS_MAX = 30;
 
 export const tourObstacleEntrySchema = z.object({
   key: obstacleKeySchema,
   /** The objects it stands for, the one nearest the route first: the map selects that one. */
-  refs: z.array(osmRefSchema).min(1).max(30),
+  refs: z.array(osmRefSchema).min(1).max(OBSTACLE_REFS_MAX),
   kind: paddleObstacleKindSchema,
   name: z.string().nullable(),
   at: latLng,
@@ -152,7 +156,7 @@ export const tourOwnEntrySchema = z.object({
   at: latLng,
   bounds,
   /** The obstacles a portage carries round. */
-  covers: z.array(obstacleKeySchema).max(30),
+  covers: z.array(obstacleKeySchema).max(OBSTACLE_REFS_MAX),
   bypassed: z.boolean(),
   advice: z.literal('sup_lock_portage').nullable(),
   /** A carrying way the data records as forbidden or private. */
@@ -188,7 +192,7 @@ export const tourObstacleCheckSchema = z.object({
   revision: z.string().min(1).max(64),
   evaluated_at: z.string(),
   entries: z.array(tourObstacleEntrySchema).max(PADDLE_CHECK_MAX_ENTRIES),
-  own: z.array(tourOwnEntrySchema).max(100),
+  own: z.array(tourOwnEntrySchema).max(PADDLE_CHECK_MAX_OWN),
 });
 export type TourObstacleCheck = z.infer<typeof tourObstacleCheckSchema>;
 
@@ -197,7 +201,7 @@ export const obstacleSnapshotSchema = z.object({
   v: z.literal(1),
   kind: paddleObstacleKindSchema,
   name: z.string().nullable(),
-  refs: z.array(osmRefSchema).min(1).max(30),
+  refs: z.array(osmRefSchema).min(1).max(OBSTACLE_REFS_MAX),
   at: latLng,
   bounds,
   relation: z.enum(['on_route', 'near']),

shared/src/tours/paddle-check.spec.ts

@@ -28,6 +28,7 @@ import {
   type PaddleCheckLine,
 } from './paddle-check-basis';
 import {
+  OBSTACLE_REFS_MAX,
   obstacleBasisSchema,
   obstacleSnapshotSchema,
   paddleCheckSchema,
@@ -223,7 +224,10 @@ function reviewOf(candidate: ObstacleCandidate, overrides: Partial<StoredObstacl
 /** A decision taken on a day about an object at a place, which no current candidate carries. */
 function earlierReview(key: string, place: [number, number], day: string, source = SOURCE): StoredObstacleReview {
   const decidedAt = `${day}T08:00:00.000Z`;
-  return reviewOf(candidateOf(key, { at: place }), { decided_at: decidedAt, source_fingerprint: source });
+  return reviewOf(candidateOf(key, { at: place, bounds: [place, place] }), {
+    decided_at: decidedAt,
+    source_fingerprint: source,
+  });
 }
 
 /** A checklist entry as obstacleEntriesOf makes one, open unless told otherwise. */
@@ -344,8 +348,8 @@ describe('obstacleCandidatesOf', () => {
     expect(lock.route.startsWith('p1:o:')).toBe(true);
     expect(sameRouteToken(lock.route, routeTokenOf(straight, [975], 'on_route'))).toBe(true);
     expect(lock.source.split(':')[1]).toBe(fnv1a(materialOf(features)));
-    // The mean of each part's own place: a gate's middle (here second) vertex, the chamber's mean outline point.
-    expect(gapM(positionOf(lock.source), at(6, 994))).toBeLessThan(1);
+    // The mean of each part's own place, the middle of its extent: the gates at 975 and 1015 m, the chamber at 995 m.
+    expect(gapM(positionOf(lock.source), at(0, 995))).toBeLessThan(1);
   });
 
   it('keeps the source through a new name or check on site, and changes it with a paddling rule on any part', () => {
@@ -504,6 +508,30 @@ describe('obstacleCandidatesOf', () => {
   });
 });
 
+describe('the caps of one entry', () => {
+  it('names a lock of more parts than an entry holds by its nearest part and the first others, as the schemas allow', () => {
+    // 40 gates along the chamber, all of one lock; the first one sits on the route.
+    const parts = Array.from({ length: 40 }, (_, i) =>
+      feature(`way/${500 + i}`, 'lock_gate', wayThrough([-10, 960 + i], [10, 960 + i]), { group_key: 'lock:way/500' }),
+    );
+    const [lock] = candidatesOf(straight, parts);
+    expect(lock?.refs).toHaveLength(OBSTACLE_REFS_MAX);
+    expect(new Set(lock?.refs).size).toBe(OBSTACLE_REFS_MAX);
+    if (!lock) throw new Error('no lock');
+    expect(obstacleSnapshotSchema.safeParse(obstacleSnapshotOf(lock)).success).toBe(true);
+  });
+
+  it('lists at most as many obstacles under one portage as an own entry holds', () => {
+    const line: PaddleCheckLine = { ...straight, portages: [{ fromM: 100, toM: 1900, index: 1 }] };
+    const candidates = Array.from({ length: 35 }, (_, i) =>
+      candidateOf(`node/${i + 1}`, { passage_m: [200 + i * 40] }),
+    );
+    const [portage] = ownEntriesOf({ line, candidates, features: [], boat: 'kayak' });
+    expect(portage?.covers).toHaveLength(OBSTACLE_REFS_MAX);
+    expect(tourOwnEntrySchema.safeParse(portage).success).toBe(true);
+  });
+});
+
 describe('ownEntriesOf', () => {
   const planned: PaddleCheckLine = {
     ...straight,
@@ -890,3 +918,40 @@ describe('paddleCheckSummaryOf', () => {
     expect(paddleCheckSummaryOf(entries, own, bench)).toMatchObject({ decided: 1, open: 0, review: 0, bans: 1 });
   });
 });
+
+describe('where an object stands', () => {
+  it('keeps the place of a line through a node added on it or the way turned round', () => {
+    const weir = feature('way/70', 'weir', wayThrough([-20, 1000], [20, 1000]));
+    const noded = feature('way/70', 'weir', wayThrough([-20, 1000], [5, 1000], [20, 1000]));
+    const turned = feature('way/70', 'weir', wayThrough([20, 1000], [-20, 1000]));
+    const [source] = candidatesOf(straight, [weir]).map((candidate) => positionOf(candidate.source));
+    for (const other of [noded, turned]) {
+      const [moved] = candidatesOf(straight, [other]).map((candidate) => positionOf(candidate.source));
+      if (!source || !moved) throw new Error('no candidate');
+      expect(gapM(moved, source)).toBeLessThan(1);
+    }
+  });
+
+  it('keeps an earlier decision about an object beside the route as one still near it, by the object itself', () => {
+    // The weir stood 140 m north of the route; the route point of its passage was on the line.
+    const review = reviewOf(candidateOf('way/71', { at: at(0, 1000), bounds: [at(140, 1000), at(140, 1000)] }), {
+      decided_at: '2026-09-02T08:00:00.000Z',
+    });
+    const entries = obstacleEntriesOf({
+      candidates: [],
+      reviews: [review],
+      dataKeys: new Set(),
+      complete: true,
+      line: straight,
+    });
+    expect(entries.map((entry) => entry.status)).toEqual(['gone']);
+    const far = reviewOf(candidateOf('way/72', { at: at(0, 1000), bounds: [at(400, 1000), at(420, 1010)] }), {
+      decided_at: '2026-09-02T08:00:00.000Z',
+    });
+    expect(
+      obstacleEntriesOf({ candidates: [], reviews: [far], dataKeys: new Set(), complete: true, line: straight }).map(
+        (entry) => entry.status,
+      ),
+    ).toEqual(['off_route']);
+  });
+});

shared/src/tours/paddle-check.ts

@@ -26,13 +26,14 @@ import {
   sourceTokenOf,
   type PaddleCheckLine,
 } from './paddle-check-basis';
-import type {
-  ObstacleDecision,
-  ObstacleEntryStatus,
-  ObstacleSnapshot,
-  PaddleCheck,
-  TourObstacleEntry,
-  TourOwnEntry,
+import {
+  OBSTACLE_REFS_MAX,
+  type ObstacleDecision,
+  type ObstacleEntryStatus,
+  type ObstacleSnapshot,
+  type PaddleCheck,
+  type TourObstacleEntry,
+  type TourOwnEntry,
 } from './paddle-check.schema';
 import type { PaddleBoatType } from './tours.schema';
 
@@ -106,11 +107,16 @@ export function paddleGeometryPoints(geometry: PaddleGeometry): Array<[number, n
   return (geometry.coordinates[0] ?? []).map(pair);
 }
 
-/** Where an object stands as one point: a point itself, a line's middle vertex, an area's mean outline point. */
+/**
+ * Where an object stands as one point: a point itself, a line or an area the
+ * middle of its extent, so adding a node or turning a way round leaves it in
+ * place and only a change of its shape moves it.
+ */
 function representative(geometry: PaddleGeometry): [number, number] {
   const points = paddleGeometryPoints(geometry);
-  if (geometry.type === 'LineString') return points[Math.floor(points.length / 2)] ?? [0, 0];
-  return mean(points);
+  if (geometry.type === 'Point' || points.length === 0) return points[0] ?? [0, 0];
+  const [[south, west], [north, east]] = boundsOf(points);
+  return [(south + north) / 2, (west + east) / 2];
 }
 
 function mean(points: ReadonlyArray<readonly [number, number]>): [number, number] {
@@ -227,13 +233,14 @@ export function obstacleCandidatesOf(input: {
     const position = mean(members.map((member) => representative(member.geometry)));
     candidates.push({
       key,
+      // The part nearest the route first, the map selects it; a huge group names its first parts only.
       refs: [
         anchor.feature.ref,
         ...members
           .map((member) => member.ref)
           .filter((ref) => ref !== anchor.feature.ref)
           .sort(),
-      ],
+      ].slice(0, OBSTACLE_REFS_MAX),
       kind,
       name: anchor.feature.name ?? members.find((member) => member.name)?.name ?? null,
       at,
@@ -302,7 +309,8 @@ export function ownEntriesOf(input: {
             (m) => m >= portage.fromM - PORTAGE_PROOF_SLACK_M && m <= portage.toM + PORTAGE_PROOF_SLACK_M,
           ),
         )
-        .map((candidate) => candidate.key),
+        .map((candidate) => candidate.key)
+        .slice(0, OBSTACLE_REFS_MAX),
       bypassed: false,
       advice: null,
       conflict: restrictions.includes('forbidden') ? 'forbidden' : restrictions.includes('private') ? 'private' : null,
@@ -375,6 +383,31 @@ function decisionRecordOf(review: StoredObstacleReview) {
   };
 }
 
+/**
+ * Whether the route still comes within NEAR_M of where an obstacle was, by
+ * its whole extent rather than the point of the passage, since an object
+ * near the route lies up to that far from it.
+ */
+function reachesRoute(line: PaddleCheckLine, bounds: ObstacleSnapshot['bounds']): boolean {
+  // Read as numbers: a consumer compiled without strict checks types the tuples loosely.
+  const [south, west] = [Number(bounds[0][0]), Number(bounds[0][1])];
+  const [north, east] = [Number(bounds[1][0]), Number(bounds[1][1])];
+  if (south === north && west === east) return distanceToRouteM(line.points, [south, west]) <= NEAR_M;
+  const extent: PaddleGeometry = {
+    type: 'Polygon',
+    coordinates: [
+      [
+        [west, south],
+        [east, south],
+        [east, north],
+        [west, north],
+        [west, south],
+      ],
+    ],
+  };
+  return routePassages(line.points, extent, NEAR_M).length > 0;
+}
+
 /**
  * The checklist: the current candidates in route order with their status,
  * then the earlier decisions no candidate carries any more, newest first.
@@ -408,11 +441,9 @@ export function obstacleEntriesOf(input: {
     .sort((a, b) => b.decided_at.localeCompare(a.decided_at))
     .map((review): TourObstacleEntry => {
       const { snapshot } = review;
-      // Read as numbers: a consumer compiled without strict checks types the tuple loosely.
-      const at: [number, number] = [Number(snapshot.at[0]), Number(snapshot.at[1])];
       let status: ObstacleEntryStatus;
       if (input.dataKeys.has(review.obstacle_key)) status = 'off_route';
-      else if (distanceToRouteM(input.line.points, at) > NEAR_M) status = 'off_route';
+      else if (!reachesRoute(input.line, snapshot.bounds)) status = 'off_route';
       else if (input.complete) status = review.source_fingerprint === 'gone' ? 'kept' : 'gone';
       else status = 'unknown';
       return {