@patterkit/runtime 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [34429f0]
+- Updated dependencies [34429f0]
+- Updated dependencies [c61c146]
+  - @patterkit/model@0.2.0
+  - @patterkit/dialect@0.1.3
+
 All notable changes to `@patterkit/runtime` (Patterplay JS) are documented here. The
 Patterplay runtimes - JS, Unity, Unreal, and Godot - are versioned in lockstep: the same
 version number always means the same runtime behaviour. This package is versioned by
@@ -7,9 +17,20 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
-## [0.1.0] - Unreleased
+## [0.2.0] - 2026-07-07
+
+### Added
+
+- **Best match** selection (a new `sequence` order, `specificity`): among the eligible children,
+  play the one whose condition most specifically fits the current state; equally-specific ties break
+  by the seeded shuffle, and a condition-less child is the filler that wins only when nothing more
+  specific applies. Composes with the exhaust axis (re-pickable, or graceful degradation to the
+  filler). Locked by the conformance corpus, so all four runtimes agree.
+
+## [0.1.0] - 2026-07-04
 
 ### Added
+
 - The Patter runtime in JS/TS: `Engine` + `Flow` over a compiled `.patterc` bundle - scenes,
   blocks, run/choice/branch/sequence selectors, sticky/fallback options, call-return jumps,
   conditions + effects, visit counts, `{@ref}` interpolation, game events, tags, gameData

package/dist/index.cjs

@@ -31,6 +31,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/engine.ts
 var import_expr = require("@wildwinter/expr");
+var import_expr_specificity = require("@wildwinter/expr-specificity");
 var import_scoperegistry = require("@wildwinter/scoperegistry");
 var import_dialect = require("@patterkit/dialect");
 var import_model = require("@patterkit/model");
@@ -933,7 +934,7 @@ var Flow = class {
       case "sequence": {
         const order = group.options?.order ?? "sequential";
         const exhaust = group.options?.exhaust ?? "once";
-        return order === "shuffle" ? this.pickShuffle(eligible, exhaust, st) : this.pickSequential(eligible, exhaust, st);
+        return order === "shuffle" ? this.pickShuffle(eligible, exhaust, st) : order === "specificity" ? this.pickSpecificity(eligible, exhaust, st) : this.pickSequential(eligible, exhaust, st);
       }
       case "run":
       case "choice":
@@ -980,6 +981,65 @@ var Flow = class {
     st.last = id;
     return eligible.find((c) => c.id === id);
   }
+  /**
+   * `sequence` with `order: "specificity"` - **Best match**: score every eligible child by how
+   * specifically its condition fits the CURRENT state (`matchedSpec`), keep the top-scoring tier,
+   * and break ties with the seeded shuffle (no immediate repeat). A child with no condition scores
+   * 0, so it is the filler that wins only when nothing more specific is eligible.
+   *
+   * `exhaust` composes as it does for the other orders: `repeat` re-scores the full eligible set
+   * every draw (re-pickable - the character keeps preferring the on-topic line); `once` uses each
+   * pick up (a bag of remaining ids), so as specific lines are consumed the group slides down to
+   * less-specific ones and finally the filler, then yields null; `stick` degrades like `once` but
+   * holds the final pick forever instead of drying up.
+   */
+  pickSpecificity(eligible, exhaust, st) {
+    let pool = eligible;
+    if (exhaust !== "repeat") {
+      if (st.bag === void 0) st.bag = eligible.map((c) => c.id);
+      const remaining = new Set(st.bag);
+      pool = eligible.filter((c) => remaining.has(c.id));
+      if (pool.length === 0) {
+        return exhaust === "stick" && st.last !== void 0 ? eligible.find((c) => c.id === st.last) ?? null : null;
+      }
+    }
+    let best = -1;
+    const scored = pool.map((c) => {
+      const s = this.specScore(c);
+      if (s > best) best = s;
+      return { c, s };
+    });
+    const tier = scored.filter((x) => x.s === best).map((x) => x.c);
+    let pick;
+    if (tier.length === 1) {
+      pick = tier[0];
+    } else {
+      const p = st.last !== void 0 ? tier.findIndex((c) => c.id === st.last) : -1;
+      let i = Math.floor(this.rng() * (p >= 0 ? tier.length - 1 : tier.length));
+      if (p >= 0 && i >= p) i++;
+      pick = tier[i];
+    }
+    if (exhaust !== "repeat") st.bag = st.bag.filter((id) => id !== pick.id);
+    st.last = pick.id;
+    return pick;
+  }
+  /** A child's Best-match score against the current state: 0 when it has no condition (the filler
+   *  tier), else the specificity of its (already-passing) condition. */
+  specScore(node) {
+    return node.condition ? this.matchedSpec(this.conditionAst(node.condition), true) : 0;
+  }
+  /**
+   * The **matched-specificity** metric (parity contract): how many atomic constraints are actively
+   * holding this condition TRUE against the live state. Evaluation-aware, not a static clause count -
+   * it walks the tree with a De-Morgan polarity flag so `or` and `not` score the branch that is
+   * actually carrying the truth. `want` = "does this subtree need to be true for the whole condition
+   * to hold?" (true at the root). Only `and`/`or`/`not`/`check_flags` are structural; every other
+   * node (comparisons, scoped vars, literals, other calls) is an atom, evaluated whole.
+   */
+  matchedSpec(node, want) {
+    const evalTruthy = (n) => truthy((0, import_expr.evaluate)(n, this.evalCtx, import_dialect.patterDialect));
+    return (0, import_expr_specificity.matchedSpecificity)(node, evalTruthy, { want });
+  }
   /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
   selectorState(group) {
     const map = group.shared ? this.host.sharedSelectors : this.selectors;
@@ -1001,12 +1061,17 @@ var Flow = class {
     return truthy(this.evalExpr(node.condition));
   }
   evalExpr(expr) {
+    return (0, import_expr.evaluate)(this.conditionAst(expr), this.evalCtx, import_dialect.patterDialect);
+  }
+  /** The deserialised (in-memory) AST for an expression, cached per Expression. Shared by the
+   *  evaluator and the Best-match specificity walker so both work off one parse. */
+  conditionAst(expr) {
     let ast = astCache.get(expr);
     if (!ast) {
       ast = (0, import_expr.deserialiseAst)(expr.ast);
       astCache.set(expr, ast);
     }
-    return (0, import_expr.evaluate)(ast, this.evalCtx, import_dialect.patterDialect);
+    return ast;
   }
   /** Record an entry of a node (entered-only; spec §7): bumps the flow + world counts. */
   enter(id) {