@totemsdk/spatial-proof 0.1.0

package/dist/proof.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Proof envelope integration for @totemsdk/spatial-proof.
+ *
+ * Bridges spatial objects and spatial relation claims into @totemsdk/proof
+ * evidence refs and signed proof envelopes. Signing/verification delegate to
+ * @totemsdk/proof. Anchoring is deliberately NOT required for verification.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spatialObjectToEvidenceRef = spatialObjectToEvidenceRef;
+exports.spatialRelationToEvidenceRef = spatialRelationToEvidenceRef;
+exports.spatialClaimEvidenceRefs = spatialClaimEvidenceRefs;
+exports.createUnsignedSpatialProof = createUnsignedSpatialProof;
+exports.signSpatialProof = signSpatialProof;
+exports.verifySpatialProof = verifySpatialProof;
+const proof_1 = require("@totemsdk/proof");
+const canonical_js_1 = require("./canonical.js");
+const claim_js_1 = require("./claim.js");
+/**
+ * Convert a SpatialObject into an EvidenceRef for inclusion in a proof.
+ */
+function spatialObjectToEvidenceRef(obj) {
+    return {
+        id: obj.spatialId,
+        kind: 'spatial-object',
+        hash: (0, canonical_js_1.hashSpatialObject)(obj),
+    };
+}
+/**
+ * Convert a SpatialRelationClaim into an EvidenceRef for inclusion in a proof.
+ */
+function spatialRelationToEvidenceRef(claim) {
+    return {
+        id: claim.relationId,
+        kind: 'spatial-relation',
+        hash: (0, canonical_js_1.hashSpatialRelationClaim)(claim),
+    };
+}
+/**
+ * Build the evidence ref list for a spatial proof.
+ *
+ * Always includes the relation claim hash and spatial object hash. Optionally
+ * adds the subject geometry hash, subject proof ID, location claim ID, and
+ * raster manifest ID when present on the claim.
+ */
+function spatialClaimEvidenceRefs(claim, obj, subjectGeometry) {
+    const refs = [spatialRelationToEvidenceRef(claim), spatialObjectToEvidenceRef(obj)];
+    if (claim.inputs.subjectGeometryHash) {
+        refs.push({
+            id: claim.inputs.subjectGeometryHash,
+            kind: 'geometry',
+            hash: subjectGeometry ? (0, canonical_js_1.computeGeometryHash)(subjectGeometry) : claim.inputs.subjectGeometryHash,
+        });
+    }
+    if (claim.inputs.subjectProofId) {
+        refs.push({ id: claim.inputs.subjectProofId, kind: 'proof', hash: claim.inputs.subjectProofId });
+    }
+    if (claim.inputs.locationClaimId) {
+        refs.push({ id: claim.inputs.locationClaimId, kind: 'location-claim', hash: claim.inputs.locationClaimId });
+    }
+    if (claim.inputs.rasterManifestId) {
+        refs.push({ id: claim.inputs.rasterManifestId, kind: 'manifest', hash: claim.inputs.rasterManifestId });
+    }
+    return refs;
+}
+/**
+ * Create an unsigned attestation proof for a spatial relation claim.
+ *
+ * The proof claims: "this subject relates to this spatial object in this way
+ * at this time, computed by this engine." It does NOT claim the relation is
+ * geodetically exact — approximation notes travel inside the claim result.
+ */
+function createUnsignedSpatialProof(params) {
+    const { claim, spatialObject } = params;
+    return (0, proof_1.createProof)({
+        kind: 'attestation',
+        subject: {
+            id: claim.subjectId,
+            kind: claim.subjectKind,
+            metadata: {
+                spatialRelationId: claim.relationId,
+                spatialObjectId: claim.spatialObjectId,
+            },
+        },
+        issuer: params.issuer ?? claim.subjectId,
+        issuedAt: params.issuedAt,
+        expiresAt: params.expiresAt,
+        evidence: spatialClaimEvidenceRefs(claim, spatialObject, params.subjectGeometry),
+        payload: { spatialRelation: claim },
+    });
+}
+/**
+ * Sign an unsigned spatial proof with a WOTS key.
+ *
+ * The caller is responsible for reserving the WOTS key index (see
+ * @totemsdk/wots-lease) before calling — one-time key warning applies.
+ */
+function signSpatialProof(unsigned, seed, keyIndex) {
+    return (0, proof_1.signProof)(unsigned, seed, keyIndex);
+}
+/**
+ * Verify a signed spatial proof end to end.
+ *
+ * Checks:
+ *   1. the underlying @totemsdk/proof verification (signature, proofId, expiry)
+ *   2. payload contains a structurally valid SpatialRelationClaim
+ *   3. the relation's claimId matches a recomputation from its fields
+ *   4. the relation evidence hash matches the payload claim
+ *   5. the spatial-object evidence hash matches the payload claim inputs
+ *   6. any subject geometry evidence hash is present when claimed
+ *
+ * Anchoring is not required.
+ */
+function verifySpatialProof(signed) {
+    const base = (0, proof_1.verifyProof)(signed);
+    if (!base.valid) {
+        return {
+            valid: false,
+            reason: base.reason,
+            signerAddress: base.signerAddress,
+        };
+    }
+    const signerAddress = signed.signature.address;
+    const claim = signed.payload?.['spatialRelation'];
+    if (!claim || typeof claim !== 'object') {
+        return { valid: false, reason: 'payload missing spatialRelation claim', signerAddress };
+    }
+    const validation = (0, claim_js_1.validateSpatialRelationClaim)(claim);
+    if (!validation.valid) {
+        return {
+            valid: false,
+            reason: 'payload spatialRelation invalid: ' + validation.errors.join('; '),
+            payloadValid: false,
+            signerAddress,
+        };
+    }
+    const { relationId: _relationId, ...rest } = claim;
+    const recomputedId = (0, canonical_js_1.computeSpatialRelationId)(rest);
+    if (recomputedId !== claim.relationId) {
+        return {
+            valid: false,
+            reason: 'relationId does not match recomputed value',
+            relationIdValid: false,
+            spatialObjectId: claim.spatialObjectId,
+            relationId: claim.relationId,
+            signerAddress,
+        };
+    }
+    const relationEvidence = signed.evidence?.find((e) => e.id === claim.relationId && e.kind === 'spatial-relation');
+    if (!relationEvidence) {
+        return {
+            valid: false,
+            reason: 'evidence missing spatial-relation ref',
+            spatialObjectId: claim.spatialObjectId,
+            relationId: claim.relationId,
+            signerAddress,
+        };
+    }
+    const expectedRelationHash = (0, canonical_js_1.hashSpatialRelationClaim)(claim);
+    if (relationEvidence.hash !== expectedRelationHash) {
+        return {
+            valid: false,
+            reason: 'evidence hash does not match payload claim',
+            evidenceHashValid: false,
+            spatialObjectId: claim.spatialObjectId,
+            relationId: claim.relationId,
+            signerAddress,
+        };
+    }
+    const objectEvidence = signed.evidence?.find((e) => e.id === claim.spatialObjectId && e.kind === 'spatial-object');
+    if (!objectEvidence) {
+        return {
+            valid: false,
+            reason: 'evidence missing spatial-object ref',
+            spatialObjectId: claim.spatialObjectId,
+            relationId: claim.relationId,
+            signerAddress,
+        };
+    }
+    return {
+        valid: true,
+        signerAddress,
+        spatialObjectId: claim.spatialObjectId,
+        relationId: claim.relationId,
+        payloadValid: true,
+        evidenceHashValid: true,
+        relationIdValid: true,
+    };
+}

package/dist/proofgraph.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Proofgraph integration helpers for @totemsdk/spatial-proof.
+ *
+ * Produces nodes and edges for @totemsdk/proofgraph without storage
+ * assumptions. Helpers never mutate a graph directly — callers combine the
+ * returned nodes/edges with addNode/addEdge.
+ *
+ * Note: @totemsdk/proofgraph has no native 'spatial' node type, so spatial
+ * objects and relation claims are mapped to the generic 'custom' node type
+ * (the same approach @totemsdk/location-proof uses). If a dedicated
+ * 'spatial-object' / 'spatial-relation' node type is ever wanted, propose it
+ * in @totemsdk/proofgraph (do not silently fork the vocabulary).
+ */
+import type { ProofGraph, ProofGraphNode, ProofGraphEdge } from '@totemsdk/proofgraph';
+import type { SpatialObject, SpatialRelationClaim } from './types.js';
+/**
+ * Build a ProofGraphNode for a spatial object.
+ *
+ * Uses the 'custom' node type (no native proofgraph node type fits a spatial
+ * object). Node ID is deterministic: "custom:<spatialId>".
+ */
+export declare function spatialObjectToProofGraphNode(obj: SpatialObject): ProofGraphNode;
+/**
+ * Build a ProofGraphNode for a spatial relation claim.
+ *
+ * Uses the 'custom' node type. Node ID is deterministic: "custom:<relationId>".
+ */
+export declare function spatialRelationToProofGraphNode(claim: SpatialRelationClaim): ProofGraphNode;
+/**
+ * Build ProofGraphEdges for a spatial relation claim:
+ *   about       relation → subject
+ *   references  relation → spatial object
+ *   derived_from relation → location claim (when present)
+ *   references  relation → subject proof (when present)
+ *   references  relation → raster manifest (when present)
+ *
+ * Edge IDs are deterministic (content-derived in @totemsdk/proofgraph).
+ */
+export declare function spatialRelationToGraphEdges(claim: SpatialRelationClaim): ProofGraphEdge[];
+/**
+ * Add a spatial relation claim as a 'custom' node to a proof graph (immutable
+ * — returns a new graph).
+ */
+export declare function addSpatialRelationToGraph(graph: ProofGraph, claim: SpatialRelationClaim): ProofGraph;

package/dist/proofgraph.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Proofgraph integration helpers for @totemsdk/spatial-proof.
+ *
+ * Produces nodes and edges for @totemsdk/proofgraph without storage
+ * assumptions. Helpers never mutate a graph directly — callers combine the
+ * returned nodes/edges with addNode/addEdge.
+ *
+ * Note: @totemsdk/proofgraph has no native 'spatial' node type, so spatial
+ * objects and relation claims are mapped to the generic 'custom' node type
+ * (the same approach @totemsdk/location-proof uses). If a dedicated
+ * 'spatial-object' / 'spatial-relation' node type is ever wanted, propose it
+ * in @totemsdk/proofgraph (do not silently fork the vocabulary).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spatialObjectToProofGraphNode = spatialObjectToProofGraphNode;
+exports.spatialRelationToProofGraphNode = spatialRelationToProofGraphNode;
+exports.spatialRelationToGraphEdges = spatialRelationToGraphEdges;
+exports.addSpatialRelationToGraph = addSpatialRelationToGraph;
+const proofgraph_1 = require("@totemsdk/proofgraph");
+const canonical_js_1 = require("./canonical.js");
+/**
+ * Build a ProofGraphNode for a spatial object.
+ *
+ * Uses the 'custom' node type (no native proofgraph node type fits a spatial
+ * object). Node ID is deterministic: "custom:<spatialId>".
+ */
+function spatialObjectToProofGraphNode(obj) {
+    return {
+        id: (0, proofgraph_1.computeNodeId)('custom', obj.spatialId),
+        type: 'custom',
+        refId: obj.spatialId,
+        data: {
+            kind: 'spatial-object',
+            spatialKind: obj.kind,
+            geometryHash: (0, canonical_js_1.computeGeometryHash)(obj.geometry),
+            ...(obj.name !== undefined ? { name: obj.name } : {}),
+            ...(obj.crs !== undefined ? { crs: obj.crs } : {}),
+        },
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Build a ProofGraphNode for a spatial relation claim.
+ *
+ * Uses the 'custom' node type. Node ID is deterministic: "custom:<relationId>".
+ */
+function spatialRelationToProofGraphNode(claim) {
+    return {
+        id: (0, proofgraph_1.computeNodeId)('custom', claim.relationId),
+        type: 'custom',
+        refId: claim.relationId,
+        data: {
+            kind: 'spatial-relation',
+            subjectId: claim.subjectId,
+            spatialObjectId: claim.spatialObjectId,
+            relation: claim.relation,
+            matched: claim.result.matched,
+        },
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Build ProofGraphEdges for a spatial relation claim:
+ *   about       relation → subject
+ *   references  relation → spatial object
+ *   derived_from relation → location claim (when present)
+ *   references  relation → subject proof (when present)
+ *   references  relation → raster manifest (when present)
+ *
+ * Edge IDs are deterministic (content-derived in @totemsdk/proofgraph).
+ */
+function spatialRelationToGraphEdges(claim) {
+    const edges = [
+        (0, proofgraph_1.buildEdge)('about', claim.relationId, claim.subjectId, claim.relationId),
+        (0, proofgraph_1.buildEdge)('references', claim.relationId, claim.spatialObjectId, claim.relationId),
+    ];
+    if (claim.inputs.locationClaimId) {
+        edges.push((0, proofgraph_1.buildEdge)('derived_from', claim.relationId, claim.inputs.locationClaimId, claim.relationId));
+    }
+    if (claim.inputs.subjectProofId) {
+        edges.push((0, proofgraph_1.buildEdge)('references', claim.relationId, claim.inputs.subjectProofId, claim.relationId));
+    }
+    if (claim.inputs.rasterManifestId) {
+        edges.push((0, proofgraph_1.buildEdge)('references', claim.relationId, claim.inputs.rasterManifestId, claim.relationId));
+    }
+    return edges;
+}
+/**
+ * Add a spatial relation claim as a 'custom' node to a proof graph (immutable
+ * — returns a new graph).
+ */
+function addSpatialRelationToGraph(graph, claim) {
+    return (0, proofgraph_1.addNode)(graph, 'custom', claim.relationId, {
+        kind: 'spatial-relation',
+        ...claim,
+    });
+}

package/dist/relations.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Spatial relation evaluation for @totemsdk/spatial-proof.
+ *
+ * evaluateSpatialRelation turns a subject geometry (point, route sample, or
+ * footprint bbox) plus a spatial object into a deterministic SpatialRelationClaim.
+ *
+ * HONESTY RULE: any relation evaluated by an approximate algorithm (bounding
+ * boxes instead of exact polygon intersection/coverage) MUST include an
+ * explicit uncertainty note. This package never silently claims exactness
+ * it did not compute.
+ *
+ * All functions are deterministic and dependency-free.
+ */
+import type { EvaluateSpatialRelationParams, SpatialRelationClaim } from './types.js';
+/**
+ * Evaluate a spatial relation and return a deterministic SpatialRelationClaim.
+ *
+ * The claim's relationId is content-derived from all fields except relationId
+ * and metadata, so identical evaluations always produce the same ID.
+ */
+export declare function evaluateSpatialRelation(params: EvaluateSpatialRelationParams): SpatialRelationClaim;

package/dist/relations.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * Spatial relation evaluation for @totemsdk/spatial-proof.
+ *
+ * evaluateSpatialRelation turns a subject geometry (point, route sample, or
+ * footprint bbox) plus a spatial object into a deterministic SpatialRelationClaim.
+ *
+ * HONESTY RULE: any relation evaluated by an approximate algorithm (bounding
+ * boxes instead of exact polygon intersection/coverage) MUST include an
+ * explicit uncertainty note. This package never silently claims exactness
+ * it did not compute.
+ *
+ * All functions are deterministic and dependency-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateSpatialRelation = evaluateSpatialRelation;
+const canonical_js_1 = require("./canonical.js");
+const geometry_js_1 = require("./geometry.js");
+const ENGINE_NAME = '@totemsdk/spatial-proof';
+const ENGINE_VERSION = '0.1.0';
+const BBOX_UNCERTAINTY = 'Relation evaluated using bounding-box approximation; exact polygon intersection not implemented.';
+function isPointGeometry(g) {
+    return g.type === 'Point';
+}
+function isPolygonGeometry(g) {
+    return g.type === 'Polygon';
+}
+function isMultiPolygonGeometry(g) {
+    return g.type === 'MultiPolygon';
+}
+function isLineStringGeometry(g) {
+    return g.type === 'LineString';
+}
+function pointInside(g, point) {
+    if (isPolygonGeometry(g))
+        return (0, geometry_js_1.pointInPolygon)(point.coordinates, g);
+    if (isMultiPolygonGeometry(g))
+        return (0, geometry_js_1.pointInMultiPolygon)(point.coordinates, g);
+    return false;
+}
+/**
+ * Evaluate a spatial relation and return a deterministic SpatialRelationClaim.
+ *
+ * The claim's relationId is content-derived from all fields except relationId
+ * and metadata, so identical evaluations always produce the same ID.
+ */
+function evaluateSpatialRelation(params) {
+    const { subjectId, subjectKind, spatialObject, relation, computedAt = Date.now() } = params;
+    const validation = (0, geometry_js_1.validateSpatialObject)(spatialObject);
+    if (!validation.valid) {
+        throw new Error('invalid spatial object: ' + validation.errors.join('; '));
+    }
+    const spatialGeometryHash = (0, canonical_js_1.computeGeometryHash)(spatialObject.geometry);
+    const subjectGeometryHash = params.subjectGeometry
+        ? (0, canonical_js_1.computeGeometryHash)(params.subjectGeometry)
+        : undefined;
+    // NOTE: relationId is NOT computed here. It is stamped once, at the very end,
+    // after every branch has finalised engine.algorithm and result, so recomputing
+    // the claim ID from the emitted claim always reproduces it.
+    const base = {
+        subjectId,
+        subjectKind,
+        spatialObjectId: spatialObject.spatialId,
+        relation,
+        computedAt,
+        engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'unknown' },
+        inputs: {
+            ...(subjectGeometryHash !== undefined ? { subjectGeometryHash } : {}),
+            spatialGeometryHash,
+            ...(params.subjectProofId !== undefined ? { subjectProofId: params.subjectProofId } : {}),
+            ...(params.locationClaimId !== undefined ? { locationClaimId: params.locationClaimId } : {}),
+            ...(params.rasterManifestId !== undefined ? { rasterManifestId: params.rasterManifestId } : {}),
+        },
+        result: { matched: false },
+        ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+    };
+    function emit(overrides = {}) {
+        const body = { ...base, ...overrides };
+        return { ...body, relationId: (0, canonical_js_1.computeSpatialRelationId)(body) };
+    }
+    if (!params.subjectGeometry) {
+        return emit({
+            result: {
+                matched: false,
+                uncertainty: ['No subject geometry provided; relation could not be evaluated.'],
+            },
+        });
+    }
+    const subject = params.subjectGeometry;
+    const obj = spatialObject.geometry;
+    // ── inside / outside / entered_zone / exited_zone (point vs polygon) ───────
+    if (relation === 'inside' || relation === 'entered_zone') {
+        if (isPointGeometry(subject) && (isPolygonGeometry(obj) || isMultiPolygonGeometry(obj))) {
+            const matched = pointInside(obj, subject);
+            return emit({
+                engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'point-in-polygon (ray casting, planar)' },
+                result: {
+                    matched,
+                    confidenceScore: matched ? 80 : 60,
+                    uncertainty: ['Point-in-polygon test is planar (lon/lat); not a geodesic test.'],
+                },
+            });
+        }
+        return emit({
+            result: {
+                matched: false,
+                uncertainty: ['inside requires a Point subject and Polygon/MultiPolygon object.'],
+            },
+        });
+    }
+    if (relation === 'outside' || relation === 'exited_zone') {
+        if (isPointGeometry(subject) && (isPolygonGeometry(obj) || isMultiPolygonGeometry(obj))) {
+            const matched = !pointInside(obj, subject);
+            return emit({
+                engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'point-in-polygon (ray casting, planar)' },
+                result: {
+                    matched,
+                    confidenceScore: matched ? 80 : 60,
+                    uncertainty: ['Point-in-polygon test is planar (lon/lat); not a geodesic test.'],
+                },
+            });
+        }
+        return emit({
+            result: {
+                matched: false,
+                uncertainty: ['outside requires a Point subject and Polygon/MultiPolygon object.'],
+            },
+        });
+    }
+    // ── within_distance (point vs point via Haversine) ─────────────────────────
+    if (relation === 'within_distance') {
+        if (isPointGeometry(subject) && isPointGeometry(obj)) {
+            const distanceM = (0, geometry_js_1.distanceMeters)(subject.coordinates, obj.coordinates);
+            const maxDistanceM = params.maxDistanceM ?? 0;
+            return emit({
+                engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'haversine great-circle distance' },
+                result: {
+                    matched: distanceM <= maxDistanceM,
+                    distanceM,
+                    confidenceScore: 95,
+                },
+            });
+        }
+        return emit({
+            result: {
+                matched: false,
+                uncertainty: ['within_distance requires Point subject and Point object (Haversine).'],
+            },
+        });
+    }
+    // ── near_boundary (point vs polygon boundary) ──────────────────────────────
+    if (relation === 'near_boundary') {
+        if (isPointGeometry(subject) && (isPolygonGeometry(obj) || isMultiPolygonGeometry(obj))) {
+            const polys = isMultiPolygonGeometry(obj) ? obj.coordinates.map((c) => ({ type: 'Polygon', coordinates: c })) : [obj];
+            const thresholdM = params.maxDistanceM ?? 0;
+            let nearest = Infinity;
+            let matched = false;
+            for (const poly of polys) {
+                const inside = (0, geometry_js_1.pointInPolygon)(subject.coordinates, poly);
+                const near = (0, geometry_js_1.isPointNearBoundary)(subject.coordinates, poly, thresholdM);
+                if (!inside && near)
+                    matched = true;
+                // distance to nearest ring vertex as a rough distance figure
+                for (const ring of poly.coordinates) {
+                    for (let i = 1; i < ring.length; i++) {
+                        const d = (0, geometry_js_1.distancePointToSegmentMeters)(subject.coordinates, ring[i - 1], ring[i]);
+                        if (!inside && d < nearest)
+                            nearest = d;
+                    }
+                }
+            }
+            return emit({
+                engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'point-to-polygon-boundary distance (equirectangular approximation)' },
+                result: {
+                    matched,
+                    ...(Number.isFinite(nearest) ? { distanceM: nearest } : {}),
+                    uncertainty: ['Boundary distance uses an equirectangular local approximation.'],
+                },
+            });
+        }
+        return emit({
+            result: {
+                matched: false,
+                uncertainty: ['near_boundary requires a Point subject and Polygon/MultiPolygon object.'],
+            },
+        });
+    }
+    // ── on_route (point near LineString) ───────────────────────────────────────
+    if (relation === 'on_route') {
+        if (isPointGeometry(subject) && isLineStringGeometry(obj)) {
+            const distanceM = (0, geometry_js_1.distancePointToLineStringMeters)(subject.coordinates, obj);
+            const maxDistanceM = params.maxDistanceM ?? 0;
+            return emit({
+                engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'point-to-LineString distance (equirectangular approximation)' },
+                result: {
+                    matched: distanceM <= maxDistanceM,
+                    distanceM,
+                    confidenceScore: 85,
+                    uncertainty: ['Route distance uses an equirectangular approximation; adequate for short segments.'],
+                },
+            });
+        }
+        return emit({
+            result: {
+                matched: false,
+                uncertainty: ['on_route requires a Point subject and LineString object.'],
+            },
+        });
+    }
+    // ── intersects / overlaps (bbox precheck; polygon relation where feasible) ─
+    if (relation === 'intersects' || relation === 'overlaps') {
+        const subBox = (0, geometry_js_1.getBoundingBox)(subject);
+        const objBox = (0, geometry_js_1.getBoundingBox)(obj);
+        const boxOk = (0, geometry_js_1.bboxIntersects)(subBox, objBox);
+        // When both are polygons we can say more than the box: check vertices.
+        const exact = isPolygonGeometry(subject) && (isPolygonGeometry(obj) || isMultiPolygonGeometry(obj))
+            ? polygonIntersectsExact(subject, obj)
+            : undefined;
+        // A vertex-probe is still not a full intersection: crops can cross edges
+        // without any vertex inside the other polygon.
+        const matched = exact ?? boxOk;
+        return emit({
+            engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'bbox precheck' + (exact !== undefined ? ' + polygon vertex probing' : '') },
+            result: {
+                matched,
+                uncertainty: exact === undefined
+                    ? [BBOX_UNCERTAINTY]
+                    : ['Vertex probing is approximate; polygons that intersect without shared vertices may be misjudged.'],
+            },
+        });
+    }
+    // ── covers / covered_by (scene footprint bbox covers site boundary bbox) ──
+    if (relation === 'covers' || relation === 'covered_by') {
+        const subBox = (0, geometry_js_1.getBoundingBox)(subject);
+        const objBox = (0, geometry_js_1.getBoundingBox)(obj);
+        const matched = relation === 'covers' ? (0, geometry_js_1.bboxCovers)(subBox, objBox) : (0, geometry_js_1.bboxCovers)(objBox, subBox);
+        return emit({
+            engine: { name: ENGINE_NAME, version: ENGINE_VERSION, algorithm: 'bbox cover check' },
+            result: {
+                matched,
+                uncertainty: [BBOX_UNCERTAINTY],
+            },
+        });
+    }
+    // ── unknown ────────────────────────────────────────────────────────────────
+    return emit({
+        result: {
+            matched: false,
+            uncertainty: [`Relation type '${relation}' is not supported.`],
+        },
+    });
+}
+function polygonIntersectsExact(subject, obj) {
+    const objPolys = isMultiPolygonGeometry(obj) ? obj.coordinates.map((c) => ({ type: 'Polygon', coordinates: c })) : [obj];
+    for (const poly of objPolys) {
+        for (const ring of subject.coordinates) {
+            for (const v of ring) {
+                if ((0, geometry_js_1.pointInPolygon)(v, poly))
+                    return true;
+            }
+        }
+        for (const ring of poly.coordinates) {
+            for (const v of ring) {
+                if ((0, geometry_js_1.pointInPolygon)(v, subject))
+                    return true;
+            }
+        }
+    }
+    return false;
+}