@dice-o-rolla/dice-core 0.2.0 → 0.3.1

package/README.md

@@ -15,5 +15,8 @@ const random = new SeededRandomSource(42);
 
 Standard dice terms support `kh`, `kl`, `dh`, and `dl` selection followed by an optional score map.
 Unlisted faces score zero. Paired percentile and d66 terms intentionally reject these operations.
+Engine-produced die results may include immutable provenance with stable term, logical-die, and
+physical-die coordinates, the settled face, inclusion state, and score contribution. Core result
+aggregation validates and freezes this metadata without depending on a renderer or physics backend.
 
 Licensed under Apache-2.0. See `LICENSE`, `NOTICE`, and `THIRD_PARTY_NOTICES.md` in the package.

package/dist/dice/types.d.ts

@@ -7,6 +7,17 @@ export interface DieDefinition {
 interface BaseDieResult {
     readonly id: string;
     readonly value: number;
+    readonly provenance?: DieResultProvenance;
+}
+export type DieResultState = 'included' | 'discarded';
+export interface DieResultProvenance {
+    readonly termId: string;
+    readonly termIndex: number;
+    readonly dieIndex: number;
+    readonly physicalIndex: number;
+    readonly state: DieResultState;
+    readonly faceValue: number;
+    readonly contribution?: number;
 }
 export type DiceComponentRole = 'tens' | 'units';
 export interface DiceComponentResult {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { DiceComponentResult, DiceComponentRole, ComponentDieResult, DieDefinition, DieResult, DieType, StandardDieResult, } from './dice/types.js';
+export type { DiceComponentResult, DiceComponentRole, ComponentDieResult, DieDefinition, DieResult, DieResultProvenance, DieResultState, DieType, StandardDieResult, } from './dice/types.js';
 export { isDieType, STANDARD_DIE_TYPES } from './dice/types.js';
 export { TypedEventEmitter } from './events/typed-event-emitter.js';
 export type { QuaternionLike, Vector3Like } from './math/types.js';

package/dist/roll/aggregation.js

@@ -21,9 +21,52 @@ export function createRollResult(options) {
     });
 }
 function freezeDieResult(die) {
-    if (die.component === undefined)
-        return Object.freeze({ ...die });
-    return Object.freeze({ ...die, component: Object.freeze({ ...die.component }) });
+    validateProvenance(die);
+    const provenance = die.provenance === undefined ? undefined : Object.freeze({ ...die.provenance });
+    if (die.component === undefined) {
+        return Object.freeze({
+            ...die,
+            ...(provenance === undefined ? {} : { provenance }),
+        });
+    }
+    return Object.freeze({
+        ...die,
+        component: Object.freeze({ ...die.component }),
+        ...(provenance === undefined ? {} : { provenance }),
+    });
+}
+function validateProvenance(die) {
+    const provenance = die.provenance;
+    if (provenance === undefined)
+        return;
+    if (provenance.termId.length === 0) {
+        throw new TypeError(`Dice provenance termId must not be empty`);
+    }
+    for (const [name, value] of [
+        ['termIndex', provenance.termIndex],
+        ['dieIndex', provenance.dieIndex],
+        ['physicalIndex', provenance.physicalIndex],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new RangeError(`Dice provenance ${name} must be a non-negative safe integer`);
+        }
+    }
+    const expectedState = die.included === false ? 'discarded' : 'included';
+    if (provenance.state !== expectedState) {
+        throw new RangeError(`Dice provenance state does not match inclusion metadata for ${die.id}`);
+    }
+    const expectedFaceValue = die.component?.faceValue ?? die.value;
+    if (provenance.faceValue !== expectedFaceValue) {
+        throw new RangeError(`Dice provenance face does not match result value for ${die.id}`);
+    }
+    const expectedContribution = die.component === undefined
+        ? provenance.state === 'discarded'
+            ? 0
+            : (die.score ?? die.value)
+        : undefined;
+    if (provenance.contribution !== expectedContribution) {
+        throw new RangeError(`Dice provenance contribution does not match result value for ${die.id}`);
+    }
 }
 function getDiceTotal(dice) {
     let total = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-core",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Framework-neutral dice notation, roll results, events, and random sources.",
   "keywords": [
     "dice",