@crewhaus/tool-flow 0.7.0 → 0.8.0

package/dist/lib/score.js

@@ -8,8 +8,23 @@
  * be re-run identically next quarter. This returns the contributors, and the
  * version of the rules that produced them.
  */
-import { runChecks } from "@crewhaus/tool-schema";
-export function scoreValue(value, model) {
+import { decimalKernel } from "@crewhaus/tool-math";
+import { checksVerdict, runChecks } from "@crewhaus/tool-schema";
+const { align, decimalAdd, decimalToNumber, parseDecimal } = decimalKernel;
+/**
+ * `a` compared with `b`, exactly: -1, 0 or 1. A bound of -Infinity or
+ * Infinity (a library caller's, since JSON cannot spell one) compares as
+ * what it is rather than failing the parse.
+ */
+function compareExact(a, b) {
+    if (b === Number.NEGATIVE_INFINITY)
+        return 1;
+    if (b === Number.POSITIVE_INFINITY)
+        return -1;
+    const aligned = align(a, parseDecimal(b));
+    return aligned.a < aligned.b ? -1 : aligned.a > aligned.b ? 1 : 0;
+}
+export function scoreValue(value, model, options = {}) {
     if (model.rules.length === 0)
         throw new Error("the scoring model has no rules");
     const seen = new Set();
@@ -29,28 +44,57 @@ export function scoreValue(value, model) {
     }
     const contributors = [];
     const missed = [];
-    let rawScore = 0;
+    // Summed as exact decimals, not doubles. Points are decimal literals, and
+    // String(number) gives that literal back, so the sum is the one a person
+    // adds up by hand: 0.7 + 0.1 is 0.8 and lands in a band at 0.8, where the
+    // float sum 0.7999999999999999 missed it. Exact addition is also
+    // associative, so the band no longer depends on the order the rules were
+    // declared in (0.1 + 0.1 + 0.6 and 0.6 + 0.1 + 0.1 used to band apart).
+    let exact = { unscaled: 0n, scale: 0 };
+    const undecided = [];
     for (const rule of model.rules) {
-        const report = runChecks(value, rule.when);
-        if (report.ok) {
-            rawScore += rule.points;
+        const report = runChecks(value, rule.when, options.regex === undefined ? {} : { regex: options.regex });
+        const verdict = checksVerdict(report, "all");
+        if (verdict === "pass") {
+            exact = decimalAdd(exact, parseDecimal(rule.points));
             contributors.push({ id: rule.id, label: rule.label ?? rule.id, points: rule.points });
         }
+        else if (verdict === "undetermined") {
+            const why = report.failures.find((f) => f.undetermined === true)?.reason ?? "";
+            undecided.push({ id: rule.id, reason: why });
+        }
         else {
             missed.push({ id: rule.id, reason: report.failures[0]?.reason ?? "" });
         }
     }
+    if (undecided.length > 0) {
+        return {
+            score: null,
+            rawScore: null,
+            band: null,
+            version: model.version ?? null,
+            contributors,
+            missed,
+            undetermined: undecided,
+        };
+    }
+    const rawScore = decimalToNumber(exact);
     let score = rawScore;
-    if (model.min !== undefined)
-        score = Math.max(model.min, score);
-    if (model.max !== undefined)
-        score = Math.min(model.max, score);
+    let clamped = exact;
+    if (model.min !== undefined && compareExact(clamped, model.min) < 0) {
+        score = model.min;
+        clamped = parseDecimal(model.min);
+    }
+    if (model.max !== undefined && compareExact(clamped, model.max) > 0) {
+        score = model.max;
+        clamped = parseDecimal(model.max);
+    }
     let band = null;
     if (model.bands && model.bands.length > 0) {
         // Highest qualifying band wins, whatever order they were declared in, so
         // a table written low-to-high and one written high-to-low agree.
         const sorted = [...model.bands].sort((a, b) => b.min - a.min);
-        band = sorted.find((b) => score >= b.min)?.name ?? null;
+        band = sorted.find((b) => compareExact(clamped, b.min) >= 0)?.name ?? null;
     }
     return { score, rawScore, band, version: model.version ?? null, contributors, missed };
 }

package/dist/lib/sequence.d.ts

@@ -27,7 +27,7 @@
  *   a step that died three turns ago.
  * - **skipped** — the step's own conditions did not hold. A settled no.
  */
-import { type Check } from "@crewhaus/tool-schema";
+import { type Check, type RegexAnswers } from "@crewhaus/tool-schema";
 import type { MatchMode } from "./branch";
 /**
  * Where a flow stands.
@@ -90,6 +90,12 @@ export type SequencePlan = {
     readonly waiting: ReadonlyArray<HeldStep>;
     readonly unreachable: ReadonlyArray<HeldStep>;
     readonly skipped: ReadonlyArray<HeldStep>;
+    /**
+     * Steps whose conditions could not be decided (a pattern had no answer):
+     * neither ready nor skipped, so the flow is `blocked` on them rather than
+     * running or ruling out a step on a guess. Present only when there are any.
+     */
+    readonly undetermined?: ReadonlyArray<HeldStep>;
     readonly completed: ReadonlyArray<string>;
     readonly failed: ReadonlyArray<string>;
     readonly version: string | null;
@@ -106,4 +112,6 @@ export type SequencePlan = {
  * a leftover from an older revision of the flow — would silently re-run a
  * step the caller believes is finished.
  */
-export declare function planSequence(value: unknown, spec: SequenceSpec, state: SequenceState): SequencePlan;
+export declare function planSequence(value: unknown, spec: SequenceSpec, state: SequenceState, options?: {
+    readonly regex?: RegexAnswers;
+}): SequencePlan;

package/dist/lib/sequence.js

@@ -27,7 +27,7 @@
  *   a step that died three turns ago.
  * - **skipped** — the step's own conditions did not hold. A settled no.
  */
-import { runChecks } from "@crewhaus/tool-schema";
+import { checksVerdict, runChecks } from "@crewhaus/tool-schema";
 /**
  * Where a flow stands.
  *
@@ -47,7 +47,7 @@ export const PLAN_STATES = ["ready", "blocked", "finished", "halted"];
  * a leftover from an older revision of the flow — would silently re-run a
  * step the caller believes is finished.
  */
-export function planSequence(value, spec, state) {
+export function planSequence(value, spec, state, options = {}) {
     const steps = spec.steps;
     if (steps.length === 0)
         throw new Error("the sequence has no steps");
@@ -132,16 +132,28 @@ export function planSequence(value, spec, state) {
             });
             continue;
         }
-        // The shared evaluator reports a check it could not evaluate — a regex
-        // that will not compile, a malformed path — as a check that did not hold,
-        // with the reason as its text and no flag to tell the two apart. That is
-        // `Branch` and `RuleScore`'s behaviour too, and inventing a different one
-        // here would mean two answers to the same question. It bites harder in a
-        // sequence, because the skip cascades into `unreachable` dependents, so
-        // the reason travels with every one of them.
+        // The shared evaluator reports a malformed check (a regex that will not
+        // compile, a bad path) as a check that did not hold, with the reason as
+        // its text. That is `Branch` and `RuleScore`'s behaviour too, and
+        // inventing a different one here would mean two answers to the same
+        // question. It bites harder in a sequence, because the skip cascades
+        // into `unreachable` dependents, so the reason travels with every one of
+        // them. A pattern that could not be run to an answer is different: it
+        // is not a verdict, so the step is held as undetermined instead.
         if (step.when && step.when.length > 0) {
-            const report = runChecks(value, step.when);
-            const holds = (step.match ?? "all") === "all" ? report.ok : report.passed > 0;
+            const report = runChecks(value, step.when, options.regex === undefined ? {} : { regex: options.regex });
+            const verdict = checksVerdict(report, step.match ?? "all");
+            if (verdict === "undetermined") {
+                // Neither due nor ruled out: skipping it would cascade `unreachable`
+                // through its dependents on an answer nobody got.
+                states.set(step.id, "undetermined");
+                reasons.set(step.id, {
+                    id: step.id,
+                    reason: report.failures.find((f) => f.undetermined === true)?.reason ?? "",
+                });
+                continue;
+            }
+            const holds = verdict === "pass";
             if (!holds) {
                 states.set(step.id, "skipped");
                 reasons.set(step.id, {
@@ -160,6 +172,7 @@ export function planSequence(value, spec, state) {
     const waiting = [];
     const unreachable = [];
     const skipped = [];
+    const undecided = [];
     const doneIds = [];
     const failedIds = [];
     for (const [index, step] of steps.entries()) {
@@ -179,6 +192,9 @@ export function planSequence(value, spec, state) {
             case "skipped":
                 skipped.push(held);
                 break;
+            case "undetermined":
+                undecided.push(held);
+                break;
             case "done":
                 doneIds.push(step.id);
                 break;
@@ -189,7 +205,7 @@ export function planSequence(value, spec, state) {
     }
     const planState = ready.length > 0
         ? "ready"
-        : waiting.length > 0
+        : waiting.length > 0 || undecided.length > 0
             ? "blocked"
             : failedIds.length > 0 || unreachable.length > 0
                 ? "halted"
@@ -201,6 +217,7 @@ export function planSequence(value, spec, state) {
         waiting,
         unreachable,
         skipped,
+        ...(undecided.length > 0 ? { undetermined: undecided } : {}),
         completed: doneIds,
         failed: failedIds,
         version: spec.version ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/tool-flow",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Deterministic control-flow tools: branching, decision tables, error classification, deadlines, consensus, stall detection, rule scoring, record routing and sequence planning",
   "main": "dist/index.js",
@@ -8,17 +8,19 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.7.0",
-    "@crewhaus/tool-builder": "0.7.0",
-    "@crewhaus/tool-catalog": "0.7.0",
-    "@crewhaus/tool-schema": "0.7.0",
+    "@crewhaus/errors": "0.8.0",
+    "@crewhaus/tool-builder": "0.8.0",
+    "@crewhaus/tool-catalog": "0.8.0",
+    "@crewhaus/tool-math": "0.8.0",
+    "@crewhaus/tool-schema": "0.8.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -42,5 +44,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
 }