@aiquants/spreadsheet 0.8.0

package/src/model/dataValidation.ts

@@ -0,0 +1,542 @@
+/**
+ * @fileoverview Data-validation rule vocabulary and the pure verdict engine (v0.8 — the
+ * getCellValidation capability, ADR-13). The consumer declares a per-cell DataValidationRule
+ * via the optional adapter capability getCellValidation(row, col); the editor asks
+ * validateCellText at COMMIT (passing the adapter's formula evaluator for `custom` rules) and
+ * the grid asks isVisiblyInvalid at PAINT (never evaluating a formula) to draw the invalid
+ * indicator. React-free and total.
+ *
+ * Engine contract (each clause is load-bearing and mutation-gated — spec 01 §8.3):
+ * - BLANK IS ALWAYS VALID: the empty string satisfies every rule (Excel "ignore blank"), so a
+ *   validated cell can always be cleared; `custom` is not even evaluated for a blank.
+ * - EXACT decimal comparison for `number` rules: the cell text and both bounds are parsed with
+ *   the SAME strict-decimal grammar as cellFormat.ts (`[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d{1,4})?`,
+ *   trimmed, no hex / grouping / ±Infinity) and compared as normalised sign / significant-digit /
+ *   point-position triples — never through a binary double — so "9007199254740993" is greater
+ *   than "9007199254740992" and "0.30000000000000004" is not equal to "0.3".
+ * - TIMEZONE-FREE dates for `date` rules: the pure-calendar grammar of cellFormat.ts
+ *   ("YYYY-MM-DD[ T HH:mm[:ss]]" or "/" separated, leap-aware ranges, no Date object), compared
+ *   as (year, month, day, hour, minute, second) tuples; `between` / `notBetween` are inclusive.
+ * - INERT INCOMPLETE RULES: a bound that does not parse (`a` / `b` for number / date, a
+ *   non-finite `a` / `b` for textLength, a missing `b` for between / notBetween, a missing `value`
+ *   for the needle text ops) makes the rule accept everything — a half-written rule never locks a
+ *   cell. Bounds are never swapped: `between 10 and 5` accepts nothing but blank.
+ * - FAIL-FAST on a rule OUTSIDE the vocabulary: an unknown `type` or `op` is a consumer bug and
+ *   throws RangeError regardless of the text (fail-soft would silently disable validation).
+ * - INTERNED list Sets per rule object (WeakMap identity), so the paint-time `list` check is O(1)
+ *   even for a 10k-item list; a fresh rule object interns a fresh Set.
+ * - MESSAGE resolution: `errorMessage` when the consumer set it (an empty string is honoured as
+ *   is), else a built-in English summary of the rule.
+ * - `custom` needs the caller's `evaluate`; without it the rule is not evaluated (verdict ok), and
+ *   truth = `true` or a finite non-zero number (the conditionalFormat customFormula convention).
+ * - Matching is exact (case-sensitive, untrimmed) for `list` / `text` / `checkbox`; textLength
+ *   counts Unicode code points. `isEmail` is the WHATWG valid-e-mail grammar with a mandatory
+ *   dotted domain; `isUrl` is a WHATWG-parsable absolute http(s) URL.
+ *
+ * データ検証の規則語彙と純関数の判定エンジン (v0.8 — getCellValidation 能力、ADR-13)。
+ * consumer が任意能力 getCellValidation(row, col) で規則を宣言し、エディタが確定時に
+ * validateCellText (custom 規則にはアダプタの数式評価器を渡す)、グリッドが描画時に
+ * isVisiblyInvalid (数式は決して評価しない) を呼んで不正インジケータを描く。React 非依存・全域関数。
+ * エンジン契約 (全て変異検証で封印 — spec 01 §8.3): 空文字は常に有効 (Excel の「空白を無視」—
+ * 検証セルは必ず消去できる、custom も評価しない)、number は cellFormat.ts と同じ厳密 10 進文法で
+ * 符号 / 有効数字 / 小数点位置の正規形として正確比較 (double 非経由)、date は Date 非依存の純暦文法を
+ * タプル比較 (between は両端含み)、不完全な規則 (解釈不能な境界・between の b 欠落・needle 欠落) は
+ * 不活性 = 全受理 (書きかけの規則でセルを閉じ込めない、境界の入替もしない)、語彙外の type / op は
+ * consumer バグとして text に依らず RangeError、list の Set は規則 object 毎に WeakMap intern、
+ * メッセージは errorMessage (空文字も尊重) が無ければ組込みの英語要約、custom は evaluate 無しなら
+ * 未評価 (ok)・真 = true か有限非 0 数、照合は完全一致 (大文字小文字区別・trim 無し)、textLength は
+ * コードポイント数、isEmail は WHATWG 文法 + ドット付きドメイン必須、isUrl は WHATWG 絶対 http(s) URL。
+ */
+
+/** Ordered comparison vocabulary shared by number / textLength / date rules; between / notBetween include both bounds. / number / textLength / date 規則が共有する比較語彙。between / notBetween は両端含み。 */
+export type ValidationCompareOp = "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between" | "notBetween"
+
+/** Text-rule vocabulary: four needle ops (need `value`) and two shape checks (ignore `value`). / text 規則の語彙。needle 系 4 つ (value 必須) と形式検査 2 つ (value 無視)。 */
+export type ValidationTextOp = "contains" | "notContains" | "startsWith" | "endsWith" | "isEmail" | "isUrl"
+
+/** Options shared by every rule: `strict` rejects the commit (else warn only), `inputMessage` shows on the active cell, `errorMessage` replaces the built-in verdict message. / 全規則共通のオプション。strict は確定拒否 (無指定は警告のみ)、inputMessage は active セルの案内、errorMessage は組込みメッセージの置換。 */
+export type ValidationRuleBase = { strict?: boolean; inputMessage?: string; errorMessage?: string }
+
+/** The text must equal one of `values` exactly; `showDropdown` is a UI hint only. / text が values のいずれかと完全一致。showDropdown は UI ヒントのみ。 */
+export type ListValidationRule = { type: "list"; values: readonly string[]; showDropdown?: boolean }
+
+/** The text must be a strict decimal satisfying `op` against the decimal-string bounds `a` (and `b` for between / notBetween). / text が厳密 10 進で、10 進文字列の境界 a (between 系は b も) に対し op を満たす。 */
+export type NumberValidationRule = { type: "number"; op: ValidationCompareOp; a: string; b?: string }
+
+/** The code-point length of the text must satisfy `op` against the finite numeric bounds `a` (and `b`). / text のコードポイント数が有限数の境界 a (と b) に対し op を満たす。 */
+export type TextLengthValidationRule = { type: "textLength"; op: ValidationCompareOp; a: number; b?: number }
+
+/** The text must be a pure-calendar date satisfying `op` against the date-string bounds `a` (and `b`). / text が純暦日付で、日付文字列の境界 a (と b) に対し op を満たす。 */
+export type DateValidationRule = { type: "date"; op: ValidationCompareOp; a: string; b?: string }
+
+/** Substring / shape checks on the text; `value` is the needle for the four needle ops and ignored by isEmail / isUrl. / text の部分文字列 / 形式検査。value は needle 系 4 op の探索文字列で isEmail / isUrl では無視。 */
+export type TextValidationRule = { type: "text"; op: ValidationTextOp; value?: string }
+
+/** The text must equal `checked` or `unchecked` (declared defaults "TRUE" / "FALSE"). / text が checked か unchecked と一致 (宣言済み既定は "TRUE" / "FALSE")。 */
+export type CheckboxValidationRule = { type: "checkbox"; checked?: string; unchecked?: string }
+
+/** The consumer's formula decides; evaluated only when the caller supplies `evaluate` (commit time). / consumer の数式が判定。呼び手が evaluate を渡すとき (確定時) だけ評価。 */
+export type CustomValidationRule = { type: "custom"; formula: string }
+
+/** A per-cell data-validation rule: the shared options intersected with one of the seven typed members (§1.2). / セル毎のデータ検証規則。共通オプションと 7 種の型付きメンバーの交差 (§1.2)。 */
+export type DataValidationRule = ValidationRuleBase & (ListValidationRule | NumberValidationRule | TextLengthValidationRule | DateValidationRule | TextValidationRule | CheckboxValidationRule | CustomValidationRule)
+
+/** The outcome of validateCellText: ok, or rejected with the resolved message. / validateCellText の結果。ok か、解決済みメッセージ付きの拒否。 */
+export type ValidationVerdict = { ok: true } | { ok: false; message: string }
+
+/** A consumer-side formula evaluator handed to validateCellText for `custom` rules. / custom 規則のために validateCellText へ渡す consumer 側の数式評価器。 */
+export type ValidationEvaluate = (formula: string) => string | number | boolean | null
+
+/** The single shared ok verdict (frozen — identity-stable, never mutated by a consumer). / 共有の ok 判定 (freeze 済み — identity 安定、consumer が変更不能)。 */
+const VALID: ValidationVerdict = Object.freeze({ ok: true })
+
+/** Declared default for CheckboxValidationRule.checked. / CheckboxValidationRule.checked の宣言済み既定。 */
+const CHECKBOX_CHECKED_DEFAULT = "TRUE"
+
+/** Declared default for CheckboxValidationRule.unchecked. / CheckboxValidationRule.unchecked の宣言済み既定。 */
+const CHECKBOX_UNCHECKED_DEFAULT = "FALSE"
+
+/** The closed comparison vocabulary as a runtime set (fail-fast membership check). / 比較語彙の閉集合 (fail-fast の所属検査用)。 */
+const COMPARE_OPS: ReadonlySet<string> = new Set<ValidationCompareOp>(["gt", "gte", "lt", "lte", "eq", "neq", "between", "notBetween"])
+
+/** The closed text vocabulary as a runtime set. / text 語彙の閉集合。 */
+const TEXT_OPS: ReadonlySet<string> = new Set<ValidationTextOp>(["contains", "notContains", "startsWith", "endsWith", "isEmail", "isUrl"])
+
+/** Strict decimal grammar — identical to cellFormat.ts parseNumber (exponent bounded to 4 digits). / 厳密 10 進文法 — cellFormat.ts の parseNumber と同一 (指数は 4 桁まで)。 */
+const DECIMAL_GRAMMAR = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d{1,4})?$/
+
+/** Pure-calendar date grammar — identical to cellFormat.ts parseDate (same separator on both sides). / 純暦日付文法 — cellFormat.ts の parseDate と同一 (両側同一区切り)。 */
+const DATE_GRAMMAR = /^(\d{4})([-/])(\d{1,2})\2(\d{1,2})(?:[ T](\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?$/
+
+/**
+ * WHATWG valid e-mail address grammar with a mandatory dotted domain (the HTML spec allows a
+ * dotless host such as "a@b"; a validation rule wants a real domain).
+ * WHATWG の有効メールアドレス文法 + ドット付きドメイン必須 (HTML 仕様は "a@b" を許すが、検証規則には実ドメインが要る)。
+ */
+const EMAIL_GRAMMAR = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/
+
+/** A normalised exact decimal: sign (0 = zero), significant digits without leading / trailing zeros, and the decimal-point position relative to the digit string. / 正規化した正確 10 進。符号 (0 = ゼロ)、先頭 / 末尾ゼロを除いた有効数字、数字列に対する小数点位置。 */
+type Decimal = { sign: -1 | 0 | 1; digits: string; point: number }
+
+/** A wall-clock date-time parsed by pure calendar math (never a Date object). / 純暦計算で解釈した壁時計日時 (Date 非経由)。 */
+type ParsedDate = { year: number; month: number; day: number; hour: number; minute: number; second: number }
+
+/** Three-way comparison result. / 三値比較の結果。 */
+type Ordering = -1 | 0 | 1
+
+/** Resolved bounds of an ordered rule; `b` is null when the op does not use it. / 順序規則の解決済み境界。op が使わないとき b は null。 */
+type Bounds<T> = { a: T; b: T | null }
+
+/** Rule-family wording for the four ordered ops (the other four are shared). / 順序 4 op の規則族別の言い回し (残る 4 つは共通)。 */
+type OrderWords = { readonly gt: string; readonly gte: string; readonly lt: string; readonly lte: string }
+
+/** Wording for number / textLength messages. / number / textLength メッセージの言い回し。 */
+const NUMERIC_WORDS: OrderWords = { gt: "greater than", gte: "greater than or equal to", lt: "less than", lte: "less than or equal to" }
+
+/** Wording for date messages. / date メッセージの言い回し。 */
+const DATE_WORDS: OrderWords = { gt: "after", gte: "on or after", lt: "before", lte: "on or before" }
+
+/**
+ * Parses a strict decimal string into its exact normalised form: trims, applies the
+ * cellFormat.ts grammar (hex / grouping / empty rejected, exponent overflow to ±Infinity
+ * rejected), then folds the mantissa and exponent into sign / significant digits / point
+ * position with NO floating-point arithmetic. Null when the text is not a strict decimal.
+ * 厳密 10 進文字列を正確な正規形へ解析。trim → cellFormat.ts の文法 (16 進 / 区切り / 空 / 指数溢れは
+ * 拒否) → 仮数と指数を浮動小数無しで符号 / 有効数字 / 小数点位置へ畳む。非 10 進は null。
+ */
+const parseDecimal = (text: string): Decimal | null => {
+    const t = text.trim()
+    // cellFormat.ts の parseNumber と同じ受理集合: 文法外と指数溢れ (1e999 → ±Infinity) は非数値
+    if (!(DECIMAL_GRAMMAR.test(t) && Number.isFinite(Number(t)))) {
+        return null
+    }
+    const negative = t.startsWith("-")
+    const unsigned = t.replace(/^[+-]/, "")
+    // 仮数と指数を分離 (指数は文法で 4 桁以内 — Number 変換は安全)
+    const exponentAt = unsigned.search(/[eE]/)
+    const mantissa = exponentAt < 0 ? unsigned : unsigned.slice(0, exponentAt)
+    const exponent = exponentAt < 0 ? 0 : Number(unsigned.slice(exponentAt + 1))
+    // 小数点を外して数字列にし、小数点位置 = 整数部の桁数 + 指数
+    const dot = mantissa.indexOf(".")
+    const integerPart = dot < 0 ? mantissa : mantissa.slice(0, dot)
+    const fractionPart = dot < 0 ? "" : mantissa.slice(dot + 1)
+    const raw = integerPart + fractionPart
+    // 先頭ゼロを落とす (落とした桁数だけ小数点位置を左へ)。全桁ゼロなら符号無しのゼロ
+    const lead = raw.search(/[^0]/)
+    if (lead < 0) {
+        return { sign: 0, digits: "", point: 0 }
+    }
+    // 末尾ゼロは小数点位置を変えずに落とす
+    return { sign: negative ? -1 : 1, digits: raw.slice(lead).replace(/0+$/, ""), point: integerPart.length + exponent - lead }
+}
+
+/** Flips an ordering (used to compare negatives by magnitude). / 順序の反転 (負数を絶対値で比べるため)。 */
+const flip = (ordering: Ordering): Ordering => (ordering === 1 ? -1 : ordering === -1 ? 1 : 0)
+
+/**
+ * Compares two normalised decimals exactly: by sign, then (same non-zero sign) by point
+ * position, then by the significant-digit strings — both are free of trailing zeros, so a
+ * lexicographic comparison is the numeric one (a proper prefix is the smaller magnitude).
+ * 正規化 10 進の正確比較。符号 → (同符号・非ゼロ) 小数点位置 → 有効数字列。両者とも末尾ゼロが無いため
+ * 辞書順比較がそのまま数値比較 (真の接頭辞は小さい方)。
+ */
+const compareDecimals = (x: Decimal, y: Decimal): Ordering => {
+    if (x.sign !== y.sign) {
+        return x.sign < y.sign ? -1 : 1
+    }
+    if (x.sign === 0) {
+        return 0
+    }
+    // 絶対値の比較: 位取り (小数点位置) が違えばそれで決まり、同じなら有効数字の辞書順
+    const magnitude: Ordering = x.point !== y.point ? (x.point < y.point ? -1 : 1) : x.digits === y.digits ? 0 : x.digits < y.digits ? -1 : 1
+    return x.sign === 1 ? magnitude : flip(magnitude)
+}
+
+/** Days in a month with proleptic-Gregorian leap rules (÷4, except ÷100 unless ÷400). / 月の日数 (グレゴリオ暦の閏年規則)。 */
+const monthDays = (year: number, month: number): number => {
+    switch (month) {
+        case 2:
+            return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28
+        case 4:
+        case 6:
+        case 9:
+        case 11:
+            return 30
+        default:
+            return 31
+    }
+}
+
+/**
+ * Parses "YYYY-MM-DD[ T HH:mm[:ss]]" (or "/" separated — the SAME separator on both sides)
+ * with pure integer range validation (month 1-12, leap-aware day, hour<24 / minute<60 /
+ * second<60) — identical to cellFormat.ts parseDate. Null on any violation or trailing garbage.
+ * 両側同一区切り・純整数の範囲検証 (月 1-12・閏年対応の日・時<24 / 分<60 / 秒<60) の日付解析 —
+ * cellFormat.ts の parseDate と同一。違反・末尾ゴミは null。
+ */
+const parseDate = (text: string): ParsedDate | null => {
+    const m = DATE_GRAMMAR.exec(text.trim())
+    if (m === null) {
+        return null
+    }
+    const year = Number(m[1])
+    const month = Number(m[3])
+    const day = Number(m[4])
+    const hour = m[5] === undefined ? 0 : Number(m[5])
+    const minute = m[6] === undefined ? 0 : Number(m[6])
+    const second = m[7] === undefined ? 0 : Number(m[7])
+    // 純整数の暦検証 — 範囲外は無効日として null (黙ったロールオーバー変換を作らない)
+    if (month < 1 || month > 12 || day < 1 || day > monthDays(year, month) || hour > 23 || minute > 59 || second > 59) {
+        return null
+    }
+    return { year, month, day, hour, minute, second }
+}
+
+/** Compares two parsed dates as (year, month, day, hour, minute, second) tuples. / 解析済み日付を (年, 月, 日, 時, 分, 秒) のタプルとして比較。 */
+const compareDates = (x: ParsedDate, y: ParsedDate): Ordering => {
+    const xs = [x.year, x.month, x.day, x.hour, x.minute, x.second]
+    const ys = [y.year, y.month, y.day, y.hour, y.minute, y.second]
+    // 上位成分から順に最初に異なる成分で決まる
+    for (let i = 0; i < xs.length; i += 1) {
+        if (xs[i] !== ys[i]) {
+            return xs[i] < ys[i] ? -1 : 1
+        }
+    }
+    return 0
+}
+
+/** Compares two finite numbers (textLength). / 有限数の比較 (textLength)。 */
+const compareNumbers = (x: number, y: number): Ordering => (x < y ? -1 : x > y ? 1 : 0)
+
+/** Whether the op consumes the second bound. / op が第 2 境界を使うかどうか。 */
+const usesB = (op: ValidationCompareOp): boolean => op === "between" || op === "notBetween"
+
+/**
+ * Resolves the bounds of an ordered rule through `parse`; null (= inert rule) when `a` does not
+ * parse, or when the op needs `b` and `b` is missing or does not parse. `b` is ignored for the
+ * six single-bound ops, so garbage there never disables the rule.
+ * 順序規則の境界を parse で解決。a が解釈不能、または op が b を要するのに b が欠落 / 解釈不能なら
+ * null (= 不活性)。単一境界の 6 op では b を見ない (ゴミがあっても規則を止めない)。
+ */
+const resolveBounds = <T, R>(op: ValidationCompareOp, a: R, b: R | undefined, parse: (raw: R) => T | null): Bounds<T> | null => {
+    const parsedA = parse(a)
+    if (parsedA === null) {
+        return null
+    }
+    if (!usesB(op)) {
+        return { a: parsedA, b: null }
+    }
+    // between 系は b 必須 — 欠落 / 解釈不能は不活性
+    const parsedB = b === undefined ? null : parse(b)
+    return parsedB === null ? null : { a: parsedA, b: parsedB }
+}
+
+/** Evaluates an ordered op from the value's ordering against `a` (and `b` for between / notBetween, inclusive). / 値と a (between 系は b も、両端含み) の順序から op を評価。 */
+const orderedHolds = (op: ValidationCompareOp, toA: Ordering, toB: Ordering): boolean => {
+    switch (op) {
+        case "gt":
+            return toA === 1
+        case "gte":
+            return toA !== -1
+        case "lt":
+            return toA === -1
+        case "lte":
+            return toA !== 1
+        case "eq":
+            return toA === 0
+        case "neq":
+            return toA !== 0
+        case "between":
+            return toA !== -1 && toB !== 1
+        default:
+            // notBetween (語彙外の op は assertRuleShape が先に拒否済み)
+            return toA === -1 || toB === 1
+    }
+}
+
+/**
+ * Generic ordered check: resolves the bounds (inert ⇒ true), parses the value (unparseable ⇒
+ * false), then compares. Shared by number / textLength / date through their own parser and
+ * comparator.
+ * 順序規則の共通判定: 境界解決 (不活性 ⇒ true) → 値解析 (解釈不能 ⇒ false) → 比較。number /
+ * textLength / date がそれぞれの parser と comparator で共有。
+ */
+const orderedRuleHolds = <T, R>(op: ValidationCompareOp, a: R, b: R | undefined, parse: (raw: R) => T | null, value: T | null, compare: (x: T, y: T) => Ordering): boolean => {
+    const bounds = resolveBounds(op, a, b, parse)
+    if (bounds === null) {
+        return true
+    }
+    if (value === null) {
+        return false
+    }
+    // b を使わない op では toB は参照されない (0 を置く — 分岐のためではなく引数の型合わせ)
+    return orderedHolds(op, compare(value, bounds.a), bounds.b === null ? 0 : compare(value, bounds.b))
+}
+
+/** A finite number parses to itself; NaN / ±Infinity do not parse (inert bound). / 有限数はそのまま、NaN / ±Infinity は解釈不能 (不活性境界)。 */
+const parseFiniteNumber = (value: number): number | null => (Number.isFinite(value) ? value : null)
+
+/** Counts Unicode code points (a surrogate pair is one character). / コードポイント数 (サロゲートペアは 1 文字)。 */
+const codePointLength = (text: string): number => {
+    let count = 0
+    // 文字列イテレータはコードポイント単位で進む
+    for (const _ of text) {
+        count += 1
+    }
+    return count
+}
+
+/** WHATWG-parsable absolute URL whose scheme is http or https. / WHATWG で解析できる http / https スキームの絶対 URL。 */
+const isHttpUrl = (text: string): boolean => URL.canParse(text) && /^https?:$/.test(new URL(text).protocol)
+
+/** Evaluates a text rule; needle ops without a `value` are inert (true). / text 規則の評価。value の無い needle 系 op は不活性 (true)。 */
+const textRuleHolds = (rule: TextValidationRule, text: string): boolean => {
+    switch (rule.op) {
+        case "isEmail":
+            return EMAIL_GRAMMAR.test(text)
+        case "isUrl":
+            return isHttpUrl(text)
+        default:
+            break
+    }
+    if (rule.value === undefined) {
+        return true
+    }
+    // needle 系 4 op: 完全一致 (大文字小文字区別・trim 無し)。空 needle は文字通り (contains "" は常に真)
+    switch (rule.op) {
+        case "contains":
+            return text.includes(rule.value)
+        case "notContains":
+            return !text.includes(rule.value)
+        case "startsWith":
+            return text.startsWith(rule.value)
+        default:
+            // 残る needle op は endsWith
+            return text.endsWith(rule.value)
+    }
+}
+
+/** The custom-formula truth convention: `true` or a finite non-zero number (conditionalFormat parity). / custom 数式の真偽規約: true か有限非 0 数 (conditionalFormat と同じ)。 */
+const isTruthyResult = (result: string | number | boolean | null): boolean => result === true || (typeof result === "number" && Number.isFinite(result) && result !== 0)
+
+/** Effective checkbox strings (declared defaults "TRUE" / "FALSE"). / checkbox の実効文字列 (宣言済み既定 "TRUE" / "FALSE")。 */
+const checkboxStrings = (rule: CheckboxValidationRule): { checked: string; unchecked: string } => ({
+    checked: rule.checked === undefined ? CHECKBOX_CHECKED_DEFAULT : rule.checked,
+    unchecked: rule.unchecked === undefined ? CHECKBOX_UNCHECKED_DEFAULT : rule.unchecked,
+})
+
+/**
+ * Rejects a rule outside the vocabulary (unknown `type`, or an unknown `op` on number /
+ * textLength / date / text) with RangeError — a consumer bug surfaces regardless of the text.
+ * 語彙外の規則 (未知 type、number / textLength / date / text の未知 op) を RangeError で拒否 —
+ * consumer バグは text に依らず表面化。
+ */
+const assertRuleShape = (rule: DataValidationRule): void => {
+    switch (rule.type) {
+        case "list":
+        case "checkbox":
+        case "custom":
+            return
+        case "number":
+        case "textLength":
+        case "date":
+            if (!COMPARE_OPS.has(rule.op)) {
+                throw new RangeError(`[spreadsheet] unknown data-validation op "${String(rule.op)}" for type "${rule.type}"`)
+            }
+            return
+        case "text":
+            if (!TEXT_OPS.has(rule.op)) {
+                throw new RangeError(`[spreadsheet] unknown data-validation op "${String(rule.op)}" for type "text"`)
+            }
+            return
+        default:
+            throw new RangeError(`[spreadsheet] unknown data-validation rule type "${String((rule as { type: unknown }).type)}"`)
+    }
+}
+
+/**
+ * Whether a NON-BLANK text satisfies a shape-checked rule (`custom` without `evaluate` is not
+ * evaluated ⇒ true).
+ * 形を検査済みの規則を非空 text が満たすか (evaluate 無しの custom は未評価 ⇒ true)。
+ */
+const ruleHolds = (rule: DataValidationRule, text: string, evaluate: ValidationEvaluate | undefined): boolean => {
+    switch (rule.type) {
+        case "list":
+            return listValuesOf(rule).has(text)
+        case "number":
+            return orderedRuleHolds(rule.op, rule.a, rule.b, parseDecimal, parseDecimal(text), compareDecimals)
+        case "textLength":
+            return orderedRuleHolds(rule.op, rule.a, rule.b, parseFiniteNumber, codePointLength(text), compareNumbers)
+        case "date":
+            return orderedRuleHolds(rule.op, rule.a, rule.b, parseDate, parseDate(text), compareDates)
+        case "text":
+            return textRuleHolds(rule, text)
+        case "checkbox": {
+            const strings = checkboxStrings(rule)
+            return text === strings.checked || text === strings.unchecked
+        }
+        default:
+            // custom — 評価器が無ければ評価しない (描画時に数式を走らせない構造的保証)
+            return evaluate === undefined || isTruthyResult(evaluate(rule.formula))
+    }
+}
+
+/** Whether the text is accepted: shape check (fail-fast), blank (always), else the rule. / text を受理するか: 形の検査 (fail-fast) → 空文字 (常に) → 規則。 */
+const accepts = (rule: DataValidationRule, text: string, evaluate: ValidationEvaluate | undefined): boolean => {
+    assertRuleShape(rule)
+    return text === "" || ruleHolds(rule, text, evaluate)
+}
+
+/** Phrase for an ordered op with the family wording: "greater than 5", "between 1 and 9", ... / 順序 op の言い回し (規則族の語彙付き)。 */
+const comparePhrase = (op: ValidationCompareOp, a: string, b: string | undefined, words: OrderWords): string => {
+    switch (op) {
+        case "gt":
+        case "gte":
+        case "lt":
+        case "lte":
+            return `${words[op]} ${a}`
+        case "eq":
+            return `equal to ${a}`
+        case "neq":
+            return `not equal to ${a}`
+        case "between":
+            return `between ${a} and ${b}`
+        default:
+            // 残る順序 op は notBetween
+            return `not between ${a} and ${b}`
+    }
+}
+
+/** Trims an optional bound string for display. / 表示用に任意の境界文字列を trim。 */
+const trimBound = (bound: string | undefined): string | undefined => (bound === undefined ? undefined : bound.trim())
+
+/** Built-in English summary of a rule, used when the consumer set no `errorMessage`. / consumer が errorMessage を置かないときの組込み英語要約。 */
+const defaultMessage = (rule: DataValidationRule): string => {
+    switch (rule.type) {
+        case "list":
+            return "Value must be one of the list items."
+        case "number":
+            return `Value must be a number ${comparePhrase(rule.op, rule.a.trim(), trimBound(rule.b), NUMERIC_WORDS)}.`
+        case "textLength":
+            return `Text length must be ${comparePhrase(rule.op, String(rule.a), rule.b === undefined ? undefined : String(rule.b), NUMERIC_WORDS)}.`
+        case "date":
+            return `Value must be a date ${comparePhrase(rule.op, rule.a.trim(), trimBound(rule.b), DATE_WORDS)}.`
+        case "text":
+            return textMessage(rule)
+        case "checkbox": {
+            const strings = checkboxStrings(rule)
+            return `Value must be "${strings.checked}" or "${strings.unchecked}".`
+        }
+        default:
+            // 残る規則種別は custom
+            return `Value does not satisfy the formula ${rule.formula}.`
+    }
+}
+
+/** Built-in summary of a text rule. / text 規則の組込み要約。 */
+const textMessage = (rule: TextValidationRule): string => {
+    switch (rule.op) {
+        case "contains":
+            return `Value must contain "${rule.value}".`
+        case "notContains":
+            return `Value must not contain "${rule.value}".`
+        case "startsWith":
+            return `Value must start with "${rule.value}".`
+        case "endsWith":
+            return `Value must end with "${rule.value}".`
+        case "isEmail":
+            return "Value must be a valid email address."
+        default:
+            // 残る text op は isUrl
+            return "Value must be a valid URL."
+    }
+}
+
+/** Interned list Sets keyed by rule object identity. / 規則 object の identity をキーにした list Set の intern。 */
+const listSets = new WeakMap<ListValidationRule, ReadonlySet<string>>()
+
+/**
+ * The interned Set of a list rule's values (one Set per rule OBJECT — the paint-time `list`
+ * check is O(1) for a 10k-item list; a fresh rule object interns a fresh Set).
+ * list 規則の値の intern 済み Set (規則 object 毎に 1 つ — 1 万項目の list でも描画時判定は O(1)。
+ * 新しい規則 object は新しい Set)。
+ */
+export const listValuesOf = (rule: ListValidationRule): ReadonlySet<string> => {
+    const cached = listSets.get(rule)
+    if (cached !== undefined) {
+        return cached
+    }
+    // 初回だけ構築して intern
+    const set: ReadonlySet<string> = new Set(rule.values)
+    listSets.set(rule, set)
+    return set
+}
+
+/**
+ * Validates committed text against a rule. Blank always passes; `custom` is evaluated only when
+ * the caller passes `evaluate` (commit time — paint omits it); an incomplete rule (unparseable
+ * bound, missing `b` / `value`) is inert; a rule outside the vocabulary throws RangeError.
+ * Message = `rule.errorMessage` when set, else a built-in English summary of the rule.
+ * 確定テキストの規則検証。空文字は常に合格、custom は呼び手が evaluate を渡すとき (確定時 — 描画は
+ * 渡さない) だけ評価、不完全な規則 (解釈不能な境界・b / value 欠落) は不活性、語彙外の規則は
+ * RangeError。メッセージは errorMessage があればそれ、無ければ組込みの英語要約。
+ */
+export const validateCellText = (rule: DataValidationRule, text: string, evaluate?: ValidationEvaluate): ValidationVerdict => {
+    if (accepts(rule, text, evaluate)) {
+        return VALID
+    }
+    // errorMessage は「置かれているか」だけを見る (空文字も consumer の意思として尊重)
+    return { ok: false, message: rule.errorMessage === undefined ? defaultMessage(rule) : rule.errorMessage }
+}
+
+/** Whether a rule can be judged at paint time without a formula evaluator (every type but `custom`). / 数式評価器なしに描画時判定できる規則か (custom 以外の全型)。 */
+export const isValidatedAtPaint = (rule: DataValidationRule): boolean => rule.type !== "custom"
+
+/**
+ * Paint-time indicator predicate: true when a paint-time rule rejects the text. `custom` is
+ * never evaluated here (structurally — no evaluator exists on this path), so it is never
+ * visibly invalid.
+ * 描画用の不正判定: 描画時規則が text を拒否するとき true。custom はこの経路に評価器が存在しないため
+ * 構造的に評価されず、決して不正表示されない。
+ */
+export const isVisiblyInvalid = (rule: DataValidationRule, text: string): boolean => isValidatedAtPaint(rule) && !accepts(rule, text, undefined)