@jgengine/core 0.9.0 → 0.11.0

package/dist/combat/resourcePool.js

@@ -1,3 +1,8 @@
+/**
+ * A regenerating resource pool — mana, stamina, energy — that actions spend from and that refills over time.
+ *
+ * @capability resource-pool a regenerating pool like mana or stamina that actions spend from
+ */
 export function createResourcePool(config) {
     let max = Math.max(0, config.max);
     const regenPerSecond = Math.max(0, config.regenPerSecond ?? 0);

package/dist/combat/rewardAllocation.d.ts

@@ -0,0 +1,121 @@
+/**
+ * One indivisible reward to distribute among participants — an opaque result id (a rolled drop, a
+ * currency bundle, a quest token) with an optional stack `count` and free-form `tags` for eligibility
+ * and provenance. Allocation never interprets the id; generation (loot tables, roll formulas) owns
+ * what it means, keeping the seam genre-agnostic.
+ */
+export interface RewardResult {
+    id: string;
+    count?: number;
+    tags?: readonly string[];
+}
+/**
+ * A participant that may receive rewards — an opaque recipient id (player, team, party slot) with an
+ * optional split `weight` (shared policy), eligibility `tags`, and an `eligible` gate. Ineligible
+ * recipients are excluded before any allocation decision so they never perturb others' streams.
+ */
+export interface RewardRecipient {
+    id: string;
+    weight?: number;
+    tags?: readonly string[];
+    eligible?: boolean;
+}
+/** The distribution policies allocation ships — each a distinct answer to "who gets this result". */
+export type RewardPolicyKind = "instanced" | "shared" | "copy" | "roundRobin" | "assigned" | "claimed";
+/** A `{ result, count }` slice of a reward — the unit shared pools and grants are expressed in. */
+export interface RewardShare {
+    result: string;
+    count: number;
+}
+/**
+ * An authoritative, serializable award of one result stack to one recipient — carries `via` (the
+ * policy that produced it) and `private` (replication scope) so provenance and visibility survive
+ * save/load and viewer projection. Applying a grant twice with the same identity is the caller's
+ * idempotency contract; this seam only decides who is owed what.
+ */
+export interface RewardGrant {
+    recipient: string;
+    result: string;
+    count: number;
+    via: RewardPolicyKind;
+    private: boolean;
+}
+/**
+ * A serializable pool of results left open for later claiming — first-come contested drops or a
+ * `reservedFor` personal reward. Tracks `eligible` claimants, optional `expiresAtMs`, and the
+ * authoritative `claimedBy` winner so reconnect and duplicate-claim attempts resolve idempotently.
+ */
+export interface ClaimablePool {
+    id: string;
+    via: RewardPolicyKind;
+    results: RewardShare[];
+    eligible: string[];
+    reservedFor: string | null;
+    expiresAtMs: number | null;
+    claimedBy: string | null;
+}
+/** How a `claimed` allocation exposes its pool: open first-come (`first`) or `reserved` to one recipient. */
+export interface RewardClaimSpec {
+    mode: "first" | "reserved";
+    reservedFor?: string;
+    expiresAtMs?: number;
+}
+/**
+ * The inputs one allocation pass consumes. `allocationSeed` governs distribution decisions
+ * (ordering, round-robin rotation, remainder splits, reservation) while the separate optional
+ * `generationSeed` seeds per-recipient `instanced` generation — keeping join order from perturbing
+ * other players' rolls. Provide `results` for pre-rolled policies, `generate` for `instanced`,
+ * `assignment` for `assigned`, and `claim` for `claimed`.
+ */
+export interface AllocationRequest {
+    recipients: readonly RewardRecipient[];
+    allocationSeed: string | number;
+    generationSeed?: string | number;
+    results?: readonly RewardResult[];
+    generate?: (rng: () => number, recipient: RewardRecipient) => readonly RewardResult[];
+    assignment?: Record<string, readonly string[]>;
+    claim?: RewardClaimSpec;
+    nowMs?: number;
+    private?: boolean;
+}
+/** The serializable result of an allocation pass — immediate `grants` plus any deferred `pools`. */
+export interface AllocationOutcome {
+    grants: RewardGrant[];
+    pools: ClaimablePool[];
+}
+/** The outcome of a claim attempt — the updated pool and the grants owed (empty when the claim is refused). */
+export interface ClaimOutcome {
+    pool: ClaimablePool;
+    grants: RewardGrant[];
+}
+/**
+ * Allocate reward results among participants under a named policy, returning immediate grants and/or
+ * claimable pools. Distribution is deterministic and serializable: the same seeds, recipients, and
+ * results yield an identical outcome on host and every peer regardless of join order, so allocation
+ * replicates as data without re-rolling. Reward *generation* stays upstream (loot tables, roll
+ * formulas); this seam only decides who is owed what.
+ *
+ * @capability reward-allocation distribute reward results among multiplayer participants deterministically
+ */
+export declare function allocateRewards(kind: RewardPolicyKind, request: AllocationRequest): AllocationOutcome;
+/**
+ * Resolve an authoritative claim against a pool. Idempotent: re-claiming an already-owned pool returns
+ * the same grants without re-awarding, a losing claimant gets no grants, and eligibility, reservation,
+ * and expiry are all enforced here — the authority, not UI hiding, decides ownership. Returns the
+ * updated (serializable) pool plus the grants owed.
+ *
+ * @capability reward-allocation resolve idempotent authoritative claims against a reward pool
+ */
+export declare function resolveClaim(pool: ClaimablePool, claimantId: string, options?: {
+    nowMs?: number;
+    private?: boolean;
+}): ClaimOutcome;
+/**
+ * Project an allocation outcome for one viewer, enforcing replication authoritatively: private grants
+ * belonging to other recipients are dropped, and pools the viewer cannot claim (not eligible, or
+ * reserved for someone else) are hidden — so private rewards never leak across the wire while
+ * provenance on the viewer's own grants is preserved.
+ *
+ * @capability reward-allocation filter reward grants and pools to a viewer so private rewards never leak
+ */
+export declare function filterOutcomeFor(outcome: AllocationOutcome, viewerId: string): AllocationOutcome;

package/dist/combat/rewardAllocation.js

@@ -0,0 +1,251 @@
+import { hashString, seededStreams } from "../random/rng.js";
+function countOf(result) {
+    const n = result.count ?? 1;
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+/** Eligible recipients in a deterministic, seed-shuffled order independent of input array order. */
+function orderedEligible(request) {
+    const eligible = request.recipients.filter((r) => r.eligible !== false);
+    const seed = String(request.allocationSeed);
+    return [...eligible].sort((a, b) => {
+        const ka = hashString(`${seed}:order:${a.id}`);
+        const kb = hashString(`${seed}:order:${b.id}`);
+        if (ka !== kb)
+            return ka - kb;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+}
+function requireResults(request, kind) {
+    if (request.results === undefined) {
+        throw new Error(`reward policy "${kind}" requires results`);
+    }
+    return request.results;
+}
+function grant(recipient, result, count, via, isPrivate) {
+    return { recipient, result, count, via, private: isPrivate };
+}
+/** Per-recipient independent generation: each eligible recipient rolls its own results from a stable stream. */
+function allocateInstanced(request) {
+    if (request.generate === undefined) {
+        throw new Error('reward policy "instanced" requires a generate function');
+    }
+    const streams = seededStreams(request.generationSeed ?? request.allocationSeed);
+    const isPrivate = request.private ?? true;
+    const grants = [];
+    for (const recipient of orderedEligible(request)) {
+        const rng = streams(`gen:${recipient.id}`);
+        for (const result of request.generate(rng, recipient)) {
+            const count = countOf(result);
+            if (count > 0)
+                grants.push(grant(recipient.id, result.id, count, "instanced", isPrivate));
+        }
+    }
+    return { grants, pools: [] };
+}
+/** Copy-to-all: every eligible recipient receives a full copy of every result. */
+function allocateCopy(request) {
+    const results = requireResults(request, "copy");
+    const isPrivate = request.private ?? false;
+    const grants = [];
+    for (const recipient of orderedEligible(request)) {
+        for (const result of results) {
+            const count = countOf(result);
+            if (count > 0)
+                grants.push(grant(recipient.id, result.id, count, "copy", isPrivate));
+        }
+    }
+    return { grants, pools: [] };
+}
+/**
+ * Shared pool: each result's count is split across eligible recipients by `weight` using the
+ * largest-remainder method, so the units always sum back to the original count with a deterministic,
+ * fair remainder distribution.
+ */
+function allocateShared(request) {
+    const results = requireResults(request, "shared");
+    const recipients = orderedEligible(request);
+    const isPrivate = request.private ?? false;
+    const grants = [];
+    if (recipients.length === 0)
+        return { grants, pools: [] };
+    const weights = recipients.map((r) => (r.weight !== undefined && r.weight > 0 ? r.weight : 1));
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    for (const result of results) {
+        const total = countOf(result);
+        if (total === 0)
+            continue;
+        const exact = weights.map((w) => (total * w) / totalWeight);
+        const base = exact.map((x) => Math.floor(x));
+        let remaining = total - base.reduce((sum, n) => sum + n, 0);
+        const byRemainder = recipients
+            .map((_, i) => i)
+            .sort((a, b) => {
+            const fa = exact[a] - base[a];
+            const fb = exact[b] - base[b];
+            if (fb !== fa)
+                return fb - fa;
+            return a - b; // canonical order tie-break
+        });
+        for (const i of byRemainder) {
+            if (remaining <= 0)
+                break;
+            base[i] += 1;
+            remaining -= 1;
+        }
+        recipients.forEach((recipient, i) => {
+            if (base[i] > 0)
+                grants.push(grant(recipient.id, result.id, base[i], "shared", isPrivate));
+        });
+    }
+    return { grants, pools: [] };
+}
+/** Round-robin: results are handed out one at a time across recipients in deterministic rotation order. */
+function allocateRoundRobin(request) {
+    const results = requireResults(request, "roundRobin");
+    const recipients = orderedEligible(request);
+    const isPrivate = request.private ?? false;
+    const grants = [];
+    if (recipients.length === 0)
+        return { grants, pools: [] };
+    results.forEach((result, index) => {
+        const count = countOf(result);
+        if (count === 0)
+            return;
+        const recipient = recipients[index % recipients.length];
+        grants.push(grant(recipient.id, result.id, count, "roundRobin", isPrivate));
+    });
+    return { grants, pools: [] };
+}
+/** Caller-defined assignment: each recipient receives exactly the result ids the `assignment` map names. */
+function allocateAssigned(request) {
+    const results = requireResults(request, "assigned");
+    if (request.assignment === undefined) {
+        throw new Error('reward policy "assigned" requires an assignment map');
+    }
+    const byId = new Map(results.map((r) => [r.id, r]));
+    const eligibleIds = new Set(orderedEligible(request).map((r) => r.id));
+    const isPrivate = request.private ?? false;
+    const grants = [];
+    for (const recipient of orderedEligible(request)) {
+        const assigned = request.assignment[recipient.id] ?? [];
+        for (const resultId of assigned) {
+            const result = byId.get(resultId);
+            if (result === undefined)
+                throw new Error(`assignment references unknown result "${resultId}"`);
+            if (!eligibleIds.has(recipient.id))
+                continue;
+            const count = countOf(result);
+            if (count > 0)
+                grants.push(grant(recipient.id, result.id, count, "assigned", isPrivate));
+        }
+    }
+    return { grants, pools: [] };
+}
+/**
+ * Claimed: results are pooled for later claiming rather than granted now. `first` mode leaves an open
+ * contested pool; `reserved` mode ties the pool to one recipient — the caller-named `reservedFor` or,
+ * absent that, a deterministically seed-picked eligible recipient.
+ */
+function allocateClaimed(request) {
+    const results = requireResults(request, "claimed");
+    const spec = request.claim ?? { mode: "first" };
+    const recipients = orderedEligible(request);
+    const shares = [];
+    for (const result of results) {
+        const count = countOf(result);
+        if (count > 0)
+            shares.push({ result: result.id, count });
+    }
+    let reservedFor = null;
+    if (spec.mode === "reserved") {
+        if (spec.reservedFor !== undefined) {
+            reservedFor = spec.reservedFor;
+        }
+        else if (recipients.length > 0) {
+            const pick = seededStreams(request.allocationSeed)("claim:reserve")();
+            reservedFor = recipients[Math.min(recipients.length - 1, Math.floor(pick * recipients.length))].id;
+        }
+    }
+    const pool = {
+        id: `pool:${hashString(`${request.allocationSeed}:claim`).toString(36)}`,
+        via: "claimed",
+        results: shares,
+        eligible: recipients.map((r) => r.id),
+        reservedFor,
+        expiresAtMs: spec.expiresAtMs ?? null,
+        claimedBy: null,
+    };
+    return { grants: [], pools: [pool] };
+}
+/**
+ * Allocate reward results among participants under a named policy, returning immediate grants and/or
+ * claimable pools. Distribution is deterministic and serializable: the same seeds, recipients, and
+ * results yield an identical outcome on host and every peer regardless of join order, so allocation
+ * replicates as data without re-rolling. Reward *generation* stays upstream (loot tables, roll
+ * formulas); this seam only decides who is owed what.
+ *
+ * @capability reward-allocation distribute reward results among multiplayer participants deterministically
+ */
+export function allocateRewards(kind, request) {
+    switch (kind) {
+        case "instanced":
+            return allocateInstanced(request);
+        case "copy":
+            return allocateCopy(request);
+        case "shared":
+            return allocateShared(request);
+        case "roundRobin":
+            return allocateRoundRobin(request);
+        case "assigned":
+            return allocateAssigned(request);
+        case "claimed":
+            return allocateClaimed(request);
+        default: {
+            const exhaustive = kind;
+            throw new Error(`unknown reward policy: ${String(exhaustive)}`);
+        }
+    }
+}
+function poolClaimable(pool, claimantId, nowMs) {
+    if (!pool.eligible.includes(claimantId))
+        return false;
+    if (pool.reservedFor !== null && pool.reservedFor !== claimantId)
+        return false;
+    if (pool.expiresAtMs !== null && nowMs !== undefined && nowMs > pool.expiresAtMs)
+        return false;
+    return true;
+}
+/**
+ * Resolve an authoritative claim against a pool. Idempotent: re-claiming an already-owned pool returns
+ * the same grants without re-awarding, a losing claimant gets no grants, and eligibility, reservation,
+ * and expiry are all enforced here — the authority, not UI hiding, decides ownership. Returns the
+ * updated (serializable) pool plus the grants owed.
+ *
+ * @capability reward-allocation resolve idempotent authoritative claims against a reward pool
+ */
+export function resolveClaim(pool, claimantId, options) {
+    const nowMs = options?.nowMs;
+    const grantsFor = (owner) => pool.results.map((share) => grant(owner, share.result, share.count, "claimed", options?.private ?? false));
+    if (pool.claimedBy !== null) {
+        return { pool, grants: pool.claimedBy === claimantId ? grantsFor(claimantId) : [] };
+    }
+    if (!poolClaimable(pool, claimantId, nowMs)) {
+        return { pool, grants: [] };
+    }
+    const claimed = { ...pool, claimedBy: claimantId };
+    return { pool: claimed, grants: grantsFor(claimantId) };
+}
+/**
+ * Project an allocation outcome for one viewer, enforcing replication authoritatively: private grants
+ * belonging to other recipients are dropped, and pools the viewer cannot claim (not eligible, or
+ * reserved for someone else) are hidden — so private rewards never leak across the wire while
+ * provenance on the viewer's own grants is preserved.
+ *
+ * @capability reward-allocation filter reward grants and pools to a viewer so private rewards never leak
+ */
+export function filterOutcomeFor(outcome, viewerId) {
+    return {
+        grants: outcome.grants.filter((g) => !g.private || g.recipient === viewerId),
+        pools: outcome.pools.filter((p) => p.eligible.includes(viewerId) && (p.reservedFor === null || p.reservedFor === viewerId)),
+    };
+}

package/dist/combat/shotOrigin.d.ts

@@ -1,14 +1,30 @@
 import type { EntityPosition } from "../scene/entityStore.js";
+import { type EntityColliderSet } from "../scene/colliders.js";
 import type { Aim } from "../scene/spatial.js";
 /**
  * How a shot's world-space origin (and optional direction) is resolved before prediction/settlement.
- * - `legacy` — `aim.origin` when present, else the shooter's entity position (pre-#431 default).
+ * - `converge` — the shot leaves the gun `muzzle` yet still passes through whatever the shooter's
+ *   sightline (crosshair) covers: origin is the muzzle offset, direction is bent from the muzzle to
+ *   the eye ray's aim point. The projectile system's default for a free `{ yaw, pitch }` aim, so a
+ *   bullet visibly comes from the barrel without missing the reticle. Needs a scene raycast to find
+ *   the aim point (`convergeShot`); a bare `resolveShot` degrades to a straight muzzle ray. Passes an
+ *   explicit `{ origin, direction }` aim through untouched.
+ * - `eye` — `aim.origin` when present, else the shooter's entity position raised to eye height; the
+ *   shot traces the shooter's sightline, so what the crosshair covers is what gets hit.
+ * - `legacy` — `aim.origin` when present, else the shooter's raw entity position (feet).
  * - `entity` — always the shooter's entity position.
  * - `entityOffset` / `muzzle` — entity-local offset rotated by the shooter's yaw (muzzle on a weapon model).
  * - `camera` — explicit camera/reticle world origin (and optional direction override).
  * - `world` — absolute world origin.
  */
 export type ShotOriginPolicy = {
+    kind: "converge";
+    muzzle?: EntityPosition;
+    height?: number;
+} | {
+    kind: "eye";
+    height?: number;
+} | {
     kind: "legacy";
 } | {
     kind: "entity";
@@ -34,7 +50,20 @@ export interface ResolvedShot {
 export interface ShotOriginDeps {
     positionOf(instanceId: string): EntityPosition | undefined;
     rotationYOf?(instanceId: string): number | undefined;
+    /** When provided, the `eye` policy sizes its height from the shooter's own hitbox instead of the humanoid default. */
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
 }
+/** Shot-origin and first-person camera eye height above an entity's position: 90% of the default 1.8m hitbox top. */
+export declare const DEFAULT_EYE_HEIGHT: number;
+/** Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown. */
+export declare function eyeHeightFromColliders(set: EntityColliderSet | null | undefined): number;
 export declare function aimDirection(aim: Aim): EntityPosition | null;
 export declare function aimSpreadDeg(aim: Aim): number;
 export declare function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy?: ShotOriginPolicy): ResolvedShot | null;
+/**
+ * Resolves a `converge` shot with scene knowledge: fires from the gun muzzle but bends the direction
+ * so the shot passes through the aim point the shooter's eye ray covers. `sightHit` casts the eye ray
+ * and returns where it lands (first impact), or `null` to fall back to a point `range` metres down the
+ * sightline. A `{ origin, direction }` aim is passed through unchanged (nothing to converge).
+ */
+export declare function convergeShot(deps: ShotOriginDeps, from: string, aim: Aim, range: number, sightHit: (origin: EntityPosition, direction: EntityPosition) => EntityPosition | null, muzzleOffset?: EntityPosition): ResolvedShot | null;

package/dist/combat/shotOrigin.js

@@ -1,5 +1,19 @@
-import { worldOffset } from "../scene/colliders.js";
+import { resolveColliders, worldOffset } from "../scene/colliders.js";
 const DEFAULT_MUZZLE_OFFSET = [0, 1.4, 0.35];
+const EYE_HEIGHT_RATIO = 0.9;
+/** Shot-origin and first-person camera eye height above an entity's position: 90% of the default 1.8m hitbox top. */
+export const DEFAULT_EYE_HEIGHT = EYE_HEIGHT_RATIO * 1.8;
+/** Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown. */
+export function eyeHeightFromColliders(set) {
+    const colliders = resolveColliders(set);
+    let top = 0;
+    for (const collider of colliders) {
+        const offsetY = collider.shape.offset?.[1] ?? 0;
+        const halfHeight = collider.shape.kind === "sphere" ? collider.shape.radius : collider.shape.halfExtents[1];
+        top = Math.max(top, offsetY + halfHeight);
+    }
+    return top > 0 ? top * EYE_HEIGHT_RATIO : DEFAULT_EYE_HEIGHT;
+}
 function normalize(vector) {
     const length = Math.sqrt(vector[0] * vector[0] + vector[1] * vector[1] + vector[2] * vector[2]);
     if (length === 0)
@@ -15,11 +29,37 @@ export function aimDirection(aim) {
 export function aimSpreadDeg(aim) {
     return "origin" in aim ? 0 : aim.spread ?? 0;
 }
-export function resolveShot(deps, from, aim, policy = { kind: "legacy" }) {
+export function resolveShot(deps, from, aim, policy = { kind: "eye" }) {
     const aimDir = aimDirection(aim);
     if (aimDir === null && policy.kind !== "camera" && policy.kind !== "world")
         return null;
     switch (policy.kind) {
+        case "converge": {
+            if ("origin" in aim) {
+                if (aimDir === null)
+                    return null;
+                return { origin: aim.origin, direction: aimDir };
+            }
+            if (aimDir === null)
+                return null;
+            const muzzle = resolveShot(deps, from, aim, { kind: "muzzle", offset: policy.muzzle });
+            return muzzle ?? null;
+        }
+        case "eye": {
+            if ("origin" in aim) {
+                if (aimDir === null)
+                    return null;
+                return { origin: aim.origin, direction: aimDir };
+            }
+            const position = deps.positionOf(from);
+            if (position === undefined || aimDir === null)
+                return null;
+            const height = policy.height ??
+                (deps.collidersOf !== undefined
+                    ? eyeHeightFromColliders(deps.collidersOf(from))
+                    : DEFAULT_EYE_HEIGHT);
+            return { origin: [position[0], position[1] + height, position[2]], direction: aimDir };
+        }
         case "legacy": {
             const origin = "origin" in aim ? aim.origin : deps.positionOf(from);
             if (origin === undefined || aimDir === null)
@@ -55,3 +95,31 @@ export function resolveShot(deps, from, aim, policy = { kind: "legacy" }) {
         }
     }
 }
+/**
+ * Resolves a `converge` shot with scene knowledge: fires from the gun muzzle but bends the direction
+ * so the shot passes through the aim point the shooter's eye ray covers. `sightHit` casts the eye ray
+ * and returns where it lands (first impact), or `null` to fall back to a point `range` metres down the
+ * sightline. A `{ origin, direction }` aim is passed through unchanged (nothing to converge).
+ */
+export function convergeShot(deps, from, aim, range, sightHit, muzzleOffset) {
+    const sight = resolveShot(deps, from, aim, { kind: "eye", height: undefined });
+    if (sight === null)
+        return null;
+    if ("origin" in aim)
+        return sight;
+    const muzzle = resolveShot(deps, from, aim, { kind: "muzzle", offset: muzzleOffset });
+    if (muzzle === null)
+        return sight;
+    const aimPoint = sightHit(sight.origin, sight.direction) ??
+        [
+            sight.origin[0] + sight.direction[0] * range,
+            sight.origin[1] + sight.direction[1] * range,
+            sight.origin[2] + sight.direction[2] * range,
+        ];
+    const direction = normalize([
+        aimPoint[0] - muzzle.origin[0],
+        aimPoint[1] - muzzle.origin[1],
+        aimPoint[2] - muzzle.origin[2],
+    ]);
+    return { origin: muzzle.origin, direction: direction ?? muzzle.direction };
+}

package/dist/combat/statusApplication.d.ts

@@ -0,0 +1,96 @@
+/**
+ * How a fresh application behaves when the target already carries the status.
+ * - `refresh` — reset duration, hold the existing stack count.
+ * - `stack` — add `add` stacks (default 1) up to `max`, and refresh duration.
+ * - `replace` — overwrite duration and magnitude, stacks reset to 1.
+ * - `ignore` — leave the existing instance untouched (first application wins).
+ */
+export type StatusStackPolicy = {
+    kind: "refresh";
+} | {
+    kind: "stack";
+    max?: number;
+    add?: number;
+} | {
+    kind: "replace";
+} | {
+    kind: "ignore";
+};
+/**
+ * A serializable, effect-agnostic description of a status a hit tries to apply: an opaque
+ * `status` id the game routes to its own effect/DoT pipeline, a base landing `chance`, and the
+ * duration/ticks/magnitude/attribution/stacking data the resolver needs. The engine never
+ * interprets `status` — it is a reference, not a built-in condition.
+ */
+export interface StatusApplicationSpec {
+    /** Opaque status/effect id the game applies (`"burn"`, `"slow"`, `"amplify"`). */
+    status: string;
+    /** Base landing probability in `[0,1]` before matchup scaling; defaults to 1 (always). */
+    chance?: number;
+    /** Base duration in milliseconds. */
+    durationMs?: number;
+    /** Base number of periodic ticks, when the status is periodic. */
+    ticks?: number;
+    /** Base per-application magnitude (damage/heal per tick, buff strength). */
+    magnitude?: number;
+    /** Behaviour when the target already carries this status; defaults to `refresh`. */
+    stack?: StatusStackPolicy;
+}
+/** A live status carried by a target — the serializable, replicable state a status application mutates. */
+export interface StatusInstance {
+    status: string;
+    /** Current stack count (>= 1 while active). */
+    stacks: number;
+    /** Milliseconds of life remaining. */
+    remainingMs: number;
+    /** Remaining periodic ticks, when tracked. */
+    ticks: number;
+    /** Per-application magnitude in force. */
+    magnitude: number;
+    /** Attribution: who/what applied (or last refreshed) the status. */
+    source?: string;
+}
+/** Statuses a target cannot receive at all — the immunity half of application policy. */
+export interface StatusImmunity {
+    statuses?: readonly string[];
+}
+/** Matchup-derived multipliers on the independent application axes. Each defaults to 1. */
+export interface StatusApplicationScale {
+    applyChance?: number;
+    magnitude?: number;
+    duration?: number;
+}
+/** Everything `resolveStatusApplication` needs; all data plus an injected RNG for reproducibility. */
+export interface StatusApplicationInput {
+    spec: StatusApplicationSpec;
+    /** Independent multipliers (typically from `resolveMatchup`). */
+    scale?: StatusApplicationScale;
+    /** The target's existing instance of this status, or `null`/absent when unafflicted. */
+    current?: StatusInstance | null;
+    immunity?: StatusImmunity | null;
+    /** Attribution written onto the resulting instance. */
+    source?: string;
+    /** Deterministic RNG returning `[0,1)`; defaults to `Math.random`. Pass a seeded stream for reproducibility. */
+    rng?: () => number;
+}
+/** Why an application did or did not take, plus the roll for provenance. */
+export type StatusApplicationOutcomeKind = "applied" | "refreshed" | "stacked" | "replaced" | "immune" | "missed" | "ignored";
+/** The result of one status application: the outcome, the resulting instance (if any), and the roll. */
+export interface StatusApplicationOutcome {
+    kind: StatusApplicationOutcomeKind;
+    /** The instance after application, or `null` when the status did not land / was blocked. */
+    instance: StatusInstance | null;
+    /** Effective landing chance after scaling, clamped to `[0,1]`. */
+    chance: number;
+    /** The RNG draw compared against `chance`; `null` when no roll was taken (immune/ignored). */
+    roll: number | null;
+}
+/**
+ * Resolve one status application: reject on immunity, roll landing chance against injected RNG,
+ * scale magnitude/duration by the matchup, then fold into any existing instance per the stacking
+ * policy. Deterministic given a seeded `rng`; pure over serializable data, so authority can run it
+ * and replicate only the returned `instance`.
+ *
+ * @capability status-application resolve a data-defined status application with chance, matchup scaling, and stacking policy
+ */
+export declare function resolveStatusApplication(input: StatusApplicationInput): StatusApplicationOutcome;