@totemsdk/act-mavlink 0.0.0-stage → 0.1.1

package/dist/cjs/envelope.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.distanceMetres = distanceMetres;
+exports.envelopeDigest = envelopeDigest;
+exports.validateMissionEnvelope = validateMissionEnvelope;
+exports.assertValidMissionEnvelope = assertValidMissionEnvelope;
+const act_core_1 = require("@totemsdk/act-core");
+const EARTH_RADIUS_METRES = 6371000;
+/** Great-circle distance between two WGS-84 points, in metres. */
+function distanceMetres(a, b) {
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(b.latitudeDeg - a.latitudeDeg);
+    const dLon = toRad(b.longitudeDeg - a.longitudeDeg);
+    const lat1 = toRad(a.latitudeDeg);
+    const lat2 = toRad(b.latitudeDeg);
+    const h = Math.sin(dLat / 2) ** 2 +
+        Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+    return 2 * EARTH_RADIUS_METRES * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+/** Canonical digest of the authorized plan. */
+function envelopeDigest(envelope) {
+    return (0, act_core_1.hashCanonical)('TOTEM_ACT_MAVLINK_MISSION_ENVELOPE_V1', {
+        envelopeId: envelope.envelopeId,
+        vehicle: envelope.vehicle,
+        waypoints: envelope.waypoints.map((waypoint) => ({
+            latitudeDeg: waypoint.latitudeDeg,
+            longitudeDeg: waypoint.longitudeDeg,
+            altitudeMetres: waypoint.altitudeMetres,
+        })),
+        maxAltitudeMetres: envelope.maxAltitudeMetres,
+        maxSpeedMetresPerSecond: envelope.maxSpeedMetresPerSecond,
+        maxDurationSeconds: envelope.maxDurationSeconds,
+        geofence: envelope.geofence
+            ? {
+                latitudeDeg: envelope.geofence.latitudeDeg,
+                longitudeDeg: envelope.geofence.longitudeDeg,
+                radiusMetres: envelope.geofence.radiusMetres,
+            }
+            : null,
+    });
+}
+function positive(value) {
+    return Number.isFinite(Number(value)) && Number(value) > 0;
+}
+/** Structural and physical validation; returns human-readable issues. */
+function validateMissionEnvelope(envelope) {
+    const issues = [];
+    if (envelope.envelopeId.trim() === '')
+        issues.push('envelopeId is required');
+    if (envelope.vehicle.trim() === '')
+        issues.push('vehicle is required');
+    if (envelope.waypoints.length === 0)
+        issues.push('at least one waypoint is required');
+    if (envelope.waypoints.length > 100)
+        issues.push('mission exceeds the 100-waypoint limit');
+    if (!positive(envelope.maxAltitudeMetres))
+        issues.push('maxAltitudeMetres must be positive');
+    if (!positive(envelope.maxSpeedMetresPerSecond))
+        issues.push('maxSpeedMetresPerSecond must be positive');
+    if (!positive(envelope.maxDurationSeconds))
+        issues.push('maxDurationSeconds must be positive');
+    const maxAltitude = Number(envelope.maxAltitudeMetres);
+    for (const [index, waypoint] of envelope.waypoints.entries()) {
+        if (!Number.isFinite(waypoint.latitudeDeg) || waypoint.latitudeDeg < -90 || waypoint.latitudeDeg > 90) {
+            issues.push(`waypoint ${index} latitude is out of range`);
+        }
+        if (!Number.isFinite(waypoint.longitudeDeg) || waypoint.longitudeDeg < -180 || waypoint.longitudeDeg > 180) {
+            issues.push(`waypoint ${index} longitude is out of range`);
+        }
+        if (!Number.isFinite(waypoint.altitudeMetres) || waypoint.altitudeMetres < 0) {
+            issues.push(`waypoint ${index} altitude is invalid`);
+        }
+        else if (waypoint.altitudeMetres > maxAltitude) {
+            issues.push(`waypoint ${index} altitude ${waypoint.altitudeMetres} m exceeds the envelope ceiling ${maxAltitude} m`);
+        }
+        if (envelope.geofence) {
+            const distance = distanceMetres({ latitudeDeg: envelope.geofence.latitudeDeg, longitudeDeg: envelope.geofence.longitudeDeg, altitudeMetres: 0 }, waypoint);
+            if (distance > envelope.geofence.radiusMetres) {
+                issues.push(`waypoint ${index} is ${Math.round(distance)} m from the geofence centre (limit ${envelope.geofence.radiusMetres} m)`);
+            }
+        }
+    }
+    return issues;
+}
+function assertValidMissionEnvelope(envelope) {
+    const issues = validateMissionEnvelope(envelope);
+    if (issues.length > 0) {
+        throw new Error(`invalid mission envelope '${envelope.envelopeId}': ${issues.join('; ')}`);
+    }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * RFC-025 — governed MAVLink / autonomous flight profile.
+ *
+ * `@totemsdk/act-mavlink` authorizes a bounded mission envelope; the connector
+ * (`@totemsdk/edge-mavlink`) carries the wire frames and the autopilot owns
+ * stabilization, failsafes and the real-time loop.
+ */
+export { MavlinkTransportError, assertEnvelopeBinding, } from './transport.js';
+export type { MavlinkTransportPort, MissionStartRequest, MissionUploadRequest, MissionUploadResult, TelemetrySnapshot, } from './transport.js';
+export { assertValidMissionEnvelope, distanceMetres, envelopeDigest, validateMissionEnvelope, } from './envelope.js';
+export type { Geofence, MissionEnvelope, Waypoint } from './envelope.js';
+export { deriveFlightEffects } from './effects.js';
+export type { FlightLimits } from './effects.js';
+export { MAVLINK_PROTOCOL, createMavlinkProfile, mavlinkErrorTaxonomy, vehicleInterlocks, vehicleResource, vehicleResourceId, } from './profile.js';
+export type { FlightVehicle, MavlinkProfileOptions } from './profile.js';
+export { createMavlinkDefinitions } from './adapter.js';
+export type { MavlinkAdapterOptions } from './adapter.js';
+export { runMavlinkConformance } from './conformance.js';
+export type { MavlinkConformanceCheck, MavlinkConformanceOptions, MavlinkConformanceReport, } from './conformance.js';

package/dist/cjs/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * RFC-025 — governed MAVLink / autonomous flight profile.
+ *
+ * `@totemsdk/act-mavlink` authorizes a bounded mission envelope; the connector
+ * (`@totemsdk/edge-mavlink`) carries the wire frames and the autopilot owns
+ * stabilization, failsafes and the real-time loop.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMavlinkConformance = exports.createMavlinkDefinitions = exports.vehicleResourceId = exports.vehicleResource = exports.vehicleInterlocks = exports.mavlinkErrorTaxonomy = exports.createMavlinkProfile = exports.MAVLINK_PROTOCOL = exports.deriveFlightEffects = exports.validateMissionEnvelope = exports.envelopeDigest = exports.distanceMetres = exports.assertValidMissionEnvelope = exports.assertEnvelopeBinding = exports.MavlinkTransportError = void 0;
+var transport_js_1 = require("./transport.js");
+Object.defineProperty(exports, "MavlinkTransportError", { enumerable: true, get: function () { return transport_js_1.MavlinkTransportError; } });
+Object.defineProperty(exports, "assertEnvelopeBinding", { enumerable: true, get: function () { return transport_js_1.assertEnvelopeBinding; } });
+var envelope_js_1 = require("./envelope.js");
+Object.defineProperty(exports, "assertValidMissionEnvelope", { enumerable: true, get: function () { return envelope_js_1.assertValidMissionEnvelope; } });
+Object.defineProperty(exports, "distanceMetres", { enumerable: true, get: function () { return envelope_js_1.distanceMetres; } });
+Object.defineProperty(exports, "envelopeDigest", { enumerable: true, get: function () { return envelope_js_1.envelopeDigest; } });
+Object.defineProperty(exports, "validateMissionEnvelope", { enumerable: true, get: function () { return envelope_js_1.validateMissionEnvelope; } });
+var effects_js_1 = require("./effects.js");
+Object.defineProperty(exports, "deriveFlightEffects", { enumerable: true, get: function () { return effects_js_1.deriveFlightEffects; } });
+var profile_js_1 = require("./profile.js");
+Object.defineProperty(exports, "MAVLINK_PROTOCOL", { enumerable: true, get: function () { return profile_js_1.MAVLINK_PROTOCOL; } });
+Object.defineProperty(exports, "createMavlinkProfile", { enumerable: true, get: function () { return profile_js_1.createMavlinkProfile; } });
+Object.defineProperty(exports, "mavlinkErrorTaxonomy", { enumerable: true, get: function () { return profile_js_1.mavlinkErrorTaxonomy; } });
+Object.defineProperty(exports, "vehicleInterlocks", { enumerable: true, get: function () { return profile_js_1.vehicleInterlocks; } });
+Object.defineProperty(exports, "vehicleResource", { enumerable: true, get: function () { return profile_js_1.vehicleResource; } });
+Object.defineProperty(exports, "vehicleResourceId", { enumerable: true, get: function () { return profile_js_1.vehicleResourceId; } });
+var adapter_js_1 = require("./adapter.js");
+Object.defineProperty(exports, "createMavlinkDefinitions", { enumerable: true, get: function () { return adapter_js_1.createMavlinkDefinitions; } });
+var conformance_js_1 = require("./conformance.js");
+Object.defineProperty(exports, "runMavlinkConformance", { enumerable: true, get: function () { return conformance_js_1.runMavlinkConformance; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/profile.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RFC-025 §5.4 / §5.9 — MAVLink flight profile.
+ *
+ * The vehicle is an asset addressed at its autopilot. Safe state is
+ * return-to-launch (a `fail-safe` in flight must never command a de-energize
+ * analogue). Interlocks enforce the vehicle's declared ceilings before
+ * authorization; safety-coded errors require the safe state and never retry.
+ */
+import { type DeviceErrorTaxonomy, type IndustrialProfile, type Interlock, type Resource, type ResourceId } from '@totemsdk/act-core';
+import { type MissionEnvelope } from './envelope.js';
+export declare const MAVLINK_PROTOCOL = "mavlink";
+export interface FlightVehicle {
+    vehicleId: string;
+    /** Ground-speed ceiling, in m/s (decimal string). */
+    maxSpeedMetresPerSecond: string;
+    /** Altitude ceiling, in metres (decimal string). */
+    maxAltitudeMetres: string;
+    /** Mission duration ceiling, in seconds (decimal string). */
+    maxDurationSeconds: string;
+    /** MAVLink addressing. */
+    systemId?: number;
+    componentId?: number;
+}
+export declare function vehicleResourceId(site: string, vehicleId: string): ResourceId;
+export declare function vehicleResource(site: string, vehicle: FlightVehicle): Resource;
+/** Interlocks enforcing the vehicle's declared envelope ceilings. */
+export declare function vehicleInterlocks(site: string, vehicle: FlightVehicle): Interlock[];
+/** MAVLink result codes → device error classification (RFC-011 §4.7). */
+export declare function mavlinkErrorTaxonomy(): DeviceErrorTaxonomy;
+export interface MavlinkProfileOptions {
+    site: string;
+    vehicles: readonly FlightVehicle[];
+}
+/** Data-only flight profile (definitions are supplied by the adapter). */
+export declare function createMavlinkProfile(options: MavlinkProfileOptions): IndustrialProfile;
+export type { MissionEnvelope };

package/dist/cjs/profile.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * RFC-025 §5.4 / §5.9 — MAVLink flight profile.
+ *
+ * The vehicle is an asset addressed at its autopilot. Safe state is
+ * return-to-launch (a `fail-safe` in flight must never command a de-energize
+ * analogue). Interlocks enforce the vehicle's declared ceilings before
+ * authorization; safety-coded errors require the safe state and never retry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAVLINK_PROTOCOL = void 0;
+exports.vehicleResourceId = vehicleResourceId;
+exports.vehicleResource = vehicleResource;
+exports.vehicleInterlocks = vehicleInterlocks;
+exports.mavlinkErrorTaxonomy = mavlinkErrorTaxonomy;
+exports.createMavlinkProfile = createMavlinkProfile;
+const act_core_1 = require("@totemsdk/act-core");
+const envelope_js_1 = require("./envelope.js");
+exports.MAVLINK_PROTOCOL = 'mavlink';
+function vehicleResourceId(site, vehicleId) {
+    return { site, area: 'flight', asset: vehicleId, point: 'autopilot' };
+}
+function vehicleResource(site, vehicle) {
+    const id = vehicleResourceId(site, vehicle.vehicleId);
+    return {
+        id,
+        kind: 'controller',
+        addresses: [
+            {
+                protocol: exports.MAVLINK_PROTOCOL,
+                endpoint: `system:${vehicle.systemId ?? 1}/component:${vehicle.componentId ?? 1}`,
+            },
+        ],
+        // Hold/land/return are deployment policy; return-to-launch is the default
+        // safe state. Never de-energize an airborne vehicle.
+        safeState: {
+            resourceId: id,
+            command: { action: 'flight:returnToLaunch' },
+        },
+        metadata: {
+            vehicleId: vehicle.vehicleId,
+            maxSpeedMetresPerSecond: vehicle.maxSpeedMetresPerSecond,
+            maxAltitudeMetres: vehicle.maxAltitudeMetres,
+            maxDurationSeconds: vehicle.maxDurationSeconds,
+        },
+    };
+}
+function numeric(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+        return Number(value);
+    }
+    if (value && typeof value === 'object' && 'value' in value) {
+        return numeric(value.value);
+    }
+    return undefined;
+}
+function ceilingInterlock(site, vehicle, id, parameter, ceiling, unit) {
+    const resourceId = vehicleResourceId(site, vehicle.vehicleId);
+    return {
+        id,
+        kind: 'precondition',
+        resources: [resourceId],
+        safeState: { resourceId, command: { action: 'flight:returnToLaunch' } },
+        evaluate({ parameters }) {
+            const requested = numeric(parameters[parameter]);
+            if (requested === undefined)
+                return { satisfied: true };
+            return requested <= Number(ceiling)
+                ? { satisfied: true }
+                : { satisfied: false, reason: `requested ${requested} ${unit} exceeds vehicle ceiling ${ceiling} ${unit}` };
+        },
+    };
+}
+/** Interlocks enforcing the vehicle's declared envelope ceilings. */
+function vehicleInterlocks(site, vehicle) {
+    const resourceId = vehicleResourceId(site, vehicle.vehicleId);
+    const interlocks = [
+        ceilingInterlock(site, vehicle, `mavlink:speed-ceiling:${vehicle.vehicleId}`, 'maxSpeedMetresPerSecond', vehicle.maxSpeedMetresPerSecond, 'm/s'),
+        ceilingInterlock(site, vehicle, `mavlink:altitude-ceiling:${vehicle.vehicleId}`, 'maxAltitudeMetres', vehicle.maxAltitudeMetres, 'm'),
+        ceilingInterlock(site, vehicle, `mavlink:duration-ceiling:${vehicle.vehicleId}`, 'maxDurationSeconds', vehicle.maxDurationSeconds, 's'),
+    ];
+    // Geofence containment is dynamic: it depends on the waypoints in the
+    // prepared request, not only on scalar ceilings.
+    interlocks.push({
+        id: `mavlink:geofence:${vehicle.vehicleId}`,
+        kind: 'precondition',
+        resources: [resourceId],
+        safeState: { resourceId, command: { action: 'flight:returnToLaunch' } },
+        evaluate({ parameters }) {
+            const latitude = numeric(parameters.geofenceLatitudeDeg);
+            const longitude = numeric(parameters.geofenceLongitudeDeg);
+            const radius = numeric(parameters.geofenceRadiusMetres);
+            if (latitude === undefined || longitude === undefined || radius === undefined) {
+                return { satisfied: true };
+            }
+            const waypoints = parameters.waypoints;
+            if (!Array.isArray(waypoints))
+                return { satisfied: true };
+            for (const [index, waypoint] of waypoints.entries()) {
+                const candidate = waypoint;
+                const distance = (0, envelope_js_1.distanceMetres)({ latitudeDeg: latitude, longitudeDeg: longitude, altitudeMetres: 0 }, candidate);
+                if (distance > radius) {
+                    return {
+                        satisfied: false,
+                        reason: `waypoint ${index} is ${Math.round(distance)} m from the geofence centre (limit ${radius} m)`,
+                    };
+                }
+            }
+            return { satisfied: true };
+        },
+    });
+    return interlocks;
+}
+/** MAVLink result codes → device error classification (RFC-011 §4.7). */
+function mavlinkErrorTaxonomy() {
+    const taxonomy = (0, act_core_1.createDeviceErrorTaxonomy)();
+    const classes = {
+        // Failsafe/geofence conditions require the safe state and never retry.
+        GEOFENCE_BREACH: 'safety',
+        FAILSAFE_TRIGGERED: 'safety',
+        BATTERY_LOW: 'safety',
+        CRITICAL_BATTERY: 'safety',
+        // Mission/protocol rejection — retrying the same plan cannot succeed.
+        MAV_MISSION_ERROR: 'permanent',
+        MAV_MISSION_UNSUPPORTED: 'permanent',
+        MAV_MISSION_UNSUPPORTED_FRAME: 'permanent',
+        MAV_MISSION_NO_SPACE: 'permanent',
+        MAV_MISSION_INVALID: 'permanent',
+        MAV_MISSION_INVALID_PARAM1: 'permanent',
+        MAV_MISSION_INVALID_PARAM2: 'permanent',
+        MAV_MISSION_INVALID_PARAM3: 'permanent',
+        MAV_MISSION_INVALID_PARAM4: 'permanent',
+        MAV_MISSION_INVALID_PARAM5_X: 'permanent',
+        MAV_MISSION_INVALID_PARAM6_Y: 'permanent',
+        MAV_MISSION_INVALID_PARAM7: 'permanent',
+        MAV_MISSION_DENIED: 'auth',
+        MAV_RESULT_UNSUPPORTED: 'permanent',
+        MAV_RESULT_FAILED: 'permanent',
+        MAV_RESULT_CANCELLED: 'permanent',
+        // Link/transport — retry under the same operation id is safe.
+        LINK_TIMEOUT: 'transient',
+        MAV_RESULT_IN_PROGRESS: 'transient',
+        TIMEOUT: 'transient',
+        // Authorization.
+        AUTHORIZATION_DENIED: 'auth',
+        ENVELOPE_MISMATCH: 'auth',
+    };
+    for (const [code, classification] of Object.entries(classes)) {
+        taxonomy.register(exports.MAVLINK_PROTOCOL, code, classification);
+    }
+    return taxonomy;
+}
+/** Data-only flight profile (definitions are supplied by the adapter). */
+function createMavlinkProfile(options) {
+    return {
+        id: 'mavlink',
+        version: 1,
+        resources: options.vehicles.map((vehicle) => vehicleResource(options.site, vehicle)),
+        interlocks: options.vehicles.flatMap((vehicle) => vehicleInterlocks(options.site, vehicle)),
+        errorTaxonomy: mavlinkErrorTaxonomy(),
+        capabilities: ['industrial:action', 'industrial:read', 'transport:mavlink'],
+        recipes: [],
+        definitions: [],
+    };
+}

package/dist/cjs/transport.d.ts

@@ -0,0 +1,56 @@
+/**
+ * RFC-025 §5.2 — MAVLink transport port.
+ *
+ * The caller injects a MAVLink client (SDK, bridge, or simulator). This package
+ * owns mission authority, bounded execution and evidence; the autopilot owns
+ * stabilization, failsafes and the real-time loop.
+ *
+ * `startMission` carries the authorized envelope digest so a transport can
+ * refuse to start a mission that differs from the one that was authorized.
+ */
+import { type MissionEnvelope, type Waypoint } from './envelope.js';
+export interface MissionUploadRequest {
+    envelopeId: string;
+    envelopeDigest: string;
+    waypoints: readonly Waypoint[];
+}
+export interface MissionUploadResult {
+    /** Autopilot-assigned mission id (the reconciliation handle). */
+    missionId: string;
+}
+export interface MissionStartRequest {
+    missionId: string;
+    envelopeDigest: string;
+}
+export interface TelemetrySnapshot {
+    /** ISO-8601 timestamp from the autopilot. */
+    timestamp: string;
+    latitudeDeg: number;
+    longitudeDeg: number;
+    altitudeMetres: number;
+    groundspeedMetresPerSecond: number;
+    batteryPercent?: number;
+    waypointIndex?: number;
+    missionFinished?: boolean;
+    armed?: boolean;
+}
+export interface MavlinkTransportPort {
+    uploadMission(request: MissionUploadRequest): Promise<MissionUploadResult>;
+    startMission(request: MissionStartRequest): Promise<void>;
+    hold(): Promise<void>;
+    returnToLaunch(): Promise<void>;
+    land(): Promise<void>;
+    /** Telemetry readback used for reconciliation; must originate from the vehicle. */
+    readTelemetry(): Promise<TelemetrySnapshot>;
+    /** Optional push path for telemetry. */
+    onTelemetry?(handler: (telemetry: TelemetrySnapshot) => void): () => void;
+}
+export declare class MavlinkTransportError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * A start must reference the exact plan that was authorized. A digest that does
+ * not match the envelope fails closed before dispatch.
+ */
+export declare function assertEnvelopeBinding(envelope: MissionEnvelope, digest: string): void;

package/dist/cjs/transport.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * RFC-025 §5.2 — MAVLink transport port.
+ *
+ * The caller injects a MAVLink client (SDK, bridge, or simulator). This package
+ * owns mission authority, bounded execution and evidence; the autopilot owns
+ * stabilization, failsafes and the real-time loop.
+ *
+ * `startMission` carries the authorized envelope digest so a transport can
+ * refuse to start a mission that differs from the one that was authorized.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MavlinkTransportError = void 0;
+exports.assertEnvelopeBinding = assertEnvelopeBinding;
+const envelope_js_1 = require("./envelope.js");
+class MavlinkTransportError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'MavlinkTransportError';
+        this.code = code;
+    }
+}
+exports.MavlinkTransportError = MavlinkTransportError;
+/**
+ * A start must reference the exact plan that was authorized. A digest that does
+ * not match the envelope fails closed before dispatch.
+ */
+function assertEnvelopeBinding(envelope, digest) {
+    const expected = (0, envelope_js_1.envelopeDigest)(envelope);
+    if (digest !== expected) {
+        throw new MavlinkTransportError('EnvelopeMismatch', `envelope digest mismatch for '${envelope.envelopeId}' (authorized ${digest}, prepared ${expected})`);
+    }
+}

package/dist/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/conformance.js

@@ -0,0 +1,119 @@
+/**
+ * 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 { createMavlinkDefinitions } from './adapter.js';
+import { distanceMetres, envelopeDigest, validateMissionEnvelope, } from './envelope.js';
+export async function runMavlinkConformance(transport, options) {
+    const checks = [];
+    const push = (name, ok, detail) => {
+        checks.push({ name, ok, ...(detail !== undefined ? { detail } : {}) });
+    };
+    const structural = validateMissionEnvelope(options.envelope);
+    push('envelope-valid', structural.length === 0, structural.join('; ') || undefined);
+    const outside = options.envelope.geofence
+        ? 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 = 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 = 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
+            ? 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/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/effects.js

@@ -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.
+ */
+export 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 }],
+        },
+    };
+}