@patterkit/runtime 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -550,11 +550,39 @@ declare class Flow {
      * permanent terminal; `once` stops after one pass; `repeat` reshuffles.
      */
     private pickShuffle;
+    /**
+     * `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.
+     */
+    private pickSpecificity;
+    /** 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. */
+    private specScore;
+    /**
+     * 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.
+     */
+    private matchedSpec;
     /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
     private selectorState;
     private runEffects;
     private eligible;
     private evalExpr;
+    /** 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. */
+    private conditionAst;
     /** Record an entry of a node (entered-only; spec §7): bumps the flow + world counts. */
     private enter;
     /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32. */

package/dist/index.d.ts

@@ -550,11 +550,39 @@ declare class Flow {
      * permanent terminal; `once` stops after one pass; `repeat` reshuffles.
      */
     private pickShuffle;
+    /**
+     * `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.
+     */
+    private pickSpecificity;
+    /** 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. */
+    private specScore;
+    /**
+     * 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.
+     */
+    private matchedSpec;
     /** A selector's cursor state - shared across flows (`group.shared`) or this flow's own. */
     private selectorState;
     private runEffects;
     private eligible;
     private evalExpr;
+    /** 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. */
+    private conditionAst;
     /** Record an entry of a node (entered-only; spec §7): bumps the flow + world counts. */
     private enter;
     /** Next float in [0, 1): the shared custom PRNG, or this flow's serialisable mulberry32. */

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/engine.ts
 import { evaluate, deserialiseAst } from "@wildwinter/expr";
+import { matchedSpecificity as scoreSpecificity } from "@wildwinter/expr-specificity";
 import { ScopeRegistry } from "@wildwinter/scoperegistry";
 import { patterDialect, interpolate, splitRef, stripCaptions } from "@patterkit/dialect";
 import { walkNodes, effectiveGameId, castStringKey, DEFAULT_CAPTION_DELIMITERS, DEFAULT_CAPTION_CHARACTER } from "@patterkit/model";
@@ -902,7 +903,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":
@@ -949,6 +950,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(evaluate(n, this.evalCtx, patterDialect));
+    return scoreSpecificity(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;
@@ -970,12 +1030,17 @@ var Flow = class {
     return truthy(this.evalExpr(node.condition));
   }
   evalExpr(expr) {
+    return evaluate(this.conditionAst(expr), this.evalCtx, 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 = deserialiseAst(expr.ast);
       astCache.set(expr, ast);
     }
-    return evaluate(ast, this.evalCtx, patterDialect);
+    return ast;
   }
   /** Record an entry of a node (entered-only; spec §7): bumps the flow + world counts. */
   enter(id) {