@erpg/dicecore 3.1.0

package/dist/v3/errors.d.cts

@@ -0,0 +1,37 @@
+export interface SourceSpan {
+    readonly start: number;
+    readonly end: number;
+}
+export type JsonPrimitive = boolean | number | string | null;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type DiceRollErrorCode = 'DICE_NOTATION_REQUIRED' | 'INPUT_TOO_LONG' | 'AST_TOO_DEEP' | 'TOO_MANY_NODES' | 'TOO_MANY_ROLLS' | 'TOO_MANY_INITIAL_DICE' | 'GENERATED_DICE_LIMIT_EXCEEDED' | 'RANDOM_BUDGET_EXCEEDED' | 'EVENT_LIMIT_EXCEEDED' | 'MODIFIER_STEP_LIMIT_EXCEEDED' | 'RESOLVED_GROUP_LIMIT_EXCEEDED' | 'RESULT_LIMIT_EXCEEDED' | 'OUTPUT_LIMIT_EXCEEDED' | 'DICE_SIDES_LIMIT_EXCEEDED' | 'INVALID_NOTATION' | 'UNSUPPORTED_NOTATION' | 'UNSUPPORTED_GROUP_MODIFIER' | 'NON_TERMINATING_MODIFIER' | 'IMPOSSIBLE_UNIQUE' | 'ROLL_EXECUTION_LIMIT' | 'RNG_UNAVAILABLE' | 'INVALID_SEED' | 'INVALID_REPLAY' | 'REPLAY_PLAN_MISMATCH' | 'INVALID_LIMIT' | 'UNSUPPORTED_REPLAY_VERSION' | 'NON_FINITE_RESULT' | 'INVALID_ERROR_DATA';
+export interface DiceErrorData {
+    readonly name: 'DiceRollError';
+    readonly code: DiceRollErrorCode;
+    readonly message: string;
+    readonly span: SourceSpan | null;
+    readonly input: string;
+    readonly details: JsonObject;
+}
+export interface DiceRollErrorOptions {
+    readonly code: DiceRollErrorCode;
+    readonly span?: SourceSpan | null;
+    readonly input?: string;
+    readonly details?: JsonObject;
+}
+/** A stable, JSON-safe error raised by the V3 compiler or executor. */
+export declare class DiceRollError extends Error {
+    readonly code: DiceRollErrorCode;
+    readonly span: SourceSpan | null;
+    readonly input: string;
+    readonly details: JsonObject;
+    constructor(message: string, options: DiceRollErrorOptions);
+    static fromJSON(data: unknown): DiceRollError;
+    toJSON(): DiceErrorData;
+}
+export declare function isDiceRollError(error: unknown): error is DiceRollError;
+/** Recognizes JSON-safe dice errors across workers, realms and process boundaries. */
+export declare function isDiceRollErrorData(value: unknown): value is DiceErrorData;

package/dist/v3/errors.d.ts

@@ -0,0 +1,37 @@
+export interface SourceSpan {
+    readonly start: number;
+    readonly end: number;
+}
+export type JsonPrimitive = boolean | number | string | null;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type DiceRollErrorCode = 'DICE_NOTATION_REQUIRED' | 'INPUT_TOO_LONG' | 'AST_TOO_DEEP' | 'TOO_MANY_NODES' | 'TOO_MANY_ROLLS' | 'TOO_MANY_INITIAL_DICE' | 'GENERATED_DICE_LIMIT_EXCEEDED' | 'RANDOM_BUDGET_EXCEEDED' | 'EVENT_LIMIT_EXCEEDED' | 'MODIFIER_STEP_LIMIT_EXCEEDED' | 'RESOLVED_GROUP_LIMIT_EXCEEDED' | 'RESULT_LIMIT_EXCEEDED' | 'OUTPUT_LIMIT_EXCEEDED' | 'DICE_SIDES_LIMIT_EXCEEDED' | 'INVALID_NOTATION' | 'UNSUPPORTED_NOTATION' | 'UNSUPPORTED_GROUP_MODIFIER' | 'NON_TERMINATING_MODIFIER' | 'IMPOSSIBLE_UNIQUE' | 'ROLL_EXECUTION_LIMIT' | 'RNG_UNAVAILABLE' | 'INVALID_SEED' | 'INVALID_REPLAY' | 'REPLAY_PLAN_MISMATCH' | 'INVALID_LIMIT' | 'UNSUPPORTED_REPLAY_VERSION' | 'NON_FINITE_RESULT' | 'INVALID_ERROR_DATA';
+export interface DiceErrorData {
+    readonly name: 'DiceRollError';
+    readonly code: DiceRollErrorCode;
+    readonly message: string;
+    readonly span: SourceSpan | null;
+    readonly input: string;
+    readonly details: JsonObject;
+}
+export interface DiceRollErrorOptions {
+    readonly code: DiceRollErrorCode;
+    readonly span?: SourceSpan | null;
+    readonly input?: string;
+    readonly details?: JsonObject;
+}
+/** A stable, JSON-safe error raised by the V3 compiler or executor. */
+export declare class DiceRollError extends Error {
+    readonly code: DiceRollErrorCode;
+    readonly span: SourceSpan | null;
+    readonly input: string;
+    readonly details: JsonObject;
+    constructor(message: string, options: DiceRollErrorOptions);
+    static fromJSON(data: unknown): DiceRollError;
+    toJSON(): DiceErrorData;
+}
+export declare function isDiceRollError(error: unknown): error is DiceRollError;
+/** Recognizes JSON-safe dice errors across workers, realms and process boundaries. */
+export declare function isDiceRollErrorData(value: unknown): value is DiceErrorData;

package/dist/v3/executor.d.cts

@@ -0,0 +1,11 @@
+import type { DiceLimits } from './runtime/limits.cjs';
+import type { RandomAlgorithm, ReplayDescriptor, SeedInput } from './runtime/replay.cjs';
+import type { DiceRollResult, DiceRollSummary, RollPlan } from './types.cjs';
+export interface ExecuteRollPlanOptions {
+    readonly limits: DiceLimits;
+    readonly seed?: SeedInput;
+    readonly replay?: ReplayDescriptor;
+    readonly randomAlgorithm?: RandomAlgorithm;
+}
+export declare function executeRollPlan(plan: RollPlan, options: ExecuteRollPlanOptions): DiceRollResult;
+export declare function executeRollPlanSummary(plan: RollPlan, options: ExecuteRollPlanOptions): DiceRollSummary;

package/dist/v3/executor.d.ts

@@ -0,0 +1,11 @@
+import type { DiceLimits } from './runtime/limits.js';
+import type { RandomAlgorithm, ReplayDescriptor, SeedInput } from './runtime/replay.js';
+import type { DiceRollResult, DiceRollSummary, RollPlan } from './types.js';
+export interface ExecuteRollPlanOptions {
+    readonly limits: DiceLimits;
+    readonly seed?: SeedInput;
+    readonly replay?: ReplayDescriptor;
+    readonly randomAlgorithm?: RandomAlgorithm;
+}
+export declare function executeRollPlan(plan: RollPlan, options: ExecuteRollPlanOptions): DiceRollResult;
+export declare function executeRollPlanSummary(plan: RollPlan, options: ExecuteRollPlanOptions): DiceRollSummary;

package/dist/v3/freeze.d.cts

@@ -0,0 +1,5 @@
+import type { DiceRollResult, DiceRollSummary, RollPlan } from './types.cjs';
+export declare function freezeRollPlan(plan: RollPlan): RollPlan;
+export declare function freezeDiceRollResult(result: DiceRollResult): DiceRollResult;
+export declare function freezeDiceRollSummary(result: DiceRollSummary): DiceRollSummary;
+export declare function shouldFreezeResults(mode: 'development' | 'always' | 'never'): boolean;

package/dist/v3/freeze.d.ts

@@ -0,0 +1,5 @@
+import type { DiceRollResult, DiceRollSummary, RollPlan } from './types.js';
+export declare function freezeRollPlan(plan: RollPlan): RollPlan;
+export declare function freezeDiceRollResult(result: DiceRollResult): DiceRollResult;
+export declare function freezeDiceRollSummary(result: DiceRollSummary): DiceRollSummary;
+export declare function shouldFreezeResults(mode: 'development' | 'always' | 'never'): boolean;

package/dist/v3/index.d.cts

@@ -0,0 +1,8 @@
+export { compileRpgDice, createDiceEngine, inspectRpgDiceNotation, rollRpgDice, rollRpgDiceSummary, verifyRpgDiceNotation, } from './engine.cjs';
+export { DiceRollError, isDiceRollError, isDiceRollErrorData, } from './errors.cjs';
+export { normalizeRpgDiceNotation } from './normalization.cjs';
+export { DEFAULT_DICE_LIMITS } from './runtime/limits.cjs';
+export type { DiceErrorData, DiceRollErrorCode, JsonObject, JsonPrimitive, JsonValue, SourceSpan, } from './errors.cjs';
+export type { DiceLimits } from './runtime/limits.cjs';
+export type { RandomAlgorithm, ReplayDescriptor, SeedInput, SeedOrigin, } from './runtime/replay.cjs';
+export type { ClassifyDiceEvent, CompileOptions, DiceCacheOptions, DiceCacheStats, DiceEngine, DiceEngineOptions, DiceEvent, DiceInspectionCost, DiceNotationInspection, DiceRollResult, DiceRollSummary, DiceSides, DiceState, EntityRange, ExcludeDiceEvent, ExcludeGroupEvent, ExplodeDiceEvent, FreezeResultsMode, GroupState, IncludeDiceEvent, IncludeGroupEvent, ExecutionStats, PoolSummary, RerollDiceEvent, ResolvedDie, ResolvedGroup, ResolvedRoll, ResolvedRollSummary, RollDiceEvent, RollOptions, RollPlan, RollPlanGroup, TransformDiceEvent, TransformGroupEvent, } from './types.cjs';

package/dist/v3/index.d.ts

@@ -0,0 +1,8 @@
+export { compileRpgDice, createDiceEngine, inspectRpgDiceNotation, rollRpgDice, rollRpgDiceSummary, verifyRpgDiceNotation, } from './engine.js';
+export { DiceRollError, isDiceRollError, isDiceRollErrorData, } from './errors.js';
+export { normalizeRpgDiceNotation } from './normalization.js';
+export { DEFAULT_DICE_LIMITS } from './runtime/limits.js';
+export type { DiceErrorData, DiceRollErrorCode, JsonObject, JsonPrimitive, JsonValue, SourceSpan, } from './errors.js';
+export type { DiceLimits } from './runtime/limits.js';
+export type { RandomAlgorithm, ReplayDescriptor, SeedInput, SeedOrigin, } from './runtime/replay.js';
+export type { ClassifyDiceEvent, CompileOptions, DiceCacheOptions, DiceCacheStats, DiceEngine, DiceEngineOptions, DiceEvent, DiceInspectionCost, DiceNotationInspection, DiceRollResult, DiceRollSummary, DiceSides, DiceState, EntityRange, ExcludeDiceEvent, ExcludeGroupEvent, ExplodeDiceEvent, FreezeResultsMode, GroupState, IncludeDiceEvent, IncludeGroupEvent, ExecutionStats, PoolSummary, RerollDiceEvent, ResolvedDie, ResolvedGroup, ResolvedRoll, ResolvedRollSummary, RollDiceEvent, RollOptions, RollPlan, RollPlanGroup, TransformDiceEvent, TransformGroupEvent, } from './types.js';

package/dist/v3/math.d.cts

@@ -0,0 +1,12 @@
+export type BinaryOperator = '+' | '-' | '*' | '/' | '%' | '^';
+export type UnaryMathFunction = 'abs' | 'ceil' | 'cos' | 'exp' | 'floor' | 'log' | 'round' | 'sign' | 'sin' | 'sqrt' | 'tan';
+export type BinaryMathFunction = 'max' | 'min' | 'pow';
+export type MathProfile = 'decimal12-v1';
+export declare const MATH_PROFILE: MathProfile;
+/** Applies the V3 cross-runtime numeric profile after every math operation. */
+export declare function normalizeMathValue(value: number, input: string): number;
+export declare function evaluateBinary(operator: BinaryOperator, left: number, right: number, input: string): number;
+export declare function evaluateUnaryFunction(name: UnaryMathFunction, value: number, input: string): number;
+export declare function evaluateBinaryFunction(name: BinaryMathFunction, left: number, right: number, input: string): number;
+export declare function compareValues(operator: '=' | '!=' | '<>' | '<' | '>' | '<=' | '>=', left: number, right: number): boolean;
+export declare function roundResult(value: number): number;

package/dist/v3/math.d.ts

@@ -0,0 +1,12 @@
+export type BinaryOperator = '+' | '-' | '*' | '/' | '%' | '^';
+export type UnaryMathFunction = 'abs' | 'ceil' | 'cos' | 'exp' | 'floor' | 'log' | 'round' | 'sign' | 'sin' | 'sqrt' | 'tan';
+export type BinaryMathFunction = 'max' | 'min' | 'pow';
+export type MathProfile = 'decimal12-v1';
+export declare const MATH_PROFILE: MathProfile;
+/** Applies the V3 cross-runtime numeric profile after every math operation. */
+export declare function normalizeMathValue(value: number, input: string): number;
+export declare function evaluateBinary(operator: BinaryOperator, left: number, right: number, input: string): number;
+export declare function evaluateUnaryFunction(name: UnaryMathFunction, value: number, input: string): number;
+export declare function evaluateBinaryFunction(name: BinaryMathFunction, left: number, right: number, input: string): number;
+export declare function compareValues(operator: '=' | '!=' | '<>' | '<' | '>' | '<=' | '>=', left: number, right: number): boolean;
+export declare function roundResult(value: number): number;

package/dist/v3/normalization.d.cts

@@ -0,0 +1,10 @@
+export interface NormalizedDiceInput {
+    readonly input: string;
+    readonly comment: string;
+    readonly notation: string;
+    readonly normalizedNotation: string;
+    readonly rollCount: number;
+    readonly isMultiRoll: boolean;
+}
+export declare function normalizeRpgDiceNotation(input: string): string;
+export declare function parseNormalizedDiceInput(input: string): NormalizedDiceInput;

package/dist/v3/normalization.d.ts

@@ -0,0 +1,10 @@
+export interface NormalizedDiceInput {
+    readonly input: string;
+    readonly comment: string;
+    readonly notation: string;
+    readonly normalizedNotation: string;
+    readonly rollCount: number;
+    readonly isMultiRoll: boolean;
+}
+export declare function normalizeRpgDiceNotation(input: string): string;
+export declare function parseNormalizedDiceInput(input: string): NormalizedDiceInput;

package/dist/v3/roll-count-expression.d.cts

@@ -0,0 +1,2 @@
+/** Resolves a deterministic expression used before the multi-roll `#` marker. */
+export declare function resolveRollCountExpression(expression: string): number | null;

package/dist/v3/roll-count-expression.d.ts

@@ -0,0 +1,2 @@
+/** Resolves a deterministic expression used before the multi-roll `#` marker. */
+export declare function resolveRollCountExpression(expression: string): number | null;

package/dist/v3/runtime/budget.d.cts

@@ -0,0 +1,57 @@
+import type { DiceLimits } from './limits.cjs';
+export interface ExecutionBudgetSnapshot {
+    readonly astNodes: number;
+    readonly rolls: number;
+    readonly initialDice: number;
+    readonly generatedDice: number;
+    readonly randomCalls: number;
+    readonly modifierSteps: number;
+    readonly events: number;
+    readonly resolvedGroups: number;
+    readonly resultItems: number;
+}
+export interface ExecutionStats {
+    readonly rolls: number;
+    readonly initialDice: number;
+    readonly generatedDice: number;
+    readonly randomCalls: number;
+    readonly modifierSteps: number;
+    readonly events: number;
+    readonly resolvedGroups: number;
+    readonly resultItems: number;
+}
+export interface RandomCallBudget {
+    consumeRandomCalls(count?: number): void;
+}
+export interface EventBudget {
+    consumeEvents(count?: number): void;
+    consumeResultItems(count?: number): void;
+}
+export declare class ExecutionBudget implements RandomCallBudget, EventBudget {
+    readonly limits: DiceLimits;
+    private astNodes;
+    private rolls;
+    private initialDice;
+    private generatedDice;
+    private randomCalls;
+    private modifierSteps;
+    private events;
+    private resolvedGroups;
+    private resultItems;
+    constructor(limits: DiceLimits);
+    assertInputLength(input: string): void;
+    consumeAstNode(depth: number): void;
+    consumeRolls(count?: number): void;
+    consumeInitialDice(count?: number): void;
+    consumeGeneratedDice(count?: number): void;
+    consumeRandomCalls(count?: number): void;
+    consumeEvents(count?: number): void;
+    consumeModifierSteps(count?: number): void;
+    consumeResolvedGroups(count?: number): void;
+    consumeResultItems(count?: number): void;
+    assertOutputLength(length: number): void;
+    snapshot(): ExecutionBudgetSnapshot;
+    stats(): ExecutionStats;
+    private consume;
+    private throwLimit;
+}

package/dist/v3/runtime/budget.d.ts

@@ -0,0 +1,57 @@
+import type { DiceLimits } from './limits.js';
+export interface ExecutionBudgetSnapshot {
+    readonly astNodes: number;
+    readonly rolls: number;
+    readonly initialDice: number;
+    readonly generatedDice: number;
+    readonly randomCalls: number;
+    readonly modifierSteps: number;
+    readonly events: number;
+    readonly resolvedGroups: number;
+    readonly resultItems: number;
+}
+export interface ExecutionStats {
+    readonly rolls: number;
+    readonly initialDice: number;
+    readonly generatedDice: number;
+    readonly randomCalls: number;
+    readonly modifierSteps: number;
+    readonly events: number;
+    readonly resolvedGroups: number;
+    readonly resultItems: number;
+}
+export interface RandomCallBudget {
+    consumeRandomCalls(count?: number): void;
+}
+export interface EventBudget {
+    consumeEvents(count?: number): void;
+    consumeResultItems(count?: number): void;
+}
+export declare class ExecutionBudget implements RandomCallBudget, EventBudget {
+    readonly limits: DiceLimits;
+    private astNodes;
+    private rolls;
+    private initialDice;
+    private generatedDice;
+    private randomCalls;
+    private modifierSteps;
+    private events;
+    private resolvedGroups;
+    private resultItems;
+    constructor(limits: DiceLimits);
+    assertInputLength(input: string): void;
+    consumeAstNode(depth: number): void;
+    consumeRolls(count?: number): void;
+    consumeInitialDice(count?: number): void;
+    consumeGeneratedDice(count?: number): void;
+    consumeRandomCalls(count?: number): void;
+    consumeEvents(count?: number): void;
+    consumeModifierSteps(count?: number): void;
+    consumeResolvedGroups(count?: number): void;
+    consumeResultItems(count?: number): void;
+    assertOutputLength(length: number): void;
+    snapshot(): ExecutionBudgetSnapshot;
+    stats(): ExecutionStats;
+    private consume;
+    private throwLimit;
+}

package/dist/v3/runtime/context.d.cts

@@ -0,0 +1,27 @@
+import type { DiceEventSink } from './journal.cjs';
+import { ExecutionBudget } from './budget.cjs';
+import { type DiceLimitOverrides, type DiceLimits } from './limits.cjs';
+import { type RandomSource } from './mt19937.cjs';
+import { type CryptoSource, type RandomAlgorithm, type ReplayDescriptor, type SeedInput } from './replay.cjs';
+export interface ExecutionContextOptions {
+    readonly limits?: DiceLimits | DiceLimitOverrides;
+    /** Already resolved immutable limits used by the engine hot path. */
+    readonly resolvedLimits?: DiceLimits;
+    readonly seed?: SeedInput;
+    readonly replay?: ReplayDescriptor;
+    readonly randomAlgorithm?: RandomAlgorithm;
+    readonly planFingerprint?: string;
+    readonly collectEvents?: boolean;
+    /** Intended for platform adapters and deterministic tests. */
+    readonly cryptoSource?: CryptoSource | null;
+}
+/** All mutable state for exactly one compilation/execution. */
+export declare class ExecutionContext {
+    readonly limits: DiceLimits;
+    readonly budget: ExecutionBudget;
+    readonly random: RandomSource;
+    readonly journal: DiceEventSink;
+    readonly replay: ReplayDescriptor;
+    constructor(options?: ExecutionContextOptions);
+}
+export declare function createExecutionContext(options?: ExecutionContextOptions): ExecutionContext;

package/dist/v3/runtime/context.d.ts

@@ -0,0 +1,27 @@
+import type { DiceEventSink } from './journal.js';
+import { ExecutionBudget } from './budget.js';
+import { type DiceLimitOverrides, type DiceLimits } from './limits.js';
+import { type RandomSource } from './mt19937.js';
+import { type CryptoSource, type RandomAlgorithm, type ReplayDescriptor, type SeedInput } from './replay.js';
+export interface ExecutionContextOptions {
+    readonly limits?: DiceLimits | DiceLimitOverrides;
+    /** Already resolved immutable limits used by the engine hot path. */
+    readonly resolvedLimits?: DiceLimits;
+    readonly seed?: SeedInput;
+    readonly replay?: ReplayDescriptor;
+    readonly randomAlgorithm?: RandomAlgorithm;
+    readonly planFingerprint?: string;
+    readonly collectEvents?: boolean;
+    /** Intended for platform adapters and deterministic tests. */
+    readonly cryptoSource?: CryptoSource | null;
+}
+/** All mutable state for exactly one compilation/execution. */
+export declare class ExecutionContext {
+    readonly limits: DiceLimits;
+    readonly budget: ExecutionBudget;
+    readonly random: RandomSource;
+    readonly journal: DiceEventSink;
+    readonly replay: ReplayDescriptor;
+    constructor(options?: ExecutionContextOptions);
+}
+export declare function createExecutionContext(options?: ExecutionContextOptions): ExecutionContext;

package/dist/v3/runtime/index.d.cts

@@ -0,0 +1,7 @@
+export * from './budget.cjs';
+export * from './context.cjs';
+export * from './journal.cjs';
+export * from './limits.cjs';
+export * from './mt19937.cjs';
+export * from './replay.cjs';
+export * from './xoshiro128ss.cjs';

package/dist/v3/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export * from './budget.js';
+export * from './context.js';
+export * from './journal.js';
+export * from './limits.js';
+export * from './mt19937.js';
+export * from './replay.js';
+export * from './xoshiro128ss.js';

package/dist/v3/runtime/journal.d.cts

@@ -0,0 +1,23 @@
+import type { ClassifyDiceEvent, DiceEvent, ExcludeDiceEvent, ExcludeGroupEvent, ExplodeDiceEvent, IncludeDiceEvent, IncludeGroupEvent, RerollDiceEvent, RollDiceEvent, TransformDiceEvent, TransformGroupEvent } from '../types.cjs';
+import type { EventBudget } from './budget.cjs';
+type WithoutSequence<T extends DiceEvent> = Omit<T, 'sequence'>;
+export type DiceEventInput = WithoutSequence<RollDiceEvent> | WithoutSequence<RerollDiceEvent> | WithoutSequence<ExplodeDiceEvent> | WithoutSequence<TransformDiceEvent> | WithoutSequence<TransformGroupEvent> | WithoutSequence<IncludeDiceEvent> | WithoutSequence<IncludeGroupEvent> | WithoutSequence<ExcludeDiceEvent> | WithoutSequence<ExcludeGroupEvent> | WithoutSequence<ClassifyDiceEvent>;
+export interface DiceEventSink {
+    readonly length: number;
+    record(event: DiceEventInput): DiceEvent | null;
+    slice(start: number, end?: number): readonly DiceEvent[];
+    toArray(): readonly DiceEvent[];
+}
+/** Counts every logical event and optionally materializes the public journal. */
+export declare class ExecutionJournal implements DiceEventSink {
+    private readonly journal;
+    private readonly budget;
+    private readonly materialize;
+    private eventCount;
+    constructor(budget?: EventBudget | null, materialize?: boolean);
+    get length(): number;
+    record(input: DiceEventInput): DiceEvent | null;
+    slice(start: number, end?: number): readonly DiceEvent[];
+    toArray(): readonly DiceEvent[];
+}
+export {};

package/dist/v3/runtime/journal.d.ts

@@ -0,0 +1,23 @@
+import type { ClassifyDiceEvent, DiceEvent, ExcludeDiceEvent, ExcludeGroupEvent, ExplodeDiceEvent, IncludeDiceEvent, IncludeGroupEvent, RerollDiceEvent, RollDiceEvent, TransformDiceEvent, TransformGroupEvent } from '../types.js';
+import type { EventBudget } from './budget.js';
+type WithoutSequence<T extends DiceEvent> = Omit<T, 'sequence'>;
+export type DiceEventInput = WithoutSequence<RollDiceEvent> | WithoutSequence<RerollDiceEvent> | WithoutSequence<ExplodeDiceEvent> | WithoutSequence<TransformDiceEvent> | WithoutSequence<TransformGroupEvent> | WithoutSequence<IncludeDiceEvent> | WithoutSequence<IncludeGroupEvent> | WithoutSequence<ExcludeDiceEvent> | WithoutSequence<ExcludeGroupEvent> | WithoutSequence<ClassifyDiceEvent>;
+export interface DiceEventSink {
+    readonly length: number;
+    record(event: DiceEventInput): DiceEvent | null;
+    slice(start: number, end?: number): readonly DiceEvent[];
+    toArray(): readonly DiceEvent[];
+}
+/** Counts every logical event and optionally materializes the public journal. */
+export declare class ExecutionJournal implements DiceEventSink {
+    private readonly journal;
+    private readonly budget;
+    private readonly materialize;
+    private eventCount;
+    constructor(budget?: EventBudget | null, materialize?: boolean);
+    get length(): number;
+    record(input: DiceEventInput): DiceEvent | null;
+    slice(start: number, end?: number): readonly DiceEvent[];
+    toArray(): readonly DiceEvent[];
+}
+export {};

package/dist/v3/runtime/limits.d.cts

@@ -0,0 +1,25 @@
+export interface DiceLimits {
+    readonly maxInputLength: number;
+    readonly maxAstDepth: number;
+    readonly maxAstNodes: number;
+    readonly maxRolls: number;
+    readonly maxInitialDice: number;
+    readonly maxGeneratedDice: number;
+    readonly maxRandomCalls: number;
+    readonly maxEvents: number;
+    readonly maxSides: number;
+    readonly maxSeedLength: number;
+    readonly maxModifierSteps: number;
+    readonly maxResolvedGroups: number;
+    readonly maxResultItems: number;
+    readonly maxOutputLength: number;
+}
+export type DiceLimitOverrides = Partial<DiceLimits>;
+export declare const DEFAULT_DICE_LIMITS: DiceLimits;
+/** Creates the immutable caps owned by a DiceEngine instance. */
+export declare function createDiceLimits(overrides?: unknown): DiceLimits;
+/**
+ * Resolves per-call limits against immutable engine caps.
+ * A call may lower a cap, but attempting to raise one is a configuration error.
+ */
+export declare function resolveDiceLimits(engineLimits: DiceLimits, callOverrides?: unknown): DiceLimits;

package/dist/v3/runtime/limits.d.ts

@@ -0,0 +1,25 @@
+export interface DiceLimits {
+    readonly maxInputLength: number;
+    readonly maxAstDepth: number;
+    readonly maxAstNodes: number;
+    readonly maxRolls: number;
+    readonly maxInitialDice: number;
+    readonly maxGeneratedDice: number;
+    readonly maxRandomCalls: number;
+    readonly maxEvents: number;
+    readonly maxSides: number;
+    readonly maxSeedLength: number;
+    readonly maxModifierSteps: number;
+    readonly maxResolvedGroups: number;
+    readonly maxResultItems: number;
+    readonly maxOutputLength: number;
+}
+export type DiceLimitOverrides = Partial<DiceLimits>;
+export declare const DEFAULT_DICE_LIMITS: DiceLimits;
+/** Creates the immutable caps owned by a DiceEngine instance. */
+export declare function createDiceLimits(overrides?: unknown): DiceLimits;
+/**
+ * Resolves per-call limits against immutable engine caps.
+ * A call may lower a cap, but attempting to raise one is a configuration error.
+ */
+export declare function resolveDiceLimits(engineLimits: DiceLimits, callOverrides?: unknown): DiceLimits;

package/dist/v3/runtime/mt19937.d.cts

@@ -0,0 +1,23 @@
+import type { RandomCallBudget } from './budget.cjs';
+export interface RandomSource {
+    nextUint32(): number;
+    integer(min: number, max: number): number;
+    real(): number;
+}
+/** A dependency-free implementation of the original 32-bit MT19937 algorithm. */
+export declare class MersenneTwister19937 implements RandomSource {
+    private readonly state;
+    private index;
+    private readonly budget;
+    constructor(seed: number | ArrayLike<number>, budget?: RandomCallBudget | null);
+    nextUint32(): number;
+    integer(min: number, max: number): number;
+    real(): number;
+    private readState;
+    private writeState;
+    private initializeSeed;
+    private initializeSeedArray;
+    private restoreCachedSeedArray;
+    private cacheSeedArray;
+    private twist;
+}

package/dist/v3/runtime/mt19937.d.ts

@@ -0,0 +1,23 @@
+import type { RandomCallBudget } from './budget.js';
+export interface RandomSource {
+    nextUint32(): number;
+    integer(min: number, max: number): number;
+    real(): number;
+}
+/** A dependency-free implementation of the original 32-bit MT19937 algorithm. */
+export declare class MersenneTwister19937 implements RandomSource {
+    private readonly state;
+    private index;
+    private readonly budget;
+    constructor(seed: number | ArrayLike<number>, budget?: RandomCallBudget | null);
+    nextUint32(): number;
+    integer(min: number, max: number): number;
+    real(): number;
+    private readState;
+    private writeState;
+    private initializeSeed;
+    private initializeSeedArray;
+    private restoreCachedSeedArray;
+    private cacheSeedArray;
+    private twist;
+}

package/dist/v3/runtime/replay.d.cts

@@ -0,0 +1,38 @@
+import { type MathProfile } from '../math.cjs';
+export type SeedInput = number | string;
+export type SeedOrigin = 'provided-number' | 'provided-string' | 'crypto';
+export type RandomAlgorithm = 'mt19937' | 'xoshiro128ss';
+export interface ReplayDescriptor {
+    readonly schemaVersion: 2;
+    readonly algorithm: RandomAlgorithm;
+    readonly algorithmVersion: 1;
+    readonly executionVersion: 1;
+    readonly mathProfile: MathProfile;
+    readonly origin: SeedOrigin;
+    readonly seedMaterial: string;
+    readonly planFingerprint: string;
+}
+export interface SeedMaterial {
+    /** Internal namespaced representation. Never included in ReplayDescriptor. */
+    readonly canonicalSeed: string;
+    readonly seedMaterial: string;
+    readonly origin: SeedOrigin;
+    readonly words: readonly number[];
+}
+export interface CryptoSource {
+    getRandomValues(array: Uint32Array): Uint32Array;
+}
+export interface ReplayDescriptorOptions {
+    readonly algorithm?: RandomAlgorithm;
+    readonly planFingerprint?: string;
+}
+export declare function isReplayDescriptor(value: unknown): value is ReplayDescriptor;
+/** Validates all replay fields and optionally binds it to an expected plan. */
+export declare function validateReplayDescriptor(value: unknown, expectedPlanFingerprint?: string): ReplayDescriptor;
+export declare function canonicalizeSeed(seed: SeedInput, maxSeedLength?: number): string;
+export declare function createProvidedSeed(seed: SeedInput, maxSeedLength?: number): SeedMaterial;
+export declare function createAutomaticSeed(cryptoSource?: CryptoSource | null): SeedMaterial;
+/** Restores the fixed 128-bit seed represented by a public replay descriptor. */
+export declare function createReplaySeed(descriptor: unknown, expectedPlanFingerprint?: string): SeedMaterial;
+export declare function createSeedMaterial(seed: SeedInput | undefined, cryptoSource?: CryptoSource | null, maxSeedLength?: number): SeedMaterial;
+export declare function createReplayDescriptor(seed: SeedMaterial, options?: ReplayDescriptorOptions): ReplayDescriptor;

package/dist/v3/runtime/replay.d.ts

@@ -0,0 +1,38 @@
+import { type MathProfile } from '../math.js';
+export type SeedInput = number | string;
+export type SeedOrigin = 'provided-number' | 'provided-string' | 'crypto';
+export type RandomAlgorithm = 'mt19937' | 'xoshiro128ss';
+export interface ReplayDescriptor {
+    readonly schemaVersion: 2;
+    readonly algorithm: RandomAlgorithm;
+    readonly algorithmVersion: 1;
+    readonly executionVersion: 1;
+    readonly mathProfile: MathProfile;
+    readonly origin: SeedOrigin;
+    readonly seedMaterial: string;
+    readonly planFingerprint: string;
+}
+export interface SeedMaterial {
+    /** Internal namespaced representation. Never included in ReplayDescriptor. */
+    readonly canonicalSeed: string;
+    readonly seedMaterial: string;
+    readonly origin: SeedOrigin;
+    readonly words: readonly number[];
+}
+export interface CryptoSource {
+    getRandomValues(array: Uint32Array): Uint32Array;
+}
+export interface ReplayDescriptorOptions {
+    readonly algorithm?: RandomAlgorithm;
+    readonly planFingerprint?: string;
+}
+export declare function isReplayDescriptor(value: unknown): value is ReplayDescriptor;
+/** Validates all replay fields and optionally binds it to an expected plan. */
+export declare function validateReplayDescriptor(value: unknown, expectedPlanFingerprint?: string): ReplayDescriptor;
+export declare function canonicalizeSeed(seed: SeedInput, maxSeedLength?: number): string;
+export declare function createProvidedSeed(seed: SeedInput, maxSeedLength?: number): SeedMaterial;
+export declare function createAutomaticSeed(cryptoSource?: CryptoSource | null): SeedMaterial;
+/** Restores the fixed 128-bit seed represented by a public replay descriptor. */
+export declare function createReplaySeed(descriptor: unknown, expectedPlanFingerprint?: string): SeedMaterial;
+export declare function createSeedMaterial(seed: SeedInput | undefined, cryptoSource?: CryptoSource | null, maxSeedLength?: number): SeedMaterial;
+export declare function createReplayDescriptor(seed: SeedMaterial, options?: ReplayDescriptorOptions): ReplayDescriptor;

package/dist/v3/runtime/xoshiro128ss.d.cts

@@ -0,0 +1,14 @@
+import type { RandomCallBudget } from './budget.cjs';
+import type { RandomSource } from './mt19937.cjs';
+/** The public-domain xoshiro128** 1.1 generator by Blackman and Vigna. */
+export declare class Xoshiro128StarStar implements RandomSource {
+    private state0;
+    private state1;
+    private state2;
+    private state3;
+    private readonly budget;
+    constructor(seed: ArrayLike<number>, budget?: RandomCallBudget | null);
+    nextUint32(): number;
+    integer(min: number, max: number): number;
+    real(): number;
+}