@its-not-rocket-science/ananke 0.1.69 → 0.5.4

package/dist/src/economy.js

@@ -17,6 +17,10 @@ export const WEAR_FUMBLE_THRESHOLD = q(0.70);
 const FUMBLE_CHANCE_Q = q(0.20); // 20%
 const DEFAULT_SELL_FRACTION = 0.40; // weapons/armour
 const MEDICAL_SELL_FRACTION = 0.50;
+const DEFAULT_DURABILITY_VALUE_POLICY = {
+    salvageFloorFraction: 0.05,
+    conditionExponent: 1.35,
+};
 // ── computeItemValue ──────────────────────────────────────────────────────────
 /**
  * Derive economic metadata for any item or medical resource.
@@ -63,19 +67,42 @@ export function computeItemValue(item, wear_Q = q(0)) {
     return { itemId: it.id, baseValue: Math.floor(it.mass_kg / SCALE.kg * 8), condition_Q: q(1.0), sellFraction: DEFAULT_SELL_FRACTION };
 }
 /**
- * Convert armour degradation state to a wear_Q fraction.
+ * Convert armour state to condition fraction.
  *
  * ```
- * wear = q(1.0) − resistRemaining_J / resist_J
+ * condition = resistRemaining_J / resist_J
  * ```
- * Used to derive `condition_Q` for ablative armour via `computeItemValue`.
+ *
+ * The result can be converted to wear via `conditionToWearQ`.
  */
 export function armourConditionQ(resist_J, resistRemaining_J) {
     if (resist_J <= 0)
-        return q(1.0);
+        return q(0);
     const fraction = Math.trunc((resistRemaining_J * SCALE.Q) / resist_J);
     return clampQ(fraction, 0, SCALE.Q);
 }
+/** Convert condition to wear (`wear = 1 - condition`) in fixed-point space. */
+export function conditionToWearQ(condition_Q) {
+    return clampQ(SCALE.Q - condition_Q, 0, SCALE.Q);
+}
+/**
+ * Convert an ItemValue into market-usable unit values.
+ *
+ * This keeps `computeItemValue` stable and lets hosts pick stricter/looser
+ * durability discounting.
+ */
+export function toMarketValue(itemValue, policy = DEFAULT_DURABILITY_VALUE_POLICY) {
+    const configured = {
+        salvageFloorFraction: policy.salvageFloorFraction ?? DEFAULT_DURABILITY_VALUE_POLICY.salvageFloorFraction,
+        conditionExponent: policy.conditionExponent ?? DEFAULT_DURABILITY_VALUE_POLICY.conditionExponent,
+    };
+    const condition = Math.max(0, Math.min(1, itemValue.condition_Q / SCALE.Q));
+    const curved = Math.pow(condition, Math.max(0.01, configured.conditionExponent));
+    const multiplier = configured.salvageFloorFraction + (1 - configured.salvageFloorFraction) * curved;
+    const buyValue = Math.max(0, Math.round(itemValue.baseValue * multiplier));
+    const sellValue = Math.max(0, Math.round(buyValue * itemValue.sellFraction));
+    return { buyValue, sellValue, conditionMultiplier: multiplier };
+}
 // ── applyWear ─────────────────────────────────────────────────────────────────
 /**
  * Apply one strike's worth of use-wear to a melee weapon.
@@ -104,42 +131,65 @@ export function applyWear(weapon, actionIntensity_Q, seed) {
     return { wear_Q: newWear, broke, fumble, penaltyActive };
 }
 // ── resolveDrops ──────────────────────────────────────────────────────────────
+function shouldResolveDrops(entity, config) {
+    if (entity.injury.dead)
+        return { shouldDrop: true, source: "dead" };
+    if (config?.dropOnIncapacitated ?? false)
+        return { shouldDrop: true, source: "incapacitated" };
+    return { shouldDrop: false, source: "none" };
+}
 /**
- * Compute the list of item IDs dropped by an entity on death or incapacitation.
- *
- * Default behaviour:
- *   - Dead entity → all equipped weapons, ranged weapons, and armour drop (guaranteed).
- *   - Incapacitated but living → nothing drops (use `config.dropOnIncapacitated = true` to override).
- *
- * Additional items from `extra.guaranteed` always drop (when applicable).
- * `extra.probabilistic` items are rolled deterministically from `seed`.
+ * Structured drop resolution for host-facing UI and telemetry.
  */
-export function resolveDrops(entity, seed, extra, config) {
-    const shouldDrop = entity.injury.dead || (config?.dropOnIncapacitated ?? false);
-    if (!shouldDrop)
-        return [];
-    const result = [];
-    // Guaranteed: all equipped weapons and armour
+export function resolveDropsDetailed(entity, seed, extra, config) {
+    const dropState = shouldResolveDrops(entity, config);
+    if (!dropState.shouldDrop) {
+        return {
+            dropped: [],
+            guaranteed: [],
+            probabilistic: [],
+            preventedByState: true,
+            source: dropState.source,
+        };
+    }
+    const guaranteed = [];
+    const probabilistic = [];
     for (const item of entity.loadout.items) {
         if (item.kind === "weapon" || item.kind === "armour" || item.kind === "ranged") {
-            result.push(item.id);
+            guaranteed.push(item.id);
         }
     }
     if (extra) {
-        for (const id of extra.guaranteed) {
-            result.push(id);
-        }
-        // Probabilistic roll — deterministic per item index
+        guaranteed.push(...extra.guaranteed);
         for (let i = 0; i < extra.probabilistic.length; i++) {
             const entry = extra.probabilistic[i];
             const rollSeed = eventSeed(seed, i, 0, 0, 0xD50A5);
             const rng = makeRng(rollSeed, SCALE.Q);
             if (rng.q01() < entry.chance_Q) {
-                result.push(entry.itemId);
+                probabilistic.push(entry.itemId);
             }
         }
     }
-    return result;
+    return {
+        dropped: [...guaranteed, ...probabilistic],
+        guaranteed,
+        probabilistic,
+        preventedByState: false,
+        source: dropState.source,
+    };
+}
+/**
+ * Compute the list of item IDs dropped by an entity on death or incapacitation.
+ *
+ * Default behaviour:
+ *   - Dead entity → all equipped weapons, ranged weapons, and armour drop (guaranteed).
+ *   - Incapacitated but living → nothing drops (use `config.dropOnIncapacitated = true` to override).
+ *
+ * Additional items from `extra.guaranteed` always drop (when applicable).
+ * `extra.probabilistic` items are rolled deterministically from `seed`.
+ */
+export function resolveDrops(entity, seed, extra, config) {
+    return resolveDropsDetailed(entity, seed, extra, config).dropped;
 }
 // ── evaluateTradeOffer ────────────────────────────────────────────────────────
 /**
@@ -153,22 +203,119 @@ export function resolveDrops(entity, seed, extra, config) {
  * `feasible` — the accepting party has all `want` items in sufficient quantities.
  */
 export function evaluateTradeOffer(offer, inventory) {
-    // Feasibility: does the accepting party have all wanted items?
-    let feasible = true;
+    const detailed = evaluateTradeOfferDetailed(offer, inventory);
+    return { netValue: detailed.netValue, feasible: detailed.feasible };
+}
+/**
+ * Inventory-aware trade evaluation that surfaces shortages and value breakdown.
+ */
+export function evaluateTradeOfferDetailed(offer, inventory) {
+    const snapshots = new Map();
+    const giveValue = offer.give.reduce((sum, g) => sum + g.count * g.unitValue, 0);
+    const wantValue = offer.want.reduce((sum, w) => sum + w.count * w.unitValue, 0);
+    const shortages = [];
     for (const w of offer.want) {
         const entry = inventory.get(w.itemId);
-        if (!entry || entry.count < w.count) {
-            feasible = false;
-            break;
+        const owned = entry?.count ?? 0;
+        const shortage = Math.max(0, w.count - owned);
+        if (shortage > 0)
+            shortages.push({ itemId: w.itemId, missingCount: shortage });
+        snapshots.set(w.itemId, {
+            ownedCount: owned,
+            shortageCount: shortage,
+            entryUnitValue: entry?.unitValue ?? 0,
+            offerUnitValue: w.unitValue,
+        });
+    }
+    for (const g of offer.give) {
+        if (!snapshots.has(g.itemId)) {
+            snapshots.set(g.itemId, {
+                ownedCount: inventory.get(g.itemId)?.count ?? 0,
+                shortageCount: 0,
+                entryUnitValue: inventory.get(g.itemId)?.unitValue ?? 0,
+                offerUnitValue: g.unitValue,
+            });
+        }
+    }
+    const feasible = shortages.length === 0;
+    const netValue = giveValue - wantValue;
+    return { netValue, feasible, giveValue, wantValue, shortages, snapshots };
+}
+// ── host reporting helpers ────────────────────────────────────────────────────
+/** Merge simple itemized counts into an ItemInventory map. */
+export function mergeIntoInventory(inventory, items, resolver) {
+    for (const item of items) {
+        if (item.count <= 0)
+            continue;
+        const existing = inventory.get(item.itemId);
+        if (existing) {
+            existing.count += item.count;
+            continue;
         }
+        inventory.set(item.itemId, { count: item.count, unitValue: resolver(item.itemId) });
     }
-    // Net value for accepting party: receive give items, pay want items
-    let netValue = 0;
-    for (const g of offer.give)
-        netValue += g.count * g.unitValue;
-    for (const w of offer.want)
-        netValue -= w.count * w.unitValue;
-    return { netValue, feasible };
+    return inventory;
+}
+/** Build a host-facing value report for any itemized list. */
+export function createEconomyReport(label, entries, resolver, tags = []) {
+    const lines = entries
+        .filter(e => e.count > 0)
+        .map((entry) => {
+        const unitValue = Math.max(0, resolver(entry.itemId));
+        return {
+            itemId: entry.itemId,
+            count: entry.count,
+            unitValue,
+            totalValue: unitValue * entry.count,
+        };
+    });
+    const grossValue = lines.reduce((sum, line) => sum + line.totalValue, 0);
+    return {
+        label,
+        totals: {
+            grossValue,
+            netValue: grossValue,
+            lineCount: lines.length,
+        },
+        lines,
+        tags,
+    };
+}
+/**
+ * Example flow: post-battle loot screen.
+ */
+export function examplePostBattleLootFlow(entity, seed, resolver) {
+    const drops = resolveDropsDetailed(entity, seed);
+    const counts = countItems(drops.dropped);
+    return createEconomyReport("post_battle_loot", counts, resolver, ["loot", drops.source]);
+}
+/**
+ * Example flow: repair/reuse loop that compares pre-repair vs post-repair resale.
+ */
+export function exampleRepairReuseLoop(item, startingWear_Q, repairedWear_Q) {
+    const before = toMarketValue(computeItemValue(item, startingWear_Q));
+    const after = toMarketValue(computeItemValue(item, repairedWear_Q));
+    return {
+        label: "repair_reuse_loop",
+        totals: {
+            grossValue: after.sellValue,
+            netValue: after.sellValue - before.sellValue,
+            lineCount: 1,
+        },
+        lines: [{
+                itemId: item.id,
+                count: 1,
+                unitValue: after.sellValue,
+                totalValue: after.sellValue,
+            }],
+        tags: ["repair", "reuse", after.sellValue >= before.sellValue ? "improved" : "degraded"],
+    };
+}
+/**
+ * Example flow: settlement/shop interaction, including affordability and shortages.
+ */
+export function exampleSettlementTradeFlow(offer, inventory) {
+    return evaluateTradeOfferDetailed(offer, inventory);
 }
 // ── totalInventoryValue ───────────────────────────────────────────────────────
 /**
@@ -180,3 +327,10 @@ export function totalInventoryValue(inventory) {
         total += entry.count * entry.unitValue;
     return total;
 }
+function countItems(ids) {
+    const counts = new Map();
+    for (const id of ids) {
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    return [...counts.entries()].map(([itemId, count]) => ({ itemId, count }));
+}

package/dist/src/history/autosave.d.ts

@@ -0,0 +1,19 @@
+import type { WorldState } from "../sim/world.js";
+export interface AutosaveConfig {
+    everyNTicks?: number;
+    onEntityDeath?: boolean;
+    autosaveKey?: string;
+}
+export interface AutosaveStorage {
+    save(key: string, bytes: Uint8Array): Promise<void>;
+    load(key: string): Promise<Uint8Array | undefined>;
+}
+export declare class AutosaveManager {
+    private readonly cfg;
+    private readonly storage;
+    constructor(storage?: AutosaveStorage, cfg?: AutosaveConfig);
+    maybeAutosave(world: WorldState, previous?: WorldState): Promise<void>;
+    saveNow(world: WorldState): Promise<void>;
+    recover(): Promise<WorldState | undefined>;
+}
+export declare function defaultAutosaveStorage(): AutosaveStorage;

package/dist/src/history/autosave.js

@@ -0,0 +1,98 @@
+import { exportWorldState, importWorldState } from "../serialization/binary.js";
+export class AutosaveManager {
+    cfg;
+    storage;
+    constructor(storage, cfg = {}) {
+        this.storage = storage ?? defaultAutosaveStorage();
+        this.cfg = {
+            everyNTicks: cfg.everyNTicks ?? 100,
+            onEntityDeath: cfg.onEntityDeath ?? true,
+            autosaveKey: cfg.autosaveKey ?? "ananke:last-autosave",
+        };
+    }
+    async maybeAutosave(world, previous) {
+        const tickPolicy = this.cfg.everyNTicks > 0 && world.tick % this.cfg.everyNTicks === 0;
+        const deathPolicy = this.cfg.onEntityDeath && previous ? hasDeath(previous, world) : false;
+        if (tickPolicy || deathPolicy) {
+            await this.saveNow(world);
+        }
+    }
+    async saveNow(world) {
+        await this.storage.save(this.cfg.autosaveKey, exportWorldState(world));
+    }
+    async recover() {
+        const bytes = await this.storage.load(this.cfg.autosaveKey);
+        if (!bytes)
+            return undefined;
+        return importWorldState(bytes);
+    }
+}
+export function defaultAutosaveStorage() {
+    if (typeof window === "undefined")
+        return new NodeAutosaveStorage();
+    return new IndexedDbAutosaveStorage();
+}
+class NodeAutosaveStorage {
+    async save(key, bytes) {
+        const fs = await import("node:fs/promises");
+        const path = await import("node:path");
+        const os = await import("node:os");
+        const dir = path.join(os.homedir(), ".ananke", "autosave");
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, sanitizeKey(key) + ".bin"), bytes);
+    }
+    async load(key) {
+        const fs = await import("node:fs/promises");
+        const path = await import("node:path");
+        const os = await import("node:os");
+        try {
+            const bytes = await fs.readFile(path.join(os.homedir(), ".ananke", "autosave", sanitizeKey(key) + ".bin"));
+            return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+class IndexedDbAutosaveStorage {
+    dbName = "ananke-autosave";
+    storeName = "snapshots";
+    async save(key, bytes) {
+        const db = await this.open();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readwrite");
+            tx.objectStore(this.storeName).put(bytes, key);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async load(key) {
+        const db = await this.open();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readonly");
+            const req = tx.objectStore(this.storeName).get(key);
+            req.onsuccess = () => resolve(req.result ? new Uint8Array(req.result) : undefined);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async open() {
+        return new Promise((resolve, reject) => {
+            const req = indexedDB.open(this.dbName, 1);
+            req.onupgradeneeded = () => {
+                const db = req.result;
+                if (!db.objectStoreNames.contains(this.storeName))
+                    db.createObjectStore(this.storeName);
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+}
+function hasDeath(previous, next) {
+    const prevAlive = previous.entities.filter(e => !e.injury.dead).length;
+    const nextAlive = next.entities.filter(e => !e.injury.dead).length;
+    return nextAlive < prevAlive;
+}
+function sanitizeKey(input) {
+    return input.replace(/[^a-z0-9_.-]/gi, "_");
+}

package/dist/src/history/timetravel.d.ts

@@ -0,0 +1,28 @@
+import type { WorldState } from "../sim/world.js";
+import type { Command, CommandMap } from "../sim/commands.js";
+import type { KernelContext } from "../sim/context.js";
+export interface TimeTravelOptions {
+    bufferSizeTicks?: number;
+}
+export interface TickRecord {
+    tick: number;
+    state: WorldState;
+    commands: Array<readonly [entityId: number, commands: readonly Command[]]>;
+}
+export interface TimeTravelWorld extends WorldState {
+    rewind(ticks: number): void;
+    fork(): WorldState;
+}
+export declare class TimeTravelController {
+    private readonly world;
+    private readonly ctx;
+    private readonly records;
+    private readonly bufferSizeTicks;
+    constructor(world: WorldState, ctx: KernelContext, opts?: TimeTravelOptions);
+    recordTick(commands: CommandMap): void;
+    step(commands: CommandMap): void;
+    rewind(ticks: number): void;
+    fork(): WorldState;
+    getHistory(): readonly TickRecord[];
+}
+export declare function enableTimeTravel(world: WorldState, ctx: KernelContext, opts?: TimeTravelOptions): TimeTravelController;

package/dist/src/history/timetravel.js

@@ -0,0 +1,61 @@
+import { stepWorld } from "../sim/kernel.js";
+export class TimeTravelController {
+    world;
+    ctx;
+    records = [];
+    bufferSizeTicks;
+    constructor(world, ctx, opts = {}) {
+        this.world = world;
+        this.ctx = ctx;
+        const configured = opts.bufferSizeTicks ?? 600;
+        this.bufferSizeTicks = Math.max(60, Math.min(3600, configured));
+        this.records.push({ tick: world.tick, state: structuredClone(world), commands: [] });
+        attachMethods(world, this);
+    }
+    recordTick(commands) {
+        const record = {
+            tick: this.world.tick,
+            state: structuredClone(this.world),
+            commands: [...commands.entries()].map(([id, cmds]) => [id, [...cmds]]),
+        };
+        this.records.push(record);
+        while (this.records.length > this.bufferSizeTicks)
+            this.records.shift();
+    }
+    step(commands) {
+        this.recordTick(commands);
+        stepWorld(this.world, commands, this.ctx);
+    }
+    rewind(ticks) {
+        if (ticks <= 0)
+            return;
+        const targetTick = this.world.tick - ticks;
+        const candidate = [...this.records].reverse().find(r => r.tick <= targetTick);
+        if (!candidate) {
+            throw new Error(`timetravel: cannot rewind ${ticks} ticks with buffer size ${this.bufferSizeTicks}`);
+        }
+        mutateWorld(this.world, structuredClone(candidate.state));
+    }
+    fork() {
+        return structuredClone(this.world);
+    }
+    getHistory() {
+        return this.records;
+    }
+}
+export function enableTimeTravel(world, ctx, opts = {}) {
+    return new TimeTravelController(world, ctx, opts);
+}
+function attachMethods(world, controller) {
+    const mutable = world;
+    mutable.rewind = (ticks) => controller.rewind(ticks);
+    mutable.fork = () => controller.fork();
+}
+function mutateWorld(target, source) {
+    for (const key of Object.keys(target)) {
+        if (!(key in source)) {
+            delete target[key];
+        }
+    }
+    Object.assign(target, source);
+}

package/dist/src/index.d.ts

@@ -1,31 +1,19 @@
-export * from "./units.js";
-export * from "./types.js";
-export * from "./archetypes.js";
-export * from "./generate.js";
-export * from "./equipment.js";
-export * from "./weapons.js";
-export * from "./presets.js";
-export * from "./channels.js";
-export * from "./traits.js";
-export * from "./describe.js";
-export * from "./sim/vec3.js";
-export * from "./sim/condition.js";
-export * from "./sim/injury.js";
-export * from "./sim/entity.js";
-export * from "./sim/commands.js";
-export * from "./sim/kinds.js";
-export * from "./sim/kernel.js";
-export * from "./sim/body.js";
-export * from "./sim/world.js";
-export * from "./model3d.js";
-export * from "./replay.js";
-export * from "./bridge/index.js";
-export * from "./world-factory.js";
-export * from "./scenario.js";
-export * from "./catalog.js";
-export * from "./sim/formation-combat.js";
-export * from "./sim/cover.js";
-export * from "./sim/ai/behavior-trees.js";
-export * from "./snapshot.js";
-export * from "./parallel.js";
-export * from "./modding.js";
+export { SCALE, G_mps2, q, clampQ, qMul, qDiv, mulDiv, to, from, sqrtQ, } from "./units.js";
+export type { I32, Q } from "./units.js";
+export type { IndividualAttributes } from "./types.js";
+export type { Entity } from "./sim/entity.js";
+export type { WorldState } from "./sim/world.js";
+export type { KernelContext } from "./sim/context.js";
+export type { Command, CommandMap } from "./sim/commands.js";
+export { createWorld } from "./world-factory.js";
+export type { EntitySpec } from "./world-factory.js";
+export { loadScenario, validateScenario } from "./scenario.js";
+export type { AnankeScenario, AnankeScenarioEntity } from "./scenario.js";
+export { stepWorld } from "./sim/kernel.js";
+export { ReplayRecorder, replayTo, serializeReplay, deserializeReplay } from "./replay.js";
+export type { Replay, ReplayFrame } from "./replay.js";
+export { extractRigSnapshots, deriveAnimationHints } from "./model3d.js";
+export type { RigSnapshot, AnimationHints } from "./model3d.js";
+export { loadPlugin } from "./plugins/loader.js";
+export { installPluginFromRegistry } from "./plugins/registry.js";
+export type { PluginManifest, PluginPermission, PluginHookContext, PluginHooks, PluginRuntimeApi, PluginModule, LoadedPlugin, } from "./plugins/types.js";

package/dist/src/index.js

@@ -1,40 +1,22 @@
-// ── Tier 1 — Stable host API ─────────────────────────────────────────────────
-// This is the only import path companion projects and hosts should use:
-//   import { stepWorld, createWorld, q, SCALE } from "@its-not-rocket-science/ananke"
+// ── Tier 1 — Stable host API (minimal contract) ─────────────────────────────
+// This is the only import path hosts should treat as semver-stable:
+//   import { createWorld, stepWorld, q, SCALE } from "@its-not-rocket-science/ananke"
 //
-// Breaking changes to any export here require a major semver bump (x.0.0) and
-// a migration guide in CHANGELOG.md.  See STABLE_API.md for the full contract.
+// Everything not exported here is intentionally Tier 2/3 and must be imported
+// via explicit subpaths (e.g. "/character", "/combat", "/tier2", "/tier3").
 //
-// Tier 2 (experimental) and Tier 3 (internal) exports are accessible via direct
-// module imports, e.g. import { stepAging } from ".../dist/src/sim/aging.js"
-export * from "./units.js"; // q(), SCALE, qMul, qDiv, clampQ, mulDiv, to, from, sqrtQ
-export * from "./types.js"; // IndividualAttributes, core scalar types
-export * from "./archetypes.js"; // Archetype, BodyPlan, built-in species presets
-export * from "./generate.js"; // generateIndividual()
-export * from "./equipment.js"; // Weapon, Armour, Gear, WeaponDamageProfile, EquipmentCatalogue
-export * from "./weapons.js"; // ALL_HISTORICAL_MELEE, ALL_HISTORICAL_RANGED, PREHISTORIC_MELEE … CONTEMPORARY_RANGED
-export * from "./presets.js"; // mkKnight(), mkBoxer(), mkWrestler(), mkOctopus(), mkScubaDiver()
-export * from "./channels.js"; // DamageChannel, ChannelMask, channelMask()
-export * from "./traits.js"; // TraitId, TRAITS, buildTraitProfile(), applyTraitsToAttributes()
-export * from "./describe.js"; // describeCharacter(), formatCharacterSheet(), formatOneLine()
-export * from "./sim/vec3.js"; // Vec3, lerpVec3, addVec3
-export * from "./sim/condition.js"; // ConditionSnapshot, condition constants
-export * from "./sim/injury.js"; // InjuryRegion, BodyRegion, injury constants
-export * from "./sim/entity.js"; // Entity (stable fields: id, pos, mass_kg, attributes…)
-export * from "./sim/commands.js"; // CommandMap, Command, noMove()
-export * from "./sim/kinds.js"; // CommandKinds, MoveModes, DefenceModes, EngageModes, HitArea
-export * from "./sim/kernel.js"; // stepWorld(), applyImpactToInjury(), applyExplosion()
-export * from "./sim/body.js"; // BodyPlan, BodySegment, humanoid / quadruped plans
-export * from "./sim/world.js"; // WorldState, KernelContext
-export * from "./model3d.js"; // extractRigSnapshots(), deriveAnimationHints(), RigSnapshot, AnimationHints
-export * from "./replay.js"; // ReplayRecorder, replayTo(), serializeReplay(), deserializeReplay()
-export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeConfig
-export * from "./world-factory.js"; // createWorld(), EntitySpec, ARCHETYPE_MAP, ITEM_MAP
-export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScenario
-export * from "./catalog.js"; // CE-12: registerArchetype(), registerWeapon(), registerArmour(), getCatalogEntry()
-export * from "./sim/formation-combat.js"; // Phase 69: FormationUnit, TacticalEngagement, resolveTacticalEngagement()
-export * from "./sim/cover.js"; // CE-15: CoverSegment, computeCoverProtection(), isLineOfSightBlocked(), applyExplosionToTerrain()
-export * from "./sim/ai/behavior-trees.js"; // CE-10: BehaviorNode, FlankTarget, RetreatTo, ProtectAlly, GuardPosition, HealTarget, Sequence, Fallback
-export * from "./snapshot.js"; // CE-9: diffWorldState(), applyDiff(), packDiff(), unpackDiff(), WorldStateDiff
-export * from "./parallel.js"; // CE-7: partitionWorld(), mergePartitions(), detectBoundaryPairs(), assignEntitiesToPartitions()
-export * from "./modding.js"; // CE-16: hashMod(), registerPostTickHook(), runPostTickHooks(), registerBehaviorNode(), computeModManifest()
+// Source of truth: docs/stable-api-manifest.json
+// Fixed-point utilities
+export { SCALE, G_mps2, q, clampQ, qMul, qDiv, mulDiv, to, from, sqrtQ, } from "./units.js";
+// World creation and scenario loading
+export { createWorld } from "./world-factory.js";
+export { loadScenario, validateScenario } from "./scenario.js";
+// Stepping
+export { stepWorld } from "./sim/kernel.js";
+// Replay / serialization
+export { ReplayRecorder, replayTo, serializeReplay, deserializeReplay } from "./replay.js";
+// Bridge extraction
+export { extractRigSnapshots, deriveAnimationHints } from "./model3d.js";
+// Plugin SDK
+export { loadPlugin } from "./plugins/loader.js";
+export { installPluginFromRegistry } from "./plugins/registry.js";