@driftengine/script 3.61.0

package/dist/host.js

@@ -0,0 +1,233 @@
+import { BEHAVIOR_CAPABILITIES, BEHAVIOR_MODULE, BEHAVIOR_TYPES, behaviorImplementation, } from './bindings/behavior.js';
+import { NAVIGATION_CAPABILITIES, NAVIGATION_MODULE, NAVIGATION_TYPES, navigationImplementation, } from './bindings/navigation.js';
+import { TERRAIN_CAPABILITIES, TERRAIN_MODULE, TERRAIN_TYPES, terrainImplementation, } from './bindings/terrain.js';
+import { SPRITES_CAPABILITIES, SPRITES_MODULE, SPRITES_TYPES, spritesImplementation, } from './bindings/sprites.js';
+import { INTERFACE_CAPABILITIES, INTERFACE_MODULE, INTERFACE_TYPES, interfaceImplementation, } from './bindings/interface.js';
+import { EDITOR_CAPABILITIES, EDITOR_MODULE, EDITOR_TYPES, editorImplementation, } from './bindings/editor.js';
+import { NETWORK_CAPABILITIES, NETWORK_MODULE, NETWORK_TYPES, networkImplementation, } from './bindings/network.js';
+import { ROLLBACK_CAPABILITIES, ROLLBACK_MODULE, ROLLBACK_TYPES, rollbackImplementation, } from './bindings/rollback.js';
+import { bindHost, createRegistry, defineTarget, } from 'driftscript';
+import { AI_CAPABILITIES, AI_MODULE, AI_TYPES, aiImplementation, } from './bindings/ai.js';
+import { AUDIO_CAPABILITIES, AUDIO_MODULE, AUDIO_TYPES, audioImplementation, } from './bindings/audio.js';
+import { XR_CAPABILITIES, XR_MODULE, XR_TYPES, xrImplementation, } from './bindings/xr.js';
+import { RENDER_CAPABILITIES, RENDER_MODULE, RENDER_TYPES, renderImplementation, } from './bindings/render.js';
+import { ANIMATION_CAPABILITIES, ANIMATION_MODULE, ANIMATION_TYPES, animationImplementation, } from './bindings/animation.js';
+import { CAMERA_CAPABILITIES, CAMERA_MODULE, CORE_TYPES, EVENTS_CAPABILITIES, EVENTS_MODULE, INPUT_CAPABILITIES, INPUT_MODULE, PERSISTENCE_CAPABILITIES, PERSISTENCE_MODULE, PHYSICS_CAPABILITIES, PHYSICS_MODULE, RANDOM_CAPABILITIES, RANDOM_MODULE, SCENE_CAPABILITIES, SCENE_MODULE, TIME_CAPABILITIES, TIME_MODULE, cameraImplementation, eventsImplementation, inputImplementation, persistenceImplementation, physicsImplementation, randomImplementation, sceneImplementation, timeImplementation, } from './bindings/core.js';
+import { ECS_CAPABILITIES, QUERY_CAPABILITIES, ECS_MODULE, ENTITY_TYPES, PREFAB_CAPABILITIES, PREFAB_MODULE, entitiesImplementation, prefabImplementation, } from './bindings/entities.js';
+import { CHEMISTRY_CAPABILITIES, CHEMISTRY_MODULE, CHEMISTRY_TYPES, chemistryImplementation, } from './bindings/chemistry.js';
+import { registerStd, stdImplementations } from 'driftscript/std';
+/**
+ * What the engine can provide. Everything wired; nothing that is not.
+ *
+ * `drift/core` is deliberately absent: §11 gives its provider as `startLoop` and `LoopHooks`, which
+ * are what *drives* a script rather than what a script calls. A module with nothing to call is not
+ * registered rather than registered empty.
+ */
+export const ENGINE_MODULES = [
+    AI_MODULE,
+    XR_MODULE,
+    ANIMATION_MODULE,
+    BEHAVIOR_MODULE,
+    AUDIO_MODULE,
+    CAMERA_MODULE,
+    CHEMISTRY_MODULE,
+    ECS_MODULE,
+    EDITOR_MODULE,
+    EVENTS_MODULE,
+    NETWORK_MODULE,
+    ROLLBACK_MODULE,
+    INPUT_MODULE,
+    NAVIGATION_MODULE,
+    PERSISTENCE_MODULE,
+    PHYSICS_MODULE,
+    RANDOM_MODULE,
+    RENDER_MODULE,
+    SCENE_MODULE,
+    SPRITES_MODULE,
+    TERRAIN_MODULE,
+    TIME_MODULE,
+    INTERFACE_MODULE,
+];
+/**
+ * A registry describing this engine's capabilities.
+ *
+ * Built rather than exported as a constant, because a registry refuses a duplicate registration —
+ * two consumers sharing one module-level instance would be one consumer's startup failing on
+ * another's import. Cheap: a few dozen object literals.
+ */
+export function engineRegistry() {
+    const registry = createRegistry();
+    /* The standard library first, because it belongs to the language rather than to this host and a
+       host that forgot it would produce scripts that fail on `math.clamp`. */
+    registerStd(registry);
+    for (const type of [
+        ...AI_TYPES,
+        ...AUDIO_TYPES,
+        ...ANIMATION_TYPES,
+        ...CHEMISTRY_TYPES,
+        ...CORE_TYPES,
+        ...ENTITY_TYPES,
+        ...BEHAVIOR_TYPES,
+        ...NAVIGATION_TYPES,
+        ...TERRAIN_TYPES,
+        ...SPRITES_TYPES,
+        ...INTERFACE_TYPES,
+        ...EDITOR_TYPES,
+        ...NETWORK_TYPES,
+        ...ROLLBACK_TYPES,
+        ...RENDER_TYPES,
+        ...XR_TYPES,
+    ]) {
+        registry.addType(type);
+    }
+    for (const capability of [
+        ...AI_CAPABILITIES,
+        ...ANIMATION_CAPABILITIES,
+        ...AUDIO_CAPABILITIES,
+        ...BEHAVIOR_CAPABILITIES,
+        ...CAMERA_CAPABILITIES,
+        ...CHEMISTRY_CAPABILITIES,
+        ...ECS_CAPABILITIES,
+        ...EDITOR_CAPABILITIES,
+        ...NETWORK_CAPABILITIES,
+        ...ROLLBACK_CAPABILITIES,
+        ...QUERY_CAPABILITIES,
+        ...EVENTS_CAPABILITIES,
+        ...INPUT_CAPABILITIES,
+        ...NAVIGATION_CAPABILITIES,
+        ...PERSISTENCE_CAPABILITIES,
+        ...PHYSICS_CAPABILITIES,
+        ...PREFAB_CAPABILITIES,
+        ...RANDOM_CAPABILITIES,
+        ...RENDER_CAPABILITIES,
+        ...XR_CAPABILITIES,
+        ...SCENE_CAPABILITIES,
+        ...SPRITES_CAPABILITIES,
+        ...INTERFACE_CAPABILITIES,
+        ...TERRAIN_CAPABILITIES,
+        ...TIME_CAPABILITIES,
+    ]) {
+        registry.add(capability);
+    }
+    return registry;
+}
+/**
+ * A target providing everything this engine has wired.
+ *
+ * A consumer that wants less passes its own list. **A consumer that wants more cannot** — the
+ * manifest may only name modules something provides, so a target claiming `drift/ecs` is refused
+ * at the manifest rather than at every call site.
+ */
+export function engineTarget(name = 'driftengine') {
+    return defineTarget(name, ENGINE_MODULES);
+}
+/**
+ * The implementation map a generated module's `__bind` receives.
+ *
+ * Keyed by logical module name, because that is what generated code looks up: `audio` in a `.drs`
+ * file is `$host['drift/audio']` in the output.
+ *
+ * **A service the consumer did not supply is absent rather than stubbed.** A module that binds it
+ * and then calls it fails at the call with the namespace's own name in the error, which is what the
+ * rule against silent no-ops asks for — a stub that quietly did nothing would make a script that
+ * plays no sound indistinguishable from one whose audio is not connected.
+ */
+export function engineImplementations(services) {
+    /* The standard library is merged in rather than bound separately, because a module importing both
+       `std/math` and `drift/audio` receives one host object. Leaving it to a consumer would produce a
+       script that fails on `math.clamp` with the namespace undefined. */
+    const map = { ...stdImplementations() };
+    if (services.audio !== undefined) {
+        map[AUDIO_MODULE] = audioImplementation(services.audio.graph, services.audio.registry);
+    }
+    if (services.clocks !== undefined)
+        map[TIME_MODULE] = timeImplementation(services.clocks);
+    if (services.entities !== undefined) {
+        map[ECS_MODULE] = entitiesImplementation(services.entities);
+        map[PREFAB_MODULE] = prefabImplementation(services.entities);
+    }
+    /*
+     * These four take their handle as an argument rather than from the host, so they need nothing
+     * supplied and are always available. A script passes the `Node` or the `Actions` it was given.
+     */
+    map[RANDOM_MODULE] = randomImplementation();
+    map[SCENE_MODULE] = sceneImplementation();
+    map[RENDER_MODULE] = renderImplementation();
+    map[PHYSICS_MODULE] = physicsImplementation();
+    map[CAMERA_MODULE] = cameraImplementation();
+    map[ANIMATION_MODULE] = animationImplementation();
+    map[EVENTS_MODULE] = eventsImplementation();
+    map[PERSISTENCE_MODULE] = persistenceImplementation();
+    /* **Unconditional, unlike the four below it.** Every terrain capability takes the field it is
+       asking about, so the module needs nothing from the host: a `Terrain` reaches a script through
+       `uses`, the way a `NavGraph` does. There is nothing for an absent service to make fail. */
+    map[TERRAIN_MODULE] = terrainImplementation();
+    /* Unconditional for the same reason: every capability takes the batch, sheet, map or tree it
+       acts on, so neither module needs anything from the host to answer. */
+    map[SPRITES_MODULE] = spritesImplementation();
+    map[INTERFACE_MODULE] = interfaceImplementation();
+    map[INPUT_MODULE] = inputImplementation();
+    /* And once more for `drift/editor`: every capability takes the gizmo it is asking about, which
+       reaches a script through `uses`. There is nothing for an absent service to make fail. */
+    map[EDITOR_MODULE] = editorImplementation();
+    /* And the two Track J surfaces: each capability takes the session or the rewind it asks about,
+       so neither needs anything from the host beyond the handle a script is given through `uses`. */
+    map[NETWORK_MODULE] = networkImplementation();
+    map[ROLLBACK_MODULE] = rollbackImplementation();
+    /* `drift/ai` needs a registry for the same reason `drift/audio` needs one: an opaque
+       handle has to enter a script through a capability, and which agents exist in a
+       scene is not something an engine can know. Absent means a script's `ai.agent` calls
+       resolve to nothing — the same bargain every other optional service makes. */
+    if (services.ai !== undefined)
+        map[AI_MODULE] = aiImplementation(services.ai);
+    if (services.xr !== undefined)
+        map[XR_MODULE] = xrImplementation(services.xr);
+    /* And `drift/chemistry` needs a world for the same reason: a `Chemistry` handle has to enter a
+       script through a capability, and which parcels exist in a scene is not something an engine can
+       know. */
+    if (services.chemistry !== undefined) {
+        map[CHEMISTRY_MODULE] = chemistryImplementation(services.chemistry);
+    }
+    /* And `drift/navigation` needs the network, for the reason above stated once more: which places
+       a world has and which of them connect is the world's, not the engine's. */
+    if (services.navigation !== undefined) {
+        map[NAVIGATION_MODULE] = navigationImplementation(services.navigation);
+    }
+    /* And `drift/behavior` needs to know what a tick is handed, which is the consumer's world. */
+    if (services.behavior !== undefined) {
+        map[BEHAVIOR_MODULE] = behaviorImplementation(services.behavior);
+    }
+    return map;
+}
+/**
+ * Give a loaded module its host, and refuse in words when the host cannot satisfy it.
+ *
+ * Checked against `__drift.requires` before anything is called, so a missing service is reported at
+ * bind time naming the module — rather than at the first capability call, deep in a frame, as an
+ * undefined property.
+ */
+export function bindModule(module, services) {
+    const implementations = engineImplementations(services);
+    const missing = module.info.requires.filter((required) => required.startsWith('drift/') && implementations[required] === undefined);
+    if (missing.length > 0) {
+        return {
+            bound: false,
+            reason: `\`${module.info.module}\` requires ${missing.map((m) => `\`${m}\``).join(', ')}, which ` +
+                'this host has not been given. Pass the service to `bindModule` before loading the module.',
+        };
+    }
+    /*
+     * Through `bindHost` rather than by calling `__bind` directly, because the runtime has to
+     * remember which host this module was bound to.
+     *
+     * `patchModule` re-binds the new version to it. Calling `__bind` here would bind this version and
+     * leave the next one with every namespace at `undefined` — which is what happened for as long as
+     * `__bind` has existed, invisible because the only module anything ever patched imported no
+     * capability at all.
+     *
+     * A module with no capability imports has no `__bind`; `bindHost` treats that as a no-op, because
+     * a consumer should not have to know which of its scripts happen to use one.
+     */
+    bindHost(module, implementations);
+    return { bound: true };
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/script` — the `drift/*` bindings, and the only place the engine and the language
+ * are coupled.
+ *
+ * `driftscript` is host-neutral and imports no `@driftengine/*` at all, which three separate
+ * mechanisms assert. Everything this engine contributes to the language arrives through this
+ * package: registry entries describing capabilities that already exist, and the implementations a
+ * host hands to a compiled module.
+ *
+ * **There is no new engine code here.** A binding is a description plus a lookup. If one needed the
+ * engine to grow a function, that function belongs in the package that owns the subsystem, and the
+ * binding then describes it like any other.
+ */
+export { AUDIO_CAPABILITIES, AUDIO_MODULE, AUDIO_TYPES, audioImplementation, } from './bindings/audio.ts';
+export type { ChemistryServices } from './bindings/chemistry.ts';
+export { CHEMISTRY_CAPABILITIES, CHEMISTRY_COMPONENT, CHEMISTRY_MODULE, CHEMISTRY_TYPES, chemistryImplementation, } from './bindings/chemistry.ts';
+export type { ComponentRegistry, RegisteredModule } from './entityHost.ts';
+export { assertHostShapes, registerEntityModule } from './entityHost.ts';
+export type { BindResult, HostServices } from './host.ts';
+export { ENGINE_MODULES, bindModule, engineImplementations, engineRegistry, engineTarget, } from './host.ts';

package/dist/index.js

@@ -0,0 +1,18 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/script` — the `drift/*` bindings, and the only place the engine and the language
+ * are coupled.
+ *
+ * `driftscript` is host-neutral and imports no `@driftengine/*` at all, which three separate
+ * mechanisms assert. Everything this engine contributes to the language arrives through this
+ * package: registry entries describing capabilities that already exist, and the implementations a
+ * host hands to a compiled module.
+ *
+ * **There is no new engine code here.** A binding is a description plus a lookup. If one needed the
+ * engine to grow a function, that function belongs in the package that owns the subsystem, and the
+ * binding then describes it like any other.
+ */
+export { AUDIO_CAPABILITIES, AUDIO_MODULE, AUDIO_TYPES, audioImplementation, } from './bindings/audio.js';
+export { CHEMISTRY_CAPABILITIES, CHEMISTRY_COMPONENT, CHEMISTRY_MODULE, CHEMISTRY_TYPES, chemistryImplementation, } from './bindings/chemistry.js';
+export { assertHostShapes, registerEntityModule } from './entityHost.js';
+export { ENGINE_MODULES, bindModule, engineImplementations, engineRegistry, engineTarget, } from './host.js';

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@driftengine/script",
+  "version": "3.61.0",
+  "description": "The drift/* capability bindings: what this engine provides to DriftScript, and the only place the two are coupled",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./capabilities.json": "./capabilities.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "driftscript": "1.13.0"
+  },
+  "peerDependencies": {
+    "@driftengine/ai": "3.61.0",
+    "@driftengine/animation": "3.61.0",
+    "@driftengine/audio": "3.61.0",
+    "@driftengine/chemistry": "3.61.0",
+    "@driftengine/core": "3.61.0",
+    "@driftengine/editor": "3.61.0",
+    "@driftengine/entities": "3.61.0",
+    "@driftengine/network": "3.61.0",
+    "@driftengine/terrain": "3.61.0",
+    "@driftengine/ui2d": "3.61.0",
+    "@driftengine/xr": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/script"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "scripting",
+    "driftscript",
+    "bindings"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bindings/ai.ts

@@ -0,0 +1,306 @@
+/**
+ * `drift/ai` — what this engine lets a script ask of an agent.
+ *
+ * **Deliberately small, and deliberately not a way to call a model.** A script wakes an
+ * agent, asks it to consider, and reads what it is doing. It never awaits a provider,
+ * because a script that could would be a script that can stall a fixed step for five
+ * seconds — and the whole of Track O is the argument that nothing should.
+ *
+ * Three constraints this surface inherits:
+ *
+ * - **`ai` is outside the determinism boundary.** A `@deterministic` function may not
+ *   call any of it. The floor is deterministic and runs inside the simulation; asking a
+ *   provider is not, and the compiler is making a line that already exists visible.
+ * - **Nothing here returns a model's answer.** `wake` and `consider` are requests that
+ *   an agent think, and they return immediately. What the agent decided arrives as the
+ *   intent its session hands the consumer on a later tick.
+ * - **Reading is cheap and stays inside the boundary.** `intentId` and `degraded` are
+ *   `@deterministic`-safe: the current intent is state the simulation already owns,
+ *   because a deterministic floor put it there and a replay recomputes it.
+ */
+import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+import type { AgentSession, NavigateArgs, NavigateResult, ToolDefinition } from '@driftengine/ai';
+import type { NavPath } from '@driftengine/core';
+
+export const AI_MODULE = 'drift/ai';
+
+/**
+ * A live agent session, held by a script and passed back to the engine.
+ *
+ * Opaque, for the reason `Sound` is: a script that could read its fields would be a
+ * script depending on a representation this package cannot then change.
+ */
+export const AI_TYPES: readonly OpaqueType[] = [
+  {
+    module: AI_MODULE,
+    name: 'Agent',
+    doc: 'A live agent session. Held and passed back; never read into.',
+  },
+];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  effects: CapabilityDefinition['effects'],
+  deterministic: boolean,
+  doc: string,
+  implementation: string,
+): CapabilityDefinition =>
+  defineCapability({
+    module: AI_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    deterministic,
+    doc,
+    implementation,
+  });
+
+export const AI_CAPABILITIES: readonly CapabilityDefinition[] = [
+  define(
+    'agent',
+    [{ name: 'id', type: 'String' }],
+    /*
+     * `Agent?`, and the `?` is the point, exactly as it is for `audio.sound`.
+     *
+     * A consumer registers the agents a script may talk to, and a script naming one
+     * that was not registered is ordinary rather than exceptional — a scene loaded
+     * without its agents, a name that moved. Returning a bare `Agent` would make every
+     * script that forgot to check talk to nothing and report success.
+     */
+    'Agent?',
+    ['pure'],
+    true,
+    'Resolve an agent by the id the consumer registered it under. Absent when there is none.',
+    'AgentRegistry.get',
+  ),
+  define(
+    'wake',
+    [
+      { name: 'agent', type: 'Agent' },
+      { name: 'reason', type: 'String' },
+      { name: 'priority', type: 'i32' },
+    ],
+    'void',
+    ['ai'],
+    false,
+    'Tell an agent something happened. Returns immediately; the agent acts at its next tick.',
+    'AgentSession.observe',
+  ),
+  define(
+    'consider',
+    [{ name: 'agent', type: 'Agent' }],
+    'void',
+    ['ai'],
+    false,
+    'Ask an agent to think, at ordinary priority. Returns immediately.',
+    'AgentSession.consider',
+  ),
+  define(
+    'intentId',
+    [{ name: 'agent', type: 'Agent' }],
+    'String',
+    ['pure'],
+    /*
+     * Readable from a `@deterministic` function, unlike everything else here.
+     *
+     * The current intent is state the simulation already owns — the floor put it there
+     * and a replay recomputes it — so reading it is reading the simulation rather than
+     * reaching outside it. Asking a provider is the part that is nondeterministic, and
+     * that is what `wake` and `consider` carry `ai` for.
+     */
+    true,
+    'What the agent is doing now. Empty before its first tick.',
+    'AgentSession.intentId',
+  ),
+  define(
+    'degraded',
+    [{ name: 'agent', type: 'Agent' }],
+    'bool',
+    ['pure'],
+    true,
+    'Whether the agent is over budget and running on its policy floor alone.',
+    'AgentSession.degraded',
+  ),
+
+  /*
+   * The two bridges, and every effect below is inherited rather than invented.
+   *
+   * **None of these duplicates `drift/navigation`.** That module binds twelve capabilities and
+   * every one takes a `NavPath` or a `NavGraph`; what a script could not do is aim any of them at
+   * an `Agent`, which is a session keyed by an id the consumer registered. `path` is the join, so
+   * one capability makes all twelve work on an agent instead of any being bound a second time.
+   */
+  define(
+    'reachable',
+    [
+      { name: 'agent', type: 'Agent' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'bool',
+    ['navigation.read'],
+    /*
+     * Deterministic, and it is the admission guard as a question. `navigation.route` computes *and
+     * writes*, so a script wanting to score a destination before committing to it had to route and
+     * then undo — which is a write a `@deterministic` system would have had to make and take back.
+     */
+    true,
+    'Whether a route exists from where this agent is to a point, without writing one.',
+    'navigationBridge.admits',
+  ),
+  define(
+    'navigate',
+    [
+      { name: 'agent', type: 'Agent' },
+      { name: 'x', type: 'float' },
+      { name: 'y', type: 'float' },
+      { name: 'z', type: 'float' },
+    ],
+    'bool',
+    ['navigation.write'],
+    /*
+     * **Deterministic, and safe on every peer, which only looks like it contradicts `deciding`.**
+     * The authority rule is about *model*-authored intents: a provider is nondeterministic, slow
+     * and metered, so two peers running one diverge. A script's own command is a function of the
+     * simulation — DriftScript 1.12.0 admitted `navigation.write` to `DETERMINISTIC_EFFECTS` on
+     * exactly that argument, since a route is a function of the graph and two endpoints and
+     * `navSearch` breaks ties on the node index — so every peer computes the same route and it
+     * replicates itself by being re-run.
+     */
+    true,
+    'Route this agent to a point. False when no route exists, and then it clears the old one.',
+    'navigationBridge.execute',
+  ),
+  define(
+    'path',
+    [{ name: 'agent', type: 'Agent' }],
+    /*
+     * `NavPath?`, from `drift/navigation`. Cross-module opaque types are ordinary here:
+     * `drift/editor.rebuildTree` takes a `drift/scene.Node` and `drift/ui.draw` takes a
+     * `drift/2d.SpriteBatch`.
+     *
+     * Optional because an agent the consumer never gave a route object to is ordinary rather than
+     * exceptional, and a bare `NavPath` would hand every script that forgot to check a handle to
+     * nothing.
+     */
+    'NavPath?',
+    ['navigation.read'],
+    true,
+    'The route object this agent follows, for `drift/navigation` to read or steer along.',
+    'AgentNavigation.pathOf',
+  ),
+  define(
+    'deciding',
+    [{ name: 'agent', type: 'Agent' }],
+    'bool',
+    /*
+     * `network.read`, and inside `DETERMINISTIC_EFFECTS`, on the same narrowing
+     * `drift/network.authority` already uses: which participant this is, and whether it is the
+     * authority, are facts that cannot vary with packet timing. This is that fact per agent.
+     */
+    ['network.read'],
+    true,
+    'Whether this peer decides this agent’s model intents. Elsewhere they arrive already taken.',
+    'AuthoritativeAgent.deciding',
+  ),
+];
+
+/**
+ * A consumer's agents, by the id a script may name them with.
+ *
+ * The registry is the consumer's, exactly as `SoundRegistry` is: this package owns the
+ * loop and the floor, and which agents exist in a scene is not something an engine can
+ * know.
+ */
+export interface AgentRegistry {
+  get(id: string): AgentSession | undefined;
+}
+
+/**
+ * What the navigation bridge needs from the host to answer for an agent.
+ *
+ * The world and the tools are the consumer's: `navigationBridge` is a factory over their adapter,
+ * and this is where the result of that factory meets a script.
+ */
+export interface AgentNavigation<W = unknown> {
+  readonly world: W;
+  readonly tools: readonly ToolDefinition<NavigateArgs, NavigateResult, W>[];
+  pathOf(agentId: string): NavPath | undefined;
+}
+
+/** Which agents this peer decides for. One method, because that is the whole script-visible fact. */
+export interface AgentAuthority {
+  deciding(agentId: string): boolean;
+}
+
+export interface AiServices<W = unknown> {
+  readonly agents: AgentRegistry;
+  /** Absent means `reachable`, `navigate` and `path` fail at the call saying what to provide. */
+  readonly navigation?: AgentNavigation<W>;
+  /** Absent means `deciding` fails at the call. */
+  readonly authority?: AgentAuthority;
+}
+
+/**
+ * Missing wiring fails at the call, naming what is absent.
+ *
+ * **Not a falsy default**, for the reason `HostServices` already gives about `drift/behavior`: a
+ * stub makes an agent whose routine never runs look exactly like one standing about with nothing to
+ * do. `navigate` returning `false` because nobody wired a bridge is indistinguishable from `false`
+ * because there is no route, and the second is a thing a script is meant to handle.
+ */
+function required<T>(value: T | undefined, what: string): T {
+  if (value === undefined) {
+    throw new Error(
+      `drift/ai: this host provides no ${what}, so that capability cannot answer. Pass it in ` +
+        `\`services.ai\` — see \`navigationBridge\` in @driftengine/ai.`,
+    );
+  }
+  return value;
+}
+
+/** The implementations the host supplies at link time, keyed by capability name. */
+export function aiImplementation(services: AiServices): Readonly<Record<string, unknown>> {
+  const { agents } = services;
+  const navigate = (
+    agent: AgentSession,
+    x: number,
+    y: number,
+    z: number,
+    act: boolean,
+  ): boolean => {
+    const nav = required(services.navigation, 'navigation bridge');
+    const tool = nav.tools.find((candidate) => candidate.id === 'navigate@1');
+    if (tool === undefined) return false;
+    const args = { agentId: agent.agentId, x, y, z };
+    /* `admits` is the guard and `execute` is the act, and `reachable` is deliberately the first
+       without the second — the whole point of exposing it is not having to route and undo. */
+    return act ? tool.execute(args, nav.world).found : tool.admits(args, nav.world);
+  };
+
+  return {
+    agent: (id: string): AgentSession | undefined => agents.get(id),
+    wake: (agent: AgentSession, reason: string, priority: number): void => {
+      agent.observe({ id: reason, priority, text: reason });
+    },
+    consider: (agent: AgentSession): void => {
+      agent.observe({ id: 'consider', priority: 0, text: 'consider' });
+    },
+    intentId: (agent: AgentSession): string => agent.current?.id ?? '',
+    degraded: (agent: AgentSession): boolean => agent.degraded,
+
+    reachable: (agent: AgentSession, x: number, y: number, z: number): boolean =>
+      navigate(agent, x, y, z, false),
+    navigate: (agent: AgentSession, x: number, y: number, z: number): boolean =>
+      navigate(agent, x, y, z, true),
+    path: (agent: AgentSession): NavPath | undefined =>
+      required(services.navigation, 'navigation bridge').pathOf(agent.agentId),
+    deciding: (agent: AgentSession): boolean =>
+      required(services.authority, 'authority bridge').deciding(agent.agentId),
+  };
+}