@totemsdk/act-mavlink 0.0.0-stage → 0.1.0

package/dist/cjs/adapter.js

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * RFC-025 §5.3 — governed MAVLink operations.
+ *
+ * `startMission` carries the authorized envelope digest; a start whose
+ * recomputed digest differs from the authorized one fails closed before
+ * dispatch. Acceptance is never completion: `startMission` reconciles through
+ * vehicle telemetry and only reports `confirmed` on observed arrival.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMavlinkDefinitions = createMavlinkDefinitions;
+const act_core_1 = require("@totemsdk/act-core");
+const effects_js_1 = require("./effects.js");
+const envelope_js_1 = require("./envelope.js");
+const profile_js_1 = require("./profile.js");
+const transport_js_1 = require("./transport.js");
+function decimal(value) {
+    return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(9)));
+}
+function quantityValue(value, unit, units) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'object' && 'value' in value && 'unit' in value) {
+        return units.convert(value, unit).value;
+    }
+    return undefined;
+}
+function numberParameter(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    throw new transport_js_1.MavlinkTransportError('Invalid', `expected a number, got '${String(value)}'`);
+}
+function stringParameter(value) {
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    throw new transport_js_1.MavlinkTransportError('Invalid', `expected a non-empty string, got '${String(value)}'`);
+}
+function waypointIssues(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return 'at least one waypoint is required';
+    if (value.length > 100)
+        return 'mission exceeds the 100-waypoint limit';
+    for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object')
+            return `waypoint ${index} must be an object`;
+        const waypoint = entry;
+        if (typeof waypoint.latitudeDeg !== 'number')
+            return `waypoint ${index} latitudeDeg must be a number`;
+        if (typeof waypoint.longitudeDeg !== 'number')
+            return `waypoint ${index} longitudeDeg must be a number`;
+        if (typeof waypoint.altitudeMetres !== 'number')
+            return `waypoint ${index} altitudeMetres must be a number`;
+    }
+    return null;
+}
+function createMavlinkDefinitions(options) {
+    const units = options.units ?? (0, act_core_1.defaultUnitRegistry)();
+    const taxonomy = (0, profile_js_1.mavlinkErrorTaxonomy)();
+    const transport = options.transport;
+    const arrivalTolerance = options.arrivalToleranceMetres ?? 15;
+    function vehicleOf(vehicleId) {
+        const vehicle = options.vehicles.find((candidate) => candidate.vehicleId === vehicleId);
+        if (!vehicle) {
+            throw new transport_js_1.MavlinkTransportError('Invalid', `vehicle '${vehicleId}' is not registered`);
+        }
+        return vehicle;
+    }
+    function resourceFor(vehicleId) {
+        return (0, act_core_1.resourceIdKey)((0, profile_js_1.vehicleResourceId)(options.site, vehicleId));
+    }
+    function envelopeFrom(params) {
+        const vehicleId = stringParameter(params.vehicle);
+        vehicleOf(vehicleId);
+        const altitude = quantityValue(params.maxAltitudeMetres, 'm', units);
+        const speed = quantityValue(params.maxSpeedMetresPerSecond, 'm/s', units);
+        const duration = quantityValue(params.maxDurationSeconds, 's', units);
+        if (altitude === undefined)
+            throw new transport_js_1.MavlinkTransportError('Invalid', 'maxAltitudeMetres is required');
+        if (speed === undefined)
+            throw new transport_js_1.MavlinkTransportError('Invalid', 'maxSpeedMetresPerSecond is required');
+        if (duration === undefined)
+            throw new transport_js_1.MavlinkTransportError('Invalid', 'maxDurationSeconds is required');
+        const geofenceLatitude = params.geofenceLatitudeDeg;
+        const geofenceLongitude = params.geofenceLongitudeDeg;
+        const geofenceRadius = params.geofenceRadiusMetres;
+        const hasGeofence = geofenceLatitude !== undefined || geofenceLongitude !== undefined || geofenceRadius !== undefined;
+        if (hasGeofence && (geofenceLatitude === undefined || geofenceLongitude === undefined || geofenceRadius === undefined)) {
+            throw new transport_js_1.MavlinkTransportError('Invalid', 'geofence requires latitude, longitude and radius');
+        }
+        const envelope = {
+            envelopeId: stringParameter(params.envelopeId),
+            vehicle: vehicleId,
+            waypoints: params.waypoints,
+            maxAltitudeMetres: decimal(altitude),
+            maxSpeedMetresPerSecond: decimal(speed),
+            maxDurationSeconds: decimal(duration),
+            ...(hasGeofence
+                ? {
+                    geofence: {
+                        latitudeDeg: numberParameter(geofenceLatitude),
+                        longitudeDeg: numberParameter(geofenceLongitude),
+                        radiusMetres: numberParameter(geofenceRadius),
+                    },
+                }
+                : {}),
+        };
+        (0, envelope_js_1.assertValidMissionEnvelope)(envelope);
+        return envelope;
+    }
+    function envelopeParameters() {
+        return [
+            { name: 'envelopeId', type: 'string', required: true, description: 'Authorized plan id.' },
+            { name: 'vehicle', type: 'string', required: true, description: 'Vehicle id.' },
+            {
+                name: 'waypoints', type: 'array', required: true,
+                description: 'Ordered WGS-84 waypoints (latitudeDeg, longitudeDeg, altitudeMetres).',
+                validation: waypointIssues,
+            },
+            {
+                name: 'maxAltitudeMetres', type: 'quantity', required: true,
+                dimension: 'length', unit: 'm', description: 'Altitude ceiling.',
+            },
+            {
+                name: 'maxSpeedMetresPerSecond', type: 'quantity', required: true,
+                dimension: 'linearSpeed', unit: 'm/s', description: 'Ground-speed ceiling.',
+            },
+            {
+                name: 'maxDurationSeconds', type: 'quantity', required: true,
+                dimension: 'time', unit: 's', description: 'Mission duration ceiling.',
+            },
+            { name: 'geofenceLatitudeDeg', type: 'number', required: false },
+            { name: 'geofenceLongitudeDeg', type: 'number', required: false },
+            { name: 'geofenceRadiusMetres', type: 'number', required: false },
+        ];
+    }
+    function telemetryConfirmed(telemetry, check) {
+        return check(telemetry);
+    }
+    const definitions = [
+        {
+            kind: 'flight:uploadMission',
+            description: 'Upload an authorized mission plan to the autopilot (no dispatch of motion).',
+            version: 1,
+            capability: 'industrial:action',
+            effect: 'write',
+            protocol: profile_js_1.MAVLINK_PROTOCOL,
+            errorTaxonomy: taxonomy,
+            schema: { parameters: envelopeParameters(), context: [] },
+            // Uploading a plan moves nothing; a failed upload is simply aborted.
+            policy: { failureMode: 'abort', timeoutMs: 30000 },
+            async prepare(params) {
+                const envelope = envelopeFrom(params);
+                const digest = (0, envelope_js_1.envelopeDigest)(envelope);
+                return {
+                    resourceId: resourceFor(envelope.vehicle),
+                    command: { action: 'uploadMission', envelope, envelopeDigest: digest },
+                };
+            },
+            deriveEffects(op) {
+                const command = op.command;
+                return (0, effects_js_1.deriveFlightEffects)({
+                    resource: resourceFor(command.envelope.vehicle),
+                    maxSpeedMetresPerSecond: command.envelope.maxSpeedMetresPerSecond,
+                    maxDurationSeconds: command.envelope.maxDurationSeconds,
+                    envelopeId: command.envelope.envelopeId,
+                    envelopeDigest: command.envelopeDigest,
+                });
+            },
+            async actuate(op) {
+                const command = op.command;
+                const result = await transport.uploadMission({
+                    envelopeId: command.envelope.envelopeId,
+                    envelopeDigest: command.envelopeDigest,
+                    waypoints: command.envelope.waypoints,
+                });
+                return {
+                    ok: true,
+                    data: { missionId: result.missionId, envelopeDigest: command.envelopeDigest },
+                };
+            },
+            async: { confirmation: 'completed' },
+        },
+        {
+            kind: 'flight:startMission',
+            description: 'Start an uploaded mission that matches the authorized envelope digest.',
+            version: 1,
+            capability: 'industrial:action',
+            effect: 'write',
+            protocol: profile_js_1.MAVLINK_PROTOCOL,
+            errorTaxonomy: taxonomy,
+            schema: {
+                parameters: [
+                    { name: 'missionId', type: 'string', required: true, description: 'Autopilot mission id.' },
+                    { name: 'envelopeDigest', type: 'string', required: true, description: 'Authorized envelope digest.' },
+                    ...envelopeParameters(),
+                ],
+                context: [],
+            },
+            policy: { failureMode: 'fail-safe', timeoutMs: 30000 },
+            safeState: async () => {
+                await transport.returnToLaunch();
+                return { ok: true };
+            },
+            async prepare(params) {
+                const envelope = envelopeFrom(params);
+                const digest = (0, envelope_js_1.envelopeDigest)(envelope);
+                (0, transport_js_1.assertEnvelopeBinding)(envelope, stringParameter(params.envelopeDigest));
+                return {
+                    resourceId: resourceFor(envelope.vehicle),
+                    command: {
+                        action: 'startMission',
+                        missionId: stringParameter(params.missionId),
+                        envelopeDigest: digest,
+                        envelope,
+                    },
+                };
+            },
+            deriveEffects(op) {
+                const command = op.command;
+                return (0, effects_js_1.deriveFlightEffects)({
+                    resource: resourceFor(command.envelope.vehicle),
+                    maxSpeedMetresPerSecond: command.envelope.maxSpeedMetresPerSecond,
+                    maxDurationSeconds: command.envelope.maxDurationSeconds,
+                    envelopeId: command.envelope.envelopeId,
+                    envelopeDigest: command.envelopeDigest,
+                });
+            },
+            async actuate(op) {
+                const command = op.command;
+                await transport.startMission({
+                    missionId: command.missionId,
+                    envelopeDigest: command.envelopeDigest,
+                });
+                return { ok: true, data: { missionId: command.missionId, envelopeDigest: command.envelopeDigest } };
+            },
+            async: {
+                confirmation: 'accepted',
+                async reconcile(op) {
+                    const command = op.command;
+                    const telemetry = await transport.readTelemetry();
+                    const final = command.envelope.waypoints.at(-1);
+                    const handle = { missionId: command.missionId };
+                    if (final && (0, envelope_js_1.distanceMetres)({ latitudeDeg: telemetry.latitudeDeg, longitudeDeg: telemetry.longitudeDeg, altitudeMetres: telemetry.altitudeMetres }, final) <= arrivalTolerance) {
+                        return {
+                            status: 'confirmed',
+                            handle,
+                            progress: { fraction: 1, detail: 'arrived at final waypoint', at: Date.now() },
+                            result: { telemetry },
+                        };
+                    }
+                    const fraction = typeof telemetry.waypointIndex === 'number' && command.envelope.waypoints.length > 0
+                        ? Math.min(1, telemetry.waypointIndex / command.envelope.waypoints.length)
+                        : undefined;
+                    return {
+                        status: 'running',
+                        handle,
+                        progress: {
+                            ...(fraction !== undefined ? { fraction } : {}),
+                            detail: `en route${typeof telemetry.waypointIndex === 'number' ? ` (waypoint ${telemetry.waypointIndex})` : ''}`,
+                            at: Date.now(),
+                        },
+                    };
+                },
+                async cancel() {
+                    await transport.hold();
+                    await transport.returnToLaunch();
+                },
+            },
+        },
+        {
+            kind: 'flight:hold',
+            description: 'Hold position; the autopilot remains in control.',
+            version: 1,
+            capability: 'industrial:action',
+            effect: 'write',
+            protocol: profile_js_1.MAVLINK_PROTOCOL,
+            errorTaxonomy: taxonomy,
+            schema: { parameters: [], context: [] },
+            policy: { failureMode: 'fail-safe', timeoutMs: 15000 },
+            safeState: async () => {
+                await transport.returnToLaunch();
+                return { ok: true };
+            },
+            async prepare() {
+                return { command: { action: 'hold' } };
+            },
+            deriveEffects() {
+                return { spends: [], physical: { speed: [] } };
+            },
+            async actuate() {
+                await transport.hold();
+                return { ok: true };
+            },
+            async: {
+                confirmation: 'accepted',
+                async reconcile() {
+                    const telemetry = await transport.readTelemetry();
+                    const stopped = telemetryConfirmed(telemetry, (snapshot) => snapshot.groundspeedMetresPerSecond <= 0.2);
+                    return stopped
+                        ? { status: 'confirmed', progress: { fraction: 1, detail: 'vehicle holding', at: Date.now() } }
+                        : { status: 'running', progress: { detail: 'slowing to hold', at: Date.now() } };
+                },
+                async cancel() {
+                    await transport.returnToLaunch();
+                },
+            },
+        },
+        {
+            kind: 'flight:returnToLaunch',
+            description: 'Return to launch; completion is observed from telemetry.',
+            version: 1,
+            capability: 'industrial:action',
+            effect: 'write',
+            protocol: profile_js_1.MAVLINK_PROTOCOL,
+            errorTaxonomy: taxonomy,
+            schema: { parameters: [], context: [] },
+            policy: { failureMode: 'fail-safe', timeoutMs: 15000 },
+            safeState: async () => {
+                await transport.land();
+                return { ok: true };
+            },
+            async prepare() {
+                return { command: { action: 'returnToLaunch' } };
+            },
+            deriveEffects() {
+                return { spends: [] };
+            },
+            async actuate() {
+                await transport.returnToLaunch();
+                return { ok: true };
+            },
+            async: {
+                confirmation: 'accepted',
+                async reconcile() {
+                    const telemetry = await transport.readTelemetry();
+                    const home = telemetry.missionFinished === true && telemetry.groundspeedMetresPerSecond <= 0.5;
+                    return home
+                        ? { status: 'confirmed', progress: { fraction: 1, detail: 'returned to launch', at: Date.now() } }
+                        : { status: 'running', progress: { detail: 'returning to launch', at: Date.now() } };
+                },
+                async cancel() {
+                    await transport.land();
+                },
+            },
+        },
+        {
+            kind: 'flight:land',
+            description: 'Land at the current position.',
+            version: 1,
+            capability: 'industrial:action',
+            effect: 'write',
+            protocol: profile_js_1.MAVLINK_PROTOCOL,
+            errorTaxonomy: taxonomy,
+            schema: { parameters: [], context: [] },
+            policy: { failureMode: 'fail-safe', timeoutMs: 15000 },
+            safeState: async () => {
+                await transport.land();
+                return { ok: true };
+            },
+            async prepare() {
+                return { command: { action: 'land' } };
+            },
+            deriveEffects() {
+                return { spends: [] };
+            },
+            async actuate() {
+                await transport.land();
+                return { ok: true };
+            },
+            async: {
+                confirmation: 'accepted',
+                async reconcile() {
+                    const telemetry = await transport.readTelemetry();
+                    return telemetry.armed === false
+                        ? { status: 'confirmed', progress: { fraction: 1, detail: 'landed and disarmed', at: Date.now() } }
+                        : { status: 'running', progress: { detail: 'landing', at: Date.now() } };
+                },
+                async cancel() {
+                    throw new transport_js_1.MavlinkTransportError('Unsupported', 'a landing cannot be cancelled; command return-to-launch from the operator console');
+                },
+            },
+        },
+        {
+            kind: 'flight:readTelemetry',
+            description: 'Read the vehicle telemetry snapshot used for reconciliation.',
+            version: 1,
+            capability: 'industrial:read',
+            effect: 'read',
+            protocol: profile_js_1.MAVLINK_PROTOCOL,
+            errorTaxonomy: taxonomy,
+            schema: { parameters: [], context: [] },
+            async prepare() {
+                return { command: { action: 'readTelemetry' } };
+            },
+            deriveEffects() {
+                return { spends: [] };
+            },
+            async actuate() {
+                return { ok: true, data: await transport.readTelemetry() };
+            },
+        },
+    ];
+    return definitions;
+}

package/dist/cjs/conformance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * RFC-025 §5.8 — autopilot conformance harness.
+ *
+ * Each supported autopilot (and each simulator) must pass these checks before
+ * it is offered in the catalogue. A second autopilot is added as a separate,
+ * tested profile — never by loosening the first.
+ */
+import { type MissionEnvelope } from './envelope.js';
+import type { FlightVehicle } from './profile.js';
+import type { MavlinkTransportPort } from './transport.js';
+export interface MavlinkConformanceCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface MavlinkConformanceReport {
+    vehicle: string;
+    ok: boolean;
+    checks: MavlinkConformanceCheck[];
+}
+export interface MavlinkConformanceOptions {
+    site: string;
+    vehicles: readonly FlightVehicle[];
+    envelope: MissionEnvelope;
+    /** Distance from the final waypoint that counts as arrival. */
+    arrivalToleranceMetres?: number;
+}
+export declare function runMavlinkConformance(transport: MavlinkTransportPort, options: MavlinkConformanceOptions): Promise<MavlinkConformanceReport>;

package/dist/cjs/conformance.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * RFC-025 §5.8 — autopilot conformance harness.
+ *
+ * Each supported autopilot (and each simulator) must pass these checks before
+ * it is offered in the catalogue. A second autopilot is added as a separate,
+ * tested profile — never by loosening the first.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMavlinkConformance = runMavlinkConformance;
+const adapter_js_1 = require("./adapter.js");
+const envelope_js_1 = require("./envelope.js");
+async function runMavlinkConformance(transport, options) {
+    const checks = [];
+    const push = (name, ok, detail) => {
+        checks.push({ name, ok, ...(detail !== undefined ? { detail } : {}) });
+    };
+    const structural = (0, envelope_js_1.validateMissionEnvelope)(options.envelope);
+    push('envelope-valid', structural.length === 0, structural.join('; ') || undefined);
+    const outside = options.envelope.geofence
+        ? (0, envelope_js_1.validateMissionEnvelope)({
+            ...options.envelope,
+            waypoints: [
+                {
+                    latitudeDeg: options.envelope.geofence.latitudeDeg + 1,
+                    longitudeDeg: options.envelope.geofence.longitudeDeg,
+                    altitudeMetres: 0,
+                },
+            ],
+        })
+        : ['no geofence declared'];
+    push('geofence-rejection', outside.length > 0, outside.join('; ') || undefined);
+    const definitions = (0, adapter_js_1.createMavlinkDefinitions)({
+        transport,
+        site: options.site,
+        vehicles: options.vehicles,
+        ...(options.arrivalToleranceMetres !== undefined
+            ? { arrivalToleranceMetres: options.arrivalToleranceMetres }
+            : {}),
+    });
+    const upload = definitions.find((def) => def.kind === 'flight:uploadMission');
+    const start = definitions.find((def) => def.kind === 'flight:startMission');
+    if (!upload || !start) {
+        push('definitions-present', false, 'upload/start definitions missing');
+        return { vehicle: options.envelope.vehicle, ok: false, checks };
+    }
+    const uploadParams = paramsFromEnvelope(options.envelope);
+    const preparedUpload = await upload.prepare(uploadParams, {});
+    const uploaded = await upload.actuate(asPrepared(preparedUpload));
+    const missionId = uploaded.data?.missionId;
+    push('mission-upload', uploaded.ok && typeof missionId === 'string', missionId ?? uploaded.error);
+    const digest = (0, envelope_js_1.envelopeDigest)(options.envelope);
+    push('envelope-binding', uploaded.data?.envelopeDigest === digest, 'upload data must carry the authorized digest');
+    if (typeof missionId !== 'string') {
+        return { vehicle: options.envelope.vehicle, ok: checks.every((check) => check.ok), checks };
+    }
+    const preparedStart = await start.prepare({ ...uploadParams, missionId, envelopeDigest: digest }, {});
+    const started = await start.actuate(asPrepared(preparedStart));
+    push('mission-start', started.ok, started.error);
+    const telemetry = await transport.readTelemetry();
+    push('telemetry-shape', Number.isFinite(telemetry.latitudeDeg) &&
+        Number.isFinite(telemetry.longitudeDeg) &&
+        Number.isFinite(telemetry.altitudeMetres) &&
+        Number.isFinite(telemetry.groundspeedMetresPerSecond) &&
+        typeof telemetry.timestamp === 'string', telemetry.timestamp);
+    // Acceptance is not completion: unless the vehicle is already at the final
+    // waypoint, reconciliation must not report `confirmed`.
+    if (start.async?.reconcile) {
+        const progress = await start.async.reconcile(asPrepared(preparedStart), {
+            operationId: 'conformance',
+            status: 'accepted',
+            attempts: 1,
+            updatedAt: Date.now(),
+            result: started.data,
+        });
+        const final = options.envelope.waypoints.at(-1);
+        const arrived = final
+            ? (0, envelope_js_1.distanceMetres)({
+                latitudeDeg: telemetry.latitudeDeg,
+                longitudeDeg: telemetry.longitudeDeg,
+                altitudeMetres: telemetry.altitudeMetres,
+            }, final) <= (options.arrivalToleranceMetres ?? 15)
+            : false;
+        push('acceptance-is-not-completion', arrived ? progress.status === 'confirmed' : progress.status !== 'confirmed', `telemetry arrival=${arrived}, reconcile=${progress.status}`);
+    }
+    push('safe-state-available', transport.returnToLaunch instanceof Function, 'return-to-launch must be available for fail-safe');
+    return { vehicle: options.envelope.vehicle, ok: checks.every((check) => check.ok), checks };
+}
+function asPrepared(prepared) {
+    return {
+        kind: 'conformance',
+        resourceId: prepared.resourceId,
+        command: prepared.command,
+        definitionVersion: 1,
+        schemaHash: 'conformance',
+        preparedCommandHash: 'conformance',
+        parameters: {},
+        context: {},
+        commitmentHash: 'conformance',
+        operationId: 'conformance',
+    };
+}
+function paramsFromEnvelope(envelope) {
+    return {
+        envelopeId: envelope.envelopeId,
+        vehicle: envelope.vehicle,
+        waypoints: envelope.waypoints,
+        maxAltitudeMetres: { value: Number(envelope.maxAltitudeMetres), unit: 'm' },
+        maxSpeedMetresPerSecond: {
+            value: Number(envelope.maxSpeedMetresPerSecond),
+            unit: 'm/s',
+        },
+        maxDurationSeconds: { value: Number(envelope.maxDurationSeconds), unit: 's' },
+        ...(envelope.geofence
+            ? {
+                geofenceLatitudeDeg: envelope.geofence.latitudeDeg,
+                geofenceLongitudeDeg: envelope.geofence.longitudeDeg,
+                geofenceRadiusMetres: envelope.geofence.radiusMetres,
+            }
+            : {}),
+    };
+}

package/dist/cjs/effects.d.ts

@@ -0,0 +1,16 @@
+/**
+ * RFC-025 §5.5 — physical effects derived from the PREPARED mission command.
+ *
+ * Speed and duration are ceilings; the envelope reference binds the receipt to
+ * the exact plan that was authorized.
+ */
+import type { StepEffects } from '@totemsdk/agent-policy';
+export interface FlightLimits {
+    /** Vehicle ResourceId key. */
+    resource: string;
+    maxSpeedMetresPerSecond: string;
+    maxDurationSeconds: string;
+    envelopeId: string;
+    envelopeDigest: string;
+}
+export declare function deriveFlightEffects(limits: FlightLimits): StepEffects;

package/dist/cjs/effects.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * RFC-025 §5.5 — physical effects derived from the PREPARED mission command.
+ *
+ * Speed and duration are ceilings; the envelope reference binds the receipt to
+ * the exact plan that was authorized.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveFlightEffects = deriveFlightEffects;
+function deriveFlightEffects(limits) {
+    return {
+        spends: [],
+        physical: {
+            speed: [{ resource: limits.resource, metresPerSecond: limits.maxSpeedMetresPerSecond }],
+            duration: [{ resource: limits.resource, seconds: limits.maxDurationSeconds }],
+            envelopes: [{ envelopeId: limits.envelopeId, envelopeDigest: limits.envelopeDigest }],
+        },
+    };
+}

package/dist/cjs/envelope.d.ts

@@ -0,0 +1,38 @@
+/**
+ * RFC-025 §5.5 — mission envelope.
+ *
+ * The envelope is the unit of authority: `uploadMission` prepares and commits
+ * it, `startMission` is authorized against its digest, and RFC-023 enforces its
+ * speed/duration/altitude bounds from the prepared command. A start that
+ * references a different plan than the one authorized fails closed.
+ */
+export interface Waypoint {
+    latitudeDeg: number;
+    longitudeDeg: number;
+    altitudeMetres: number;
+}
+export interface Geofence {
+    latitudeDeg: number;
+    longitudeDeg: number;
+    radiusMetres: number;
+}
+export interface MissionEnvelope {
+    envelopeId: string;
+    /** ResourceId key of the target vehicle. */
+    vehicle: string;
+    waypoints: readonly Waypoint[];
+    /** Altitude ceiling, in metres (decimal string). */
+    maxAltitudeMetres: string;
+    /** Ground-speed ceiling, in m/s (decimal string). */
+    maxSpeedMetresPerSecond: string;
+    /** Mission wall-clock ceiling, in seconds (decimal string). */
+    maxDurationSeconds: string;
+    geofence?: Geofence;
+}
+/** Great-circle distance between two WGS-84 points, in metres. */
+export declare function distanceMetres(a: Waypoint, b: Waypoint): number;
+/** Canonical digest of the authorized plan. */
+export declare function envelopeDigest(envelope: MissionEnvelope): string;
+/** Structural and physical validation; returns human-readable issues. */
+export declare function validateMissionEnvelope(envelope: MissionEnvelope): string[];
+export declare function assertValidMissionEnvelope(envelope: MissionEnvelope): void;