feat(vessels): key vessels by their source's stable id, and share a selected vessel

AIS Vessels are keyed by the id their live source gives, with the MMSI as an
attribute: an MMSI can be shared, spoofed or reused, so two vessels with one
MMSI are now two vessels. Looking a vessel up or selecting it by MMSI still
finds it.

A share link made while a vessel is selected opens that vessel. A UUID vessel
id travels as 16 bytes in a new thing field (13). A shared thing that is not
reporting now says so in a sentence per kind, with its id (ICAO, NORAD, MMSI
or vessel UUID) on a second line.
This commit is contained in:
Sameh Khamis committed 2026-11-10 18:12:53 -08:00
1 parent 57ff81f723
commit cbbf55cacd
74 files changed
+2481 -586

No files matched your search

+36 -10
View File
@@ -28,6 +28,14 @@ const MMSI_SCHEMA = Object.freeze({
pattern: '^\\d{5,10}$',
description: 'Maritime Mobile Service Identity, such as "366999712".',
});
const VESSEL_ID_SCHEMA = Object.freeze({
type: 'string',
minLength: 1,
maxLength: 128,
description:
'The vessel id a vessel search returned. Vessels can share an MMSI; ' +
'the id names one of them.',
});
const MAX_TRACK_POINTS = 200;
const ALL_VESSELS = 1_000_000;
@@ -47,10 +55,13 @@ const vesselDestination = (value) => {
return destination && /\p{L}/u.test(destination) ? destination : null;
};
// `id` is the vessel's key; `mmsi` is its MMSI when known (vessels can share
// one), else null.
function vesselRow(record, from) {
const point = { lat: record.latitude, lon: record.longitude };
return {
mmsi: record.id,
id: record.id,
mmsi: text(record.mmsi),
name: text(record.name),
imo: text(record.imo),
type: vesselType(record.type),
@@ -194,7 +205,7 @@ export const findVessel = defineTool({
const [key] = given;
const wanted = args[key].trim().toUpperCase();
const matches = {
mmsi: (record) => record.id === wanted,
mmsi: (record) => String(record.mmsi ?? '') === wanted,
imo: (record) => String(record.imo).replace(/^IMO/i, '') === wanted,
name: (record) => String(record.name).toUpperCase().includes(wanted),
}[key];
@@ -227,25 +238,40 @@ export const getVesselTrack = defineTool({
name: 'get_vessel_track',
title: 'Vessel track',
description:
'Recent positions of one ship by MMSI, oldest first. Long tracks are ' +
`evenly thinned to at most ${MAX_TRACK_POINTS} points.`,
'Recent positions of one ship by its vessel id or MMSI, oldest first. ' +
`Long tracks are evenly thinned to at most ${MAX_TRACK_POINTS} points.`,
inputSchema: {
type: 'object',
properties: { mmsi: MMSI_SCHEMA },
required: ['mmsi'],
properties: { id: VESSEL_ID_SCHEMA, mmsi: MMSI_SCHEMA },
additionalProperties: false,
},
requires: ['vessels'],
async run(args, { services, signal }) {
const track = await services.vessels.getTrack(args.mmsi, { signal });
const given = ['id', 'mmsi'].filter((key) => args[key] != null);
if (given.length !== 1)
throw new ToolError(
'invalid_arguments',
'Give exactly one of id or mmsi',
);
const [key] = given;
const wanted = String(args[key]).trim();
// A track is asked for by the source's reference for the vessel, which
// for an id is the reported vessel's; an MMSI is passed as it is.
let reference = wanted;
if (key === 'id') {
const snapshot = await readVessels(services, signal);
const record = snapshot.records.find((item) => item.id === wanted);
reference = record?.reference ?? wanted;
}
const track = await services.vessels.getTrack(reference, { signal });
const points = track.records
.filter((point) => Number.isFinite(point.observedAtMs))
.sort((a, b) => a.observedAtMs - b.observedAtMs);
const kept = thinEvenly(points, MAX_TRACK_POINTS);
return {
summary: points.length
? `${countNoun(points.length, 'position')} for ${args.mmsi} from ${isoTime(points[0].observedAtMs)} to ${isoTime(points.at(-1).observedAtMs)}.`
: `No recent track is available for ${args.mmsi}.`,
? `${countNoun(points.length, 'position')} for ${wanted} from ${isoTime(points[0].observedAtMs)} to ${isoTime(points.at(-1).observedAtMs)}.`
: `No recent track is available for ${wanted}.`,
data: {
view: kept.length
? suggestView(services, {
@@ -254,7 +280,7 @@ export const getVesselTrack = defineTool({
altitudeM: 20_000,
})
: null,
mmsi: args.mmsi,
...(key === 'id' ? { id: wanted } : { mmsi: wanted }),
total: points.length,
returned: kept.length,
thinned: kept.length < points.length,
+50
View File
@@ -5,8 +5,10 @@ import { LiveSourceError } from '../../sources/live/contract.js';
import { createVesselSource } from '../../sources/live/standalone.js';
import { AISSTREAM_CACHE_MAX } from '../../../server/providers/vessels/ais-store.js';
// An AIS source's vessel: keyed by its MMSI, which it also reports.
const vessel = (id, latitude, longitude, extra = {}) => ({
id,
mmsi: id,
reference: id,
latitude,
longitude,
@@ -79,6 +81,7 @@ test('vessels in an area are nearest first and filterable by type', async () =>
['366999712', '538001234'],
);
assert.deepEqual(all.data.rows[0], {
id: '366999712',
mmsi: '366999712',
name: 'GOLDEN BEAR',
imo: '9123456',
@@ -164,6 +167,53 @@ test('vessel tracks are ordered and drop untimed positions', async () => {
);
});
test('vessels sharing an MMSI are found as two, each by its own id', async () => {
const shared = [
vessel('hull-a', 37.81, -122.41, { mmsi: '366999712', name: 'A' }),
vessel('hull-b', 37.79, -122.42, {
mmsi: '366999712',
name: 'B',
reference: 'track:hull-b',
}),
vessel('hull-c', 37.8, -122.4, { mmsi: undefined, name: 'C' }),
];
const tracks = [];
const catalog = composeCatalog({
tools: coreTools,
services: {
vessels: {
getSnapshot: async () => ({ records: shared, freshness: 'current' }),
getTrack: async (reference) => {
tracks.push(reference);
return { records: [] };
},
},
},
});
const found = await catalog.call('find_vessel', { mmsi: '366999712' });
assert.deepEqual(
found.data.rows.map((row) => [row.id, row.mmsi]),
[
['hull-a', '366999712'],
['hull-b', '366999712'],
],
);
const area = await catalog.call('vessels_in_area', { area: bay });
assert.deepEqual(
area.data.rows.find((row) => row.id === 'hull-c').mmsi,
null,
'a vessel with no MMSI says so',
);
const track = await catalog.call('get_vessel_track', { id: 'hull-b' });
assert.deepEqual(tracks, ['track:hull-b'], "asked by the vessel's reference");
assert.equal(track.data.id, 'hull-b');
assert.equal(track.summary, 'No recent track is available for hull-b.');
await assert.rejects(
catalog.call('get_vessel_track', { id: 'hull-b', mmsi: '366999712' }),
/exactly one/,
);
});
test('a missing AIS key surfaces as an unavailable feed', async () => {
const keyless = {
getSnapshot: async () => {