@crewhaus/tool-flow 0.7.0 → 0.8.0

package/dist/lib/consensus.js

@@ -24,13 +24,17 @@ export function normalizeValue(value, options = {}) {
 }
 /** Jaccard similarity of two arrays treated as sets of stringified members. */
 export function jaccard(a, b) {
-    const left = new Set(a.map(canonicalize));
-    const right = new Set(b.map(canonicalize));
+    return jaccardOfSets(new Set(a.map(canonicalize)), new Set(b.map(canonicalize)));
+}
+/** {@link jaccard} of two arrays already turned into sets of stringified members. */
+function jaccardOfSets(left, right) {
     if (left.size === 0 && right.size === 0)
         return 1;
+    // The shared count is the same whichever side is walked; walk the smaller.
+    const [small, large] = left.size <= right.size ? [left, right] : [right, left];
     let shared = 0;
-    for (const item of left)
-        if (right.has(item))
+    for (const item of small)
+        if (large.has(item))
             shared += 1;
     return shared / (left.size + right.size - shared);
 }
@@ -56,6 +60,71 @@ export function tallyVotes(votes, options = {}) {
         throw new Error("no votes were given");
     const groups = [];
     let total = 0;
+    const mode = options.mode ?? "exact";
+    const overlap = options.overlap ?? 1;
+    // Groups by canonical form, where "the same answer" is equality of that
+    // form: `exact`, and `set` at overlap 1, where a Jaccard of 1 means equal
+    // sets. Each vote then finds its group by one lookup, where comparing it
+    // with every group canonicalized both sides each time: 512 votes of a
+    // kilobyte made 270 million characters of JSON.
+    const byKey = new Map();
+    /** `set`: the first group whose value is an array, the only kind a set vote can join. */
+    const arrays = {};
+    const membersOf = (value) => new Set(value.map(canonicalize));
+    /** The canonical form of a set vote at overlap 1: its distinct members, sorted. */
+    const setKey = (members) => JSON.stringify([...members].sort());
+    /**
+     * The first group `value` counts as the same answer as, or undefined —
+     * what `groups.find((g) => same(g.value, value, options))` returns, with
+     * each value's canonical form or members worked out once, at the point the
+     * pairwise comparison first needed them, so anything that cannot be
+     * canonicalized throws exactly where it did.
+     */
+    const firstSame = (value, created) => {
+        if (mode === "exact") {
+            const first = groups[0];
+            if (first === undefined)
+                return undefined;
+            if (first.key === undefined) {
+                first.key = canonicalize(first.value);
+                byKey.set(first.key, first);
+            }
+            created.key = canonicalize(value);
+            return byKey.get(created.key);
+        }
+        if (mode === "set") {
+            if (!Array.isArray(value))
+                return undefined;
+            let mine;
+            if (overlap === 1) {
+                // Only array groups can match; the first of them may not have its
+                // members yet, every later one got them when it was created.
+                const first = arrays.first;
+                if (first === undefined)
+                    return undefined;
+                if (first.members === undefined) {
+                    first.members = membersOf(first.value);
+                    first.key = setKey(first.members);
+                    byKey.set(first.key, first);
+                }
+                mine = membersOf(value);
+                created.members = mine;
+                created.key = setKey(mine);
+                return byKey.get(created.key);
+            }
+            for (const g of groups) {
+                if (!Array.isArray(g.value))
+                    continue;
+                g.members ??= membersOf(g.value);
+                mine ??= membersOf(value);
+                created.members = mine;
+                if (jaccardOfSets(g.members, mine) >= overlap)
+                    return g;
+            }
+            return undefined;
+        }
+        return groups.find((g) => same(g.value, value, options));
+    };
     for (const [index, vote] of votes.entries()) {
         const weight = vote.weight ?? 1;
         if (!Number.isFinite(weight) || weight < 0) {
@@ -65,16 +134,24 @@ export function tallyVotes(votes, options = {}) {
         total += weight;
         const voter = vote.voter ?? `#${index}`;
         // Grouping is by first-match against existing groups, which is what makes
-        // `numeric` and `set` work at all: they are not transitive, so there is no
-        // canonical key to bucket by. Declared order therefore decides which
-        // group a borderline value joins, and that is why it is documented.
-        const existing = groups.find((g) => same(g.value, value, options));
+        // `numeric` and `set` below full overlap work at all: they are not
+        // transitive, so there is no canonical key to bucket by. Declared order
+        // therefore decides which group a borderline value joins, and that is why
+        // it is documented. (`exact` and full-overlap `set` are transitive, and
+        // `firstSame` buckets them.)
+        const created = {};
+        const existing = firstSame(value, created);
         if (existing) {
             existing.weight += weight;
             existing.voters.push(voter);
         }
         else {
-            groups.push({ value, weight, voters: [voter], order: index });
+            const group = { ...created, value, weight, voters: [voter], order: index };
+            groups.push(group);
+            if (group.key !== undefined)
+                byKey.set(group.key, group);
+            if (arrays.first === undefined && Array.isArray(value))
+                arrays.first = group;
         }
     }
     const ranked = [...groups].sort((a, b) => b.weight - a.weight || a.order - b.order);

package/dist/lib/decision.d.ts

@@ -1,4 +1,4 @@
-import { type Check } from "@crewhaus/tool-schema";
+import { type Check, type RegexAnswers } from "@crewhaus/tool-schema";
 import type { MatchMode } from "./branch";
 export declare const HIT_POLICIES: readonly ["first", "unique", "priority", "collect"];
 export type HitPolicy = (typeof HIT_POLICIES)[number];
@@ -30,9 +30,16 @@ export type DecisionResult = {
     readonly fallback: boolean;
     /** Set when the table could not answer: ambiguity under `unique`/`priority`. */
     readonly conflict: string | null;
+    /**
+     * Set when a row could not be decided (a pattern had no answer) that could
+     * have changed the outcome: no outputs are given, not even `otherwise`'s.
+     */
+    readonly undetermined?: string;
     /** Stable digest of the table, so a changed policy is visible in a log. */
     readonly tableHash: string;
 };
 /** Digest of the rows and policy — not the version string, which is a label. */
 export declare function hashTable(table: DecisionTable): string;
-export declare function evaluateTable(value: unknown, table: DecisionTable): DecisionResult;
+export declare function evaluateTable(value: unknown, table: DecisionTable, options?: {
+    readonly regex?: RegexAnswers;
+}): DecisionResult;

package/dist/lib/decision.js

@@ -8,7 +8,7 @@
  * policy bug that "first wins" hides.
  */
 import { createHash } from "node:crypto";
-import { runChecks } from "@crewhaus/tool-schema";
+import { checksVerdict, runChecks } from "@crewhaus/tool-schema";
 import { canonicalize } from "./canonical";
 export const HIT_POLICIES = ["first", "unique", "priority", "collect"];
 /** Digest of the rows and policy — not the version string, which is a label. */
@@ -16,7 +16,7 @@ export function hashTable(table) {
     const material = canonicalize({ policy: table.policy, rows: table.rows });
     return createHash("sha256").update(material).digest("hex").slice(0, 16);
 }
-export function evaluateTable(value, table) {
+export function evaluateTable(value, table, options = {}) {
     if (table.rows.length === 0)
         throw new Error("the decision table has no rows");
     const seen = new Set();
@@ -32,10 +32,19 @@ export function evaluateTable(value, table) {
     const version = table.version ?? null;
     const base = { policy: table.policy, version, tableHash };
     const matches = [];
+    const undecided = [];
     for (const row of table.rows) {
-        const report = runChecks(value, row.when);
-        const ok = (row.match ?? "all") === "all" ? report.ok : report.passed > 0;
-        if (ok) {
+        const report = runChecks(value, row.when, options.regex === undefined ? {} : { regex: options.regex });
+        const verdict = checksVerdict(report, row.match ?? "all");
+        if (verdict === "undetermined") {
+            const why = report.failures.find((f) => f.undetermined === true)?.reason ?? "";
+            undecided.push(`row "${row.id}": ${why}`);
+            // Under `first`, a later row cannot be taken past one not decided.
+            if (table.policy === "first")
+                break;
+            continue;
+        }
+        if (verdict === "pass") {
             matches.push(row);
             // `first` needs no further rows; the others need to see them all.
             if (table.policy === "first")
@@ -43,6 +52,18 @@ export function evaluateTable(value, table) {
         }
     }
     const matchedIds = matches.map((r) => r.id);
+    if (undecided.length > 0) {
+        return {
+            ...base,
+            ok: false,
+            matched: false,
+            matchedIds,
+            outputs: null,
+            fallback: false,
+            conflict: null,
+            undetermined: `could not decide ${undecided.join("; ")}`,
+        };
+    }
     if (matches.length === 0) {
         if (table.otherwise) {
             return {

package/dist/lib/errors.d.ts

@@ -14,6 +14,7 @@
  * called `Date.now()` would return a different answer every second, which is
  * exactly what this package promises not to do.
  */
+import { type RegexAnswers } from "@crewhaus/tool-schema";
 export declare const ERROR_CLASSES: readonly ["ok", "transient", "timeout", "unavailable", "rate_limited", "quota", "auth", "permission", "not_found", "bad_request", "conflict", "too_large", "unsupported", "capacity", "integrity", "cancelled", "redirect", "bug", "unknown"];
 export type ErrorClass = (typeof ERROR_CLASSES)[number];
 export declare const NEXT_ACTIONS: readonly ["continue", "retry", "retry_after", "backoff", "reauth", "reduce_input", "escalate", "skip", "fail"];
@@ -56,22 +57,42 @@ export type Classification = {
     readonly retryAt: string | null;
     /** Which rule decided this: a pack entry's id, or a caller rule's id. */
     readonly matched: string;
-    readonly source: "custom" | "status" | "exit" | "signal" | "code" | "message" | "default";
+    readonly source: "custom" | "status" | "exit" | "signal" | "code" | "message" | "default" | "undetermined";
     /** True when attempts ran out, which downgrades a retry to an escalation. */
     readonly exhausted: boolean;
+    /**
+     * Set when a caller rule tried before any match could not be decided (its
+     * pattern had no answer): no class is given for it (`unknown`, source
+     * `undetermined`) and the action is `escalate`, never a later rule's or a
+     * builtin pack's answer, which that rule might have overridden.
+     */
+    readonly undetermined?: string;
 };
 /**
- * Parse `Retry-After`. Two forms are legal: delta-seconds, and an HTTP-date.
- * The date form needs a reference point to become a duration, so without
- * `nowMs` it is returned as a date and `waitMs` stays null.
+ * Parse `Retry-After`. Two forms are legal: delta-seconds, and an HTTP-date
+ * (RFC 9110: IMF-fixdate, or the obsolete rfc850 and asctime forms, all
+ * GMT). An RFC 5322 date-time with its zone written (`+0200`, `UTC`,
+ * `-0000`), and an ISO-8601 instant with an explicit offset, are read too,
+ * because each is unambiguous and 0.7.0 read them. Anything else — a date
+ * with no zone, an offset-less ISO string, prose — answers nulls rather than
+ * being read as the host's local time. The date form needs a reference point to become a duration, so
+ * without `nowMs` it is returned as a date and `waitMs` stays null.
  */
 export declare function parseRetryAfter(raw: string, nowMs?: number): {
     waitMs: number | null;
     retryAt: string | null;
 };
+/**
+ * Ask `regex` about every caller rule's pattern for `signal`, so one
+ * resolve in the worker settles them before {@link classifyError} reads
+ * them. The fields are the ones {@link classifyError} tests.
+ */
+export declare function askErrorPatterns(signal: ErrorSignal, rules: ReadonlyArray<ErrorRule>, regex: RegexAnswers): void;
 export type ClassifyOptions = {
     readonly rules?: ReadonlyArray<ErrorRule>;
     /** Epoch milliseconds, only used to turn an HTTP-date `Retry-After` into a wait. */
     readonly nowMs?: number;
+    /** Answers for the caller rules' `matches` patterns; see {@link askErrorPatterns}. */
+    readonly regex?: RegexAnswers;
 };
 export declare function classifyError(signal: ErrorSignal, options?: ClassifyOptions): Classification;

package/dist/lib/errors.js

@@ -14,6 +14,8 @@
  * called `Date.now()` would return a different answer every second, which is
  * exactly what this package promises not to do.
  */
+import { testPatternSync } from "@crewhaus/tool-schema";
+import { parseHttpDate, parseIsoInstantWithOffset, parseRfc5322WithZone } from "./http-date";
 export const ERROR_CLASSES = [
     "ok",
     "transient",
@@ -247,9 +249,14 @@ const MESSAGE_TABLE = [
 /** Guards the substring scan against a multi-megabyte error body. */
 const MAX_MESSAGE_CHARS = 64_000;
 /**
- * Parse `Retry-After`. Two forms are legal: delta-seconds, and an HTTP-date.
- * The date form needs a reference point to become a duration, so without
- * `nowMs` it is returned as a date and `waitMs` stays null.
+ * Parse `Retry-After`. Two forms are legal: delta-seconds, and an HTTP-date
+ * (RFC 9110: IMF-fixdate, or the obsolete rfc850 and asctime forms, all
+ * GMT). An RFC 5322 date-time with its zone written (`+0200`, `UTC`,
+ * `-0000`), and an ISO-8601 instant with an explicit offset, are read too,
+ * because each is unambiguous and 0.7.0 read them. Anything else — a date
+ * with no zone, an offset-less ISO string, prose — answers nulls rather than
+ * being read as the host's local time. The date form needs a reference point to become a duration, so
+ * without `nowMs` it is returned as a date and `waitMs` stays null.
  */
 export function parseRetryAfter(raw, nowMs) {
     const text = raw.trim();
@@ -259,8 +266,8 @@ export function parseRetryAfter(raw, nowMs) {
         const seconds = Number.parseInt(text, 10);
         return { waitMs: seconds * 1000, retryAt: null };
     }
-    const parsed = Date.parse(text);
-    if (Number.isNaN(parsed))
+    const parsed = parseHttpDate(text, nowMs) ?? parseRfc5322WithZone(text) ?? parseIsoInstantWithOffset(text);
+    if (parsed === undefined)
         return { waitMs: null, retryAt: null };
     const retryAt = new Date(parsed).toISOString();
     if (nowMs === undefined)
@@ -281,7 +288,7 @@ export function parseRetryAfter(raw, nowMs) {
  *   matched immediately into a backtracking search over attacker-supplied
  *   text. Joining the fields manufactured the worst case for free.
  */
-function matchCustom(signal, rules, fields) {
+function matchCustom(signal, rules, fields, regex) {
     for (const rule of rules) {
         if (rule.status !== undefined && rule.status !== signal.status)
             continue;
@@ -293,15 +300,29 @@ function matchCustom(signal, rules, fields) {
                 continue;
         }
         if (rule.matches !== undefined) {
-            let re;
-            try {
-                re = new RegExp(rule.matches, "i");
-            }
-            catch (err) {
-                throw new Error(`rule "${rule.id}" has an invalid pattern: ${err.message}`);
-            }
-            if (!fields.some((f) => re.test(f)))
+            // The caller's pattern never runs on this thread: the tool answered it
+            // in the worker (a library caller gets the bounded fallback). Either
+            // field matching decides it; otherwise one without an answer leaves
+            // the rule undecided, never "no match".
+            const pattern = rule.matches;
+            const answers = fields.map((f) => regex === undefined ? testPatternSync(pattern, "i", f) : regex.lookup(pattern, "i", f));
+            if (!answers.includes(true)) {
+                for (const answer of answers) {
+                    if (typeof answer === "object" && "refused" in answer) {
+                        throw new Error(`rule "${rule.id}" has an invalid pattern: ${answer.refused}`);
+                    }
+                }
+                // `undefined` is a question not answered yet: as open as undetermined.
+                const open = answers.findIndex((a) => a !== false);
+                if (open !== -1) {
+                    const answer = answers[open];
+                    const why = typeof answer === "object" && "undetermined" in answer
+                        ? answer.undetermined
+                        : "its answer has not been worked out yet";
+                    return { undetermined: `rule "${rule.id}" could not be decided: ${why}`, rule };
+                }
                 continue;
+            }
         }
         // A rule with no conditions at all would match everything silently.
         const hasCondition = rule.status !== undefined ||
@@ -314,16 +335,49 @@ function matchCustom(signal, rules, fields) {
     }
     return null;
 }
+/**
+ * Ask `regex` about every caller rule's pattern for `signal`, so one
+ * resolve in the worker settles them before {@link classifyError} reads
+ * them. The fields are the ones {@link classifyError} tests.
+ */
+export function askErrorPatterns(signal, rules, regex) {
+    for (const field of classifiedFields(signal)) {
+        for (const rule of rules) {
+            if (rule.matches !== undefined)
+                regex.lookup(rule.matches, "i", field);
+        }
+    }
+}
+function classifiedFields(signal) {
+    const message = (signal.message ?? "").slice(0, MAX_MESSAGE_CHARS);
+    return [message.toLowerCase(), (signal.code ?? "").toLowerCase()];
+}
 export function classifyError(signal, options = {}) {
     const message = (signal.message ?? "").slice(0, MAX_MESSAGE_CHARS);
-    const fields = [message.toLowerCase(), (signal.code ?? "").toLowerCase()];
+    const fields = classifiedFields(signal);
     const retry = signal.retryAfter === undefined
         ? { waitMs: null, retryAt: null }
         : parseRetryAfter(signal.retryAfter, options.nowMs);
     let verdict = null;
     let matched = "default";
     let source = "default";
-    const custom = matchCustom(signal, options.rules ?? [], fields);
+    const custom = matchCustom(signal, options.rules ?? [], fields, options.regex);
+    if (custom !== null && "undetermined" in custom) {
+        const exhausted = signal.attempt !== undefined &&
+            signal.maxAttempts !== undefined &&
+            signal.attempt >= signal.maxAttempts;
+        return {
+            class: "unknown",
+            action: "escalate",
+            retryable: false,
+            waitMs: null,
+            retryAt: retry.retryAt,
+            matched: custom.rule.id,
+            source: "undetermined",
+            exhausted,
+            undetermined: custom.undetermined,
+        };
+    }
     if (custom) {
         verdict = { class: custom.class, action: custom.action, waitMs: custom.waitMs };
         matched = custom.id;

package/dist/lib/http-date.d.ts

@@ -0,0 +1,30 @@
+/**
+ * HTTP-dates (RFC 9110 §5.6.7), read as the instants they name.
+ *
+ * `Date.parse` is not an HTTP-date reader. It accepts anything a browser
+ * ever did, and reads a string with no zone as the HOST's local time: an
+ * asctime date (which the RFC defines as GMT), a zone-less RFC 1123 date or
+ * an offset-less ISO-8601 string meant 10:00 UTC on one machine and 01:00
+ * UTC on another, so ErrorClassify's wait for the same header differed by
+ * the operator's timezone. This reads exactly the three forms the RFC
+ * defines, all of which are GMT by definition, builds the instant from
+ * its UTC fields, and answers undefined for anything else — never a guess.
+ * Two unambiguous non-HTTP forms that 0.7.0 read correctly are read too,
+ * each only with its zone written: an RFC 5322 date-time and an ISO-8601
+ * instant with an offset.
+ */
+/**
+ * The epoch milliseconds an HTTP-date names, or undefined when `text` is not
+ * one of the RFC 9110 forms.
+ *
+ * An rfc850-date has a two-digit year; per the RFC it is read as the most
+ * recent year with those digits that is not more than 50 years after
+ * `nowMs`. Without `nowMs` its century is unknown, so it answers undefined
+ * rather than guessing one. Names are matched without regard to case; the
+ * weekday is checked to be a weekday but not against the date, as
+ * recipients commonly do.
+ */
+export declare function parseHttpDate(text: string, nowMs?: number): number | undefined;
+/** The epoch milliseconds an RFC 5322 date-time with a written zone names, or undefined. */
+export declare function parseRfc5322WithZone(text: string): number | undefined;
+export declare function parseIsoInstantWithOffset(text: string): number | undefined;

package/dist/lib/http-date.js

@@ -0,0 +1,175 @@
+/**
+ * HTTP-dates (RFC 9110 §5.6.7), read as the instants they name.
+ *
+ * `Date.parse` is not an HTTP-date reader. It accepts anything a browser
+ * ever did, and reads a string with no zone as the HOST's local time: an
+ * asctime date (which the RFC defines as GMT), a zone-less RFC 1123 date or
+ * an offset-less ISO-8601 string meant 10:00 UTC on one machine and 01:00
+ * UTC on another, so ErrorClassify's wait for the same header differed by
+ * the operator's timezone. This reads exactly the three forms the RFC
+ * defines, all of which are GMT by definition, builds the instant from
+ * its UTC fields, and answers undefined for anything else — never a guess.
+ * Two unambiguous non-HTTP forms that 0.7.0 read correctly are read too,
+ * each only with its zone written: an RFC 5322 date-time and an ISO-8601
+ * instant with an offset.
+ */
+const DAY_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const LONG_DAY_NAMES = [
+    "sunday",
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+];
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+// Bounded, anchored, and with no nested quantifiers: each is linear.
+/** IMF-fixdate: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const IMF_FIXDATE = /^([A-Za-z]{3}), (\d{2}) ([A-Za-z]{3}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/i;
+/** rfc850-date (obsolete): `Sunday, 06-Nov-94 08:49:37 GMT`. */
+const RFC850_DATE = /^([A-Za-z]{6,9}), (\d{2})-([A-Za-z]{3})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/i;
+/** asctime-date (obsolete): `Sun Nov  6 08:49:37 1994`, GMT with no zone written. */
+const ASCTIME_DATE = /^([A-Za-z]{3}) ([A-Za-z]{3}) ( \d|\d{2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/i;
+/**
+ * The epoch milliseconds of a UTC calendar time, or undefined when any field
+ * is out of range. The year is used as written: `Date.UTC` maps 0-99 to
+ * 1900-1999, which read `Sat, 26 Sep 0026 …` as 1926.
+ */
+function utcInstant(year, month, day, hour, minute, second, ms = 0) {
+    if (month < 0 || month > 11 || day < 1 || hour > 23 || minute > 59 || second > 60) {
+        return undefined;
+    }
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    // Refuse a day the month does not have (31 Nov, 30 Feb), rather than
+    // rolling over into the next month as Date does.
+    if (date.getUTCMonth() !== month || date.getUTCDate() !== day)
+        return undefined;
+    // A leap second is legal on the wire; it names the same instant as :59
+    // plus one second, which is what adding 60 seconds gives.
+    return date.getTime() + ((hour * 60 + minute) * 60 + second) * 1000 + ms;
+}
+function instant(year, monthName, day, hour, minute, second) {
+    return utcInstant(year, MONTHS.indexOf(monthName.toLowerCase()), day, hour, minute, second);
+}
+/**
+ * The epoch milliseconds an HTTP-date names, or undefined when `text` is not
+ * one of the RFC 9110 forms.
+ *
+ * An rfc850-date has a two-digit year; per the RFC it is read as the most
+ * recent year with those digits that is not more than 50 years after
+ * `nowMs`. Without `nowMs` its century is unknown, so it answers undefined
+ * rather than guessing one. Names are matched without regard to case; the
+ * weekday is checked to be a weekday but not against the date, as
+ * recipients commonly do.
+ */
+export function parseHttpDate(text, nowMs) {
+    const t = text.trim();
+    let m = IMF_FIXDATE.exec(t);
+    if (m !== null) {
+        if (!DAY_NAMES.includes(m[1].toLowerCase()))
+            return undefined;
+        return instant(Number(m[4]), m[3], Number(m[2]), Number(m[5]), Number(m[6]), Number(m[7]));
+    }
+    m = RFC850_DATE.exec(t);
+    if (m !== null) {
+        if (!LONG_DAY_NAMES.includes(m[1].toLowerCase()))
+            return undefined;
+        if (nowMs === undefined || !Number.isFinite(nowMs))
+            return undefined;
+        const nowYear = new Date(nowMs).getUTCFullYear();
+        const yy = Number(m[4]);
+        let year = nowYear - (nowYear % 100) + yy;
+        if (year > nowYear + 50)
+            year -= 100;
+        return instant(year, m[3], Number(m[2]), Number(m[5]), Number(m[6]), Number(m[7]));
+    }
+    m = ASCTIME_DATE.exec(t);
+    if (m !== null) {
+        if (!DAY_NAMES.includes(m[1].toLowerCase()))
+            return undefined;
+        return instant(Number(m[7]), m[2], Number(m[3].trim()), Number(m[4]), Number(m[5]), Number(m[6]));
+    }
+    return undefined;
+}
+/**
+ * RFC 5322 date-time: optional weekday, a one- or two-digit day, a
+ * four-digit year, optional seconds, and a zone that is WRITTEN — GMT, UT,
+ * UTC, Z, `±hhmm`, or one of the eight North American names RFC 5322 gives
+ * fixed offsets. Mail libraries write these (`… 07:28:00 -0000`, `… +0200`),
+ * and `Date.parse` read them correctly on 0.7.0 on every host, because the
+ * zone is in the text. Military one-letter zones are refused: RFC 5322 says
+ * their signs were botched in practice and to treat them as unknown.
+ */
+const RFC5322_DATE = /^(?:([A-Za-z]{3}),\s*)?(\d{1,2})\s+([A-Za-z]{3})\s+(\d{4})\s+(\d{2}):(\d{2})(?::(\d{2}))?\s+(GMT|UTC|UT|Z|[+-]\d{4}|[ECMP][SD]T)$/i;
+/** RFC 5322's named zones, as offsets in minutes east of UTC. */
+const NAMED_ZONES = new Map([
+    ["gmt", 0],
+    ["utc", 0],
+    ["ut", 0],
+    ["z", 0],
+    ["est", -300],
+    ["edt", -240],
+    ["cst", -360],
+    ["cdt", -300],
+    ["mst", -420],
+    ["mdt", -360],
+    ["pst", -480],
+    ["pdt", -420],
+]);
+/** The epoch milliseconds an RFC 5322 date-time with a written zone names, or undefined. */
+export function parseRfc5322WithZone(text) {
+    const m = RFC5322_DATE.exec(text.trim());
+    if (m === null)
+        return undefined;
+    if (m[1] !== undefined && !DAY_NAMES.includes(m[1].toLowerCase()))
+        return undefined;
+    const zone = m[8].toLowerCase();
+    let offsetMinutes;
+    if (zone.startsWith("+") || zone.startsWith("-")) {
+        const hours = Number(zone.slice(1, 3));
+        const minutes = Number(zone.slice(3, 5));
+        if (hours > 23 || minutes > 59)
+            return undefined;
+        offsetMinutes = (zone.startsWith("-") ? -1 : 1) * (hours * 60 + minutes);
+    }
+    else {
+        const named = NAMED_ZONES.get(zone);
+        if (named === undefined)
+            return undefined;
+        offsetMinutes = named;
+    }
+    const ms = instant(Number(m[4]), m[3], Number(m[2]), Number(m[5]), Number(m[6]), Number(m[7] ?? "0"));
+    return ms === undefined ? undefined : ms - offsetMinutes * 60_000;
+}
+/**
+ * An ISO-8601 / RFC 3339 date-time that carries its own UTC offset (`Z`,
+ * `±hh:mm` or `±hhmm`), with `T` or a single space between date and time
+ * (RFC 3339 §5.6 allows the space; Python's `str(datetime)` writes it). Not
+ * an HTTP-date, but unambiguous, and `Date.parse` read it correctly on
+ * 0.7.0, so a server that sends one keeps working. Without the offset it is
+ * refused like any other zone-less time.
+ *
+ * The fields are checked here, not by `Date.parse`, which rolls an
+ * impossible day over (`2026-02-30` became 2 March). Fractional seconds past
+ * the millisecond are dropped, as `Date.parse` drops them.
+ */
+const ISO_WITH_OFFSET = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:?\d{2})$/i;
+export function parseIsoInstantWithOffset(text) {
+    const m = ISO_WITH_OFFSET.exec(text.trim());
+    if (m === null)
+        return undefined;
+    const zone = m[8].toUpperCase();
+    let offsetMinutes = 0;
+    if (zone !== "Z") {
+        const digits = zone.slice(1).replace(":", "");
+        const hours = Number(digits.slice(0, 2));
+        const minutes = Number(digits.slice(2, 4));
+        if (hours > 23 || minutes > 59)
+            return undefined;
+        offsetMinutes = (zone.startsWith("-") ? -1 : 1) * (hours * 60 + minutes);
+    }
+    const ms = utcInstant(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6] ?? "0"), Number(`${m[7] ?? ""}000`.slice(0, 3)));
+    return ms === undefined ? undefined : ms - offsetMinutes * 60_000;
+}

package/dist/lib/score.d.ts

@@ -1,14 +1,4 @@
-/**
- * Additive rule scoring with an attributable breakdown.
- *
- * Any "score this thing and decide which band it lands in" job — lead
- * qualification, risk, triage priority — is a table lookup plus addition.
- * The reason to do it here rather than in a model is not only cost: a score
- * a model produced cannot be explained to the person it affects, and cannot
- * be re-run identically next quarter. This returns the contributors, and the
- * version of the rules that produced them.
- */
-import { type Check } from "@crewhaus/tool-schema";
+import { type Check, type RegexAnswers } from "@crewhaus/tool-schema";
 export type ScoreRule = {
     readonly id: string;
     /** All of these must hold for the points to be awarded. */
@@ -31,9 +21,10 @@ export type ScoreModel = {
     readonly max?: number;
 };
 export type ScoreResult = {
-    readonly score: number;
+    /** Null when a rule could not be decided: its points may or may not count. */
+    readonly score: number | null;
     /** The sum before clamping, which differs from `score` when it was clamped. */
-    readonly rawScore: number;
+    readonly rawScore: number | null;
     readonly band: string | null;
     readonly version: string | null;
     readonly contributors: ReadonlyArray<{
@@ -46,5 +37,16 @@ export type ScoreResult = {
         readonly id: string;
         readonly reason: string;
     }>;
+    /**
+     * Rules that could not be decided (a pattern had no answer), with why. When
+     * any is listed, `score`, `rawScore` and `band` are null: a total that left
+     * their points out would be a guess.
+     */
+    readonly undetermined?: ReadonlyArray<{
+        readonly id: string;
+        readonly reason: string;
+    }>;
 };
-export declare function scoreValue(value: unknown, model: ScoreModel): ScoreResult;
+export declare function scoreValue(value: unknown, model: ScoreModel, options?: {
+    readonly regex?: RegexAnswers;
+}): ScoreResult;