@jgengine/core 0.10.0 → 0.12.0

package/dist/inventory/slotModel.js

@@ -1,6 +1,8 @@
+/** @internal */
 export function createSlots(size) {
     return new Array(Math.max(0, size)).fill(null);
 }
+/** @internal */
 export function normalizeSlots(values, size) {
     const grid = createSlots(size);
     for (let index = 0; index < size; index++)
@@ -10,6 +12,7 @@ export function normalizeSlots(values, size) {
 function inRange(grid, index) {
     return Number.isInteger(index) && index >= 0 && index < grid.length;
 }
+/** @internal */
 export function placeAt(grid, index, value) {
     if (!inRange(grid, index))
         return { status: "rejected", reason: "invalid-slot" };
@@ -19,6 +22,7 @@ export function placeAt(grid, index, value) {
     next[index] = value;
     return { status: "ok", grid: next };
 }
+/** @internal */
 export function removeAt(grid, index) {
     if (!inRange(grid, index))
         return { status: "rejected", reason: "invalid-slot" };
@@ -28,6 +32,7 @@ export function removeAt(grid, index) {
     next[index] = null;
     return { status: "ok", grid: next };
 }
+/** @internal */
 export function moveSlot(grid, from, to) {
     if (!inRange(grid, from) || !inRange(grid, to))
         return { status: "rejected", reason: "invalid-slot" };
@@ -39,6 +44,7 @@ export function moveSlot(grid, from, to) {
     next[to] = moved;
     return { status: "ok", grid: next };
 }
+/** @internal */
 export function firstEmpty(grid) {
     for (let index = 0; index < grid.length; index++) {
         if (grid[index] === null)
@@ -46,12 +52,14 @@ export function firstEmpty(grid) {
     }
     return null;
 }
+/** @internal */
 export function insertFirst(grid, value) {
     const index = firstEmpty(grid);
     if (index === null)
         return { status: "rejected", reason: "slot-occupied" };
     return placeAt(grid, index, value);
 }
+/** @internal */
 export function compactSlots(grid) {
     const filled = grid.filter((slot) => slot !== null);
     const next = createSlots(grid.length);
@@ -59,6 +67,7 @@ export function compactSlots(grid) {
         next[index] = filled[index];
     return next;
 }
+/** @internal */
 export function countFilled(grid) {
     let count = 0;
     for (const slot of grid)
@@ -66,6 +75,7 @@ export function countFilled(grid) {
             count += 1;
     return count;
 }
+/** @internal */
 export function indexOfSlot(grid, match) {
     for (let index = 0; index < grid.length; index++) {
         const slot = grid[index];

package/dist/item/durability.d.ts

@@ -33,6 +33,11 @@ export declare function durabilityFraction(state: DurabilityState): number;
 export declare function isBroken(state: DurabilityState): boolean;
 export declare function isDisabled(spec: DurabilitySpec, state: DurabilityState): boolean;
 export declare function wearAmount(spec: DurabilitySpec, kind: WearKind): number;
+/**
+ * Apply wear to an item, tracking breakage and repair eligibility.
+ *
+ * @capability durability track item wear, breakage, and repair
+ */
 export declare function applyWear(state: DurabilityState, amount: number): DurabilityState;
 export declare function wear(spec: DurabilitySpec, state: DurabilityState, kind: WearKind, times?: number): DurabilityState;
 export declare function canRepairAt(spec: DurabilitySpec, stationId?: string): boolean;

package/dist/item/durability.js

@@ -1,6 +1,4 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
+import { clamp } from "../math/scalar.js";
 export function createDurability(spec) {
     const max = Math.max(0, spec.max);
     return { current: max, max };
@@ -17,6 +15,11 @@ export function isDisabled(spec, state) {
 export function wearAmount(spec, kind) {
     return kind === "use" ? spec.wearPerUse ?? 0 : spec.wearPerHit ?? 0;
 }
+/**
+ * Apply wear to an item, tracking breakage and repair eligibility.
+ *
+ * @capability durability track item wear, breakage, and repair
+ */
 export function applyWear(state, amount) {
     if (amount <= 0)
         return state;

package/dist/item/itemIdentity.d.ts

@@ -0,0 +1,171 @@
+import type { InstalledPart, PartDef } from "./modularItem.js";
+/**
+ * The declarative identity of a built modular item: a caller-named family, its
+ * provenance tags, and the parts occupying its slots. This is the "what an item
+ * is" layer above the raw stat rollup in ./modularItem — a plain, serializable
+ * value with no game noun baked in ("gun", "manufacturer", "potion" are all
+ * caller data in `family`/`tags`).
+ */
+export interface ItemIdentity {
+    family: string;
+    tags: readonly string[];
+    parts: readonly InstalledPart[];
+}
+/**
+ * A predicate over an {@link ItemIdentity}, expressed as data so a whole rule
+ * set round-trips through JSON. An empty query matches every identity; each
+ * present field narrows the match and all present fields must hold (AND).
+ */
+export interface IdentityQuery {
+    /** Match only this family id; omit to match any family. */
+    family?: string;
+    /** Every listed tag must be present on the identity. */
+    allTags?: readonly string[];
+    /** At least one listed tag must be present on the identity. */
+    anyTags?: readonly string[];
+    /** A part of this category must occupy some slot. */
+    hasCategory?: string;
+    /** A part with this id must occupy some slot. */
+    hasPart?: string;
+}
+/**
+ * A rule that requires a second condition to hold whenever the first matches —
+ * e.g. "a scoped rifle requires a stock". Checked at completeness time, not
+ * during incremental placement, because the `then` side may be satisfied by a
+ * part chosen later in a generation pass.
+ */
+export interface RequireRule {
+    id: string;
+    kind: "require";
+    when: IdentityQuery;
+    then: IdentityQuery;
+    message?: string;
+}
+/**
+ * A rule that forbids a combination — e.g. "an incendiary barrel cannot pair
+ * with a cryo core". A forbid rule can never become satisfiable by adding more
+ * parts, so it is the check a backtracking generator runs on each candidate.
+ */
+export interface ForbidRule {
+    id: string;
+    kind: "forbid";
+    when: IdentityQuery;
+    forbid: IdentityQuery;
+    message?: string;
+}
+/**
+ * A cross-slot compatibility rule constraining which part/tag/family
+ * combinations a modular item may hold.
+ */
+export type CompatibilityRule = RequireRule | ForbidRule;
+/**
+ * A match/set bonus: extra stats granted when enough parts (or a tag) of a
+ * given kind are present — e.g. "3 Blackwood parts grant +recoil control".
+ * Counting is declarative (`countBy`/`value`) so the whole catalog is data.
+ */
+export interface SetBonus {
+    id: string;
+    /** Dimension counted for membership: a part category, a part id, or an identity tag. */
+    countBy: "category" | "partId" | "tag";
+    /** The value counted; membership is the number of matching parts (or 0/1 for a tag). */
+    value: string;
+    /** Minimum matching count for the bonus to activate. */
+    min: number;
+    /** Additive stat deltas applied when the bonus is active. */
+    stats: Record<string, number>;
+    /** Optional name fragment recorded in provenance/UI when active. */
+    namePart?: string;
+}
+/**
+ * One failed {@link CompatibilityRule}, carrying the rule id, its kind, and a
+ * human-readable message for UI or generator diagnostics.
+ */
+export interface ConstraintViolation {
+    ruleId: string;
+    kind: "require" | "forbid";
+    message: string;
+}
+/**
+ * A part proposed for a slot during generation, before it is committed to an
+ * identity. Used by the backtracking contract to test a placement in isolation.
+ */
+export interface CandidatePlacement {
+    slotId: string;
+    part: PartDef;
+}
+/**
+ * The serializable record of how an item was generated: its family, tags,
+ * per-slot part selection, applied set-bonus ids, and the deterministic seed.
+ * Enough for UI provenance display and byte-exact regeneration.
+ */
+export interface ItemProvenance {
+    family: string;
+    tags: readonly string[];
+    /** slotId -> partId of the selected parts. */
+    parts: Readonly<Record<string, string>>;
+    /** Ids of the set bonuses that were active, for display and re-derivation. */
+    bonuses: readonly string[];
+    /** Seed of the roll that produced this item; omit for hand-authored items. */
+    seed?: number;
+}
+/**
+ * Assemble an {@link ItemIdentity} from a family, tags, and installed parts.
+ *
+ * @capability item-identity assemble a serializable modular-item identity from family, tags, and installed parts
+ */
+export declare function identityOf(family: string, tags: readonly string[], parts: readonly InstalledPart[]): ItemIdentity;
+/**
+ * Test whether an identity satisfies a declarative {@link IdentityQuery}.
+ *
+ * @capability item-identity evaluate a data-defined compatibility query against a modular-item identity
+ */
+export declare function matchesQuery(identity: ItemIdentity, query: IdentityQuery): boolean;
+/**
+ * Collect every compatibility rule a completed identity violates. An empty
+ * result means the identity is legal.
+ *
+ * @capability item-identity validate a completed modular item against its compatibility rule set
+ */
+export declare function validateIdentity(identity: ItemIdentity, rules: readonly CompatibilityRule[]): ConstraintViolation[];
+/**
+ * Convenience predicate: true when {@link validateIdentity} finds no violations.
+ *
+ * @capability item-identity check whether a completed modular item is compatibility-valid
+ */
+export declare function isIdentityValid(identity: ItemIdentity, rules: readonly CompatibilityRule[]): boolean;
+/**
+ * The generic backtracking contract for procedural generation (see #908): given
+ * a partial identity and a candidate part, return the first forbid rule the
+ * placement would violate, or null if it stays viable. Require rules are ignored
+ * here because they may still be satisfied by a later placement.
+ *
+ * @capability item-identity test a candidate part placement against forbid rules for generation backtracking
+ */
+export declare function candidateViolatesForbid(partial: ItemIdentity, candidate: CandidatePlacement, rules: readonly CompatibilityRule[]): ForbidRule | null;
+/**
+ * Count how many parts (or tags) contribute to a set bonus on an identity.
+ *
+ * @capability item-identity count set-bonus membership across an item's parts and tags
+ */
+export declare function countSetMembers(identity: ItemIdentity, bonus: SetBonus): number;
+/**
+ * Select the set bonuses whose membership count meets their threshold, in the
+ * order they were declared.
+ *
+ * @capability item-identity resolve which match/set bonuses an item qualifies for
+ */
+export declare function activeSetBonuses(identity: ItemIdentity, bonuses: readonly SetBonus[]): SetBonus[];
+/**
+ * Fold a set of active bonuses' additive stats onto a stat map, returning a new
+ * map (the input is not mutated).
+ *
+ * @capability item-identity apply active set-bonus stats onto an item's resolved stats
+ */
+export declare function applySetBonuses(stats: Record<string, number>, bonuses: readonly SetBonus[]): Record<string, number>;
+/**
+ * Capture the provenance of a generated item — family, tags, per-slot parts,
+ * active bonus ids, and optional seed — as a JSON-safe record.
+ *
+ * @capability item-identity capture serializable provenance for UI display and deterministic regeneration
+ */
+export declare function captureProvenance(identity: ItemIdentity, activeBonuses: readonly SetBonus[], seed?: number): ItemProvenance;

package/dist/item/itemIdentity.js

@@ -0,0 +1,138 @@
+/**
+ * Assemble an {@link ItemIdentity} from a family, tags, and installed parts.
+ *
+ * @capability item-identity assemble a serializable modular-item identity from family, tags, and installed parts
+ */
+export function identityOf(family, tags, parts) {
+    return { family, tags, parts };
+}
+function hasCategory(identity, category) {
+    return identity.parts.some((installed) => installed.part.category === category);
+}
+function hasPart(identity, partId) {
+    return identity.parts.some((installed) => installed.part.id === partId);
+}
+/**
+ * Test whether an identity satisfies a declarative {@link IdentityQuery}.
+ *
+ * @capability item-identity evaluate a data-defined compatibility query against a modular-item identity
+ */
+export function matchesQuery(identity, query) {
+    if (query.family !== undefined && query.family !== identity.family)
+        return false;
+    if (query.allTags !== undefined && !query.allTags.every((tag) => identity.tags.includes(tag)))
+        return false;
+    if (query.anyTags !== undefined && !query.anyTags.some((tag) => identity.tags.includes(tag)))
+        return false;
+    if (query.hasCategory !== undefined && !hasCategory(identity, query.hasCategory))
+        return false;
+    if (query.hasPart !== undefined && !hasPart(identity, query.hasPart))
+        return false;
+    return true;
+}
+function ruleFails(identity, rule) {
+    if (!matchesQuery(identity, rule.when))
+        return false;
+    return rule.kind === "require" ? !matchesQuery(identity, rule.then) : matchesQuery(identity, rule.forbid);
+}
+function defaultMessage(rule) {
+    return rule.message ?? (rule.kind === "require" ? `${rule.id}: required combination missing` : `${rule.id}: forbidden combination`);
+}
+/**
+ * Collect every compatibility rule a completed identity violates. An empty
+ * result means the identity is legal.
+ *
+ * @capability item-identity validate a completed modular item against its compatibility rule set
+ */
+export function validateIdentity(identity, rules) {
+    const violations = [];
+    for (const rule of rules) {
+        if (ruleFails(identity, rule))
+            violations.push({ ruleId: rule.id, kind: rule.kind, message: defaultMessage(rule) });
+    }
+    return violations;
+}
+/**
+ * Convenience predicate: true when {@link validateIdentity} finds no violations.
+ *
+ * @capability item-identity check whether a completed modular item is compatibility-valid
+ */
+export function isIdentityValid(identity, rules) {
+    return validateIdentity(identity, rules).length === 0;
+}
+/**
+ * The generic backtracking contract for procedural generation (see #908): given
+ * a partial identity and a candidate part, return the first forbid rule the
+ * placement would violate, or null if it stays viable. Require rules are ignored
+ * here because they may still be satisfied by a later placement.
+ *
+ * @capability item-identity test a candidate part placement against forbid rules for generation backtracking
+ */
+export function candidateViolatesForbid(partial, candidate, rules) {
+    const projected = {
+        family: partial.family,
+        tags: partial.tags,
+        parts: [...partial.parts, { slotId: candidate.slotId, part: candidate.part }],
+    };
+    for (const rule of rules) {
+        if (rule.kind === "forbid" && ruleFails(projected, rule))
+            return rule;
+    }
+    return null;
+}
+/**
+ * Count how many parts (or tags) contribute to a set bonus on an identity.
+ *
+ * @capability item-identity count set-bonus membership across an item's parts and tags
+ */
+export function countSetMembers(identity, bonus) {
+    switch (bonus.countBy) {
+        case "category":
+            return identity.parts.filter((installed) => installed.part.category === bonus.value).length;
+        case "partId":
+            return identity.parts.filter((installed) => installed.part.id === bonus.value).length;
+        case "tag":
+            return identity.tags.includes(bonus.value) ? 1 : 0;
+    }
+}
+/**
+ * Select the set bonuses whose membership count meets their threshold, in the
+ * order they were declared.
+ *
+ * @capability item-identity resolve which match/set bonuses an item qualifies for
+ */
+export function activeSetBonuses(identity, bonuses) {
+    return bonuses.filter((bonus) => countSetMembers(identity, bonus) >= bonus.min);
+}
+/**
+ * Fold a set of active bonuses' additive stats onto a stat map, returning a new
+ * map (the input is not mutated).
+ *
+ * @capability item-identity apply active set-bonus stats onto an item's resolved stats
+ */
+export function applySetBonuses(stats, bonuses) {
+    const out = { ...stats };
+    for (const bonus of bonuses) {
+        for (const [key, delta] of Object.entries(bonus.stats))
+            out[key] = (out[key] ?? 0) + delta;
+    }
+    return out;
+}
+/**
+ * Capture the provenance of a generated item — family, tags, per-slot parts,
+ * active bonus ids, and optional seed — as a JSON-safe record.
+ *
+ * @capability item-identity capture serializable provenance for UI display and deterministic regeneration
+ */
+export function captureProvenance(identity, activeBonuses, seed) {
+    const parts = {};
+    for (const installed of identity.parts)
+        parts[installed.slotId] = installed.part.id;
+    return {
+        family: identity.family,
+        tags: [...identity.tags],
+        parts,
+        bonuses: activeBonuses.map((bonus) => bonus.id),
+        ...(seed === undefined ? {} : { seed }),
+    };
+}

package/dist/item/itemInstanceRegistry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A runtime store for procedurally generated item instances — a rolled unique gun, a rolled
+ * affixed relic — keyed by a generated id distinct from any static catalog id. The counterpart a
+ * game's `content.itemById` consults for ids `lootTable`'s `generate` entries hand back, so runtime
+ * rolls never need a hand-rolled parallel registry (#536.1).
+ */
+export interface ItemInstanceRegistry<TDef> {
+    /** Stores `def` under a fresh generated id derived from `baseId`; returns that id. */
+    register(baseId: string, def: TDef): string;
+    get(id: string): TDef | undefined;
+    has(id: string): boolean;
+    /** Drop a generated instance once nothing references it (consumed, destroyed, sold). */
+    release(id: string): void;
+    count(): number;
+}
+/**
+ * Builds an {@link ItemInstanceRegistry}; generated ids are `"<prefix>:<baseId>:<n>"`, unique per
+ * registry instance.
+ *
+ * @capability item-instance-registry a runtime store for procedurally generated item instances
+ */
+export declare function createItemInstanceRegistry<TDef>(prefix?: string): ItemInstanceRegistry<TDef>;
+/**
+ * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
+ * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.
+ *
+ * @capability item-instance-registry roll and register a procedural item as a loot-table drop
+ */
+export declare function proceduralLootEntry<TDef>(registry: ItemInstanceRegistry<TDef>, roll: (rng: () => number) => {
+    baseId: string;
+    def: TDef;
+}): (rng: () => number) => string;

package/dist/item/itemInstanceRegistry.js

@@ -0,0 +1,34 @@
+/**
+ * Builds an {@link ItemInstanceRegistry}; generated ids are `"<prefix>:<baseId>:<n>"`, unique per
+ * registry instance.
+ *
+ * @capability item-instance-registry a runtime store for procedurally generated item instances
+ */
+export function createItemInstanceRegistry(prefix = "item") {
+    let seq = 0;
+    const store = new Map();
+    return {
+        register(baseId, def) {
+            seq += 1;
+            const id = `${prefix}:${baseId}:${seq}`;
+            store.set(id, def);
+            return id;
+        },
+        get: (id) => store.get(id),
+        has: (id) => store.has(id),
+        release: (id) => void store.delete(id),
+        count: () => store.size,
+    };
+}
+/**
+ * Bridges any procedural roller into a `LootEntry.generate` callback: rolls a `{ baseId, def }` pair
+ * and registers it, returning the runtime id the loot roll hands back as the drop's `item`.
+ *
+ * @capability item-instance-registry roll and register a procedural item as a loot-table drop
+ */
+export function proceduralLootEntry(registry, roll) {
+    return (rng) => {
+        const rolled = roll(rng);
+        return registry.register(rolled.baseId, rolled.def);
+    };
+}

package/dist/item/itemgen.d.ts

@@ -0,0 +1,163 @@
+/**
+ * One selectable option in a generation step's pool: a stable `id` used in provenance and pinning,
+ * the payload `value` a chosen option contributes, and an optional relative `weight` (default 1).
+ */
+export interface GenOption<V = unknown> {
+    id: string;
+    value: V;
+    weight?: number;
+}
+/**
+ * Read-only view of the choices resolved so far, threaded into a later step's pool, constraint,
+ * weight function, or transform so a decision can depend on earlier picks (dependent choice).
+ */
+export interface GenChoices {
+    /** Whether a step has resolved to a (non-skipped) option. */
+    has(step: string): boolean;
+    /** The chosen option id for a step, or undefined if unresolved or skipped. */
+    optionId(step: string): string | undefined;
+    /** The chosen option value for a step, or undefined if unresolved or skipped. */
+    value<V = unknown>(step: string): V | undefined;
+}
+/**
+ * A step's candidate options: a fixed list, or a function of the choices resolved so far so pools
+ * can narrow to earlier picks (a slot pool that depends on a chosen category).
+ */
+export type GenPool<V = unknown> = readonly GenOption<V>[] | ((choices: GenChoices) => readonly GenOption<V>[]);
+/**
+ * One decision point in a {@link GenSchema}: pick a single option from a pool, honoring an optional
+ * constraint, dependent weighting, selection mode, and optionality. Steps resolve in array order.
+ */
+export interface GenStep<V = unknown> {
+    id: string;
+    pool: GenPool<V>;
+    /** `"weighted"` (default) picks proportional to weight; `"uniform"` ignores weight and picks evenly. */
+    select?: "weighted" | "uniform";
+    /** Constraint: only options for which this returns true are eligible, given the earlier choices. */
+    accept?: (option: GenOption<V>, choices: GenChoices) => boolean;
+    /** Override an option's weight as a function of earlier choices; falls back to `option.weight ?? 1`. */
+    weightOf?: (option: GenOption<V>, choices: GenChoices) => number;
+    /** When no option is eligible, skip this step instead of failing or backtracking. */
+    optional?: boolean;
+}
+/**
+ * Mutation surface a {@link GenTransform} uses to derive numeric fields after choices resolve.
+ * Every `set`/`add`/`mul` is captured as a {@link GenFieldRecord}, and `rng` is the same injected
+ * stream the choices drew from, so rolled derivations stay deterministic and explainable.
+ */
+export interface TransformApi {
+    readonly choices: GenChoices;
+    readonly rng: () => number;
+    /** Current value of a field, or 0 if unset. */
+    get(field: string): number;
+    /** Replace a field's value, recording the change. */
+    set(field: string, value: number, note?: string): void;
+    /** Add to a field's value, recording the change. */
+    add(field: string, amount: number, note?: string): void;
+    /** Multiply a field's value, recording the change. */
+    mul(field: string, factor: number, note?: string): void;
+}
+/**
+ * A named derivation over the numeric field bag, applied in schema order after all choices resolve
+ * (affix rolls, level scaling, budget spend). Each field mutation it makes is recorded as provenance.
+ */
+export interface GenTransform {
+    id: string;
+    apply: (api: TransformApi) => void;
+}
+/**
+ * The resolved-but-unvalidated draft passed to each {@link GenValidator}: the step choices, their
+ * values, and the transformed fields. Returning false from any validator rerolls the whole
+ * generation up to the attempt budget.
+ */
+export interface GenDraft {
+    choices: Readonly<Record<string, string>>;
+    values: Readonly<Record<string, unknown>>;
+    fields: Readonly<Record<string, number>>;
+}
+/** A final-assembly check over a {@link GenDraft}; false triggers a whole-pipeline reroll. */
+export type GenValidator = (draft: GenDraft) => boolean;
+/**
+ * Provenance for one resolved step: which option stuck, its effective weight, how many options were
+ * eligible after constraints, and how many eligible options backtracking rejected before this one.
+ * A skipped optional step is recorded with an empty `optionId`.
+ */
+export interface GenChoiceRecord {
+    step: string;
+    optionId: string;
+    weight: number;
+    eligible: number;
+    rerolls: number;
+}
+/** Provenance for one field mutation a transform made: which transform, field, op, and before/after. */
+export interface GenFieldRecord {
+    transform: string;
+    field: string;
+    op: "set" | "add" | "mul";
+    from: number;
+    to: number;
+    note?: string;
+}
+/**
+ * The full explanation of a generated result: how many whole-pipeline attempts it took, every step
+ * choice, and every field mutation. Plain, serializable data for UI, debugging, balancing, and
+ * regeneration.
+ */
+export interface GenProvenance {
+    attempts: number;
+    choices: readonly GenChoiceRecord[];
+    fields: readonly GenFieldRecord[];
+}
+/**
+ * A successful generation: the step-to-option map, step-to-value map, transformed numeric fields,
+ * and the {@link GenProvenance} that explains them. Entirely serializable; round-trips through
+ * save/load and multiplayer sync unchanged.
+ */
+export interface GenResult {
+    choices: Readonly<Record<string, string>>;
+    values: Readonly<Record<string, unknown>>;
+    fields: Readonly<Record<string, number>>;
+    provenance: GenProvenance;
+}
+/**
+ * The outcome of {@link generate}: either a successful {@link GenResult}, or a failure carrying the
+ * reason (`"unsatisfiable"` — constraints left no valid assignment; `"rejected"` — validators kept
+ * rejecting drafts) and the attempts spent.
+ */
+export type GenOutcome = {
+    ok: true;
+    result: GenResult;
+} | {
+    ok: false;
+    reason: "unsatisfiable" | "rejected";
+    attempts: number;
+};
+/**
+ * A caller-defined generation schema over plain data: ordered choice steps, optional field
+ * transforms, optional validators, and bounded reroll/backtracking budgets. Genre-agnostic — it
+ * carries no built-in notion of rarity, element, weapon, or name; those are caller step and option ids.
+ */
+export interface GenSchema {
+    steps: readonly GenStep[];
+    transforms?: readonly GenTransform[];
+    validate?: readonly GenValidator[];
+    /** Max whole-pipeline attempts when a validator rejects a draft (default 24). */
+    maxAttempts?: number;
+    /** Max option picks the backtracking search may spend satisfying constraints in one attempt (default 1024). */
+    maxPicks?: number;
+}
+/** Per-call options for {@link generate}. */
+export interface GenerateOptions {
+    /** Force a step to a specific option id, consuming no rng for it (a requested rarity or family). */
+    pin?: Readonly<Record<string, string>>;
+}
+/**
+ * Run a caller-defined {@link GenSchema} against an injected `rng` into a deterministic, serializable
+ * {@link GenResult} with full provenance. Composes weighted/uniform choice, dependent choice,
+ * constraints with bounded backtracking, field transforms, and validation reroll over plain data —
+ * the generic seam procedural loot, affix, and modular-part rollers assemble on. Identical schema,
+ * seed, and pins reproduce an identical result across server/client and save/load.
+ *
+ * @capability item-generation compose constraints, weighted pools, transforms, and provenance into a deterministic generated item
+ */
+export declare function generate(schema: GenSchema, rng: () => number, options?: GenerateOptions): GenOutcome;