@rpgm-tools/neo-angband-core 0.10.0

package/dist/z-queue.js

@@ -0,0 +1,283 @@
+/**
+ * The integer priority queue from reference/src/z-queue.c (Angband 4.2.6): the
+ * two sift helpers up_heap (L115) and down_heap (L139), qp_new (L194),
+ * qp_resize (L224), qp_flush (L251), qp_free (L271), qp_size (L291),
+ * qp_len (L300), qp_push_int / qp_push_ptr (L317 / L337), qp_pop_int /
+ * qp_pop_ptr (L358 / L382), qp_pushpop_int / qp_pushpop_ptr (L410 / L449),
+ * qp_peek_int / qp_peek_ptr (L478 / L490) and qp_isinvalid (L500).
+ *
+ * It is a min-heap packed into an array: the LOWEST priority pops first.
+ *
+ * WHY THIS IS CORE AND NOT PLUMBING. find_path (player-path.c L1069) - the
+ * routine do_cmd_pathfind calls to travel to a clicked grid - runs A* over this
+ * heap. A heap is not a set: when several grids share a priority, WHICH one
+ * pops first is decided entirely by the sift order in up_heap / down_heap and
+ * by qp_pushpop_int's preference for the incoming element on a tie (L415). On
+ * an open floor equal-cost routes are everywhere, so those comparisons pick the
+ * route the character actually walks. Every one of them is therefore
+ * transcribed rather than reimplemented - in particular the asymmetric pair in
+ * down_heap's two-child branch (L158-L162), where the parent is compared to
+ * child1 with `>` but to child1 + 1 with `<=`, and the two children with `<`.
+ * A textbook "swap with the smaller child" heap is NOT this heap.
+ *
+ * THE ONE STRUCTURAL DIFFERENCE. Upstream keeps the payload in a
+ * `union { void *p; int i; }` and exposes each half through its own entry point
+ * (qp_push_int vs qp_push_ptr, qp_pop_int vs qp_pop_ptr, ...), declaring it
+ * undefined behaviour to mix the two in one queue. The bodies of each pair are
+ * line-for-line identical - only the union member read differs. TypeScript has
+ * a single payload slot and no tagged union, so the pair collapses into one
+ * generic parameter: `PriorityQueue<number>` is upstream's `_int` queue and
+ * `PriorityQueue<SomeObject>` its `_ptr` queue, with reference identity
+ * standing in for pointer identity.
+ *
+ * THE payload_free CALLBACK. Upstream's qp_resize / qp_flush / qp_free take a
+ * `void (*payload_free)(void*)` so the C can release memory it owns. JS is
+ * garbage-collected, so nothing here needs freeing - but the callback cannot be
+ * dropped, because passing NULL rather than non-NULL selects DIFFERENT
+ * BEHAVIOUR in qp_resize (L231): with a NULL callback the elements that no
+ * longer fit are not discarded, and the queue is left with count > size. That
+ * wart is reproduced; the callback is invoked on every element the C would have
+ * freed, so a caller can observe which ones those are.
+ */
+/**
+ * struct priority_queue (z-queue.h L59): a min-heap packed into an array.
+ *
+ * `count` is the occupancy and lives as `data.length`; `size` is the separately
+ * tracked capacity qp_new allocated, which upstream's callers grow explicitly
+ * (find_path, player-path.c L1253-L1258) rather than relying on the array to
+ * grow itself.
+ */
+export class PriorityQueue {
+    data = [];
+    capacity;
+    /**
+     * qp_new (L194). Upstream quit()s when the requested size would overflow
+     * SIZE_MAX / MAX(2, sizeof(element)); a JS array has no such ceiling, so the
+     * only thing kept is the recorded capacity.
+     */
+    constructor(size) {
+        this.capacity = size;
+    }
+    /** qp_size (L291): the maximum number of elements the queue can hold. */
+    size() {
+        return this.capacity;
+    }
+    /** qp_len (L300): the number of elements currently in the queue. */
+    len() {
+        return this.data.length;
+    }
+    /**
+     * up_heap (L115): push the ith element upward while its priority is less
+     * than its parent's.
+     */
+    upHeap(i) {
+        for (;;) {
+            if (i === 0)
+                break;
+            const parent = (i - 1) >> 1;
+            if (this.data[i].priority >=
+                this.data[parent].priority) {
+                break;
+            }
+            this.swap(i, parent);
+            i = parent;
+        }
+    }
+    /**
+     * down_heap (L139): push the ith element downward while its priority is
+     * greater than a child's. The comparisons are upstream's, including the
+     * `<=` / `<` asymmetry that decides which child a tie sinks through.
+     */
+    downHeap(i) {
+        const count = this.data.length;
+        for (;;) {
+            const child1 = (i << 1) + 1;
+            if (child1 >= count)
+                break;
+            const pri = this.data[i].priority;
+            const pri1 = this.data[child1].priority;
+            if (child1 === count - 1) {
+                /* There's only one child. */
+                if (pri <= pri1)
+                    break;
+                this.swap(i, child1);
+                break;
+            }
+            const pri2 = this.data[child1 + 1].priority;
+            if (pri > pri1) {
+                if (pri <= pri2 || pri1 < pri2) {
+                    this.swap(i, child1);
+                    i = child1;
+                }
+                else {
+                    this.swap(i, child1 + 1);
+                    i = child1 + 1;
+                }
+            }
+            else if (pri > pri2) {
+                this.swap(i, child1 + 1);
+                i = child1 + 1;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    swap(a, b) {
+        const tmp = this.data[a];
+        this.data[a] = this.data[b];
+        this.data[b] = tmp;
+    }
+    /**
+     * qp_push_int (L317) / qp_push_ptr (L337): push a payload with the given
+     * priority. Upstream asserts count < size and is otherwise undefined; the
+     * assert is kept as a throw so a caller that forgets to resize (as find_path
+     * does at L1253) is caught rather than silently corrupting the heap.
+     */
+    push(priority, payload) {
+        if (this.data.length >= this.capacity) {
+            throw new Error("priority queue overflow (qp_push past qp_size)");
+        }
+        this.data.push({ priority, payload });
+        this.upHeap(this.data.length - 1);
+    }
+    /**
+     * qp_pop_int (L358) / qp_pop_ptr (L382): pop the head and return its
+     * payload. Undefined upstream when the queue is empty.
+     */
+    pop() {
+        if (this.data.length === 0) {
+            throw new Error("priority queue underflow (qp_pop while empty)");
+        }
+        const result = this.data[0].payload;
+        const last = this.data.pop();
+        if (this.data.length > 0) {
+            /* C: --count; data[0] = data[count]; i.e. the old tail becomes the root
+             * (a no-op self-assignment when the queue had one element). */
+            this.data[0] = last;
+            this.downHeap(0);
+        }
+        return result;
+    }
+    /**
+     * qp_pushpop_int (L410) / qp_pushpop_ptr (L449): push then pop the head, in
+     * one pass and without growing the heap.
+     *
+     * The `priority <= data[0].priority` test at L415 hands the NEW element
+     * straight back on a tie, leaving the heap untouched - that is the tie-break
+     * find_path leans on at L1281 when the last neighbour it examined ties with
+     * the best pending grid.
+     */
+    pushpop(priority, payload) {
+        const count = this.data.length;
+        if (count === 0 || priority <= this.data[0].priority) {
+            return payload;
+        }
+        const result = this.data[0].payload;
+        if (priority <= this.data[count - 1].priority) {
+            this.data[0] = { priority, payload };
+        }
+        else {
+            this.data[0] = this.data[count - 1];
+            this.data[count - 1] = { priority, payload };
+        }
+        this.downHeap(0);
+        return result;
+    }
+    /**
+     * qp_peek_int (L478) / qp_peek_ptr (L490): the payload at the head.
+     * Undefined upstream when the queue is empty.
+     */
+    peek() {
+        if (this.data.length === 0) {
+            throw new Error("priority queue underflow (qp_peek while empty)");
+        }
+        return this.data[0].payload;
+    }
+    /**
+     * qp_resize (L224): change the capacity. Returns false on success, as
+     * upstream does (the SIZE_MAX overflow that makes it return true has no JS
+     * counterpart, so it always succeeds).
+     *
+     * WART KEPT: the elements that no longer fit are dropped only when
+     * payloadFree is supplied (L231, `size < qp->count && payload_free`). With no
+     * callback the occupancy is left alone and the queue ends up with
+     * count > size, which upstream's own qp_size / qp_len asserts would then
+     * trip. Callers that shrink are expected to pass a callback; find_path only
+     * ever grows.
+     */
+    resize(size, payloadFree) {
+        if (size < this.data.length && payloadFree) {
+            for (let i = size; i < this.data.length; ++i) {
+                payloadFree(this.data[i].payload);
+            }
+            this.data.length = size;
+        }
+        this.capacity = size;
+        return false;
+    }
+    /**
+     * qp_flush (L251): remove every entry, calling payloadFree on each first if
+     * given. The capacity is unchanged.
+     */
+    flush(payloadFree) {
+        if (payloadFree) {
+            for (const element of this.data)
+                payloadFree(element.payload);
+        }
+        this.data.length = 0;
+    }
+    /**
+     * qp_free (L271): upstream releases the queue itself. Here it only runs the
+     * payload callback over what is left, since the queue is garbage-collected.
+     */
+    free(payloadFree) {
+        if (payloadFree) {
+            for (const element of this.data)
+                payloadFree(element.payload);
+        }
+        this.data.length = 0;
+    }
+    /**
+     * qp_isinvalid (L500): true when the heap invariant is broken. Upstream's
+     * debug self-check, walking the deepest layer upward in sibling pairs.
+     */
+    isInvalid() {
+        const count = this.data.length;
+        if (count > this.capacity)
+            return true;
+        /* Queues with less than two elements have nothing to check. */
+        if (count < 2)
+            return false;
+        let start;
+        if ((count & 1) === 0) {
+            /* On the deepest layer, there is a node with no sibling. */
+            const parent = (count - 2) >> 1;
+            if (this.data[count - 1].priority <
+                this.data[parent].priority) {
+                return true;
+            }
+            start = count - 2;
+        }
+        else {
+            /* All nodes on the deepest layer have a sibling. */
+            start = count - 1;
+        }
+        while (start > 1) {
+            const parent = (start - 1) >> 1;
+            if (this.data[start].priority <
+                this.data[parent].priority ||
+                this.data[start - 1].priority <
+                    this.data[parent].priority) {
+                return true;
+            }
+            start -= 2;
+        }
+        return false;
+    }
+}
+/** qp_new (z-queue.c L194): a priority queue holding up to `size` elements. */
+export function qpNew(size) {
+    return new PriorityQueue(size);
+}
+//# sourceMappingURL=z-queue.js.map

package/dist/z-queue.js.map

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@rpgm-tools/neo-angband-core",
+  "version": "0.10.0",
+  "description": "Headless Neo Angband game engine: rules, world, entities, effects, generation",
+  "license": "GPL-2.0-only",
+  "author": "neostryder (RPGM Tools)",
+  "homepage": "https://github.com/neostryder/neo-angband#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neostryder/neo-angband.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/neostryder/neo-angband/issues",
+  "keywords": [
+    "angband",
+    "roguelike",
+    "game-engine",
+    "neo-angband",
+    "modding"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "//files": [
+    "This engine keeps its 248 test modules beside its 485 source modules in src/,",
+    "not in a tests/ tree, so a bare `dist` would publish 248 compiled test files",
+    "that import vitest - a dependency this package does not declare and a consumer",
+    "does not have. The negations drop them, and tools/check-npm-package.mjs runs",
+    "`npm pack` and FAILS if one survives; a `files` list is a claim, and the",
+    "tarball is the measurement.",
+    "src/ ships on purpose: the .js.map files point into it, so a stack trace out of",
+    "the engine lands on real TypeScript instead of nowhere."
+  ],
+  "files": [
+    "dist",
+    "src",
+    "!**/*.test.ts",
+    "!**/*.test.js",
+    "!**/*.test.js.map",
+    "!**/*.test.d.ts",
+    "!**/*.test.d.ts.map",
+    "!**/*.tsbuildinfo",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "//publishConfig": [
+    "provenance is NOT set here, and its absence is load-bearing. Trusted publishing",
+    "generates a provenance attestation on its own, with no flag; setting the flag",
+    "instead forces provenance on EVERY publish, including the one manual publish a",
+    "brand-new package needs before it has a settings page to configure a trusted",
+    "publisher on - and provenance cannot be generated outside a cloud CI runner, so",
+    "that first publish would fail. See docs/RELEASING.md step 4."
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/agent/act.ts

@@ -0,0 +1,114 @@
+/**
+ * The act facade (P7.7): the BORG_AS_MOD section-3 semantic verbs as typed
+ * command builders over the engine's PlayerCommand model, plus set-target as a
+ * direct state action (target.c). The arg keys match what the ported actions
+ * read (game/obj-cmd.ts, spell-cmd.ts, ranged-cmd.ts, cave-cmd.ts): item verbs
+ * carry `handle`, drop adds `quantity`, cast carries `spell`, movement/terrain
+ * verbs carry `dir`.
+ *
+ * Building a command is always legal; whether a code is fully wired in the
+ * engine yet is orthogonal to the contract (several are stubs today and are
+ * completed as the Borg port, P8, drives them). Store verbs emit semantic codes
+ * that the store API binds in P8; they are here so the contract is complete.
+ *
+ * Capability: command:add - enforced per verb when an AgentCapabilities is
+ * supplied (and still at controller install, controller.ts). With no caps (a
+ * trusted in-process host) every verb is granted.
+ */
+
+import type { GameState } from "../game/context.js";
+import { targetSetLocation, targetSetMonster } from "../game/target.js";
+import { loc } from "../loc.js";
+import { AgentCapabilityError } from "./types.js";
+import type { AgentActions, AgentCapabilities, AgentCommand } from "./types.js";
+
+/**
+ * Wrap every act verb so it throws AgentCapabilityError unless the caller was
+ * granted "command:add". With no AgentCapabilities (a trusted in-process host)
+ * the facade is returned unchanged - every verb is granted.
+ */
+function gateActions(
+  actions: AgentActions,
+  caps: AgentCapabilities | undefined,
+): AgentActions {
+  if (!caps) return actions;
+  const guard = (): void => {
+    if (!caps.has("command:add")) {
+      throw new AgentCapabilityError(
+        `agent act: capability "command:add" is not granted`,
+      );
+    }
+  };
+  const out = {} as Record<string, (...args: unknown[]) => unknown>;
+  for (const [key, fn] of Object.entries(actions) as [
+    string,
+    (...args: unknown[]) => unknown,
+  ][]) {
+    out[key] = (...args: unknown[]): unknown => {
+      guard();
+      return fn(...args);
+    };
+  }
+  return out as unknown as AgentActions;
+}
+
+/** Build the act facade bound to a live state, gated by the given caps. */
+export function createAgentActions(
+  state: GameState,
+  caps?: AgentCapabilities,
+): AgentActions {
+  const cmd = (code: string, args?: Record<string, unknown>): AgentCommand =>
+    args ? { code, args } : { code };
+  const dirCmd = (code: string, dir: number): AgentCommand => ({ code, dir });
+  const itemCmd = (code: string, handle: number): AgentCommand =>
+    cmd(code, { handle });
+
+  const actions: AgentActions = {
+    move: (dir) => dirCmd("walk", dir),
+    melee: (dir) => dirCmd("walk", dir),
+    hold: () => cmd("hold"),
+    rest: () => cmd("rest"),
+    descend: () => cmd("descend"),
+    ascend: () => cmd("ascend"),
+    tunnel: (dir) => dirCmd("tunnel", dir),
+    open: (dir) => dirCmd("open", dir),
+    close: (dir) => dirCmd("close", dir),
+    disarm: (dir) => dirCmd("disarm", dir),
+
+    quaff: (handle) => itemCmd("quaff", handle),
+    read: (handle) => itemCmd("read", handle),
+    eat: (handle) => itemCmd("eat", handle),
+    wear: (handle) => itemCmd("wield", handle),
+    takeoff: (handle) => itemCmd("takeoff", handle),
+    drop: (handle, number) =>
+      cmd("drop", number !== undefined ? { handle, quantity: number } : { handle }),
+    pickup: () => cmd("pickup"),
+    destroy: (handle) => itemCmd("destroy", handle),
+    aimWand: (handle) => itemCmd("aim-wand", handle),
+    zapRod: (handle) => itemCmd("zap-rod", handle),
+    useStaff: (handle) => itemCmd("use-staff", handle),
+    activate: (handle) => itemCmd("activate", handle),
+
+    fire: (handle) => itemCmd("fire", handle),
+    throw: (handle) => itemCmd("throw", handle),
+    cast: (spell) => cmd("cast", { spell }),
+
+    setTargetMonster: (midx) => {
+      const mon = state.monsters[midx] ?? null;
+      return targetSetMonster(state, mon);
+    },
+    setTargetLocation: (x, y) => {
+      targetSetLocation(state, loc(x, y));
+    },
+
+    shopBuy: (index, number) =>
+      cmd("shop-buy", number !== undefined ? { index, quantity: number } : { index }),
+    shopSell: (handle, number) =>
+      cmd("shop-sell", number !== undefined ? { handle, quantity: number } : { handle }),
+    shopExit: () => cmd("shop-exit"),
+
+    raw: (code, args) => cmd(code, args),
+  };
+
+  return gateActions(actions, caps);
+}

package/src/agent/controller.ts

@@ -0,0 +1,109 @@
+/**
+ * The controller seam (P7.7): bind an AgentController as the game's nextCommand
+ * provider. runGameLoop calls state.nextCommand() each time it needs a command
+ * and returns LOOP_STATUS.INPUT when it yields null (game/loop.ts) - that is the
+ * perceive -> think -> act boundary. installController wires a controller into
+ * exactly that seam, hands it a perceive view and the act facade, and taps the
+ * message sink so the view can report "messages since the last decision".
+ *
+ * Capability gating (MOD_LIFECYCLE section 4): a controller must be able to ACT,
+ * so command:add is required at install; when a CapabilitySet is supplied and
+ * lacks it, install throws an author-facing error. Read access is NOT required
+ * as a blanket state:*.read wildcard - that would defeat least privilege for a
+ * controller that legitimately reads only a subset of domains (the sandboxed-
+ * plugin case, W2.1). Reads are gated per domain by the perceive facade (W1.4):
+ * a controller that reads a domain it was not granted throws at read time. With
+ * no CapabilitySet (an in-process trusted host, e.g. the bundled Borg before the
+ * sandbox), everything is granted.
+ *
+ * Determinism (the core-owned one-way ratchet, save-blocks.ts): a controller
+ * that declares nondeterministic:true trips the ratchet once via
+ * onNondeterministic - the runtime flips the save's determinism mode. A
+ * deterministic controller (the procedural Borg) draws only the seeded RNG and
+ * leaves the mode untouched.
+ */
+
+import type { GameState, PlayerCommand } from "../game/context.js";
+import { createAgentView } from "./perceive.js";
+import { createAgentActions } from "./act.js";
+import { AgentCapabilityError } from "./types.js";
+import type {
+  AgentCapabilities,
+  AgentController,
+  AgentSession,
+  ControllerOptions,
+} from "./types.js";
+
+export { AgentCapabilityError } from "./types.js";
+
+/**
+ * Capabilities every controller needs at install: it must be able to drive
+ * commands. Read access is enforced per domain by the perceive facade at read
+ * time, not required wholesale here (see the file header on least privilege).
+ */
+const REQUIRED_CAPABILITIES = ["command:add"] as const;
+
+function requireCapabilities(caps: AgentCapabilities): void {
+  for (const cap of REQUIRED_CAPABILITIES) {
+    if (!caps.has(cap)) {
+      throw new AgentCapabilityError(
+        `agent controller requires capability "${cap}" - grant it in the mod manifest`,
+      );
+    }
+  }
+}
+
+/** A per-decision message tap: buffer messages, drain them when perceived. */
+function makeMessageBuffer(): { push(text: string): void; drain(): string[] } {
+  let buffer: string[] = [];
+  return {
+    push: (text) => {
+      buffer.push(text);
+    },
+    drain: () => {
+      const out = buffer;
+      buffer = [];
+      return out;
+    },
+  };
+}
+
+/**
+ * Install `controller` as the state's command provider, returning a session with
+ * the live facades and an uninstall that restores the previous provider and
+ * message sink. The controller is invoked at each LOOP_STATUS.INPUT boundary.
+ */
+export function installController(
+  state: GameState,
+  controller: AgentController,
+  opts: ControllerOptions = {},
+): AgentSession {
+  if (opts.capabilities) requireCapabilities(opts.capabilities);
+  if (opts.nondeterministic) opts.onNondeterministic?.();
+
+  const buffer = makeMessageBuffer();
+  const view = createAgentView(state, buffer, opts.viewDeps, opts.capabilities);
+  const act = createAgentActions(state, opts.capabilities);
+
+  const prevNextCommand = state.nextCommand;
+  const prevMsg = state.msg;
+
+  /* Tap the message sink so the view reports messages since the last decision,
+   * while still forwarding to whatever sink was installed (a shell renderer). */
+  state.msg = (text: string): void => {
+    buffer.push(text);
+    prevMsg?.(text);
+  };
+
+  state.nextCommand = (): PlayerCommand | null => controller(view, act);
+
+  return {
+    view,
+    act,
+    uninstall: (): void => {
+      state.nextCommand = prevNextCommand;
+      if (prevMsg) state.msg = prevMsg;
+      else delete state.msg;
+    },
+  };
+}

package/src/agent/events.ts

@@ -0,0 +1,47 @@
+/**
+ * The capability-gated event-subscription seam (W1.6): a mod subscribes to the
+ * game event bus (events.ts) to react to what happens - turn/level changes,
+ * messages, sound, monster events - the "hooks" half of behavioral modding.
+ *
+ * A subscription wraps a GameEvents bus and checks "event:<name>" (the
+ * capability-model vocabulary, capabilities.ts) before honoring an `on`; an
+ * ungranted event throws AgentCapabilityError, exactly like the perceive/act
+ * facades (W1.4). With no AgentCapabilities (a trusted in-process host) every
+ * event is granted. The bus itself is core's faithful game-event.c port; this
+ * only adds the consent gate a sandboxed plugin (W2.1) needs.
+ */
+
+import type { GameEventHandler, GameEvents, GameEventType } from "../events.js";
+import { AgentCapabilityError } from "./types.js";
+import type { AgentCapabilities } from "./types.js";
+
+/** A capability-gated view of the event bus handed to a mod. */
+export interface AgentEventSubscription {
+  /** Subscribe to an event, if "event:<type>" is granted (else throws). */
+  on<K extends GameEventType>(type: K, fn: GameEventHandler<K>): void;
+  /** Unsubscribe a handler (always allowed - dropping a hook needs no grant). */
+  off<K extends GameEventType>(type: K, fn: GameEventHandler<K>): void;
+}
+
+/**
+ * Build a capability-gated subscription over `bus`. `on` throws
+ * AgentCapabilityError unless "event:<type>" is granted; absent caps grants all.
+ */
+export function subscribeEvents(
+  bus: GameEvents,
+  caps?: AgentCapabilities,
+): AgentEventSubscription {
+  return {
+    on: (type, fn) => {
+      if (caps && !caps.has(`event:${type}`)) {
+        throw new AgentCapabilityError(
+          `agent events: capability "event:${type}" is not granted`,
+        );
+      }
+      bus.on(type, fn);
+    },
+    off: (type, fn) => {
+      bus.off(type, fn);
+    },
+  };
+}

package/src/agent/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @rpgm-tools/neo-angband-core agent API (P7 phase 7): the frozen perceive/act/controller
+ * facade every agent mod - the bundled Borg (P8) first, third-party and AI
+ * agents after - drives the game through, with no privileged core access.
+ *
+ * See BORG_AS_MOD.md sections 3 and 5 for the contract this realizes. FROZEN at
+ * AGENT_API_VERSION 1.0.0 (ratified 2026-07-14, the P7 -> P8 gate); add-only
+ * from here (see types.ts freeze note).
+ */
+
+export { AGENT_API_VERSION, AGENT_STATE_DOMAINS } from "./types.js";
+export type {
+  AgentCapabilities,
+  AgentCommand,
+  AgentActions,
+  AgentController,
+  AgentSession,
+  AgentView,
+  AgentViewDeps,
+  CellView,
+  ControllerOptions,
+  ItemView,
+  MonsterView,
+  PlayerStatusView,
+  PlayerView,
+  SpellbookView,
+  SpellView,
+  StoreItemView,
+  StoreView,
+  TargetView,
+} from "./types.js";
+export { createAgentView } from "./perceive.js";
+export { createAgentActions } from "./act.js";
+export { AgentCapabilityError, installController } from "./controller.js";
+export { subscribeEvents } from "./events.js";
+export type { AgentEventSubscription } from "./events.js";