@higher.archi/boe 1.0.3 → 1.0.5

package/dist/qfacts/strategies/seeded.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seededCollapse = seededCollapse;
+function createRng(seed) {
+    let state = seed;
+    return () => {
+        state |= 0;
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function djb2Hash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+    }
+    return hash >>> 0;
+}
+function seededCollapse(amplitudes, seed, fieldName) {
+    const fieldSeed = (seed ^ djb2Hash(fieldName)) >>> 0;
+    const rng = createRng(fieldSeed);
+    const roll = rng();
+    const keys = Object.keys(amplitudes);
+    let cumulative = 0;
+    for (const key of keys) {
+        cumulative += amplitudes[key];
+        if (roll < cumulative)
+            return key;
+    }
+    return keys[keys.length - 1];
+}
+//# sourceMappingURL=seeded.js.map

package/dist/qfacts/strategies/seeded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeded.js","sourceRoot":"","sources":["../../../src/qfacts/strategies/seeded.ts"],"names":[],"mappings":";;AAmBA,wCAYC;AA/BD,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,OAAO,GAAG,EAAE;QACV,KAAK,IAAI,CAAC,CAAC;QACX,KAAK,GAAG,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC;QACrD,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,SAAgB,cAAc,CAAC,UAAkC,EAAE,IAAY,EAAE,SAAiB;IAChG,MAAM,SAAS,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC;IAEnB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACrC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,UAAU,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,IAAI,GAAG,UAAU;YAAE,OAAO,GAAG,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/qfacts/types.d.ts

@@ -0,0 +1,36 @@
+import type { FactInput } from '../core';
+export type AmplitudeValue = number | `${number}%`;
+export type Superposition = {
+    state: 'superposition';
+    amplitudes: Record<string, number>;
+};
+export type QValue = any | Superposition;
+export type QFactInput = {
+    id?: string;
+    type: string;
+    data: Record<string, QValue>;
+};
+export type CollapseStrategy = 'seeded' | 'crypto' | 'deterministic' | 'quasi-random';
+export type CollapseOptions = {
+    strategy?: CollapseStrategy;
+    seed?: number;
+    coerce?: boolean;
+};
+export type CollapseRecord = {
+    field: string;
+    selectedValue: any;
+    amplitudes: Record<string, number>;
+    strategy: CollapseStrategy;
+    seed?: number;
+};
+export type CollapsedFact = {
+    fact: FactInput;
+    collapseLog: CollapseRecord[];
+};
+export type SimulationResult<T = any> = {
+    runs: number;
+    results: T[];
+    collapseHistory: CollapseRecord[][];
+    strategy: CollapseStrategy;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/qfacts/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/qfacts/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC;AAEnD,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,eAAe,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,aAAa,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,cAAc,CAAC;AAEtF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,GAAG,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,cAAc,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,GAAG,IAAI;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,eAAe,EAAE,cAAc,EAAE,EAAE,CAAC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,CAAC"}

package/dist/qfacts/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/qfacts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/qfacts/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higher.archi/boe",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A multi-strategy rule engine supporting forward chaining, backward chaining, scoring, sequential, fuzzy logic, and Bayesian inference",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/engines/scoring/strategy.ts

@@ -135,6 +135,58 @@ export class ScoringStrategy {
       }
     }
 
+    // Phase 2.75: Compute confidence score (signal coverage ratio)
+    let confidence = 0;
+    const allRules = ruleSet.rules;
+    if (allRules.length === 0) {
+      confidence = 1;
+    } else if (config.categories?.length) {
+      // Category-aware confidence: per-category weighted confidence combined by category weights
+      const categories = config.categories;
+      let totalCatWeight = 0;
+      let weightedConfidenceSum = 0;
+
+      for (const cat of categories) {
+        const catRules = allRules.filter(r => r.category === cat.id);
+        if (catRules.length === 0) continue;
+
+        let allSignalWeight = 0;
+        let firedSignalWeight = 0;
+        for (const rule of catRules) {
+          const w = (rule.action as CompiledScoringAction).weight ?? 1;
+          allSignalWeight += w;
+          if (fired.includes(rule.id)) {
+            firedSignalWeight += w;
+          }
+        }
+
+        const totalSignals = catRules.length;
+        const firedCount = catRules.filter(r => fired.includes(r.id)).length;
+        const minRatio = cat.minSignalRatio ?? 0.5;
+        const excluded = totalSignals > 0 && (firedCount / totalSignals) < minRatio;
+
+        if (!excluded) {
+          const catConfidence = allSignalWeight > 0 ? firedSignalWeight / allSignalWeight : 0;
+          weightedConfidenceSum += cat.weight * catConfidence;
+          totalCatWeight += cat.weight;
+        }
+      }
+
+      confidence = totalCatWeight > 0 ? weightedConfidenceSum / totalCatWeight : 0;
+    } else {
+      // Global weighted confidence: sum(fired weights) / sum(all weights)
+      let allWeight = 0;
+      let firedWeight = 0;
+      for (const rule of allRules) {
+        const w = (rule.action as CompiledScoringAction).weight ?? 1;
+        allWeight += w;
+        if (fired.includes(rule.id)) {
+          firedWeight += w;
+        }
+      }
+      confidence = allWeight > 0 ? firedWeight / allWeight : 0;
+    }
+
     // Phase 3: Apply global strategies
     let categoryBreakdown: CategoryResult[] | undefined;
 
@@ -366,6 +418,7 @@ export class ScoringStrategy {
             const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
             return {
               totalScore: 0,
+              confidence,
               contributions: {},
               fired: [],
               iterations: 1,
@@ -416,6 +469,7 @@ export class ScoringStrategy {
 
     return {
       totalScore,
+      confidence,
       contributions,
       fired,
       iterations: 1,

package/src/engines/scoring/types.ts

@@ -376,6 +376,7 @@ export type ScoringOptions = {
  */
 export type ScoringResult = {
   totalScore: number;
+  confidence: number;  // 0-1, signal coverage ratio (weighted if weights present)
   contributions: Record<string, number>;  // Which rules contributed what scores
   fired: string[];  // Rules that matched and contributed
   iterations: 1;  // Scoring is always one-pass

package/src/index.ts

@@ -374,3 +374,9 @@ export type {
 // ========================================
 
 export { soundex, nysiis, caverphone2, cosineSimilarity } from './functions';
+
+// ========================================
+// QFacts - Probabilistic Fact Hydration
+// ========================================
+
+export * from './qfacts';

package/src/qfacts/README.md

@@ -0,0 +1,243 @@
+# QFacts - Probabilistic Fact Hydration
+
+QFacts is a pre-processing layer that handles **uncertain data** before it reaches any BOE engine. It accepts facts where some fields have multiple possible values (probability distributions), picks a concrete value for each one, and hands clean `FactInput` objects to the engine. BOE stays deterministic and auditable. QFacts extends the audit trail upstream.
+
+## What Problem Does This Solve?
+
+The real world doesn't arrive in clean rows. An NLP model says "this is 80% positive, 15% neutral, 5% negative." A sensor reads a temperature but with a margin of error. A classifier returns probabilities across several categories. Right now, something upstream has to commit to a single value before BOE ever sees it — and that throws away the uncertainty silently.
+
+QFacts keeps the uncertainty visible. You describe the distribution, QFacts collapses it to a single value, and the collapse is recorded — what the options were, what was picked, and how.
+
+```
+Uncertain World → QFacts (collapse) → FactInput → BOE Engine → Result
+```
+
+## When to Use QFacts
+
+Use QFacts when your input data has uncertainty that you want to preserve, collapse deliberately, or simulate across:
+
+- **ML/NLP output** - Classifiers return probability distributions, not hard labels
+- **Sensor data** - Readings have confidence intervals or error margins
+- **Survey data** - Responses mapped to weighted categories
+- **Monte Carlo analysis** - Run thousands of collapses to see how uncertainty affects outcomes
+- **Reproducible pipelines** - Same seed, same collapse, every time
+
+If your facts are already concrete values, you don't need QFacts. Just use `FactInput` directly.
+
+## Core Concepts
+
+### Superposition
+
+A superposition is a field that hasn't been decided yet. It holds multiple possible values, each with a weight (amplitude) representing how likely that value is.
+
+Think of it like a coin that hasn't been flipped. It's not heads or tails — it's both, with weights. A fair coin would be `{ heads: 0.5, tails: 0.5 }`. A loaded coin might be `{ heads: 0.8, tails: 0.2 }`.
+
+You create a superposition using the `superposition()` factory:
+
+```typescript
+superposition({ high: 0.8, moderate: 0.15, low: 0.05 })
+```
+
+This returns an object with `state: 'superposition'` and normalized amplitudes that always sum to 1.0.
+
+### Amplitude Formats
+
+The `superposition()` factory is flexible about how you express weights. All three of these mean exactly the same thing:
+
+```typescript
+superposition({ high: 0.9, moderate: 0.1 })    // decimals
+superposition({ high: 90, moderate: 10 })        // whole numbers
+superposition({ high: '90%', moderate: '10%' })  // percentage strings
+```
+
+You can even mix formats:
+
+```typescript
+superposition({ high: '90%', moderate: 10 })     // mixed — fine
+```
+
+Values don't need to sum to 100 or 1.0. QFacts normalizes everything automatically:
+
+```typescript
+superposition({ high: 120, moderate: 80 })
+// total = 200 → stored as { high: 0.6, moderate: 0.4 }
+```
+
+Internally, amplitudes are always stored as numbers between 0 and 1 that sum to 1.0. The flexible input is only accepted by the factory — the `Superposition` type itself is always normalized.
+
+### QFactInput
+
+A `QFactInput` looks just like a `FactInput`, but any field in `data` can be a superposition instead of a concrete value:
+
+```typescript
+const qfact: QFactInput = {
+  type: 'SentimentAnalysis',
+  data: {
+    text: 'Great product, minor issues',                    // concrete
+    sentiment: superposition({ positive: 0.8, mixed: 0.15, negative: 0.05 }),  // uncertain
+    confidence: 0.92                                         // concrete
+  }
+};
+```
+
+Fields that are already concrete pass through untouched. Only superpositions get collapsed.
+
+### Collapse
+
+Collapsing is the act of picking one concrete value from a superposition. The `collapse()` function walks through every field in a `QFactInput`, collapses any superpositions it finds, and returns a clean `FactInput` plus a log of what happened.
+
+The collapse log records each decision: which field, what the options were, what was picked, which strategy was used, and (for seeded strategies) what seed was used. This is your audit trail.
+
+### Strategies
+
+QFacts supports four collapse strategies. Each one answers the same question — "given these weighted options, pick one" — but they differ in how they pick.
+
+| Strategy | Randomness | Best For |
+|----------|-----------|----------|
+| **seeded** | Pseudo-random (reproducible) | Default. Same seed always gives same result. |
+| **deterministic** | None | Always picks the highest-weighted option. No surprises. |
+| **crypto** | True random | When you need cryptographic randomness. Not reproducible. |
+| **quasi-random** | Low-discrepancy sequence | Monte Carlo simulations. Better coverage with fewer runs. |
+
+#### Seeded (default)
+
+Uses a fast pseudo-random number generator (Mulberry32). Given the same seed, it always produces the same result. This is the default because it follows the principle of least surprise — calling `collapse(qfact)` with no options always returns the same output.
+
+Each field gets its own derived seed based on the field name, so the collapse of one field doesn't affect another. Reordering fields won't change results.
+
+#### Deterministic
+
+Always picks the option with the highest amplitude. On ties, picks the first one in insertion order. No randomness at all. Useful when you just want the most likely value and don't care about simulating alternatives.
+
+#### Crypto
+
+Uses `crypto.getRandomValues()` for true randomness. Not reproducible — every call gives a different result. Throws a descriptive error if crypto isn't available (Node < 19 without the global).
+
+#### Quasi-Random
+
+Uses a Halton sequence instead of pseudo-random numbers. Halton sequences are "low-discrepancy" — they spread out more evenly than random numbers. This means Monte Carlo simulations converge faster. You get better coverage of the probability space with fewer runs.
+
+Takes an `index` parameter (typically the simulation loop counter) to determine position in the sequence.
+
+## API
+
+### `superposition(amplitudes)`
+
+Creates a superposition from weighted options. Accepts numbers, percentages, or percentage strings. Always normalizes to 0-1 internally.
+
+### `isSuperposition(value)`
+
+Type guard. Returns `true` if the value is a `Superposition` object (has `state: 'superposition'` and an `amplitudes` record).
+
+### `collapse(qfact, options?)`
+
+Collapses a single `QFactInput` into a `CollapsedFact`, which contains a clean `FactInput` and a `collapseLog` array.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `strategy` | `CollapseStrategy` | `'seeded'` | Which collapse strategy to use |
+| `seed` | `number` | `0` | Base seed for the `'seeded'` strategy |
+| `coerce` | `boolean` | `false` | Parse string keys to numbers/booleans via `JSON.parse` |
+
+When `coerce` is `true`, QFacts attempts to parse the selected key back to its original type. Since amplitude keys are always strings (`Record<string, number>`), a superposition like `{ "100": 0.7, "200": 0.3 }` would normally collapse to the string `"100"`. With `coerce: true`, it becomes the number `100`.
+
+### `collapseAll(qfacts, options?)`
+
+Collapses an array of `QFactInput` objects. Each fact gets its own derived seed (base seed + index) so collapses are independent of each other and of array order.
+
+### `simulate(qfacts, engineFn, options?)`
+
+Runs a Monte Carlo simulation. Collapses the same set of `QFactInput` objects many times with different seeds, passes each set of collapsed facts through your engine function, and collects the results.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `runs` | `number` | `1000` | Number of simulation runs |
+| `strategy` | `CollapseStrategy` | `'seeded'` | Strategy for each run |
+
+Returns a `SimulationResult` with the array of engine results, the full collapse history for every run, and metadata.
+
+## Types
+
+### `Superposition`
+
+```typescript
+type Superposition = {
+  state: 'superposition';
+  amplitudes: Record<string, number>;  // normalized 0-1, sums to 1.0
+};
+```
+
+### `QFactInput`
+
+```typescript
+type QFactInput = {
+  id?: string;
+  type: string;
+  data: Record<string, QValue>;  // QValue = any concrete value OR a Superposition
+};
+```
+
+### `CollapseRecord`
+
+```typescript
+type CollapseRecord = {
+  field: string;                       // which field was collapsed
+  selectedValue: any;                  // what it collapsed to
+  amplitudes: Record<string, number>;  // what the options were
+  strategy: CollapseStrategy;          // how it was picked
+  seed?: number;                       // seed used (seeded strategy only)
+};
+```
+
+### `CollapsedFact`
+
+```typescript
+type CollapsedFact = {
+  fact: FactInput;              // clean, ready for any BOE engine
+  collapseLog: CollapseRecord[];
+};
+```
+
+### `SimulationResult<T>`
+
+```typescript
+type SimulationResult<T> = {
+  runs: number;
+  results: T[];                          // one engine result per run
+  collapseHistory: CollapseRecord[][];   // one collapse log per run
+  strategy: CollapseStrategy;
+};
+```
+
+## Structure
+
+```
+src/qfacts/
+├── types.ts                  # All type definitions
+├── collapse.ts               # Core collapse functions + superposition factory
+├── simulate.ts               # Monte Carlo simulation wrapper
+├── strategies/
+│   ├── seeded.ts             # Mulberry32 PRNG collapse
+│   ├── deterministic.ts      # Argmax collapse (no randomness)
+│   ├── crypto.ts             # crypto.getRandomValues collapse
+│   ├── quasi-random.ts       # Halton sequence collapse
+│   └── index.ts              # Strategy barrel + dispatcher
+└── index.ts                  # Module barrel exports
+```
+
+## Design Decisions
+
+| Decision | Choice | Why |
+|----------|--------|-----|
+| BOE stays untouched | QFacts is pre-processing only | BOE remains deterministic and auditable. QFacts extends the audit trail upstream, not inside. |
+| Default seed is `0`, not random | Reproducibility by default | First call always gives the same result. No surprises. Opt into randomness explicitly. |
+| Per-field seed derivation | `baseSeed ^ hash(fieldName)` | Collapse of one field doesn't affect another. Reordering fields doesn't change results. |
+| Amplitude normalization | Accept 0.9, 90, or '90%' | All three forms mean the same thing. Don't make users do math. |
+| Duplicate Mulberry32 PRNG | Copied, not imported from Monte Carlo engine | 14 lines. Avoids coupling QFacts to a specific engine. |
+| Top-level fields only | No nested superposition (v1) | Recursive traversal complicates types significantly. Can add later without breaking the API. |
+| Pure functions | No classes, no state | Matches the existing functions module pattern. Composable and testable. |
+| Coercion is opt-in | Off by default | Amplitude keys are strings. Automatic type guessing is risky. User opts in when they know their keys are parseable. |

package/src/qfacts/collapse.ts

@@ -0,0 +1,111 @@
+import type { FactInput } from '../core';
+import type {
+  Superposition,
+  QFactInput,
+  CollapseOptions,
+  CollapseRecord,
+  CollapsedFact,
+  AmplitudeValue,
+} from './types';
+import { resolveStrategy } from './strategies';
+
+export function isSuperposition(value: unknown): value is Superposition {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as any).state === 'superposition' &&
+    typeof (value as any).amplitudes === 'object' &&
+    (value as any).amplitudes !== null
+  );
+}
+
+function normalizeAmplitudes(amplitudes: Record<string, AmplitudeValue>): Record<string, number> {
+  const parsed: Record<string, number> = {};
+
+  for (const [key, raw] of Object.entries(amplitudes)) {
+    if (typeof raw === 'string' && raw.endsWith('%')) {
+      parsed[key] = parseFloat(raw.slice(0, -1));
+    } else {
+      parsed[key] = Number(raw);
+    }
+  }
+
+  const values = Object.values(parsed);
+  const total = values.reduce((sum, v) => sum + v, 0);
+  const anyAboveOne = values.some((v) => v > 1);
+
+  if (anyAboveOne || total > 1.001) {
+    // Treat as raw numbers, normalize against total
+    for (const key of Object.keys(parsed)) {
+      parsed[key] = parsed[key] / total;
+    }
+  } else if (Math.abs(total - 1.0) > 0.001) {
+    // All ≤ 1 but doesn't sum to 1 — normalize
+    for (const key of Object.keys(parsed)) {
+      parsed[key] = parsed[key] / total;
+    }
+  }
+  // else: all ≤ 1 and total ≈ 1.0 — use as-is
+
+  return parsed;
+}
+
+export function superposition(amplitudes: Record<string, AmplitudeValue>): Superposition {
+  return {
+    state: 'superposition',
+    amplitudes: normalizeAmplitudes(amplitudes),
+  };
+}
+
+export function collapse(qfact: QFactInput, options?: CollapseOptions): CollapsedFact {
+  const strategy = options?.strategy ?? 'seeded';
+  const collapseLog: CollapseRecord[] = [];
+  const data: Record<string, any> = {};
+
+  let fieldIndex = 0;
+  for (const [field, value] of Object.entries(qfact.data)) {
+    if (isSuperposition(value)) {
+      const resolve = resolveStrategy(strategy, options ?? {}, fieldIndex);
+      const selectedKey = resolve(value.amplitudes, field);
+      let selectedValue: any = selectedKey;
+
+      if (options?.coerce) {
+        try {
+          selectedValue = JSON.parse(selectedKey);
+        } catch {
+          // keep as string
+        }
+      }
+
+      data[field] = selectedValue;
+      collapseLog.push({
+        field,
+        selectedValue,
+        amplitudes: { ...value.amplitudes },
+        strategy,
+        ...(strategy === 'seeded' ? { seed: options?.seed ?? 0 } : {}),
+      });
+    } else {
+      data[field] = value;
+    }
+    fieldIndex++;
+  }
+
+  const fact: FactInput = {
+    ...(qfact.id != null ? { id: qfact.id } : {}),
+    type: qfact.type,
+    data,
+  };
+
+  return { fact, collapseLog };
+}
+
+export function collapseAll(qfacts: QFactInput[], options?: CollapseOptions): CollapsedFact[] {
+  const baseSeed = options?.seed ?? 0;
+  return qfacts.map((qfact, index) =>
+    collapse(qfact, {
+      ...options,
+      seed: (baseSeed + index) >>> 0,
+    })
+  );
+}

package/src/qfacts/index.ts

@@ -0,0 +1,27 @@
+// Types
+export type {
+  AmplitudeValue,
+  Superposition,
+  QValue,
+  QFactInput,
+  CollapseStrategy,
+  CollapseOptions,
+  CollapseRecord,
+  CollapsedFact,
+  SimulationResult,
+} from './types';
+
+// Core collapse functions
+export { isSuperposition, superposition, collapse, collapseAll } from './collapse';
+
+// Simulation
+export { simulate } from './simulate';
+
+// Strategies
+export {
+  seededCollapse,
+  cryptoCollapse,
+  deterministicCollapse,
+  quasiRandomCollapse,
+  resolveStrategy,
+} from './strategies';

package/src/qfacts/simulate.ts

@@ -0,0 +1,25 @@
+import type { FactInput } from '../core';
+import type { QFactInput, CollapseStrategy, CollapseRecord, SimulationResult } from './types';
+import { collapseAll } from './collapse';
+
+export function simulate<T>(
+  qfacts: QFactInput[],
+  engineFn: (facts: FactInput[]) => T,
+  options?: { runs?: number; strategy?: CollapseStrategy }
+): SimulationResult<T> {
+  const runs = options?.runs ?? 1000;
+  const strategy = options?.strategy ?? 'seeded';
+  const results: T[] = [];
+  const collapseHistory: CollapseRecord[][] = [];
+
+  for (let i = 0; i < runs; i++) {
+    const collapsed = collapseAll(qfacts, { strategy, seed: i });
+    const facts = collapsed.map((c) => c.fact);
+    const logs = collapsed.flatMap((c) => c.collapseLog);
+
+    results.push(engineFn(facts));
+    collapseHistory.push(logs);
+  }
+
+  return { runs, results, collapseHistory, strategy };
+}

package/src/qfacts/strategies/crypto.ts

@@ -0,0 +1,20 @@
+export function cryptoCollapse(amplitudes: Record<string, number>): string {
+  if (!globalThis.crypto?.getRandomValues) {
+    throw new Error(
+      'crypto.getRandomValues is not available. Requires Node >= 19 or a browser environment. ' +
+      'Use strategy "seeded" or "deterministic" as an alternative.'
+    );
+  }
+
+  const arr = new Uint32Array(1);
+  globalThis.crypto.getRandomValues(arr);
+  const roll = arr[0] / 4294967296;
+
+  const keys = Object.keys(amplitudes);
+  let cumulative = 0;
+  for (const key of keys) {
+    cumulative += amplitudes[key];
+    if (roll < cumulative) return key;
+  }
+  return keys[keys.length - 1];
+}

package/src/qfacts/strategies/deterministic.ts

@@ -0,0 +1,11 @@
+export function deterministicCollapse(amplitudes: Record<string, number>): string {
+  let maxKey = '';
+  let maxVal = -Infinity;
+  for (const [key, val] of Object.entries(amplitudes)) {
+    if (val > maxVal) {
+      maxVal = val;
+      maxKey = key;
+    }
+  }
+  return maxKey;
+}

package/src/qfacts/strategies/index.ts

@@ -0,0 +1,25 @@
+export { seededCollapse } from './seeded';
+export { cryptoCollapse } from './crypto';
+export { deterministicCollapse } from './deterministic';
+export { quasiRandomCollapse } from './quasi-random';
+
+import { seededCollapse } from './seeded';
+import { cryptoCollapse } from './crypto';
+import { deterministicCollapse } from './deterministic';
+import { quasiRandomCollapse } from './quasi-random';
+import type { CollapseStrategy, CollapseOptions } from '../types';
+
+type CollapseFunction = (amplitudes: Record<string, number>, fieldName: string) => string;
+
+export function resolveStrategy(strategy: CollapseStrategy, options: CollapseOptions, fieldIndex?: number): CollapseFunction {
+  switch (strategy) {
+    case 'seeded':
+      return (amplitudes, fieldName) => seededCollapse(amplitudes, options.seed ?? 0, fieldName);
+    case 'crypto':
+      return (amplitudes) => cryptoCollapse(amplitudes);
+    case 'deterministic':
+      return (amplitudes) => deterministicCollapse(amplitudes);
+    case 'quasi-random':
+      return (amplitudes) => quasiRandomCollapse(amplitudes, fieldIndex ?? 0);
+  }
+}