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

package/dist/src/model3d.js

@@ -55,6 +55,67 @@ function getCanonicalOffset(segId) {
         return { xFrac: lat * 0.50, yFrac: 0.65 };
     return { xFrac: 0, yFrac: 0.50 }; // unknown: geometric midpoint
 }
+const VERTICAL_POSITION_TO_Y_FRAC = {
+    crown: 0.94,
+    high: 0.80,
+    upper: 0.68,
+    mid: 0.50,
+    lower: 0.28,
+    ground: 0.03,
+};
+const RIG_ROLE_TO_Y_FRAC = {
+    head: 0.94,
+    neck: 0.80,
+    torso: 0.63,
+    abdomen: 0.52,
+    pelvis: 0.43,
+    shoulder: 0.72,
+    arm_upper: 0.68,
+    arm_lower: 0.56,
+    hand: 0.44,
+    leg_upper: 0.33,
+    leg_lower: 0.17,
+    foot: 0.03,
+    tail: 0.35,
+    wing: 0.65,
+    appendage: 0.50,
+    core: 0.50,
+};
+const RIG_ROLE_TO_X_FRAC_MAGNITUDE = {
+    shoulder: 0.20,
+    arm_upper: 0.20,
+    arm_lower: 0.22,
+    hand: 0.25,
+    leg_upper: 0.07,
+    leg_lower: 0.07,
+    foot: 0.07,
+    wing: 0.50,
+};
+function sideToSign(side) {
+    if (side === "left")
+        return -1;
+    if (side === "right")
+        return 1;
+    return 0;
+}
+function getCanonicalOffsetFromMetadata(segId, spatial) {
+    if (!spatial)
+        return null;
+    const legacy = getCanonicalOffset(segId);
+    const side = sideToSign(spatial.lateralSide);
+    const fromHintX = spatial.centerOfMassHint?.xFrac;
+    const fromHintY = spatial.centerOfMassHint?.yFrac;
+    const fromVertical = spatial.verticalPosition ? VERTICAL_POSITION_TO_Y_FRAC[spatial.verticalPosition] : undefined;
+    const fromRigY = spatial.rigRole ? RIG_ROLE_TO_Y_FRAC[spatial.rigRole] : undefined;
+    const xMag = spatial.rigRole ? (RIG_ROLE_TO_X_FRAC_MAGNITUDE[spatial.rigRole] ?? 0) : 0;
+    return {
+        xFrac: Math.max(-1, Math.min(1, fromHintX ?? (side * xMag))),
+        yFrac: Math.max(0, Math.min(1, fromHintY ?? fromVertical ?? fromRigY ?? legacy.yFrac)),
+    };
+}
+function resolveCanonicalOffset(seg) {
+    return getCanonicalOffsetFromMetadata(seg.id, seg.renderSpatial) ?? getCanonicalOffset(seg.id);
+}
 /**
  * Derive mass distribution and centre of gravity from entity body plan.
  * Falls back to a single "body" segment at the geometric midpoint when no
@@ -69,7 +130,7 @@ export function deriveMassDistribution(entity) {
         let cogX = 0;
         let cogY = 0;
         const segments = segs.map(seg => {
-            const off = getCanonicalOffset(seg.id);
+            const off = resolveCanonicalOffset(seg);
             const mass_r = seg.mass_kg / SCALE.kg;
             cogX += mass_r * off.xFrac * stature_m;
             cogY += mass_r * off.yFrac * stature_m;
@@ -104,7 +165,7 @@ export function deriveInertiaTensor(entity) {
     if (entity.bodyPlan) {
         let I_yaw = 0, I_pitch = 0, I_roll = 0;
         for (const seg of entity.bodyPlan.segments) {
-            const off = getCanonicalOffset(seg.id);
+            const off = resolveCanonicalOffset(seg);
             const m = seg.mass_kg / SCALE.kg;
             const x = off.xFrac * stature_m;
             const y = off.yFrac * stature_m;

package/dist/src/narrative/combat-logger.d.ts

@@ -0,0 +1,25 @@
+export type NarrativeVerbosity = "tactical" | "cinematic";
+export interface NarrativeActionContext {
+    attackerName?: string;
+    targetName?: string;
+    terrain?: string;
+    weather?: string;
+    weaponName?: string;
+    distance_m?: number;
+    causes?: string[];
+}
+export interface CombatAction {
+    kind: "melee" | "ranged" | "morale" | "status";
+    hit?: boolean;
+    damage?: number;
+    blocked?: boolean;
+    parried?: boolean;
+    shieldBlocked?: boolean;
+    region?: string;
+    critical?: boolean;
+    suppressed?: boolean;
+}
+export interface DescribeActionOptions {
+    verbosity?: NarrativeVerbosity;
+}
+export declare function describeAction(action: CombatAction, context?: NarrativeActionContext, options?: DescribeActionOptions): string;

package/dist/src/narrative/combat-logger.js

@@ -0,0 +1,97 @@
+import { SCALE } from "../units.js";
+function name(label, fallback) {
+    return label?.trim() || fallback;
+}
+function joinCauses(context) {
+    const causes = [...(context.causes ?? [])];
+    if (context.terrain)
+        causes.push(`${context.terrain} terrain`);
+    if (context.weather)
+        causes.push(context.weather);
+    if (causes.length === 0)
+        return "";
+    if (causes.length === 1)
+        return ` because of ${causes[0]}`;
+    return ` because of ${causes.slice(0, -1).join(", ")} and ${causes.at(-1)}`;
+}
+function cinematicMelee(action, context) {
+    const attacker = name(context.attackerName, "The attacker");
+    const target = name(context.targetName, "the defender");
+    const weapon = context.weaponName ?? "weapon";
+    if (action.hit === false) {
+        return `${attacker}'s ${weapon} clangs against ${target}${action.shieldBlocked ? "'s shield" : ""} — a near miss${joinCauses(context)}!`;
+    }
+    if (action.blocked || action.parried || action.shieldBlocked) {
+        return `${target} turns aside ${attacker}'s strike at the last instant${joinCauses(context)}.`;
+    }
+    const damageText = typeof action.damage === "number"
+        ? ` for ${action.damage} damage`
+        : "";
+    const critText = action.critical ? " It's a decisive blow." : "";
+    const regionText = action.region ? ` into ${target}'s ${action.region}` : " into the opening";
+    return `${attacker} drives the ${weapon}${regionText}${damageText}${critText}`;
+}
+function tacticalMelee(action, context) {
+    const attacker = name(context.attackerName, "attacker");
+    const target = name(context.targetName, "target");
+    const weapon = context.weaponName ?? "weapon";
+    if (action.hit === false) {
+        return `${attacker} misses ${target} with ${weapon}${joinCauses(context)}.`;
+    }
+    if (action.blocked || action.parried || action.shieldBlocked) {
+        const defense = action.parried ? "parried" : action.shieldBlocked ? "shield block" : "blocked";
+        return `${attacker} attacks ${target}; ${defense}${joinCauses(context)}.`;
+    }
+    const distance = typeof context.distance_m === "number"
+        ? ` at ${(context.distance_m / SCALE.m).toFixed(1)}m`
+        : "";
+    return `${attacker} hits ${target}${action.region ? ` (${action.region})` : ""} for ${action.damage ?? 0} damage${distance}.`;
+}
+function tacticalRanged(action, context) {
+    const shooter = name(context.attackerName, "shooter");
+    const target = name(context.targetName, "target");
+    const weapon = context.weaponName ?? "projectile";
+    const distance = typeof context.distance_m === "number"
+        ? ` at ${(context.distance_m / SCALE.m).toFixed(1)}m`
+        : "";
+    if (action.hit === false) {
+        return `${shooter} misses ${target} with ${weapon}${distance}${joinCauses(context)}.`;
+    }
+    if (action.suppressed) {
+        return `${shooter} suppresses ${target} with ${weapon}${distance}.`;
+    }
+    return `${shooter} lands a shot on ${target}${action.region ? ` (${action.region})` : ""}${distance}.`;
+}
+function cinematicRanged(action, context) {
+    const shooter = name(context.attackerName, "The archer");
+    const target = name(context.targetName, "the enemy");
+    const weapon = context.weaponName ?? "shot";
+    if (action.hit === false) {
+        return `${shooter}'s ${weapon} whistles past ${target}${joinCauses(context)}.`;
+    }
+    if (action.suppressed) {
+        return `${shooter} pins ${target} down in a storm of fire.`;
+    }
+    return `${shooter}'s ${weapon} finds ${target}${action.region ? `'s ${action.region}` : ""}, shifting the momentum of the fight.`;
+}
+export function describeAction(action, context = {}, options = {}) {
+    const verbosity = options.verbosity ?? "tactical";
+    if (action.kind === "morale") {
+        return verbosity === "cinematic"
+            ? `${name(context.attackerName, "The line")} falters as fear spreads${joinCauses(context)}.`
+            : `${name(context.attackerName, "Unit")} suffers a morale break${joinCauses(context)}.`;
+    }
+    if (action.kind === "status") {
+        return verbosity === "cinematic"
+            ? `${name(context.attackerName, "The warrior")} staggers but refuses to fall.`
+            : `${name(context.attackerName, "Entity")} status changed.`;
+    }
+    if (action.kind === "ranged") {
+        return verbosity === "cinematic"
+            ? cinematicRanged(action, context)
+            : tacticalRanged(action, context);
+    }
+    return verbosity === "cinematic"
+        ? cinematicMelee(action, context)
+        : tacticalMelee(action, context);
+}

package/dist/src/narrative/plausibility.d.ts

@@ -0,0 +1,30 @@
+export interface NarrativeWeight {
+    expectedWinnerId?: number;
+    expectedWinnerTeamId?: number;
+    heroIds?: number[];
+    desiredBeat?: "heroic_near_win" | "clean_victory" | "tragic_loss" | "upset";
+    dramaticTolerance?: number;
+}
+export interface WorldPlausibilityState {
+    winnerId?: number;
+    winnerTeamId?: number;
+    casualtiesByEntityId?: Record<number, boolean>;
+    eliminationOrder?: number[];
+    rareEventRolls?: Array<{
+        label: string;
+        chance: number;
+        happened: boolean;
+    }>;
+}
+export interface NarrativeViolation {
+    code: "hero_fell_to_mook" | "unlikely_chain" | "expected_winner_lost";
+    message: string;
+    severity: "low" | "medium" | "high";
+}
+export interface PlausibilityReport {
+    score: number;
+    violations: NarrativeViolation[];
+    suggestedSeeds: number[];
+}
+export declare function analyzePlausibility(worldState: WorldPlausibilityState, narrativeWeight: NarrativeWeight): PlausibilityReport;
+export declare function scorePlausibility(worldState: WorldPlausibilityState, narrativeWeight: NarrativeWeight): number;

package/dist/src/narrative/plausibility.js

@@ -0,0 +1,70 @@
+function clampScore(v) {
+    return Math.max(0, Math.min(100, Math.round(v)));
+}
+export function analyzePlausibility(worldState, narrativeWeight) {
+    const violations = [];
+    let score = 100;
+    const tolerance = narrativeWeight.dramaticTolerance ?? 0.25;
+    const heroIds = narrativeWeight.heroIds ?? [];
+    if (narrativeWeight.expectedWinnerTeamId !== undefined && worldState.winnerTeamId !== undefined) {
+        if (narrativeWeight.expectedWinnerTeamId !== worldState.winnerTeamId) {
+            score -= 28;
+            violations.push({
+                code: "expected_winner_lost",
+                message: `Expected team ${narrativeWeight.expectedWinnerTeamId} to win, but team ${worldState.winnerTeamId} prevailed.`,
+                severity: "high",
+            });
+        }
+    }
+    if (narrativeWeight.expectedWinnerId !== undefined && worldState.winnerId !== undefined) {
+        if (narrativeWeight.expectedWinnerId !== worldState.winnerId) {
+            score -= 22;
+            violations.push({
+                code: "expected_winner_lost",
+                message: `Expected entity ${narrativeWeight.expectedWinnerId} to win, but entity ${worldState.winnerId} won.`,
+                severity: "medium",
+            });
+        }
+    }
+    const deadHeroes = heroIds.filter(id => worldState.casualtiesByEntityId?.[id]);
+    if (deadHeroes.length > 0 && (narrativeWeight.desiredBeat === "heroic_near_win" || narrativeWeight.desiredBeat === "clean_victory")) {
+        score -= 35;
+        violations.push({
+            code: "hero_fell_to_mook",
+            message: `Named hero(es) ${deadHeroes.join(", ")} died against the target beat.`,
+            severity: "high",
+        });
+    }
+    const improbableWins = (worldState.rareEventRolls ?? []).filter(r => r.happened && r.chance <= 0.01);
+    if (improbableWins.length > Math.max(0, Math.round(2 * tolerance))) {
+        score -= 18;
+        violations.push({
+            code: "unlikely_chain",
+            message: `Outcome relied on ${improbableWins.length} ultra-rare events (${improbableWins.map(r => r.label).join(", ")}).`,
+            severity: "medium",
+        });
+    }
+    if (narrativeWeight.desiredBeat === "heroic_near_win" && heroIds.length > 0) {
+        const hero = heroIds[0];
+        const eliminationOrder = worldState.eliminationOrder ?? [];
+        const heroElimIndex = eliminationOrder.indexOf(hero);
+        if (heroElimIndex !== -1) {
+            score -= 30;
+            violations.push({
+                code: "hero_fell_to_mook",
+                message: `Hero ${hero} was eliminated at position ${heroElimIndex + 1} during a near-win target beat.`,
+                severity: "high",
+            });
+        }
+    }
+    const suggestedSeeds = buildSuggestedSeeds(score, narrativeWeight.desiredBeat);
+    return { score: clampScore(score), violations, suggestedSeeds };
+}
+function buildSuggestedSeeds(score, beat) {
+    const base = beat === "heroic_near_win" ? 7300 : beat === "clean_victory" ? 4100 : 9100;
+    const adjustment = Math.max(1, Math.trunc((100 - score) / 5));
+    return [base + adjustment, base + adjustment + 17, base + adjustment + 49];
+}
+export function scorePlausibility(worldState, narrativeWeight) {
+    return analyzePlausibility(worldState, narrativeWeight).score;
+}

package/dist/src/narrative-layer.d.ts

@@ -18,3 +18,5 @@ export * from "./narrative.js";
 export * from "./narrative-stress.js";
 export * from "./metrics.js";
 export * from "./arena.js";
+export * from "./narrative/combat-logger.js";
+export * from "./narrative/plausibility.js";

package/dist/src/narrative-layer.js

@@ -18,3 +18,5 @@ export * from "./narrative.js";
 export * from "./narrative-stress.js";
 export * from "./metrics.js";
 export * from "./arena.js";
+export * from "./narrative/combat-logger.js";
+export * from "./narrative/plausibility.js";

package/dist/src/navigation/causal-chain.d.ts

@@ -0,0 +1,26 @@
+import type { TraceEvent } from "../sim/trace.js";
+export interface TickRange {
+    start: number;
+    end: number;
+}
+export interface CausalFactor {
+    label: string;
+    weight: number;
+    evidence: string[];
+}
+export interface Explanation {
+    entityId: number;
+    tickRange: TickRange;
+    summary: string;
+    factors: CausalFactor[];
+    mermaid: string;
+}
+export interface ExplanationContext {
+    trace: TraceEvent[];
+    windPenaltyByTick?: Record<number, number>;
+    fatigueByEntityId?: Record<number, number>;
+}
+export declare function explainOutcome(entityId: number, tickRange: TickRange, context: ExplanationContext): Explanation;
+export declare function createCausalExplainer(context: ExplanationContext): {
+    explainOutcome: (entityId: number, tickRange: TickRange) => Explanation;
+};

package/dist/src/navigation/causal-chain.js

@@ -0,0 +1,74 @@
+import { TraceKinds } from "../sim/kinds.js";
+function inRange(tick, range) {
+    return tick >= range.start && tick <= range.end;
+}
+function toMermaid(entityId, factors) {
+    const lines = [
+        "flowchart TD",
+        `  ROOT[Why entity ${entityId} got this outcome]`,
+    ];
+    for (let i = 0; i < factors.length; i++) {
+        const node = `F${i}`;
+        lines.push(`  ROOT --> ${node}[${factors[i].label} (${factors[i].weight.toFixed(2)})]`);
+        for (let e = 0; e < factors[i].evidence.length; e++) {
+            lines.push(`  ${node} --> ${node}_${e}[${factors[i].evidence[e]}]`);
+        }
+    }
+    return lines.join("\n");
+}
+export function explainOutcome(entityId, tickRange, context) {
+    const relevant = context.trace.filter(ev => inRange(ev.tick, tickRange));
+    const missEvents = relevant.filter((ev) => ev.kind === TraceKinds.ProjectileHit && ev.shooterId === entityId && !ev.hit);
+    const totalShots = relevant.filter((ev) => ev.kind === TraceKinds.ProjectileHit && ev.shooterId === entityId).length;
+    const avgDistance = missEvents.length > 0
+        ? missEvents.reduce((sum, ev) => sum + ev.distance_m, 0) / missEvents.length
+        : 0;
+    const windPenalty = missEvents.reduce((sum, ev) => sum + (context.windPenaltyByTick?.[ev.tick] ?? 0), 0);
+    const fatigue = context.fatigueByEntityId?.[entityId] ?? 0;
+    const factors = [];
+    if (missEvents.length > 0) {
+        factors.push({
+            label: "Range pressure",
+            weight: Math.min(1, avgDistance / 50000),
+            evidence: [`${missEvents.length}/${totalShots} shots missed`, `Average miss distance ${(avgDistance / 1000).toFixed(1)}m`],
+        });
+    }
+    if (fatigue > 0) {
+        factors.push({
+            label: "Fatigue accumulation",
+            weight: Math.min(1, fatigue),
+            evidence: [`Fatigue score ${fatigue.toFixed(2)} reduced aim stability`],
+        });
+    }
+    if (windPenalty > 0) {
+        factors.push({
+            label: "Crosswind interference",
+            weight: Math.min(1, windPenalty / 3),
+            evidence: [`Wind penalty total ${windPenalty.toFixed(2)} across selected ticks`],
+        });
+    }
+    if (factors.length === 0) {
+        factors.push({
+            label: "No dominant penalty detected",
+            weight: 0.2,
+            evidence: ["Trace did not include ranged misses or explicit penalties"],
+        });
+    }
+    const summary = missEvents.length >= 3
+        ? `Entity ${entityId} missed repeatedly due to stacked penalties in the selected tick window.`
+        : `Entity ${entityId} outcome explained from ${factors.length} weighted factor(s).`;
+    return {
+        entityId,
+        tickRange,
+        summary,
+        factors,
+        mermaid: toMermaid(entityId, factors),
+    };
+}
+export function createCausalExplainer(context) {
+    return {
+        explainOutcome(entityId, tickRange) {
+            return explainOutcome(entityId, tickRange, context);
+        },
+    };
+}

package/dist/src/netcode.d.ts

@@ -5,7 +5,7 @@ import { type Replay } from "./replay.js";
  * Compute a deterministic 64-bit hash of the simulation's core state.
  *
  * Covers `tick`, `seed`, and all entity data sorted by `id`.  Optional
- * subsystem fields (`__sensoryEnv`, `__factionRegistry`, etc.) are excluded —
+ * subsystem fields (`runtimeState.sensoryEnv`, `runtimeState.factionRegistry`, etc.) are excluded —
  * they are host concerns and do not affect simulation determinism.
  *
  * Use this as a desync checksum in multiplayer loops:

package/dist/src/netcode.js

@@ -44,7 +44,7 @@ function stableReplacer(_key, value) {
  * Compute a deterministic 64-bit hash of the simulation's core state.
  *
  * Covers `tick`, `seed`, and all entity data sorted by `id`.  Optional
- * subsystem fields (`__sensoryEnv`, `__factionRegistry`, etc.) are excluded —
+ * subsystem fields (`runtimeState.sensoryEnv`, `runtimeState.factionRegistry`, etc.) are excluded —
  * they are host concerns and do not affect simulation determinism.
  *
  * Use this as a desync checksum in multiplayer loops:

package/dist/src/performance/adaptive-tick.d.ts

@@ -0,0 +1,23 @@
+export type AdaptiveFallback = "reduceDistanceChecks" | "skipNonVisible" | "batchMoves";
+export interface AdaptiveTickConfig {
+    targetHz: number;
+    maxEntities: number;
+    fallback: AdaptiveFallback;
+    overshootToleranceMs?: number;
+}
+export interface AdaptiveTickInput {
+    frameTimeMs: number;
+    entityCount: number;
+    visibleEntityRatio: number;
+}
+export interface AdaptiveTickPlan {
+    fidelityScale: number;
+    processDistanceChecks: boolean;
+    processVisibilityOnly: boolean;
+    batchMovement: boolean;
+}
+export declare function createAdaptiveTick(config?: Partial<AdaptiveTickConfig>): {
+    config: AdaptiveTickConfig;
+    frameBudgetMs: number;
+    plan: (input: AdaptiveTickInput) => AdaptiveTickPlan;
+};

package/dist/src/performance/adaptive-tick.js

@@ -0,0 +1,50 @@
+const DEFAULT_CONFIG = {
+    targetHz: 60,
+    maxEntities: 2000,
+    fallback: "reduceDistanceChecks",
+    overshootToleranceMs: 1,
+};
+export function createAdaptiveTick(config = {}) {
+    const resolved = { ...DEFAULT_CONFIG, ...config };
+    const frameBudgetMs = 1000 / resolved.targetHz;
+    function plan(input) {
+        const overshoot = input.frameTimeMs - frameBudgetMs;
+        const overload = input.entityCount > resolved.maxEntities;
+        const shouldFallback = overload || overshoot > (resolved.overshootToleranceMs ?? 1);
+        if (!shouldFallback) {
+            return {
+                fidelityScale: 1,
+                processDistanceChecks: true,
+                processVisibilityOnly: false,
+                batchMovement: false,
+            };
+        }
+        if (resolved.fallback === "skipNonVisible") {
+            return {
+                fidelityScale: Math.max(0.3, input.visibleEntityRatio),
+                processDistanceChecks: true,
+                processVisibilityOnly: true,
+                batchMovement: false,
+            };
+        }
+        if (resolved.fallback === "batchMoves") {
+            return {
+                fidelityScale: 0.6,
+                processDistanceChecks: true,
+                processVisibilityOnly: false,
+                batchMovement: true,
+            };
+        }
+        return {
+            fidelityScale: 0.5,
+            processDistanceChecks: false,
+            processVisibilityOnly: false,
+            batchMovement: true,
+        };
+    }
+    return {
+        config: resolved,
+        frameBudgetMs,
+        plan,
+    };
+}

package/dist/src/plugins/loader.d.ts

@@ -0,0 +1,23 @@
+import type { LoadedPlugin } from "./types.js";
+export interface PluginLoaderOptions {
+    onTelemetry?: (pluginId: string, metric: string, payload: unknown) => void;
+    artifactsRoot?: string;
+    /**
+     * Optional evaluator override for hardened runtimes.
+     *
+     * Node hosts can swap this with a vm2/isolated-vm adapter for stronger isolation,
+     * while browser hosts can evaluate plugins in a Web Worker.
+     */
+    evaluator?: (source: string, filename: string) => unknown;
+}
+/**
+ * Load plugin manifest + module from disk.
+ *
+ * Security notes:
+ * - Node default uses node:vm with a minimal CommonJS sandbox.
+ * - For untrusted third-party code in production, use the `evaluator` option with
+ *   vm2 or isolated-vm.
+ * - Browser hosts should evaluate plugin code inside a dedicated Web Worker and
+ *   proxy only the PluginRuntimeApi methods.
+ */
+export declare function loadPlugin(path: string, options?: PluginLoaderOptions): LoadedPlugin;

package/dist/src/plugins/loader.js

@@ -0,0 +1,86 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import vm from "node:vm";
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        Object.freeze(value);
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+    }
+    return value;
+}
+function hasPermission(manifest, permission) {
+    return manifest.permissions.includes(permission);
+}
+function evaluateCommonJsModule(source, filename) {
+    const module = { exports: {} };
+    const sandbox = {
+        module,
+        exports: module.exports,
+    };
+    const script = new vm.Script(source, { filename });
+    script.runInNewContext(sandbox, {
+        timeout: 100,
+        microtaskMode: "afterEvaluate",
+    });
+    return module.exports;
+}
+function createRuntimeApi(manifest, options) {
+    return {
+        manifest,
+        hasPermission: permission => hasPermission(manifest, permission),
+        readWorldState: value => deepFreeze(structuredClone(value)),
+        mutateWorld: (worldState, mutator) => {
+            if (!hasPermission(manifest, "write:worldState")) {
+                throw new Error(`Plugin ${manifest.id} attempted world mutation without write:worldState permission`);
+            }
+            mutator(worldState);
+        },
+        emitTelemetry: (metric, payload) => {
+            if (!hasPermission(manifest, "write:telemetry")) {
+                throw new Error(`Plugin ${manifest.id} attempted telemetry write without write:telemetry permission`);
+            }
+            options.onTelemetry?.(manifest.id, metric, payload);
+        },
+        writeArtifact: (path, contents) => {
+            if (!hasPermission(manifest, "write:artifacts")) {
+                throw new Error(`Plugin ${manifest.id} attempted artifact write without write:artifacts permission`);
+            }
+            const outputPath = resolve(options.artifactsRoot ?? ".ananke-artifacts", manifest.id, path);
+            mkdirSync(dirname(outputPath), { recursive: true });
+            writeFileSync(outputPath, contents, "utf8");
+        },
+    };
+}
+/**
+ * Load plugin manifest + module from disk.
+ *
+ * Security notes:
+ * - Node default uses node:vm with a minimal CommonJS sandbox.
+ * - For untrusted third-party code in production, use the `evaluator` option with
+ *   vm2 or isolated-vm.
+ * - Browser hosts should evaluate plugin code inside a dedicated Web Worker and
+ *   proxy only the PluginRuntimeApi methods.
+ */
+export function loadPlugin(path, options = {}) {
+    const pluginRoot = resolve(path);
+    const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "plugin.json"), "utf8"));
+    const source = readFileSync(resolve(pluginRoot, "index.js"), "utf8");
+    const rawModule = (options.evaluator ?? evaluateCommonJsModule)(source, `${manifest.id}/index.js`);
+    const pluginModule = rawModule;
+    if (!pluginModule || typeof pluginModule.setup !== "function") {
+        throw new Error(`Plugin ${manifest.id} must export setup(api)`);
+    }
+    const hooks = pluginModule.setup(createRuntimeApi(manifest, options));
+    return {
+        manifest,
+        hooks,
+        async runHook(hook, context) {
+            const handler = hooks[hook];
+            if (!handler)
+                return;
+            await handler(context);
+        },
+    };
+}

package/dist/src/plugins/registry.d.ts

@@ -0,0 +1,11 @@
+export interface RegistryIndexEntry {
+    name: string;
+    manifestUrl: string;
+    moduleUrl: string;
+}
+export interface RegistryInstallerOptions {
+    registryIndexUrl?: string;
+    pluginsDir?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function installPluginFromRegistry(pluginName: string, options?: RegistryInstallerOptions): Promise<string>;

package/dist/src/plugins/registry.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const DEFAULT_REGISTRY_INDEX_URL = "https://raw.githubusercontent.com/its-not-rocket-science/ananke-plugins/main/index.json";
+export async function installPluginFromRegistry(pluginName, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const indexUrl = options.registryIndexUrl ?? DEFAULT_REGISTRY_INDEX_URL;
+    const pluginsDir = resolve(options.pluginsDir ?? "plugins");
+    const indexResp = await fetchImpl(indexUrl);
+    if (!indexResp.ok) {
+        throw new Error(`Failed to fetch registry index: ${indexResp.status} ${indexResp.statusText}`);
+    }
+    const entries = (await indexResp.json());
+    const entry = entries.find(candidate => candidate.name === pluginName);
+    if (!entry) {
+        throw new Error(`Plugin ${pluginName} was not found in ${indexUrl}`);
+    }
+    const [manifestResp, moduleResp] = await Promise.all([
+        fetchImpl(entry.manifestUrl),
+        fetchImpl(entry.moduleUrl),
+    ]);
+    if (!manifestResp.ok || !moduleResp.ok) {
+        throw new Error(`Failed to fetch ${pluginName} package files from registry`);
+    }
+    mkdirSync(resolve(pluginsDir, pluginName), { recursive: true });
+    writeFileSync(resolve(pluginsDir, pluginName, "plugin.json"), await manifestResp.text(), "utf8");
+    writeFileSync(resolve(pluginsDir, pluginName, "index.js"), await moduleResp.text(), "utf8");
+    return resolve(pluginsDir, pluginName);
+}