koota-kit 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.8.0 (2026-10-14)
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+* feat(spatial): add renderer-neutral clearance queries by @jbdevprimary in https://github.com/jbcom/koota-kit/pull/55
+
+
+**Full Changelog**: https://github.com/jbcom/koota-kit/compare/v0.7.1...v0.8.0
+
 ## 0.7.1 (2026-10-14)
 
 <!-- Release notes generated using configuration in .github/release.yml at main -->

package/README.md

@@ -265,6 +265,7 @@ are also available:
 | `koota-kit/traits` | Safe trait declaration |
 | `koota-kit/schedule` | Fixed-step system schedule with a step cap |
 | `koota-kit/eventLog` | World-scoped publish/drain logs |
+| `koota-kit/spatial` | Renderer-neutral point-to-open-surface clearance queries |
 | `koota-kit/react` | `SimWorldProvider` and `useSimWorld` (optional React peer) |
 
 See the [API reference](./docs/API.md) for signatures and validation behavior,
@@ -285,6 +286,9 @@ For task-oriented usage, read the Sourcey guides on
 - `advanceClock` accepts finite, non-negative `dt`; `0` is a valid paused tick.
 - `createSchedule` needs a finite `step > 0` and a safe-integer `maxSteps >= 1`;
   a negative, `NaN` or infinite `frameDt` counts as `0`.
+- `queryPointClearance` accepts only finite coordinates and a shared Euclidean
+  frame/unit. It proves distance to declared open surfaces, never containment
+  or solid nonpenetration.
 - `nextInt` requires safe-integer bounds with `maxExclusive > minInclusive` and
   a range no larger than `2**32`.
 - `chance` accepts only finite probabilities in `[0, 1]`.

package/dist/cjs/index.cjs

@@ -13,7 +13,7 @@
 //   ./eventLog — scratch-backed publish/drain event logs with a peek seam for
 //                observers (harnesses, tests, HUDs)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CoordinationRegistration = exports.CoordinationBinding = exports.bindCoordination = exports.defineTrait = exports.defineEventLog = exports.createSchedule = exports.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.shuffle = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.pick = exports.nextU32 = exports.nextInt = exports.nextFloat = exports.getSubstream = exports.createSubstreams = exports.createRng = exports.chance = exports.trait = exports.snapshotWorld = exports.restoreWorldHeader = exports.relation = exports.destroySimWorld = exports.createSimWorld = exports.createActions = exports.advanceClock = void 0;
+exports.CoordinationRegistration = exports.CoordinationBinding = exports.bindCoordination = exports.defineTrait = exports.queryPointClearance = exports.defineEventLog = exports.createSchedule = exports.MASTER_SEED_BYTES = exports.isMasterSeed = exports.deriveSeed = exports.createMasterSeed = exports.substream = exports.snapshotSubstreams = exports.snapshotStream = exports.snapshotLayers = exports.shuffle = exports.restoreSubstreams = exports.restoreStream = exports.restoreLayers = exports.pick = exports.nextU32 = exports.nextInt = exports.nextFloat = exports.getSubstream = exports.createSubstreams = exports.createRng = exports.chance = exports.trait = exports.snapshotWorld = exports.restoreWorldHeader = exports.relation = exports.destroySimWorld = exports.createSimWorld = exports.createActions = exports.advanceClock = void 0;
 var world_js_1 = require("./world.cjs");
 Object.defineProperty(exports, "advanceClock", { enumerable: true, get: function () { return world_js_1.advanceClock; } });
 Object.defineProperty(exports, "createActions", { enumerable: true, get: function () { return world_js_1.createActions; } });
@@ -49,6 +49,8 @@ var schedule_js_1 = require("./schedule.cjs");
 Object.defineProperty(exports, "createSchedule", { enumerable: true, get: function () { return schedule_js_1.createSchedule; } });
 var eventLog_js_1 = require("./eventLog.cjs");
 Object.defineProperty(exports, "defineEventLog", { enumerable: true, get: function () { return eventLog_js_1.defineEventLog; } });
+var spatial_js_1 = require("./spatial.cjs");
+Object.defineProperty(exports, "queryPointClearance", { enumerable: true, get: function () { return spatial_js_1.queryPointClearance; } });
 var index_js_1 = require("./traits/index.cjs");
 Object.defineProperty(exports, "defineTrait", { enumerable: true, get: function () { return index_js_1.defineTrait; } });
 var coordination_js_1 = require("./coordination.cjs");

package/dist/cjs/index.d.cts

@@ -8,6 +8,8 @@ export { createSchedule } from "./schedule.cjs";
 export type { Schedule, ScheduleOptions, System } from "./schedule.cjs";
 export { defineEventLog } from "./eventLog.cjs";
 export type { EventLog } from "./eventLog.cjs";
+export { queryPointClearance } from "./spatial.cjs";
+export type { SpatialAabb, SpatialClearanceQuery, SpatialClearanceResult, SpatialFrame, SpatialIdentity, SpatialNearestSurfaceOracle, SpatialNearestWitness, SpatialOracleReply, SpatialPartRecord, SpatialPoint, SpatialProvider, SpatialQueryExactness, SpatialQueryReason, SpatialQueryStatus, SpatialRecordStamp, SpatialRegistrationIdentity, SpatialRevision, SpatialTopology, SpatialTopologySelection, } from "./spatial.cjs";
 export { defineTrait } from "./traits/index.cjs";
 export type { SafeSchema } from "./traits/index.cjs";
 export { bindCoordination, CoordinationBinding, CoordinationRegistration, } from "./coordination.cjs";

package/dist/cjs/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,2BAA2B,EAC3B,eAAe,EACf,eAAe,EACf,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/cjs/spatial.cjs

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * Renderer-neutral point-to-surface clearance queries.
+ *
+ * Producers own their buffers, transforms, and exact geometry implementations.
+ * This module only validates a completed provider snapshot, filters certified
+ * AABBs, and calls an injected oracle in one declared common metric.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryPointClearance = queryPointClearance;
+const finitePoint = (value, label) => {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a point.`);
+    const point = value;
+    for (const axis of ["x", "y", "z"]) {
+        if (!Number.isFinite(point[axis]))
+            throw new RangeError(`spatial: ${label}.${axis} must be finite.`);
+    }
+    return Object.freeze({ x: point.x, y: point.y, z: point.z });
+};
+const nonEmpty = (value, label) => {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`spatial: ${label} must be a non-empty string.`);
+    return value;
+};
+const nonNegativeRevision = (value, label) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`spatial: ${label} must be a non-negative safe integer.`);
+    }
+    return value;
+};
+function copyFrame(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a frame.`);
+    const frame = value;
+    if (frame.metric !== "euclidean")
+        throw new TypeError(`spatial: ${label}.metric must be euclidean.`);
+    return Object.freeze({
+        id: nonEmpty(frame.id, `${label}.id`),
+        unit: nonEmpty(frame.unit, `${label}.unit`),
+        metric: "euclidean",
+    });
+}
+function sameFrame(left, right) {
+    return left.id === right.id && left.unit === right.unit && left.metric === right.metric;
+}
+function copyIdentity(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be an identity.`);
+    const identity = value;
+    if (typeof identity.registration !== "object" || identity.registration === null) {
+        throw new TypeError(`spatial: ${label}.registration must be an identity.`);
+    }
+    return Object.freeze({
+        sourceId: nonEmpty(identity.sourceId, `${label}.sourceId`),
+        instanceId: nonEmpty(identity.instanceId, `${label}.instanceId`),
+        partId: nonEmpty(identity.partId, `${label}.partId`),
+        registration: Object.freeze({
+            id: nonEmpty(identity.registration.id, `${label}.registration.id`),
+            generation: nonNegativeRevision(identity.registration.generation, `${label}.registration.generation`),
+        }),
+    });
+}
+function sameIdentity(left, right) {
+    return (left.sourceId === right.sourceId &&
+        left.instanceId === right.instanceId &&
+        left.partId === right.partId &&
+        left.registration.id === right.registration.id &&
+        left.registration.generation === right.registration.generation);
+}
+function identityKey(identity) {
+    return JSON.stringify([
+        identity.sourceId,
+        identity.instanceId,
+        identity.partId,
+        identity.registration.id,
+        identity.registration.generation,
+    ]);
+}
+function compareIdentity(left, right) {
+    const leftKey = identityKey(left);
+    const rightKey = identityKey(right);
+    return Number(leftKey > rightKey) - Number(leftKey < rightKey);
+}
+function copyRevisions(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be revisions.`);
+    const revisions = value;
+    return Object.freeze({
+        geometry: nonNegativeRevision(revisions.geometry, `${label}.geometry`),
+        topology: nonNegativeRevision(revisions.topology, `${label}.topology`),
+        pose: nonNegativeRevision(revisions.pose, `${label}.pose`),
+        transform: nonNegativeRevision(revisions.transform, `${label}.transform`),
+    });
+}
+function sameRevisions(left, right) {
+    return (left.geometry === right.geometry &&
+        left.topology === right.topology &&
+        left.pose === right.pose &&
+        left.transform === right.transform);
+}
+function copyBounds(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be an AABB.`);
+    const bounds = value;
+    const min = finitePoint(bounds.min, `${label}.min`);
+    const max = finitePoint(bounds.max, `${label}.max`);
+    for (const axis of ["x", "y", "z"]) {
+        if (min[axis] > max[axis])
+            throw new RangeError(`spatial: ${label}.min.${axis} must not exceed max.${axis}.`);
+    }
+    return Object.freeze({ min, max });
+}
+function copyTopology(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be topology.`);
+    const topology = value;
+    if (topology.enclosesSurface !== true)
+        throw new TypeError(`spatial: ${label}.enclosesSurface must certify true.`);
+    return Object.freeze({
+        id: nonEmpty(topology.id, `${label}.id`),
+        bounds: copyBounds(topology.bounds, `${label}.bounds`),
+        enclosesSurface: true,
+    });
+}
+function copyRecord(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a part record.`);
+    const record = value;
+    if (typeof record.topology !== "object" || record.topology === null)
+        throw new TypeError(`spatial: ${label}.topology must be an object.`);
+    if (!Array.isArray(record.capabilities))
+        throw new TypeError(`spatial: ${label}.capabilities must be an array.`);
+    const capabilities = Array.from(record.capabilities);
+    if (capabilities.some((capability) => capability !== "nearest-surface") ||
+        new Set(capabilities).size !== capabilities.length) {
+        throw new TypeError(`spatial: ${label}.capabilities may only contain nearest-surface.`);
+    }
+    return Object.freeze({
+        identity: copyIdentity(record.identity, `${label}.identity`),
+        frame: copyFrame(record.frame, `${label}.frame`),
+        revisions: copyRevisions(record.revisions, `${label}.revisions`),
+        topology: Object.freeze({
+            full: copyTopology(record.topology.full, `${label}.topology.full`),
+            visible: copyTopology(record.topology.visible, `${label}.topology.visible`),
+        }),
+        capabilities: Object.freeze(capabilities),
+    });
+}
+function makeStamp(record, selection) {
+    return Object.freeze({
+        identity: record.identity,
+        frame: record.frame,
+        topology: Object.freeze({ selection, id: record.topology[selection].id }),
+        revisions: record.revisions,
+    });
+}
+function sameStamp(left, right) {
+    return (sameIdentity(left.identity, right.identity) &&
+        sameFrame(left.frame, right.frame) &&
+        left.topology.selection === right.topology.selection &&
+        left.topology.id === right.topology.id &&
+        sameRevisions(left.revisions, right.revisions));
+}
+function copyStamp(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a record stamp.`);
+    const stamp = value;
+    if (typeof stamp.topology !== "object" ||
+        stamp.topology === null ||
+        (stamp.topology.selection !== "full" && stamp.topology.selection !== "visible")) {
+        throw new TypeError(`spatial: ${label}.topology.selection must be full or visible.`);
+    }
+    return Object.freeze({
+        identity: copyIdentity(stamp.identity, `${label}.identity`),
+        frame: copyFrame(stamp.frame, `${label}.frame`),
+        topology: Object.freeze({
+            selection: stamp.topology.selection,
+            id: nonEmpty(stamp.topology.id, `${label}.topology.id`),
+        }),
+        revisions: copyRevisions(stamp.revisions, `${label}.revisions`),
+    });
+}
+function distanceToBounds(point, bounds) {
+    const delta = ["x", "y", "z"].map((axis) => Math.max(bounds.min[axis] - point[axis], 0, point[axis] - bounds.max[axis]));
+    return Math.hypot(...delta);
+}
+function pointDistance(left, right) {
+    return Math.hypot(left.x - right.x, left.y - right.y, left.z - right.z);
+}
+function pointIsInside(point, bounds) {
+    return ["x", "y", "z"].every((axis) => point[axis] >= bounds.min[axis] && point[axis] <= bounds.max[axis]);
+}
+function sameDistance(left, right) {
+    return Math.abs(left - right) <= Math.max(1e-9, Math.max(Math.abs(left), Math.abs(right)) / 1e9);
+}
+function result(status, reason, exactness, topology, checked, exclusions, witnesses) {
+    return Object.freeze({
+        status,
+        reason,
+        exactness,
+        topology,
+        checked: Object.freeze([...checked]),
+        exclusions: Object.freeze([...exclusions]),
+        witnesses: Object.freeze([...witnesses]),
+    });
+}
+/**
+ * Decide a point-to-open-surface clearance predicate in the given common
+ * Euclidean frame. It never proves containment or solid nonpenetration.
+ *
+ * Status precedence is stale, then violated, then unsupported/unknown, then
+ * satisfied. An exact close witness therefore proves a violation even if a
+ * different selected provider cannot answer.
+ */
+function queryPointClearance(provider, oracle, query) {
+    if (typeof provider !== "object" || provider === null || typeof provider.snapshot !== "function")
+        throw new TypeError("spatial: provider must expose snapshot().");
+    if (typeof oracle !== "object" || oracle === null || typeof oracle.nearest !== "function")
+        throw new TypeError("spatial: oracle must expose nearest().");
+    if (typeof query !== "object" || query === null)
+        throw new TypeError("spatial: query must be an object.");
+    const point = finitePoint(query.point, "query.point");
+    const frame = copyFrame(query.frame, "query.frame");
+    const minimumDistance = query.minimumDistance;
+    const searchDistance = query.searchDistance;
+    if (!Number.isFinite(minimumDistance) || minimumDistance < 0)
+        throw new RangeError("spatial: query.minimumDistance must be finite and non-negative.");
+    if (!Number.isFinite(searchDistance) || searchDistance < minimumDistance)
+        throw new RangeError("spatial: query.searchDistance must be finite and at least minimumDistance.");
+    const topology = query.topology ?? "full";
+    if (topology !== "full" && topology !== "visible")
+        throw new TypeError("spatial: query.topology must be full or visible.");
+    if (query.exclusions !== undefined && !Array.isArray(query.exclusions))
+        throw new TypeError("spatial: query.exclusions must be an array.");
+    if (query.expected !== undefined && !Array.isArray(query.expected))
+        throw new TypeError("spatial: query.expected must be an array.");
+    const exclusions = Array.from(query.exclusions ?? [], (value, index) => copyIdentity(value, `query.exclusions[${index}]`)).sort(compareIdentity);
+    const exclusionKeys = new Set(exclusions.map(identityKey));
+    if (exclusionKeys.size !== exclusions.length)
+        throw new TypeError("spatial: query.exclusions must not contain duplicates.");
+    const expected = Array.from(query.expected ?? [], (value, index) => copyStamp(value, `query.expected[${index}]`));
+    const expectedKeys = new Set(expected.map((stamp) => identityKey(stamp.identity)));
+    if (expectedKeys.size !== expected.length)
+        throw new TypeError("spatial: query.expected must not contain duplicate identities.");
+    const snapshot = provider.snapshot();
+    if (!Array.isArray(snapshot))
+        throw new TypeError("spatial: provider.snapshot() must return an array.");
+    let records;
+    try {
+        records = Array.from(snapshot, (record, index) => copyRecord(record, `provider.snapshot()[${index}]`));
+    }
+    catch {
+        return result("unsupported", "provider-contract-invalid", "none", topology, [], exclusions, []);
+    }
+    const recordKeys = new Set(records.map((record) => identityKey(record.identity)));
+    if (recordKeys.size !== records.length) {
+        return result("unsupported", "provider-duplicate-record", "none", topology, [], exclusions, []);
+    }
+    records.sort((left, right) => compareIdentity(left.identity, right.identity));
+    const allStamps = records.map((record) => makeStamp(record, topology));
+    if (expected.length > 0) {
+        const stampsByIdentity = new Map(allStamps.map((stamp) => [identityKey(stamp.identity), stamp]));
+        if (expected.some((stamp) => {
+            const current = stampsByIdentity.get(identityKey(stamp.identity));
+            return !current || !sameStamp(current, stamp);
+        })) {
+            return result("stale", "revision-mismatch", "none", topology, allStamps, exclusions, []);
+        }
+    }
+    const selected = records.filter((record) => !exclusionKeys.has(identityKey(record.identity)));
+    const stamps = selected.map((record) => makeStamp(record, topology));
+    let unresolved;
+    const prepared = [];
+    for (const record of selected) {
+        if (!sameFrame(record.frame, frame)) {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        const stamp = makeStamp(record, topology);
+        prepared.push(Object.freeze({
+            record,
+            stamp,
+            boundsDistance: distanceToBounds(point, record.topology[topology].bounds),
+        }));
+    }
+    const candidates = prepared.filter(({ boundsDistance }) => boundsDistance < minimumDistance);
+    const witnesses = [];
+    for (const candidate of candidates) {
+        if (!candidate.record.capabilities.includes("nearest-surface")) {
+            if (unresolved !== "provider-contract-invalid")
+                unresolved = "nearest-surface-unsupported";
+            continue;
+        }
+        const reply = oracle.nearest(Object.freeze({
+            record: candidate.record,
+            topology,
+            point,
+            maximumDistance: searchDistance,
+        }));
+        if (reply === undefined) {
+            if (unresolved !== "provider-contract-invalid")
+                unresolved = "nearest-surface-unsupported";
+            continue;
+        }
+        if (typeof reply !== "object" ||
+            reply === null ||
+            (reply.kind !== "nearest" && reply.kind !== "no-hit" && reply.kind !== "unknown")) {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        let consumed;
+        try {
+            consumed = copyStamp(reply.kind === "nearest" ? reply.witness?.consumed : reply.consumed, "oracle.consumed");
+        }
+        catch {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        if (!sameStamp(consumed, candidate.stamp)) {
+            return result("stale", "oracle-stale", "none", topology, stamps, exclusions, witnesses);
+        }
+        if (reply.kind === "unknown") {
+            if (typeof reply.reason !== "string" || reply.reason.length === 0)
+                unresolved = "provider-contract-invalid";
+            else
+                unresolved ?? (unresolved = "oracle-unknown");
+            continue;
+        }
+        if (reply.kind === "no-hit")
+            continue;
+        let witness;
+        try {
+            const witnessPoint = finitePoint(reply.witness.point, "oracle.witness.point");
+            const distance = reply.witness.distance;
+            const actualDistance = pointDistance(point, witnessPoint);
+            if (!Number.isFinite(distance) ||
+                distance < 0 ||
+                distance > searchDistance ||
+                !Number.isFinite(actualDistance) ||
+                actualDistance > searchDistance ||
+                !sameDistance(distance, actualDistance) ||
+                !pointIsInside(witnessPoint, candidate.record.topology[topology].bounds))
+                throw new RangeError();
+            if (!sameFrame(copyFrame(reply.witness.frame, "oracle.witness.frame"), frame))
+                throw new TypeError();
+            witness = Object.freeze({
+                triangleId: nonEmpty(reply.witness.triangleId, "oracle.witness.triangleId"),
+                point: witnessPoint,
+                distance: actualDistance,
+                frame,
+                consumed: candidate.stamp,
+            });
+        }
+        catch {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        witnesses.push(witness);
+    }
+    const violation = witnesses.find((witness) => witness.distance < minimumDistance);
+    if (violation)
+        return result("violated", "clearance-violated", "exact", topology, stamps, exclusions, witnesses);
+    if (unresolved === "provider-contract-invalid")
+        return result("unsupported", "provider-contract-invalid", "none", topology, stamps, exclusions, witnesses);
+    if (unresolved === "nearest-surface-unsupported")
+        return result("unsupported", "nearest-surface-unsupported", "none", topology, stamps, exclusions, witnesses);
+    if (unresolved === "oracle-unknown")
+        return result("unknown", "oracle-unknown", "none", topology, stamps, exclusions, witnesses);
+    return result("satisfied", "clearance-satisfied", candidates.length > 0 && candidates.length === selected.length ? "exact" : "conservative", topology, stamps, exclusions, witnesses);
+}

package/dist/cjs/spatial.d.cts

@@ -0,0 +1,130 @@
+/**
+ * Renderer-neutral point-to-surface clearance queries.
+ *
+ * Producers own their buffers, transforms, and exact geometry implementations.
+ * This module only validates a completed provider snapshot, filters certified
+ * AABBs, and calls an injected oracle in one declared common metric.
+ */
+export type SpatialPoint = Readonly<{
+    x: number;
+    y: number;
+    z: number;
+}>;
+export type SpatialAabb = Readonly<{
+    min: SpatialPoint;
+    max: SpatialPoint;
+}>;
+export type SpatialFrame = Readonly<{
+    id: string;
+    unit: string;
+    metric: "euclidean";
+}>;
+/** A provider-local registration identity. It is deliberately not a coordination token. */
+export type SpatialRegistrationIdentity = Readonly<{
+    id: string;
+    generation: number;
+}>;
+export type SpatialIdentity = Readonly<{
+    sourceId: string;
+    instanceId: string;
+    partId: string;
+    registration: SpatialRegistrationIdentity;
+}>;
+/** Independent completed producer epochs; none is a coordination publication revision. */
+export type SpatialRevision = Readonly<{
+    geometry: number;
+    topology: number;
+    pose: number;
+    transform: number;
+}>;
+export type SpatialTopology = Readonly<{
+    id: string;
+    /** The provider certifies that this AABB encloses the topology it supplies to the oracle. */
+    bounds: SpatialAabb;
+    enclosesSurface: true;
+}>;
+export type SpatialPartRecord = Readonly<{
+    identity: SpatialIdentity;
+    frame: SpatialFrame;
+    revisions: SpatialRevision;
+    /** `full` remains the default. `visible` is only selected explicitly by a query. */
+    topology: Readonly<{
+        full: SpatialTopology;
+        visible: SpatialTopology;
+    }>;
+    capabilities: readonly "nearest-surface"[];
+}>;
+export type SpatialTopologySelection = "full" | "visible";
+export type SpatialRecordStamp = Readonly<{
+    identity: SpatialIdentity;
+    frame: SpatialFrame;
+    topology: Readonly<{
+        selection: SpatialTopologySelection;
+        id: string;
+    }>;
+    revisions: SpatialRevision;
+}>;
+export type SpatialNearestWitness = Readonly<{
+    triangleId: string;
+    point: SpatialPoint;
+    distance: number;
+    frame: SpatialFrame;
+    consumed: SpatialRecordStamp;
+}>;
+export type SpatialOracleReply = Readonly<{
+    kind: "nearest";
+    witness: SpatialNearestWitness;
+}> | Readonly<{
+    kind: "no-hit";
+    consumed: SpatialRecordStamp;
+}> | Readonly<{
+    kind: "unknown";
+    reason: string;
+    consumed: SpatialRecordStamp;
+}>;
+export type SpatialNearestSurfaceOracle = Readonly<{
+    nearest: (request: Readonly<{
+        record: SpatialPartRecord;
+        topology: SpatialTopologySelection;
+        point: SpatialPoint;
+        maximumDistance: number;
+    }>) => SpatialOracleReply | undefined;
+}>;
+/** Provider snapshots must be completed, immutable records for one query call. */
+export type SpatialProvider = Readonly<{
+    snapshot: () => readonly SpatialPartRecord[];
+}>;
+export type SpatialClearanceQuery = Readonly<{
+    point: SpatialPoint;
+    frame: SpatialFrame;
+    /** The predicate: every selected open surface must be at least this far away. */
+    minimumDistance: number;
+    /** Finite oracle search bound; it must be at least `minimumDistance`. */
+    searchDistance: number;
+    topology?: SpatialTopologySelection;
+    exclusions?: readonly SpatialIdentity[];
+    /** A mismatch is stale, before an oracle result can be trusted. */
+    expected?: readonly SpatialRecordStamp[];
+}>;
+export type SpatialQueryStatus = "satisfied" | "violated" | "unknown" | "unsupported" | "stale";
+export type SpatialQueryExactness = "exact" | "conservative" | "none";
+export type SpatialQueryReason = "clearance-satisfied" | "clearance-violated" | "oracle-unknown" | "nearest-surface-unsupported" | "provider-contract-invalid" | "provider-duplicate-record" | "revision-mismatch" | "oracle-stale";
+export type SpatialClearanceResult = Readonly<{
+    status: SpatialQueryStatus;
+    reason: SpatialQueryReason;
+    exactness: SpatialQueryExactness;
+    topology: SpatialTopologySelection;
+    checked: readonly SpatialRecordStamp[];
+    exclusions: readonly SpatialIdentity[];
+    witnesses: readonly SpatialNearestWitness[];
+}>;
+/**
+ * Decide a point-to-open-surface clearance predicate in the given common
+ * Euclidean frame. It never proves containment or solid nonpenetration.
+ *
+ * Status precedence is stale, then violated, then unsupported/unknown, then
+ * satisfied. An exact close witness therefore proves a violation even if a
+ * different selected provider cannot answer.
+ */
+export declare function queryPointClearance(provider: SpatialProvider, oracle: SpatialNearestSurfaceOracle, query: SpatialClearanceQuery): SpatialClearanceResult;
+//# sourceMappingURL=spatial.d.cts.map

package/dist/cjs/spatial.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial.d.ts","sourceRoot":"","sources":["../../src/spatial.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEzE,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;AAE7E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC,CAAC;AAEH,2FAA2F;AAC3F,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,2BAA2B,CAAC;CAC3C,CAAC,CAAC;AAEH,0FAA0F;AAC1F,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,6FAA6F;IAC7F,MAAM,EAAE,WAAW,CAAC;IACpB,eAAe,EAAE,IAAI,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,eAAe,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IACxE,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5C,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;QAAE,SAAS,EAAE,wBAAwB,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxE,SAAS,EAAE,eAAe,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC,GAC7D,QAAQ,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,CAAC,GAC1D,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;AAEhF,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,OAAO,EAAE,CACP,OAAO,EAAE,QAAQ,CAAC;QAChB,MAAM,EAAE,iBAAiB,CAAC;QAC1B,QAAQ,EAAE,wBAAwB,CAAC;QACnC,KAAK,EAAE,YAAY,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC,KACC,kBAAkB,GAAG,SAAS,CAAC;CACrC,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IAAE,QAAQ,EAAE,MAAM,SAAS,iBAAiB,EAAE,CAAA;CAAE,CAAC,CAAC;AAEzF,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC1C,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;AAEhG,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,cAAc,GAAG,MAAM,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAC1B,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,6BAA6B,GAC7B,2BAA2B,GAC3B,2BAA2B,GAC3B,mBAAmB,GACnB,cAAc,CAAC;AAEnB,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE,qBAAqB,CAAC;IACjC,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC7C,CAAC,CAAC;AA+PH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,2BAA2B,EACnC,KAAK,EAAE,qBAAqB,GAC3B,sBAAsB,CAkNxB"}

package/dist/esm/index.d.ts

@@ -8,6 +8,8 @@ export { createSchedule } from "./schedule.js";
 export type { Schedule, ScheduleOptions, System } from "./schedule.js";
 export { defineEventLog } from "./eventLog.js";
 export type { EventLog } from "./eventLog.js";
+export { queryPointClearance } from "./spatial.js";
+export type { SpatialAabb, SpatialClearanceQuery, SpatialClearanceResult, SpatialFrame, SpatialIdentity, SpatialNearestSurfaceOracle, SpatialNearestWitness, SpatialOracleReply, SpatialPartRecord, SpatialPoint, SpatialProvider, SpatialQueryExactness, SpatialQueryReason, SpatialQueryStatus, SpatialRecordStamp, SpatialRegistrationIdentity, SpatialRevision, SpatialTopology, SpatialTopologySelection, } from "./spatial.js";
 export { defineTrait } from "./traits/index.js";
 export type { SafeSchema } from "./traits/index.js";
 export { bindCoordination, CoordinationBinding, CoordinationRegistration, } from "./coordination.js";

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,OAAO,EACP,IAAI,EACJ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,2BAA2B,EAC3B,eAAe,EACf,eAAe,EACf,wBAAwB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -16,5 +16,6 @@ export { chance, createRng, createSubstreams, getSubstream, nextFloat, nextInt,
 export { createMasterSeed, deriveSeed, isMasterSeed, MASTER_SEED_BYTES } from "./seed.js";
 export { createSchedule } from "./schedule.js";
 export { defineEventLog } from "./eventLog.js";
+export { queryPointClearance } from "./spatial.js";
 export { defineTrait } from "./traits/index.js";
 export { bindCoordination, CoordinationBinding, CoordinationRegistration, } from "./coordination.js";

package/dist/esm/spatial.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Renderer-neutral point-to-surface clearance queries.
+ *
+ * Producers own their buffers, transforms, and exact geometry implementations.
+ * This module only validates a completed provider snapshot, filters certified
+ * AABBs, and calls an injected oracle in one declared common metric.
+ */
+export type SpatialPoint = Readonly<{
+    x: number;
+    y: number;
+    z: number;
+}>;
+export type SpatialAabb = Readonly<{
+    min: SpatialPoint;
+    max: SpatialPoint;
+}>;
+export type SpatialFrame = Readonly<{
+    id: string;
+    unit: string;
+    metric: "euclidean";
+}>;
+/** A provider-local registration identity. It is deliberately not a coordination token. */
+export type SpatialRegistrationIdentity = Readonly<{
+    id: string;
+    generation: number;
+}>;
+export type SpatialIdentity = Readonly<{
+    sourceId: string;
+    instanceId: string;
+    partId: string;
+    registration: SpatialRegistrationIdentity;
+}>;
+/** Independent completed producer epochs; none is a coordination publication revision. */
+export type SpatialRevision = Readonly<{
+    geometry: number;
+    topology: number;
+    pose: number;
+    transform: number;
+}>;
+export type SpatialTopology = Readonly<{
+    id: string;
+    /** The provider certifies that this AABB encloses the topology it supplies to the oracle. */
+    bounds: SpatialAabb;
+    enclosesSurface: true;
+}>;
+export type SpatialPartRecord = Readonly<{
+    identity: SpatialIdentity;
+    frame: SpatialFrame;
+    revisions: SpatialRevision;
+    /** `full` remains the default. `visible` is only selected explicitly by a query. */
+    topology: Readonly<{
+        full: SpatialTopology;
+        visible: SpatialTopology;
+    }>;
+    capabilities: readonly "nearest-surface"[];
+}>;
+export type SpatialTopologySelection = "full" | "visible";
+export type SpatialRecordStamp = Readonly<{
+    identity: SpatialIdentity;
+    frame: SpatialFrame;
+    topology: Readonly<{
+        selection: SpatialTopologySelection;
+        id: string;
+    }>;
+    revisions: SpatialRevision;
+}>;
+export type SpatialNearestWitness = Readonly<{
+    triangleId: string;
+    point: SpatialPoint;
+    distance: number;
+    frame: SpatialFrame;
+    consumed: SpatialRecordStamp;
+}>;
+export type SpatialOracleReply = Readonly<{
+    kind: "nearest";
+    witness: SpatialNearestWitness;
+}> | Readonly<{
+    kind: "no-hit";
+    consumed: SpatialRecordStamp;
+}> | Readonly<{
+    kind: "unknown";
+    reason: string;
+    consumed: SpatialRecordStamp;
+}>;
+export type SpatialNearestSurfaceOracle = Readonly<{
+    nearest: (request: Readonly<{
+        record: SpatialPartRecord;
+        topology: SpatialTopologySelection;
+        point: SpatialPoint;
+        maximumDistance: number;
+    }>) => SpatialOracleReply | undefined;
+}>;
+/** Provider snapshots must be completed, immutable records for one query call. */
+export type SpatialProvider = Readonly<{
+    snapshot: () => readonly SpatialPartRecord[];
+}>;
+export type SpatialClearanceQuery = Readonly<{
+    point: SpatialPoint;
+    frame: SpatialFrame;
+    /** The predicate: every selected open surface must be at least this far away. */
+    minimumDistance: number;
+    /** Finite oracle search bound; it must be at least `minimumDistance`. */
+    searchDistance: number;
+    topology?: SpatialTopologySelection;
+    exclusions?: readonly SpatialIdentity[];
+    /** A mismatch is stale, before an oracle result can be trusted. */
+    expected?: readonly SpatialRecordStamp[];
+}>;
+export type SpatialQueryStatus = "satisfied" | "violated" | "unknown" | "unsupported" | "stale";
+export type SpatialQueryExactness = "exact" | "conservative" | "none";
+export type SpatialQueryReason = "clearance-satisfied" | "clearance-violated" | "oracle-unknown" | "nearest-surface-unsupported" | "provider-contract-invalid" | "provider-duplicate-record" | "revision-mismatch" | "oracle-stale";
+export type SpatialClearanceResult = Readonly<{
+    status: SpatialQueryStatus;
+    reason: SpatialQueryReason;
+    exactness: SpatialQueryExactness;
+    topology: SpatialTopologySelection;
+    checked: readonly SpatialRecordStamp[];
+    exclusions: readonly SpatialIdentity[];
+    witnesses: readonly SpatialNearestWitness[];
+}>;
+/**
+ * Decide a point-to-open-surface clearance predicate in the given common
+ * Euclidean frame. It never proves containment or solid nonpenetration.
+ *
+ * Status precedence is stale, then violated, then unsupported/unknown, then
+ * satisfied. An exact close witness therefore proves a violation even if a
+ * different selected provider cannot answer.
+ */
+export declare function queryPointClearance(provider: SpatialProvider, oracle: SpatialNearestSurfaceOracle, query: SpatialClearanceQuery): SpatialClearanceResult;
+//# sourceMappingURL=spatial.d.ts.map

package/dist/esm/spatial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial.d.ts","sourceRoot":"","sources":["../../src/spatial.ts"],"names":[],"mappings":"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"}

package/dist/esm/spatial.js

@@ -0,0 +1,368 @@
+/**
+ * Renderer-neutral point-to-surface clearance queries.
+ *
+ * Producers own their buffers, transforms, and exact geometry implementations.
+ * This module only validates a completed provider snapshot, filters certified
+ * AABBs, and calls an injected oracle in one declared common metric.
+ */
+const finitePoint = (value, label) => {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a point.`);
+    const point = value;
+    for (const axis of ["x", "y", "z"]) {
+        if (!Number.isFinite(point[axis]))
+            throw new RangeError(`spatial: ${label}.${axis} must be finite.`);
+    }
+    return Object.freeze({ x: point.x, y: point.y, z: point.z });
+};
+const nonEmpty = (value, label) => {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`spatial: ${label} must be a non-empty string.`);
+    return value;
+};
+const nonNegativeRevision = (value, label) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`spatial: ${label} must be a non-negative safe integer.`);
+    }
+    return value;
+};
+function copyFrame(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a frame.`);
+    const frame = value;
+    if (frame.metric !== "euclidean")
+        throw new TypeError(`spatial: ${label}.metric must be euclidean.`);
+    return Object.freeze({
+        id: nonEmpty(frame.id, `${label}.id`),
+        unit: nonEmpty(frame.unit, `${label}.unit`),
+        metric: "euclidean",
+    });
+}
+function sameFrame(left, right) {
+    return left.id === right.id && left.unit === right.unit && left.metric === right.metric;
+}
+function copyIdentity(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be an identity.`);
+    const identity = value;
+    if (typeof identity.registration !== "object" || identity.registration === null) {
+        throw new TypeError(`spatial: ${label}.registration must be an identity.`);
+    }
+    return Object.freeze({
+        sourceId: nonEmpty(identity.sourceId, `${label}.sourceId`),
+        instanceId: nonEmpty(identity.instanceId, `${label}.instanceId`),
+        partId: nonEmpty(identity.partId, `${label}.partId`),
+        registration: Object.freeze({
+            id: nonEmpty(identity.registration.id, `${label}.registration.id`),
+            generation: nonNegativeRevision(identity.registration.generation, `${label}.registration.generation`),
+        }),
+    });
+}
+function sameIdentity(left, right) {
+    return (left.sourceId === right.sourceId &&
+        left.instanceId === right.instanceId &&
+        left.partId === right.partId &&
+        left.registration.id === right.registration.id &&
+        left.registration.generation === right.registration.generation);
+}
+function identityKey(identity) {
+    return JSON.stringify([
+        identity.sourceId,
+        identity.instanceId,
+        identity.partId,
+        identity.registration.id,
+        identity.registration.generation,
+    ]);
+}
+function compareIdentity(left, right) {
+    const leftKey = identityKey(left);
+    const rightKey = identityKey(right);
+    return Number(leftKey > rightKey) - Number(leftKey < rightKey);
+}
+function copyRevisions(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be revisions.`);
+    const revisions = value;
+    return Object.freeze({
+        geometry: nonNegativeRevision(revisions.geometry, `${label}.geometry`),
+        topology: nonNegativeRevision(revisions.topology, `${label}.topology`),
+        pose: nonNegativeRevision(revisions.pose, `${label}.pose`),
+        transform: nonNegativeRevision(revisions.transform, `${label}.transform`),
+    });
+}
+function sameRevisions(left, right) {
+    return (left.geometry === right.geometry &&
+        left.topology === right.topology &&
+        left.pose === right.pose &&
+        left.transform === right.transform);
+}
+function copyBounds(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be an AABB.`);
+    const bounds = value;
+    const min = finitePoint(bounds.min, `${label}.min`);
+    const max = finitePoint(bounds.max, `${label}.max`);
+    for (const axis of ["x", "y", "z"]) {
+        if (min[axis] > max[axis])
+            throw new RangeError(`spatial: ${label}.min.${axis} must not exceed max.${axis}.`);
+    }
+    return Object.freeze({ min, max });
+}
+function copyTopology(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be topology.`);
+    const topology = value;
+    if (topology.enclosesSurface !== true)
+        throw new TypeError(`spatial: ${label}.enclosesSurface must certify true.`);
+    return Object.freeze({
+        id: nonEmpty(topology.id, `${label}.id`),
+        bounds: copyBounds(topology.bounds, `${label}.bounds`),
+        enclosesSurface: true,
+    });
+}
+function copyRecord(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a part record.`);
+    const record = value;
+    if (typeof record.topology !== "object" || record.topology === null)
+        throw new TypeError(`spatial: ${label}.topology must be an object.`);
+    if (!Array.isArray(record.capabilities))
+        throw new TypeError(`spatial: ${label}.capabilities must be an array.`);
+    const capabilities = Array.from(record.capabilities);
+    if (capabilities.some((capability) => capability !== "nearest-surface") ||
+        new Set(capabilities).size !== capabilities.length) {
+        throw new TypeError(`spatial: ${label}.capabilities may only contain nearest-surface.`);
+    }
+    return Object.freeze({
+        identity: copyIdentity(record.identity, `${label}.identity`),
+        frame: copyFrame(record.frame, `${label}.frame`),
+        revisions: copyRevisions(record.revisions, `${label}.revisions`),
+        topology: Object.freeze({
+            full: copyTopology(record.topology.full, `${label}.topology.full`),
+            visible: copyTopology(record.topology.visible, `${label}.topology.visible`),
+        }),
+        capabilities: Object.freeze(capabilities),
+    });
+}
+function makeStamp(record, selection) {
+    return Object.freeze({
+        identity: record.identity,
+        frame: record.frame,
+        topology: Object.freeze({ selection, id: record.topology[selection].id }),
+        revisions: record.revisions,
+    });
+}
+function sameStamp(left, right) {
+    return (sameIdentity(left.identity, right.identity) &&
+        sameFrame(left.frame, right.frame) &&
+        left.topology.selection === right.topology.selection &&
+        left.topology.id === right.topology.id &&
+        sameRevisions(left.revisions, right.revisions));
+}
+function copyStamp(value, label) {
+    if (typeof value !== "object" || value === null)
+        throw new TypeError(`spatial: ${label} must be a record stamp.`);
+    const stamp = value;
+    if (typeof stamp.topology !== "object" ||
+        stamp.topology === null ||
+        (stamp.topology.selection !== "full" && stamp.topology.selection !== "visible")) {
+        throw new TypeError(`spatial: ${label}.topology.selection must be full or visible.`);
+    }
+    return Object.freeze({
+        identity: copyIdentity(stamp.identity, `${label}.identity`),
+        frame: copyFrame(stamp.frame, `${label}.frame`),
+        topology: Object.freeze({
+            selection: stamp.topology.selection,
+            id: nonEmpty(stamp.topology.id, `${label}.topology.id`),
+        }),
+        revisions: copyRevisions(stamp.revisions, `${label}.revisions`),
+    });
+}
+function distanceToBounds(point, bounds) {
+    const delta = ["x", "y", "z"].map((axis) => Math.max(bounds.min[axis] - point[axis], 0, point[axis] - bounds.max[axis]));
+    return Math.hypot(...delta);
+}
+function pointDistance(left, right) {
+    return Math.hypot(left.x - right.x, left.y - right.y, left.z - right.z);
+}
+function pointIsInside(point, bounds) {
+    return ["x", "y", "z"].every((axis) => point[axis] >= bounds.min[axis] && point[axis] <= bounds.max[axis]);
+}
+function sameDistance(left, right) {
+    return Math.abs(left - right) <= Math.max(1e-9, Math.max(Math.abs(left), Math.abs(right)) / 1e9);
+}
+function result(status, reason, exactness, topology, checked, exclusions, witnesses) {
+    return Object.freeze({
+        status,
+        reason,
+        exactness,
+        topology,
+        checked: Object.freeze([...checked]),
+        exclusions: Object.freeze([...exclusions]),
+        witnesses: Object.freeze([...witnesses]),
+    });
+}
+/**
+ * Decide a point-to-open-surface clearance predicate in the given common
+ * Euclidean frame. It never proves containment or solid nonpenetration.
+ *
+ * Status precedence is stale, then violated, then unsupported/unknown, then
+ * satisfied. An exact close witness therefore proves a violation even if a
+ * different selected provider cannot answer.
+ */
+export function queryPointClearance(provider, oracle, query) {
+    if (typeof provider !== "object" || provider === null || typeof provider.snapshot !== "function")
+        throw new TypeError("spatial: provider must expose snapshot().");
+    if (typeof oracle !== "object" || oracle === null || typeof oracle.nearest !== "function")
+        throw new TypeError("spatial: oracle must expose nearest().");
+    if (typeof query !== "object" || query === null)
+        throw new TypeError("spatial: query must be an object.");
+    const point = finitePoint(query.point, "query.point");
+    const frame = copyFrame(query.frame, "query.frame");
+    const minimumDistance = query.minimumDistance;
+    const searchDistance = query.searchDistance;
+    if (!Number.isFinite(minimumDistance) || minimumDistance < 0)
+        throw new RangeError("spatial: query.minimumDistance must be finite and non-negative.");
+    if (!Number.isFinite(searchDistance) || searchDistance < minimumDistance)
+        throw new RangeError("spatial: query.searchDistance must be finite and at least minimumDistance.");
+    const topology = query.topology ?? "full";
+    if (topology !== "full" && topology !== "visible")
+        throw new TypeError("spatial: query.topology must be full or visible.");
+    if (query.exclusions !== undefined && !Array.isArray(query.exclusions))
+        throw new TypeError("spatial: query.exclusions must be an array.");
+    if (query.expected !== undefined && !Array.isArray(query.expected))
+        throw new TypeError("spatial: query.expected must be an array.");
+    const exclusions = Array.from(query.exclusions ?? [], (value, index) => copyIdentity(value, `query.exclusions[${index}]`)).sort(compareIdentity);
+    const exclusionKeys = new Set(exclusions.map(identityKey));
+    if (exclusionKeys.size !== exclusions.length)
+        throw new TypeError("spatial: query.exclusions must not contain duplicates.");
+    const expected = Array.from(query.expected ?? [], (value, index) => copyStamp(value, `query.expected[${index}]`));
+    const expectedKeys = new Set(expected.map((stamp) => identityKey(stamp.identity)));
+    if (expectedKeys.size !== expected.length)
+        throw new TypeError("spatial: query.expected must not contain duplicate identities.");
+    const snapshot = provider.snapshot();
+    if (!Array.isArray(snapshot))
+        throw new TypeError("spatial: provider.snapshot() must return an array.");
+    let records;
+    try {
+        records = Array.from(snapshot, (record, index) => copyRecord(record, `provider.snapshot()[${index}]`));
+    }
+    catch {
+        return result("unsupported", "provider-contract-invalid", "none", topology, [], exclusions, []);
+    }
+    const recordKeys = new Set(records.map((record) => identityKey(record.identity)));
+    if (recordKeys.size !== records.length) {
+        return result("unsupported", "provider-duplicate-record", "none", topology, [], exclusions, []);
+    }
+    records.sort((left, right) => compareIdentity(left.identity, right.identity));
+    const allStamps = records.map((record) => makeStamp(record, topology));
+    if (expected.length > 0) {
+        const stampsByIdentity = new Map(allStamps.map((stamp) => [identityKey(stamp.identity), stamp]));
+        if (expected.some((stamp) => {
+            const current = stampsByIdentity.get(identityKey(stamp.identity));
+            return !current || !sameStamp(current, stamp);
+        })) {
+            return result("stale", "revision-mismatch", "none", topology, allStamps, exclusions, []);
+        }
+    }
+    const selected = records.filter((record) => !exclusionKeys.has(identityKey(record.identity)));
+    const stamps = selected.map((record) => makeStamp(record, topology));
+    let unresolved;
+    const prepared = [];
+    for (const record of selected) {
+        if (!sameFrame(record.frame, frame)) {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        const stamp = makeStamp(record, topology);
+        prepared.push(Object.freeze({
+            record,
+            stamp,
+            boundsDistance: distanceToBounds(point, record.topology[topology].bounds),
+        }));
+    }
+    const candidates = prepared.filter(({ boundsDistance }) => boundsDistance < minimumDistance);
+    const witnesses = [];
+    for (const candidate of candidates) {
+        if (!candidate.record.capabilities.includes("nearest-surface")) {
+            if (unresolved !== "provider-contract-invalid")
+                unresolved = "nearest-surface-unsupported";
+            continue;
+        }
+        const reply = oracle.nearest(Object.freeze({
+            record: candidate.record,
+            topology,
+            point,
+            maximumDistance: searchDistance,
+        }));
+        if (reply === undefined) {
+            if (unresolved !== "provider-contract-invalid")
+                unresolved = "nearest-surface-unsupported";
+            continue;
+        }
+        if (typeof reply !== "object" ||
+            reply === null ||
+            (reply.kind !== "nearest" && reply.kind !== "no-hit" && reply.kind !== "unknown")) {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        let consumed;
+        try {
+            consumed = copyStamp(reply.kind === "nearest" ? reply.witness?.consumed : reply.consumed, "oracle.consumed");
+        }
+        catch {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        if (!sameStamp(consumed, candidate.stamp)) {
+            return result("stale", "oracle-stale", "none", topology, stamps, exclusions, witnesses);
+        }
+        if (reply.kind === "unknown") {
+            if (typeof reply.reason !== "string" || reply.reason.length === 0)
+                unresolved = "provider-contract-invalid";
+            else
+                unresolved ?? (unresolved = "oracle-unknown");
+            continue;
+        }
+        if (reply.kind === "no-hit")
+            continue;
+        let witness;
+        try {
+            const witnessPoint = finitePoint(reply.witness.point, "oracle.witness.point");
+            const distance = reply.witness.distance;
+            const actualDistance = pointDistance(point, witnessPoint);
+            if (!Number.isFinite(distance) ||
+                distance < 0 ||
+                distance > searchDistance ||
+                !Number.isFinite(actualDistance) ||
+                actualDistance > searchDistance ||
+                !sameDistance(distance, actualDistance) ||
+                !pointIsInside(witnessPoint, candidate.record.topology[topology].bounds))
+                throw new RangeError();
+            if (!sameFrame(copyFrame(reply.witness.frame, "oracle.witness.frame"), frame))
+                throw new TypeError();
+            witness = Object.freeze({
+                triangleId: nonEmpty(reply.witness.triangleId, "oracle.witness.triangleId"),
+                point: witnessPoint,
+                distance: actualDistance,
+                frame,
+                consumed: candidate.stamp,
+            });
+        }
+        catch {
+            unresolved = "provider-contract-invalid";
+            continue;
+        }
+        witnesses.push(witness);
+    }
+    const violation = witnesses.find((witness) => witness.distance < minimumDistance);
+    if (violation)
+        return result("violated", "clearance-violated", "exact", topology, stamps, exclusions, witnesses);
+    if (unresolved === "provider-contract-invalid")
+        return result("unsupported", "provider-contract-invalid", "none", topology, stamps, exclusions, witnesses);
+    if (unresolved === "nearest-surface-unsupported")
+        return result("unsupported", "nearest-surface-unsupported", "none", topology, stamps, exclusions, witnesses);
+    if (unresolved === "oracle-unknown")
+        return result("unknown", "oracle-unknown", "none", topology, stamps, exclusions, witnesses);
+    return result("satisfied", "clearance-satisfied", candidates.length > 0 && candidates.length === selected.length ? "exact" : "conservative", topology, stamps, exclusions, witnesses);
+}

package/docs/API.md

@@ -5,6 +5,45 @@ bindings, which are only available from `koota-kit/react` so the root entry
 never loads React. The module-specific import paths shown below can reduce
 coupling in larger codebases.
 
+## `spatial`
+
+Import from `koota-kit/spatial` or the root:
+
+```ts
+function queryPointClearance(
+  provider: SpatialProvider,
+  oracle: SpatialNearestSurfaceOracle,
+  query: SpatialClearanceQuery,
+): SpatialClearanceResult;
+```
+
+`queryPointClearance` decides one explicit predicate: the query point is at
+least `minimumDistance` from every selected **open surface**. The default
+selection is each part's `full` topology; callers must explicitly request
+`visible` topology. A provider record carries stable source, instance, part,
+and provider-local registration identity; a common Euclidean frame and unit;
+independent geometry, topology, pose, and transform revisions; and certified
+enclosing AABBs for both topology selections.
+
+The core performs deterministic AABB broadphase only. It invokes the supplied
+nearest-surface oracle for overlapping candidates and validates that its
+witness is in the selected certified bound, in the same frame/unit, and was
+computed from the exact consumed identity/topology/revision tuple. Results
+include those checked tuples, ordered witnesses, exclusions, one of
+`satisfied`, `violated`, `unknown`, `unsupported`, or `stale`, and an
+exactness label. An AABB rejection can conservatively satisfy the threshold;
+an oracle witness or a stamped bounded `no-hit` is exact. Satisfaction that
+combines AABB and oracle evidence is conservative. A stale expected/provider
+tuple wins before the result can be trusted; otherwise an exact violating
+witness wins over an unavailable or foreign-frame peer. Sparse provider
+snapshots and capability lists fail closed. Validated query thresholds are captured before any
+provider or oracle callback and cannot change during evaluation.
+
+There is no geometry kernel, BVH, renderer, model, physics, Koota, or React
+dependency in this entry. It does not prove containment or solid
+nonpenetration: an open-surface nearest query has no watertightness/thickness
+semantics. A future solid query needs an injected containment-capable oracle.
+
 ## `world`
 
 ### `createSimWorld(seeds)`

package/docs/ARCHITECTURE.md

@@ -13,6 +13,7 @@ rng ──────────────────> seedrandom + seed
 world ────────────────> koota + rng
 schedule ─────────────> world (advanceClock) + WorldHandle scratch
 eventLog ─────────────> WorldHandle scratch
+spatial ──────────────> (leaf: caller-provided provider + exact oracle)
 coordination ─────────> koota (borrowed World, no sibling runtime dependency)
 react ────────────────> koota/react + react + world (type only)
 index ────────────────> public re-exports only (never react)
@@ -45,6 +46,20 @@ than carrying it, so one huge dt cannot cause a catch-up storm.
 `eventLog` uses the handle's scratch map so event lifetime matches world
 lifetime. It does not use a process-global queue.
 
+`spatial` is a renderer-neutral leaf entry. Providers publish immutable,
+completed records with caller-owned source/instance/part/registration identity,
+common frame/unit, separate geometry/topology/pose/transform revisions, full
+and visible topology identities, and certified enclosing AABBs. The module
+sorts records deterministically, does only conservative AABB filtering, and
+delegates exact nearest-surface work to an injected oracle. It retains neither
+provider records nor buffers, so producer-owned buffers cannot be aliased by a
+core cache. Full topology is the default; a visible selection is explicit.
+Sparse provider slots and capability lists fail closed; copied query thresholds stay fixed through
+callbacks. Foreign-frame peers remain unresolved while compatible candidates
+are evaluated, preserving exact violation precedence. Satisfaction involving
+any AABB-only evidence remains conservative.
+Point clearance establishes distance to open surfaces only. It deliberately
+does not infer solid containment or nonpenetration from triangle proximity.
 `coordination` accepts an existing raw Koota `World` and attaches only its
 own ownership and registration traits. Its immutable snapshot is a completed
 metadata projection, not a second World or ECS serializer. The World retains
@@ -90,9 +105,12 @@ it reaches `react` or `koota/react`.
     delivered at any frame rate runs the same steps in the same order, as long
     as no single tick owes more than `maxSteps` (beyond that, the excess is
     dropped by design, so a one-second frame and sixty 1/60 s frames differ).
-11. A coordination snapshot publishes only fully validated completed metadata;
+11. Spatial query results are stamped with the provider's full identity,
+    selected topology, frame/unit, and independent completed revisions. A
+    mismatched expected or oracle-consumed tuple is stale, never exact.
+12. A coordination snapshot publishes only fully validated completed metadata;
     failed batch preparation leaves the prior projection visible.
-12. Coordination disposal never destroys or resets a caller-owned World,
+13. Coordination disposal never destroys or resets a caller-owned World,
     entity, caller trait, provider, or geometry buffer.
 
 ## Performance choices
@@ -102,6 +120,10 @@ it reaches `react` or `koota/react`.
   through JSON.
 - Event logs allocate on first push, leave scratch untouched for empty reads,
   truncate in place on drain, and expose a non-allocating `size` operation.
+- Spatial expected stamps use a per-query map keyed by the complete encoded
+  identity tuple. Matching all expectations takes linear lookup work after
+  preparing the snapshot, before any exclusions; no map is retained between
+  queries. Queries without expected stamps do not allocate this map.
 - Coordination snapshots are rebuilt only after a completed registration,
   publication, removal, or explicit prune. Equal completed revisions retain
   the prior snapshot identity and do not notify subscribers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koota-kit",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Deterministic Koota simulation conventions: world lifecycle, dual RNG streams, safe object traits, and world-scoped event logs.",
   "type": "module",
   "license": "MIT",
@@ -83,14 +83,14 @@
         "default": "./dist/cjs/eventLog.cjs"
       }
     },
-    "./coordination": {
+    "./spatial": {
       "import": {
-        "types": "./dist/esm/coordination.d.ts",
-        "default": "./dist/esm/coordination.js"
+        "types": "./dist/esm/spatial.d.ts",
+        "default": "./dist/esm/spatial.js"
       },
       "require": {
-        "types": "./dist/cjs/coordination.d.cts",
-        "default": "./dist/cjs/coordination.cjs"
+        "types": "./dist/cjs/spatial.d.cts",
+        "default": "./dist/cjs/spatial.cjs"
       }
     },
     "./react": {
@@ -103,7 +103,17 @@
         "default": "./dist/cjs/react.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./coordination": {
+      "import": {
+        "types": "./dist/esm/coordination.d.ts",
+        "default": "./dist/esm/coordination.js"
+      },
+      "require": {
+        "types": "./dist/cjs/coordination.d.cts",
+        "default": "./dist/cjs/coordination.cjs"
+      }
+    }
   },
   "files": [
     "CHANGELOG.md",
@@ -215,14 +225,17 @@
       "eventLog": [
         "./dist/esm/eventLog.d.ts"
       ],
-      "coordination": [
-        "./dist/esm/coordination.d.ts"
+      "spatial": [
+        "./dist/esm/spatial.d.ts"
       ],
       "react": [
         "./dist/esm/react.d.ts"
       ],
       "*": [
         "./dist/esm/index.d.ts"
+      ],
+      "coordination": [
+        "./dist/esm/coordination.d.ts"
       ]
     }
   },