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

package/dist/src/debug.d.ts

@@ -2,6 +2,7 @@ import type { WorldState } from "./sim/world.js";
 import type { Vec3 } from "./sim/vec3.js";
 import type { Q } from "./units.js";
 import type { TraceEvent } from "./sim/trace.js";
+import { type Explanation, type ExplanationContext, type TickRange } from "./navigation/causal-chain.js";
 /**
  * Per-entity motion state — position, velocity, and facing direction.
  * Suitable for overlaying movement arrows in a host renderer.
@@ -84,3 +85,8 @@ export interface ConditionSample {
  *   const samples = extractConditionSamples(past);
  */
 export declare function extractConditionSamples(world: WorldState): ConditionSample[];
+/**
+ * Convenience adapter for debugger UIs that need a reasoned explanation
+ * for an entity outcome over a tick range.
+ */
+export declare function explainOutcomeFromTrace(entityId: number, tickRange: TickRange, context: ExplanationContext): Explanation;

package/dist/src/debug.js

@@ -6,6 +6,7 @@
 // Each function transforms WorldState or TraceEvent[] into a structured
 // snapshot that a host renderer can consume directly.
 import { TraceKinds } from "./sim/kinds.js";
+import { explainOutcome } from "./navigation/causal-chain.js";
 /**
  * Extract per-entity motion vectors from the current world state.
  * Call once per tick after stepWorld to get the latest motion snapshot.
@@ -74,3 +75,11 @@ export function extractConditionSamples(world) {
         dead: e.injury.dead,
     }));
 }
+// ─── Causal chain explanations ───────────────────────────────────────────────
+/**
+ * Convenience adapter for debugger UIs that need a reasoned explanation
+ * for an entity outcome over a tick range.
+ */
+export function explainOutcomeFromTrace(entityId, tickRange, context) {
+    return explainOutcome(entityId, tickRange, context);
+}

package/dist/src/determinism.d.ts

@@ -0,0 +1,12 @@
+import type { WorldState } from "./sim/world.js";
+export declare function assertNoFloatUsage(world: WorldState): void;
+export declare function assertNoFloatUsageInProduction(world: WorldState): void;
+/**
+ * Strict deterministic-world invariants used by CI fuzzing and replay checks.
+ *
+ * Covers:
+ * - no NaN/Infinity in core numeric state
+ * - deterministic ordering in entity/id lists
+ * - stable entity indexing assumptions used by kernel/index layers
+ */
+export declare function assertDeterministicWorldLike(world: WorldState, stage?: string): void;

package/dist/src/determinism.js

@@ -0,0 +1,93 @@
+let asserted = false;
+function assertInteger(name, value) {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new Error(`determinism assertion failed: ${name} must be a finite integer, received ${value}`);
+    }
+}
+export function assertNoFloatUsage(world) {
+    assertInteger("world.tick", world.tick);
+    assertInteger("world.seed", world.seed);
+    for (const e of world.entities) {
+        assertInteger(`entity:${e.id}.position.x`, e.position_m.x);
+        assertInteger(`entity:${e.id}.position.y`, e.position_m.y);
+        assertInteger(`entity:${e.id}.velocity.x`, e.velocity_mps.x);
+        assertInteger(`entity:${e.id}.velocity.y`, e.velocity_mps.y);
+        assertInteger(`entity:${e.id}.injury.fluidLoss`, e.injury.fluidLoss);
+        assertInteger(`entity:${e.id}.injury.shock`, e.injury.shock);
+        assertInteger(`entity:${e.id}.injury.consciousness`, e.injury.consciousness);
+    }
+}
+export function assertNoFloatUsageInProduction(world) {
+    if (asserted)
+        return;
+    asserted = true;
+    if (typeof process !== "undefined" && process.env.NODE_ENV === "production") {
+        assertNoFloatUsage(world);
+    }
+}
+function assertFiniteNumber(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`determinism invariant failed: ${name} must be a finite number, received ${String(value)}`);
+    }
+}
+function assertSortedUniqueAscending(name, values) {
+    let prev = -Infinity;
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        assertFiniteNumber(`${name}[${i}]`, value);
+        if (!Number.isInteger(value)) {
+            throw new Error(`determinism invariant failed: ${name}[${i}] must be an integer id, received ${String(value)}`);
+        }
+        if (value <= prev) {
+            throw new Error(`determinism invariant failed: ${name} must be strictly ascending (idx ${i - 1}=${prev}, idx ${i}=${value})`);
+        }
+        prev = value;
+    }
+}
+/**
+ * Strict deterministic-world invariants used by CI fuzzing and replay checks.
+ *
+ * Covers:
+ * - no NaN/Infinity in core numeric state
+ * - deterministic ordering in entity/id lists
+ * - stable entity indexing assumptions used by kernel/index layers
+ */
+export function assertDeterministicWorldLike(world, stage = "unknown") {
+    assertFiniteNumber(`world.tick @${stage}`, world.tick);
+    assertFiniteNumber(`world.seed @${stage}`, world.seed);
+    if (!Number.isInteger(world.tick)) {
+        throw new Error(`determinism invariant failed: world.tick @${stage} must be an integer`);
+    }
+    if (!Number.isInteger(world.seed)) {
+        throw new Error(`determinism invariant failed: world.seed @${stage} must be an integer`);
+    }
+    const ids = world.entities.map((e) => e.id);
+    assertSortedUniqueAscending(`world.entities.id @${stage}`, ids);
+    const byId = new Map();
+    for (let i = 0; i < world.entities.length; i++) {
+        const e = world.entities[i];
+        byId.set(e.id, i);
+        assertFiniteNumber(`entity:${e.id}.id @${stage}`, e.id);
+        assertFiniteNumber(`entity:${e.id}.teamId @${stage}`, e.teamId);
+        assertFiniteNumber(`entity:${e.id}.position.x @${stage}`, e.position_m.x);
+        assertFiniteNumber(`entity:${e.id}.position.y @${stage}`, e.position_m.y);
+        assertFiniteNumber(`entity:${e.id}.position.z @${stage}`, e.position_m.z);
+        assertFiniteNumber(`entity:${e.id}.velocity.x @${stage}`, e.velocity_mps.x);
+        assertFiniteNumber(`entity:${e.id}.velocity.y @${stage}`, e.velocity_mps.y);
+        assertFiniteNumber(`entity:${e.id}.velocity.z @${stage}`, e.velocity_mps.z);
+        assertFiniteNumber(`entity:${e.id}.injury.fluidLoss @${stage}`, e.injury.fluidLoss);
+        assertFiniteNumber(`entity:${e.id}.injury.shock @${stage}`, e.injury.shock);
+        assertFiniteNumber(`entity:${e.id}.injury.consciousness @${stage}`, e.injury.consciousness);
+        assertFiniteNumber(`entity:${e.id}.grapple.holdingTargetId @${stage}`, e.grapple.holdingTargetId);
+        assertFiniteNumber(`entity:${e.id}.action.attackCooldownTicks @${stage}`, e.action.attackCooldownTicks);
+        assertFiniteNumber(`entity:${e.id}.action.defenceCooldownTicks @${stage}`, e.action.defenceCooldownTicks);
+        assertFiniteNumber(`entity:${e.id}.action.grappleCooldownTicks @${stage}`, e.action.grappleCooldownTicks);
+        assertSortedUniqueAscending(`entity:${e.id}.grapple.heldByIds @${stage}`, e.grapple.heldByIds);
+    }
+    for (const [id, idx] of byId) {
+        const entityAtIndex = world.entities[idx];
+        if (!entityAtIndex || entityAtIndex.id !== id) {
+            throw new Error(`determinism invariant failed: unstable entity indexing for id=${id} @${stage}`);
+        }
+    }
+}

package/dist/src/dialogue.d.ts

@@ -1,6 +1,9 @@
 import type { Q } from "./units.js";
 import type { Entity } from "./sim/entity.js";
 import type { NarrativeConfig } from "./narrative.js";
+import type { FactionRegistry } from "./faction.js";
+import type { RelationshipGraph, RelationshipEventType } from "./relationships.js";
+import type { CampaignState } from "./campaign.js";
 /** A lightweight trade item for negotiation offers. Full item economy is Phase 25. */
 export interface TradeItem {
     id: string;
@@ -61,6 +64,18 @@ export interface DialogueContext {
     tick: number;
     sharedFaction?: boolean;
     priorFailedAttempts?: number;
+    /** Initiator standing with target's faction (q(0.5)=neutral). */
+    factionStanding_Q?: Q;
+    /** Existing interpersonal trust between initiator and target. */
+    relationshipTrust_Q?: Q;
+    /** Existing interpersonal affinity (-q(1.0)..q(1.0)). */
+    relationshipAffinity_Q?: Q;
+    /** Initiator fame axis from renown registry. */
+    initiatorRenown_Q?: Q;
+    /** Initiator dark reputation axis from renown registry. */
+    initiatorInfamy_Q?: Q;
+    /** Campaign pressure on target (siege, attrition, isolation). */
+    campaignPressure_Q?: Q;
 }
 /** Reduction to intimidation probability when target has the "leader" trait. */
 export declare const LEADER_INTIMIDATE_REDUCTION: Q;
@@ -79,6 +94,17 @@ export declare const SURRENDER_THRESHOLD: Q;
  * the target interprets the attempt as an insult and escalates.
  */
 export declare const ESCALATE_THRESHOLD: Q;
+export declare const STANDING_NEUTRAL_Q: Q;
+export declare const RELATIONSHIP_NEUTRAL_AFFINITY_Q: Q;
+export declare const INTIMIDATE_REPUTATION_WEIGHT_Q: Q;
+export declare const PERSUADE_STANDING_WEIGHT_Q: Q;
+export declare const PERSUADE_TRUST_WEIGHT_Q: Q;
+export declare const PERSUADE_AFFINITY_WEIGHT_Q: Q;
+export declare const PERSUADE_RENOWN_WEIGHT_Q: Q;
+export declare const SURRENDER_PRESSURE_WEIGHT_Q: Q;
+export declare const NEGOTIATE_STANDING_WEIGHT_Q: Q;
+export declare const NEGOTIATE_TRUST_WEIGHT_Q: Q;
+export declare const NEGOTIATE_AFFINITY_WEIGHT_Q: Q;
 /**
  * Compute the success probability for a dialogue action without rolling RNG.
  *
@@ -107,6 +133,21 @@ export declare function resolveDialogue(action: DialogueAction, ctx: DialogueCon
  * No-op if `outcome.result !== "success"`.
  */
 export declare function applyDialogueOutcome(outcome: DialogueOutcome, target: Entity): void;
+export interface DialogueStateAdapters {
+    factionRegistry?: FactionRegistry;
+    relationshipGraph?: RelationshipGraph;
+    campaign?: CampaignState;
+}
+export interface DialogueStateReport {
+    reputationDelta_Q: Q;
+    relationshipEvent?: RelationshipEventType;
+    campaignLogEntry?: string;
+}
+/**
+ * Apply dialogue outcome to broader campaign/faction/relationship state.
+ * All state holders are optional and explicitly injected by host code.
+ */
+export declare function applyDialogueState(action: DialogueAction, outcome: DialogueOutcome, ctx: DialogueContext, state: DialogueStateAdapters): DialogueStateReport;
 /**
  * Produce a human-readable description of a dialogue action and its outcome.
  *

package/dist/src/dialogue.js

@@ -10,6 +10,7 @@ import { SCALE, q, clampQ, qMul, mulDiv, to } from "./units.js";
 import { eventSeed } from "./sim/seeds.js";
 import { makeRng } from "./rng.js";
 import { resolveSignal } from "./competence/interspecies.js";
+import { recordRelationshipEvent } from "./relationships.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 /** Real-newton threshold where intimidation force factor reaches q(1.0). */
 const INTIMIDATE_FORCE_SCALE = to.N(4000);
@@ -30,6 +31,17 @@ export const SURRENDER_THRESHOLD = q(0.40);
  * the target interprets the attempt as an insult and escalates.
  */
 export const ESCALATE_THRESHOLD = q(0.20);
+export const STANDING_NEUTRAL_Q = q(0.50);
+export const RELATIONSHIP_NEUTRAL_AFFINITY_Q = q(0);
+export const INTIMIDATE_REPUTATION_WEIGHT_Q = q(0.20);
+export const PERSUADE_STANDING_WEIGHT_Q = q(0.20);
+export const PERSUADE_TRUST_WEIGHT_Q = q(0.20);
+export const PERSUADE_AFFINITY_WEIGHT_Q = q(0.10);
+export const PERSUADE_RENOWN_WEIGHT_Q = q(0.15);
+export const SURRENDER_PRESSURE_WEIGHT_Q = q(0.20);
+export const NEGOTIATE_STANDING_WEIGHT_Q = q(0.30);
+export const NEGOTIATE_TRUST_WEIGHT_Q = q(0.20);
+export const NEGOTIATE_AFFINITY_WEIGHT_Q = q(0.10);
 // ── RNG salts ─────────────────────────────────────────────────────────────────
 const SALT_INTIMIDATE = 0xD1A100;
 const SALT_PERSUADE = 0xD1A101;
@@ -57,6 +69,31 @@ function attentionDepthQ(depth) {
 function learningBonus(attentionDepth) {
     return clampQ(Math.max(0, attentionDepth - 4) * 250, 0, q(0.20));
 }
+function signedMulQ(value_Q, weight_Q) {
+    return Math.trunc((value_Q * weight_Q) / SCALE.Q);
+}
+function standingCenteredQ(standing_Q) {
+    return ((standing_Q ?? STANDING_NEUTRAL_Q) - STANDING_NEUTRAL_Q);
+}
+function persuasionSocialModifier(ctx) {
+    const standingBonus = signedMulQ(standingCenteredQ(ctx.factionStanding_Q), PERSUADE_STANDING_WEIGHT_Q);
+    const trustBonus = signedMulQ(((ctx.relationshipTrust_Q ?? STANDING_NEUTRAL_Q) - STANDING_NEUTRAL_Q), PERSUADE_TRUST_WEIGHT_Q);
+    const affinityBonus = signedMulQ((ctx.relationshipAffinity_Q ?? RELATIONSHIP_NEUTRAL_AFFINITY_Q), PERSUADE_AFFINITY_WEIGHT_Q);
+    const renownDelta = ((ctx.initiatorRenown_Q ?? q(0)) - (ctx.initiatorInfamy_Q ?? q(0)));
+    const renownBonus = signedMulQ(renownDelta, PERSUADE_RENOWN_WEIGHT_Q);
+    return (standingBonus + trustBonus + affinityBonus + renownBonus);
+}
+function intimidationReputationModifier(ctx) {
+    const profile = Math.max(ctx.initiatorRenown_Q ?? q(0), ctx.initiatorInfamy_Q ?? q(0));
+    return signedMulQ(profile, INTIMIDATE_REPUTATION_WEIGHT_Q);
+}
+function negotiationSocialBias(ctx) {
+    const standingBias = signedMulQ(standingCenteredQ(ctx.factionStanding_Q), NEGOTIATE_STANDING_WEIGHT_Q);
+    const trustCentered = ((ctx.relationshipTrust_Q ?? STANDING_NEUTRAL_Q) - STANDING_NEUTRAL_Q);
+    const trustBias = signedMulQ(trustCentered, NEGOTIATE_TRUST_WEIGHT_Q);
+    const affinityBias = signedMulQ((ctx.relationshipAffinity_Q ?? RELATIONSHIP_NEUTRAL_AFFINITY_Q), NEGOTIATE_AFFINITY_WEIGHT_Q);
+    return (standingBias + trustBias + affinityBias);
+}
 // ── Probability computation ───────────────────────────────────────────────────
 /**
  * Compute the success probability for a dialogue action without rolling RNG.
@@ -74,6 +111,7 @@ export function dialogueProbability(action, ctx) {
             return clampQ(forceFrac
                 + target.condition.fearQ
                 - target.attributes.resilience.distressTolerance
+                + intimidationReputationModifier(ctx)
                 - leaderRed, 0, SCALE.Q);
         }
         case "persuade": {
@@ -87,6 +125,7 @@ export function dialogueProbability(action, ctx) {
             return clampQ(dynamicBase
                 + learningBonus(target.attributes.perception?.attentionDepth ?? 0)
                 + (ctx.sharedFaction ? PERSUADE_FACTION_BONUS : 0)
+                + persuasionSocialModifier(ctx)
                 - (failed * PERSUADE_FAILURE_PENALTY), 0, SCALE.Q);
         }
         case "deceive": {
@@ -100,11 +139,16 @@ export function dialogueProbability(action, ctx) {
         }
         case "surrender":
             // Returns non-zero only when target's fear exceeds the acceptance threshold.
-            return clampQ(target.condition.fearQ - SURRENDER_THRESHOLD, 0, SCALE.Q);
+            return clampQ(target.condition.fearQ
+                + signedMulQ((ctx.campaignPressure_Q ?? q(0)), SURRENDER_PRESSURE_WEIGHT_Q)
+                - SURRENDER_THRESHOLD, 0, SCALE.Q);
         case "negotiate": {
             const given = action.offer.giving.reduce((s, i) => s + i.value, 0);
             const received = action.offer.receiving.reduce((s, i) => s + i.value, 0);
-            return given > received ? SCALE.Q : 0;
+            const total = Math.max(1, given + received);
+            const baseUtility_Q = Math.trunc(((given - received) * SCALE.Q) / total);
+            const adjusted = (baseUtility_Q + negotiationSocialBias(ctx));
+            return adjusted > 0 ? SCALE.Q : 0;
         }
         case "signal":
             // Phase 36: signal probability is computed in resolveSignal; here we return a placeholder
@@ -194,6 +238,73 @@ export function applyDialogueOutcome(outcome, target) {
         target.condition.surrendered = true;
     }
 }
+function applyFactionDelta(registry, actorId, factionId, delta_Q) {
+    if (!factionId || delta_Q === 0)
+        return;
+    let reps = registry.entityReputations.get(actorId);
+    if (!reps) {
+        reps = new Map();
+        registry.entityReputations.set(actorId, reps);
+    }
+    const current = reps.get(factionId) ?? STANDING_NEUTRAL_Q;
+    reps.set(factionId, clampQ((current + delta_Q), 0, SCALE.Q));
+}
+/**
+ * Apply dialogue outcome to broader campaign/faction/relationship state.
+ * All state holders are optional and explicitly injected by host code.
+ */
+export function applyDialogueState(action, outcome, ctx, state) {
+    applyDialogueOutcome(outcome, ctx.target);
+    let reputationDelta_Q = q(0);
+    let relationshipEvent;
+    let campaignLogEntry;
+    if (outcome.result === "success") {
+        if (action.kind === "surrender") {
+            reputationDelta_Q = q(0.05);
+            relationshipEvent = "saved";
+            campaignLogEntry = `Entity ${ctx.target.id} surrendered to entity ${ctx.initiator.id}.`;
+        }
+        else if (action.kind === "negotiate") {
+            reputationDelta_Q = q(0.04);
+            relationshipEvent = "gift_given";
+        }
+        else if (action.kind === "persuade") {
+            reputationDelta_Q = q(0.02);
+            relationshipEvent = "bonded";
+        }
+        else if (action.kind === "intimidate") {
+            reputationDelta_Q = q(-0.03);
+            relationshipEvent = "insult";
+        }
+    }
+    else if (outcome.result === "failure" || outcome.result === "escalate") {
+        if (action.kind === "negotiate" || action.kind === "persuade") {
+            relationshipEvent = "insult";
+        }
+    }
+    if (state.factionRegistry) {
+        applyFactionDelta(state.factionRegistry, ctx.initiator.id, ctx.target.faction, reputationDelta_Q);
+    }
+    if (state.relationshipGraph && relationshipEvent) {
+        recordRelationshipEvent(state.relationshipGraph, ctx.initiator.id, ctx.target.id, {
+            tick: ctx.tick,
+            type: relationshipEvent,
+            magnitude_Q: outcome.result === "success" ? q(0.20) : q(0.10),
+        });
+    }
+    if (state.campaign && campaignLogEntry) {
+        state.campaign.log.push({
+            worldTime_s: state.campaign.worldTime_s,
+            text: campaignLogEntry,
+        });
+    }
+    const report = { reputationDelta_Q };
+    if (relationshipEvent !== undefined)
+        report.relationshipEvent = relationshipEvent;
+    if (campaignLogEntry !== undefined)
+        report.campaignLogEntry = campaignLogEntry;
+    return report;
+}
 // ── Narrative ─────────────────────────────────────────────────────────────────
 /** Short display label per action kind. */
 function actionLabel(action) {

package/dist/src/economy.d.ts

@@ -33,6 +33,60 @@ export interface TradeEvaluation {
     /** True when the accepting party has all "want" items in sufficient quantity. */
     feasible: boolean;
 }
+export interface DurabilityValuePolicy {
+    /**
+     * Minimum retained value fraction even at zero condition.
+     * Useful for salvage economies.
+     */
+    salvageFloorFraction?: number;
+    /**
+     * Curvature applied to condition in [0, 1].
+     * - >1 discounts damaged gear harder.
+     * - <1 is more forgiving to worn gear.
+     */
+    conditionExponent?: number;
+}
+export interface ItemizedCount {
+    itemId: string;
+    count: number;
+}
+export interface DropResolution {
+    dropped: string[];
+    guaranteed: string[];
+    probabilistic: string[];
+    preventedByState: boolean;
+    source: "dead" | "incapacitated" | "none";
+}
+export interface TradeInventorySnapshot {
+    ownedCount: number;
+    shortageCount: number;
+    entryUnitValue: number;
+    offerUnitValue: number;
+}
+export interface TradeEvaluationDetailed extends TradeEvaluation {
+    giveValue: number;
+    wantValue: number;
+    shortages: Array<{
+        itemId: string;
+        missingCount: number;
+    }>;
+    snapshots: Map<string, TradeInventorySnapshot>;
+}
+export interface EconomyHostReport {
+    label: string;
+    totals: {
+        grossValue: number;
+        netValue: number;
+        lineCount: number;
+    };
+    lines: Array<{
+        itemId: string;
+        count: number;
+        unitValue: number;
+        totalValue: number;
+    }>;
+    tags: string[];
+}
 /**
  * Campaign-level item inventory: maps itemId → { count, unitValue }.
  * `unitValue` is in cost units; used by totalInventoryValue.
@@ -65,14 +119,28 @@ export declare const WEAR_FUMBLE_THRESHOLD: Q;
  */
 export declare function computeItemValue(item: Item | MedicalResource, wear_Q?: Q): ItemValue;
 /**
- * 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 declare function armourConditionQ(resist_J: number, resistRemaining_J: number): Q;
+/** Convert condition to wear (`wear = 1 - condition`) in fixed-point space. */
+export declare function conditionToWearQ(condition_Q: Q): Q;
+/**
+ * Convert an ItemValue into market-usable unit values.
+ *
+ * This keeps `computeItemValue` stable and lets hosts pick stricter/looser
+ * durability discounting.
+ */
+export declare function toMarketValue(itemValue: ItemValue, policy?: DurabilityValuePolicy): {
+    buyValue: number;
+    sellValue: number;
+    conditionMultiplier: number;
+};
 /**
  * Apply one strike's worth of use-wear to a melee weapon.
  *
@@ -86,6 +154,12 @@ export declare function armourConditionQ(resist_J: number, resistRemaining_J: nu
  * The returned `wear_Q` should be written back to `weapon.wear_Q` by the caller.
  */
 export declare function applyWear(weapon: Weapon, actionIntensity_Q: Q, seed?: number): WearResult;
+/**
+ * Structured drop resolution for host-facing UI and telemetry.
+ */
+export declare function resolveDropsDetailed(entity: Entity, seed: number, extra?: DropTable, config?: {
+    dropOnIncapacitated?: boolean;
+}): DropResolution;
 /**
  * Compute the list of item IDs dropped by an entity on death or incapacitation.
  *
@@ -110,6 +184,26 @@ export declare function resolveDrops(entity: Entity, seed: number, extra?: DropT
  * `feasible` — the accepting party has all `want` items in sufficient quantities.
  */
 export declare function evaluateTradeOffer(offer: TradeOffer, inventory: ItemInventory): TradeEvaluation;
+/**
+ * Inventory-aware trade evaluation that surfaces shortages and value breakdown.
+ */
+export declare function evaluateTradeOfferDetailed(offer: TradeOffer, inventory: ItemInventory): TradeEvaluationDetailed;
+/** Merge simple itemized counts into an ItemInventory map. */
+export declare function mergeIntoInventory(inventory: ItemInventory, items: ItemizedCount[], resolver: (itemId: string) => number): ItemInventory;
+/** Build a host-facing value report for any itemized list. */
+export declare function createEconomyReport(label: string, entries: ItemizedCount[], resolver: (itemId: string) => number, tags?: string[]): EconomyHostReport;
+/**
+ * Example flow: post-battle loot screen.
+ */
+export declare function examplePostBattleLootFlow(entity: Entity, seed: number, resolver: (itemId: string) => number): EconomyHostReport;
+/**
+ * Example flow: repair/reuse loop that compares pre-repair vs post-repair resale.
+ */
+export declare function exampleRepairReuseLoop(item: Item, startingWear_Q: Q, repairedWear_Q: Q): EconomyHostReport;
+/**
+ * Example flow: settlement/shop interaction, including affordability and shortages.
+ */
+export declare function exampleSettlementTradeFlow(offer: TradeOffer, inventory: ItemInventory): TradeEvaluationDetailed;
 /**
  * Sum the total value of all items in an inventory (count × unitValue for each entry).
  */