@wrongstack/primitives 0.317.2 → 0.319.0

package/dist/index.js

@@ -1,3 +1,536 @@
+// src/regex-ambiguity.ts
+var MAX_CP = 1114111;
+function complementOf(set) {
+  const out = [];
+  let next = 0;
+  for (const [lo, hi] of set) {
+    if (lo > next) out.push([next, lo - 1]);
+    next = hi + 1;
+  }
+  if (next <= MAX_CP) out.push([next, MAX_CP]);
+  return out;
+}
+function intersect(a, b) {
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    const lo = Math.max(a[i][0], b[j][0]);
+    const hi = Math.min(a[i][1], b[j][1]);
+    if (lo <= hi) out.push([lo, hi]);
+    if (a[i][1] < b[j][1]) i++;
+    else j++;
+  }
+  return out;
+}
+function anyMember(set) {
+  return set[0][0];
+}
+var WORD = [
+  [48, 57],
+  [65, 90],
+  [95, 95],
+  [97, 122]
+];
+var DIGIT = [[48, 57]];
+var SPACE = [
+  [9, 13],
+  [32, 32]
+];
+var NAMED_SETS = {
+  w: WORD,
+  W: complementOf(WORD),
+  d: DIGIT,
+  D: complementOf(DIGIT),
+  s: SPACE,
+  S: complementOf(SPACE)
+};
+var DOT = [
+  [0, 9],
+  [11, MAX_CP]
+];
+var CHECKER_BUDGET = 6e4;
+var Budget = class {
+  left = CHECKER_BUDGET;
+  spend(n = 1) {
+    this.left -= n;
+    return this.left >= 0;
+  }
+  get exhausted() {
+    return this.left < 0;
+  }
+};
+var MAX_COPIES = 64;
+var Cursor = class {
+  constructor(s) {
+    this.s = s;
+  }
+  s;
+  i = 0;
+  peek() {
+    return this.s[this.i];
+  }
+  eat(ch) {
+    if (this.s[this.i] === ch) {
+      this.i++;
+      return true;
+    }
+    return false;
+  }
+};
+function parseAlt(c, budget) {
+  const first = parseSeq(c, budget);
+  if (first === null) return null;
+  const parts = [first];
+  while (c.eat("|")) {
+    const p = parseSeq(c, budget);
+    if (p === null) return null;
+    parts.push(p);
+  }
+  return parts.length === 1 ? parts[0] : { k: "alt", parts };
+}
+function parseSeq(c, budget) {
+  const parts = [];
+  for (; ; ) {
+    const ch = c.peek();
+    if (ch === void 0 || ch === "|" || ch === ")") break;
+    if (!budget.spend()) return null;
+    let atom;
+    if (ch === "(") {
+      c.i++;
+      if (c.s[c.i] === "?") {
+        const n = c.s[c.i + 1];
+        if (n === ":") {
+          c.i += 2;
+        } else if (n === "<" && /[A-Za-z_$]/.test(c.s[c.i + 2] ?? "")) {
+          const close = c.s.indexOf(">", c.i + 2);
+          if (close === -1) return null;
+          c.i = close + 1;
+        } else {
+          return null;
+        }
+      }
+      const node = parseAlt(c, budget);
+      if (node === null || !c.eat(")")) return null;
+      atom = node;
+    } else if (ch === "[") {
+      const set = parseClass(c);
+      if (set === null) return null;
+      atom = { k: "cls", set };
+    } else if (ch === "\\") {
+      const t = parseEscape(c);
+      if (t === null) return null;
+      atom = { k: "cls", set: t };
+    } else if (ch === ".") {
+      c.i++;
+      atom = { k: "cls", set: DOT };
+    } else if (ch === "^" || ch === "$" || ch === "{" || ch === "*" || ch === "+" || ch === "?") {
+      return null;
+    } else {
+      const cp = ch.codePointAt(0);
+      c.i++;
+      atom = { k: "cls", set: [[cp, cp]] };
+    }
+    const q = c.peek();
+    if (q === "*") {
+      c.i++;
+      atom = { k: "rep", node: atom, min: 0, max: Number.POSITIVE_INFINITY };
+    } else if (q === "+") {
+      c.i++;
+      atom = { k: "rep", node: atom, min: 1, max: Number.POSITIVE_INFINITY };
+    } else if (q === "?") {
+      c.i++;
+      atom = { k: "rep", node: atom, min: 0, max: 1 };
+    } else if (q === "{") {
+      const close = c.s.indexOf("}", c.i);
+      if (close === -1) return null;
+      const m = /^(\d+)(,(\d*)?)?$/.exec(c.s.slice(c.i + 1, close));
+      if (!m) return null;
+      const min = Number.parseInt(m[1], 10);
+      const max = m[2] === void 0 ? min : m[3] === "" ? Number.POSITIVE_INFINITY : Number.parseInt(m[3], 10);
+      if (max < min || min > MAX_COPIES || max > MAX_COPIES) return null;
+      c.i = close + 1;
+      atom = { k: "rep", node: atom, min, max };
+    }
+    parts.push(atom);
+  }
+  return parts.length === 0 ? { k: "seq", parts: [] } : parts.length === 1 ? parts[0] : { k: "seq", parts };
+}
+function parseClass(c) {
+  const s = c.s;
+  let i = c.i + 1;
+  let negated = false;
+  if (s[i] === "^") {
+    negated = true;
+    i++;
+  }
+  const ranges = [];
+  let first = true;
+  while (i < s.length && (s[i] !== "]" || first)) {
+    first = false;
+    let lo;
+    if (s[i] === "\\") {
+      const t = escapeAt(s, i);
+      if (t === null) return null;
+      if (typeof t !== "number") {
+        ranges.push(...NAMED_SETS[t]);
+        i += 2;
+        continue;
+      }
+      lo = t;
+      i += escapeWidth(s, i);
+    } else {
+      lo = s[i].codePointAt(0);
+      i++;
+    }
+    if (s[i] === "-" && s[i + 1] !== "]" && s[i + 1] !== void 0) {
+      i++;
+      let hi;
+      if (s[i] === "\\") {
+        const t = escapeAt(s, i);
+        if (t === null || typeof t !== "number") return null;
+        hi = t;
+        i += escapeWidth(s, i);
+      } else {
+        hi = s[i].codePointAt(0);
+        i++;
+      }
+      if (hi < lo) return null;
+      ranges.push([lo, hi]);
+    } else {
+      ranges.push([lo, lo]);
+    }
+  }
+  if (s[i] !== "]") return null;
+  c.i = i + 1;
+  if (ranges.length === 0) return null;
+  ranges.sort((a, b) => a[0] - b[0]);
+  const merged = [ranges[0]];
+  for (let k = 1; k < ranges.length; k++) {
+    const last = merged[merged.length - 1];
+    if (ranges[k][0] <= last[1] + 1) last[1] = Math.max(last[1], ranges[k][1]);
+    else merged.push(ranges[k]);
+  }
+  return negated ? complementOf(merged) : merged;
+}
+function escapeWidth(s, i) {
+  const ch = s[i + 1];
+  if (ch === "x") return 4;
+  if (ch === "u") return s[i + 2] === "{" ? s.indexOf("}", i + 3) - i + 1 : 6;
+  return 2;
+}
+function escapeAt(s, i) {
+  const ch = s[i + 1];
+  if (ch === void 0) return null;
+  if (NAMED_SETS[ch] !== void 0) return ch;
+  const simple = { n: 10, r: 13, t: 9, f: 12, v: 11, 0: 0 };
+  if (simple[ch] !== void 0) return simple[ch];
+  if (ch === "x") {
+    const cp = Number.parseInt(s.slice(i + 2, i + 4), 16);
+    return Number.isFinite(cp) ? cp : null;
+  }
+  if (ch === "u") {
+    if (s[i + 2] === "{") {
+      const close = s.indexOf("}", i + 3);
+      if (close === -1) return null;
+      const cp2 = Number.parseInt(s.slice(i + 3, close), 16);
+      return Number.isFinite(cp2) && cp2 <= MAX_CP ? cp2 : null;
+    }
+    const cp = Number.parseInt(s.slice(i + 2, i + 6), 16);
+    return Number.isFinite(cp) ? cp : null;
+  }
+  if (/[A-Za-z0-9]/.test(ch)) return null;
+  return ch.codePointAt(0);
+}
+function parseEscape(c) {
+  const t = escapeAt(c.s, c.i);
+  if (t === null) return null;
+  const w = escapeWidth(c.s, c.i);
+  c.i += w;
+  return typeof t === "number" ? [[t, t]] : NAMED_SETS[t];
+}
+var MAX_NFA_STATES = 600;
+var Nfa = class {
+  edges = [];
+  start = -1;
+  accept = -1;
+  newState() {
+    this.edges.push([]);
+    return this.edges.length - 1;
+  }
+  add(from, to, set) {
+    this.edges[from].push({ to, set });
+  }
+  chain(f1, f2) {
+    this.add(f1.accept, f2.start, null);
+    return { start: f1.start, accept: f2.accept };
+  }
+  opt(f) {
+    const s = this.newState();
+    const a = this.newState();
+    this.add(s, f.start, null);
+    this.add(f.accept, a, null);
+    this.add(s, a, null);
+    return { start: s, accept: a };
+  }
+  star(node, budget) {
+    const inner = this.build(node, budget);
+    if (inner === null) return null;
+    const s = this.newState();
+    const a = this.newState();
+    this.add(s, inner.start, null);
+    this.add(s, a, null);
+    this.add(inner.accept, inner.start, null);
+    this.add(inner.accept, a, null);
+    return { start: s, accept: a };
+  }
+  build(node, budget) {
+    if (this.edges.length > MAX_NFA_STATES || !budget.spend()) return null;
+    if (node.k === "cls") {
+      const s = this.newState();
+      const a = this.newState();
+      this.add(s, a, node.set);
+      return { start: s, accept: a };
+    }
+    if (node.k === "seq") {
+      if (node.parts.length === 0) {
+        const s = this.newState();
+        return { start: s, accept: s };
+      }
+      let frag2 = null;
+      for (const p of node.parts) {
+        const f = this.build(p, budget);
+        if (f === null) return null;
+        frag2 = frag2 === null ? f : this.chain(frag2, f);
+      }
+      return frag2;
+    }
+    if (node.k === "alt") {
+      const s = this.newState();
+      const a = this.newState();
+      for (const p of node.parts) {
+        const f = this.build(p, budget);
+        if (f === null) return null;
+        this.add(s, f.start, null);
+        this.add(f.accept, a, null);
+      }
+      return { start: s, accept: a };
+    }
+    if (node.max === Number.POSITIVE_INFINITY) {
+      if (node.min === 0) return this.star(node.node, budget);
+      let frag2 = null;
+      for (let i = 0; i < Math.min(node.min, MAX_COPIES); i++) {
+        const copy = this.build(node.node, budget);
+        if (copy === null) return null;
+        frag2 = frag2 === null ? copy : this.chain(frag2, copy);
+      }
+      const tail = this.star(node.node, budget);
+      if (tail === null || frag2 === null) return null;
+      return this.chain(frag2, tail);
+    }
+    let frag = null;
+    for (let i = 0; i < node.max; i++) {
+      let copy = this.build(node.node, budget);
+      if (copy === null) return null;
+      if (i >= node.min) copy = this.opt(copy);
+      frag = frag === null ? copy : this.chain(frag, copy);
+    }
+    if (frag === null) {
+      const s = this.newState();
+      return { start: s, accept: s };
+    }
+    return frag;
+  }
+};
+function epsilonClosure(nfa, from) {
+  const out = new Set(from);
+  const stack = [...from];
+  while (stack.length > 0) {
+    const p = stack.pop();
+    for (const e of nfa.edges[p]) {
+      if (e.set === null && !out.has(e.to)) {
+        out.add(e.to);
+        stack.push(e.to);
+      }
+    }
+  }
+  return out;
+}
+function parseAmbiguity(nfa, startSources, acceptReachable, budget) {
+  const n = nfa.edges.length;
+  const key = (p, q) => p * n + q;
+  const seen = /* @__PURE__ */ new Map();
+  const completions = /* @__PURE__ */ new Map();
+  let head = 0;
+  const queue = [];
+  for (const p of startSources) {
+    for (const q of startSources) {
+      const k = key(p, q);
+      if (!seen.has(k)) {
+        seen.set(k, null);
+        queue.push({ p, q, diverged: p !== q });
+      }
+    }
+  }
+  while (head < queue.length) {
+    if (!budget.spend(4)) return { ambiguous: false };
+    const { p, q, diverged } = queue[head++];
+    const k = key(p, q);
+    const nextSources = (target) => [...epsilonClosure(nfa, [target])].filter((s) => nfa.edges[s].some((e) => e.set !== null));
+    for (const e1 of nfa.edges[p]) {
+      if (e1.set === null) continue;
+      for (const e2 of nfa.edges[q]) {
+        if (e2.set === null) continue;
+        const both = intersect(e1.set, e2.set);
+        if (both.length === 0) continue;
+        if (diverged && acceptReachable.has(e1.to) && acceptReachable.has(e2.to) && !completions.has(k)) {
+          completions.set(k, String.fromCodePoint(anyMember(both)));
+        }
+        const from1 = nextSources(e1.to);
+        const from2 = nextSources(e2.to);
+        const stepChar = String.fromCodePoint(anyMember(both));
+        for (const p2 of from1) {
+          for (const q2 of from2) {
+            const k2 = key(p2, q2);
+            if (!seen.has(k2)) {
+              const childDiverged = diverged || p2 !== q2;
+              seen.set(k2, [k, stepChar, childDiverged]);
+              queue.push({ p: p2, q: q2, diverged: childDiverged });
+            }
+          }
+        }
+      }
+    }
+  }
+  if (completions.size === 0) return { ambiguous: false };
+  const [doneKey, doneChar] = completions.entries().next().value;
+  let witness = doneChar;
+  let cur = seen.get(doneKey);
+  while (cur !== null && cur !== void 0) {
+    witness = cur[1] + witness;
+    cur = seen.get(cur[0]);
+  }
+  return { ambiguous: true, witness };
+}
+var WORD_MAX = 6;
+var MAX_WORDS = 120;
+function decompositionAmbiguity(nfa, startClosure, acceptClosureOf, budget) {
+  if (startClosure.has(nfa.accept)) {
+    return { ambiguous: true, witness: "\u03B5 (empty iterations insertable)" };
+  }
+  const labels = [];
+  for (const edges of nfa.edges) {
+    for (const e of edges) {
+      if (e.set !== null && !labels.some((l) => l === e.set)) labels.push(e.set);
+    }
+  }
+  const repsSet = /* @__PURE__ */ new Set();
+  for (let i = 0; i < labels.length; i++) {
+    repsSet.add(anyMember(labels[i]));
+    for (let j = i + 1; j < labels.length; j++) {
+      const ov = intersect(labels[i], labels[j]);
+      if (ov.length > 0) repsSet.add(anyMember(ov));
+    }
+  }
+  const reps = [...repsSet].slice(0, 8);
+  if (reps.length === 0) return { ambiguous: false };
+  const step = (config, ch) => {
+    const next = /* @__PURE__ */ new Set();
+    for (const p of config) {
+      for (const e of nfa.edges[p]) {
+        if (e.set?.some(([lo, hi]) => ch >= lo && ch <= hi)) {
+          for (const s of epsilonClosure(nfa, [e.to])) next.add(s);
+        }
+      }
+    }
+    return next;
+  };
+  const words = [];
+  let level = [
+    { config: new Set(startClosure), s: "" }
+  ];
+  for (let len = 1; len <= WORD_MAX && level.length > 0 && words.length < MAX_WORDS; len++) {
+    if (!budget.spend(level.length * reps.length)) return { ambiguous: false };
+    const nextLevel = [];
+    for (const { config, s } of level) {
+      for (const rep of reps) {
+        const next = step(config, rep);
+        if (next.size === 0) continue;
+        const ns = s + String.fromCodePoint(rep);
+        if ([...next].some((p) => acceptClosureOf.has(p))) words.push(ns);
+        nextLevel.push({ config: next, s: ns });
+      }
+    }
+    level = nextLevel;
+  }
+  if (words.length === 0) return { ambiguous: false };
+  const wordSet = new Set(words);
+  const residualsOf = (sources) => {
+    const out = /* @__PURE__ */ new Set();
+    for (const u of sources) {
+      for (const x of words) {
+        if (x.length > u.length && x.startsWith(u)) out.add(x.slice(u.length));
+      }
+    }
+    return out;
+  };
+  const leftDiv = (src) => {
+    const out = /* @__PURE__ */ new Set();
+    for (const l of words) {
+      for (const t of src) {
+        if (t.length > l.length && t.startsWith(l)) out.add(t.slice(l.length));
+      }
+    }
+    return out;
+  };
+  let frontier = residualsOf(words);
+  const visited = /* @__PURE__ */ new Set();
+  while (frontier.size > 0) {
+    if (!budget.spend(words.length)) return { ambiguous: false };
+    const frozen = [...frontier].sort().join("
");
+    if (visited.has(frozen)) break;
+    visited.add(frozen);
+    for (const v of frontier) {
+      if (v === "" || wordSet.has(v)) {
+        return { ambiguous: true, witness: `Sardinas\u2013Patterson residual '${v || "\u03B5"}'` };
+      }
+    }
+    const next = residualsOf(frontier);
+    for (const v of leftDiv(frontier)) next.add(v);
+    frontier = next;
+  }
+  return { ambiguous: false };
+}
+function detectQuantifiedAmbiguity(content) {
+  const budget = new Budget();
+  const cursor = new Cursor(content);
+  const ast = parseAlt(cursor, budget);
+  if (ast === null || cursor.i !== content.length) return { verdict: "unparsable" };
+  const nfa = new Nfa();
+  const frag = nfa.build(ast, budget);
+  if (frag === null) return { verdict: budget.exhausted ? "budget" : "unparsable" };
+  nfa.start = frag.start;
+  nfa.accept = frag.accept;
+  const startClosure = epsilonClosure(nfa, [nfa.start]);
+  const charSources = /* @__PURE__ */ new Set();
+  for (let p = 0; p < nfa.edges.length; p++) {
+    if (nfa.edges[p].some((e) => e.set !== null)) charSources.add(p);
+  }
+  const acceptClosureOf = /* @__PURE__ */ new Set();
+  for (let p = 0; p < nfa.edges.length; p++) {
+    if (epsilonClosure(nfa, [p]).has(nfa.accept)) acceptClosureOf.add(p);
+  }
+  const startSources = /* @__PURE__ */ new Set();
+  for (const p of startClosure) {
+    if (charSources.has(p)) startSources.add(p);
+  }
+  const s1 = parseAmbiguity(nfa, startSources, acceptClosureOf, budget);
+  if (s1.ambiguous) return { verdict: "ambiguous", witness: s1.witness };
+  const s2 = decompositionAmbiguity(nfa, startClosure, acceptClosureOf, budget);
+  if (s2.ambiguous) return { verdict: "ambiguous", witness: s2.witness };
+  return { verdict: budget.exhausted ? "budget" : "unambiguous" };
+}
+
 // src/regex-guard.ts
 var MAX_PATTERN_LEN = 256;
 var DANGEROUS_PATTERNS = [
@@ -11,6 +544,408 @@ var DANGEROUS_PATTERNS = [
   // Greedy quantifier inside lookahead/lookbehind — (?!.*a+)
   /\(\?<?[!=][^)]*[+*][^)]*\)/
 ];
+var GROUP_PREFIX_RE = /^\?(?::|[=!]|<[=!]|<[$_\p{ID_Start}][$_\p{ID_Continue}\u200C\u200D]*>)/u;
+function stripGroupPrefix(inner) {
+  return inner.replace(GROUP_PREFIX_RE, "");
+}
+function splitTopLevelBranches(inner) {
+  const branches = [];
+  let current = "";
+  let d = 0;
+  let cls = false;
+  for (let k = 0; k < inner.length; k++) {
+    const ch = inner[k];
+    if (ch === "\\") {
+      current += ch + (inner[k + 1] ?? "");
+      k++;
+      continue;
+    }
+    if (cls) {
+      if (ch === "]") cls = false;
+      current += ch;
+      continue;
+    }
+    if (ch === "[") {
+      cls = true;
+      current += ch;
+      continue;
+    }
+    if (ch === "(") d++;
+    if (ch === ")") d--;
+    if (ch === "|" && d === 0) {
+      branches.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  branches.push(current);
+  return branches;
+}
+function branchesOverlap(branches) {
+  const norm = branches.map(unwrapGroupBranch);
+  for (const list of [branches, norm]) {
+    for (let a = 0; a < list.length; a++) {
+      for (let b = a + 1; b < list.length; b++) {
+        const x = list[a];
+        const y = list[b];
+        if (x === "" || y === "") return true;
+        if (matchesEmptyToken(x) || matchesEmptyToken(y)) return true;
+        if (x === y || x.startsWith(y) || y.startsWith(x)) return true;
+        const sx = singleTokenCharSet(x);
+        const sy = singleTokenCharSet(y);
+        if (sx && sy && charSetsIntersect(sx, sy)) return true;
+        const fx = fixedTokenSets(x);
+        const fy = fixedTokenSets(y);
+        if (fx && fy && fx.length === fy.length && fx.every((s, idx) => charSetsIntersect(s, fy[idx]))) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+var MAX_CP2 = 1114111;
+var WORD_SET = [
+  [48, 57],
+  [65, 90],
+  [95, 95],
+  [97, 122]
+];
+var DIGIT_SET = [[48, 57]];
+var SPACE_SET = [
+  [9, 13],
+  [32, 32],
+  [160, 160],
+  [5760, 5760],
+  [8192, 8202],
+  [8232, 8233],
+  [8239, 8239],
+  [8287, 8287],
+  [12288, 12288],
+  [65279, 65279]
+];
+var DOT_SET = [
+  [0, 9],
+  [11, MAX_CP2]
+];
+function complementOf2(set) {
+  const out = [];
+  let next = 0;
+  for (const [lo, hi] of set) {
+    if (lo > next) out.push([next, lo - 1]);
+    next = hi + 1;
+  }
+  if (next <= MAX_CP2) out.push([next, MAX_CP2]);
+  return out;
+}
+function mergeRanges(ranges) {
+  if (ranges.length === 0) return [];
+  ranges.sort((a, b) => a[0] - b[0]);
+  const out = [ranges[0]];
+  for (let i = 1; i < ranges.length; i++) {
+    const last = out[out.length - 1];
+    const r = ranges[i];
+    if (r[0] <= last[1] + 1) {
+      last[1] = Math.max(last[1], r[1]);
+    } else {
+      out.push(r);
+    }
+  }
+  return out;
+}
+function charSetsIntersect(a, b) {
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    const [alo, ahi] = a[i];
+    const [blo, bhi] = b[j];
+    if (alo <= bhi && blo <= ahi) return true;
+    if (ahi < bhi) i++;
+    else j++;
+  }
+  return false;
+}
+var NAMED_CLASS_SETS = {
+  w: WORD_SET,
+  W: complementOf2(WORD_SET),
+  d: DIGIT_SET,
+  D: complementOf2(DIGIT_SET),
+  s: SPACE_SET,
+  S: complementOf2(SPACE_SET)
+};
+var SIMPLE_ESCAPES = {
+  n: 10,
+  r: 13,
+  t: 9,
+  f: 12,
+  v: 11,
+  0: 0,
+  b: 8
+  // backspace inside a class; outside, a lone `\b` is caught by matchesEmptyToken first
+};
+function hexAt(s, start, len) {
+  if (start + len > s.length) return null;
+  const cp = Number.parseInt(s.slice(start, start + len), 16);
+  return Number.isFinite(cp) ? cp : null;
+}
+function parseEscape2(s, i) {
+  const ch = s[i + 1];
+  if (ch === void 0) return null;
+  if (NAMED_CLASS_SETS[ch] !== void 0) {
+    return { kind: "named", cp: -1, name: ch, next: i + 2 };
+  }
+  const simple = SIMPLE_ESCAPES[ch];
+  if (simple !== void 0) {
+    return { kind: "literal", cp: simple, name: "", next: i + 2 };
+  }
+  if (ch === "x") {
+    const cp = hexAt(s, i + 2, 2);
+    if (cp === null) return null;
+    return { kind: "literal", cp, name: "", next: i + 4 };
+  }
+  if (ch === "u") {
+    if (s[i + 2] === "{") {
+      const close = s.indexOf("}", i + 3);
+      if (close === -1 || close - (i + 3) > 6) return null;
+      const cp2 = hexAt(s, i + 3, close - (i + 3));
+      if (cp2 === null || cp2 > MAX_CP2) return null;
+      return { kind: "literal", cp: cp2, name: "", next: close + 1 };
+    }
+    const cp = hexAt(s, i + 2, 4);
+    if (cp === null) return null;
+    return { kind: "literal", cp, name: "", next: i + 6 };
+  }
+  if (/[A-Za-z]/.test(ch)) return null;
+  return { kind: "literal", cp: ch.codePointAt(0) ?? -1, name: "", next: i + 2 };
+}
+function groupCloseIndex(s, open) {
+  let depth = 0;
+  let inClass = false;
+  for (let j = open; j < s.length; j++) {
+    const c = s[j];
+    if (c === "\\") {
+      j++;
+      continue;
+    }
+    if (inClass) {
+      if (c === "]") inClass = false;
+      continue;
+    }
+    if (c === "[") {
+      inClass = true;
+      continue;
+    }
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0) return j;
+    }
+  }
+  return -1;
+}
+function unwrapGroupBranch(branch) {
+  let s = branch;
+  for (; ; ) {
+    if (!s.startsWith("(") || !s.endsWith(")")) return s;
+    const close = groupCloseIndex(s, 0);
+    if (close !== s.length - 1) return s;
+    let inner = s.slice(1, -1);
+    if (inner.startsWith("?")) {
+      if (/^(?:=|!|<=|<!)/.test(inner.slice(1))) return s;
+      const prefix = GROUP_PREFIX_RE.exec(inner);
+      if (!prefix) return s;
+      inner = inner.slice(prefix[0].length);
+    }
+    s = inner;
+  }
+}
+function matchesEmptyToken(branch) {
+  return branch === "^" || branch === "$" || branch === "\\b" || branch === "\\B" || /^\(\?(?:=|!|<=|<!)[\s\S]*\)$/.test(branch);
+}
+function parseCharClass(s) {
+  if (!s.startsWith("[") || !s.endsWith("]") || s.length < 3) return null;
+  let i = 1;
+  let negated = false;
+  if (s[i] === "^") {
+    negated = true;
+    i++;
+  }
+  const ranges = [];
+  let first = true;
+  while (i < s.length - 1) {
+    const ch = s[i];
+    let lo;
+    let width;
+    if (ch === "\\") {
+      const tok = parseEscape2(s, i);
+      if (!tok) return null;
+      if (tok.kind === "named") {
+        ranges.push(...NAMED_CLASS_SETS[tok.name]);
+        i = tok.next;
+        first = false;
+        continue;
+      }
+      lo = tok.cp;
+      width = tok.next - i;
+    } else {
+      lo = ch.codePointAt(0) ?? -1;
+      width = 1;
+    }
+    const nextCh = s[i + width];
+    if (nextCh === "-" && i + width + 1 < s.length - 1) {
+      const hiStart = i + width + 1;
+      let hi;
+      if (s[hiStart] === "\\") {
+        const tok = parseEscape2(s, hiStart);
+        if (tok?.kind !== "literal") return null;
+        hi = tok.cp;
+        i = tok.next;
+      } else {
+        hi = s[hiStart].codePointAt(0) ?? -1;
+        i = hiStart + 1;
+      }
+      if (hi < lo) return null;
+      ranges.push([lo, hi]);
+    } else {
+      ranges.push([lo, lo]);
+      i += width;
+    }
+    first = false;
+    void first;
+  }
+  if (ranges.length === 0) return null;
+  const merged = mergeRanges(ranges);
+  return negated ? complementOf2(merged) : merged;
+}
+function singleTokenCharSet(branch) {
+  if (branch === ".") return DOT_SET;
+  if (branch.startsWith("\\")) {
+    const tok = parseEscape2(branch, 0);
+    if (!tok || tok.next !== branch.length) return null;
+    if (tok.kind === "named") return NAMED_CLASS_SETS[tok.name] ?? null;
+    return [[tok.cp, tok.cp]];
+  }
+  if (branch.length === 1) {
+    const cp = branch.codePointAt(0);
+    return cp === void 0 ? null : [[cp, cp]];
+  }
+  if (branch.startsWith("[")) return parseCharClass(branch);
+  return null;
+}
+function fixedTokenSets(branch) {
+  const sets = [];
+  let i = 0;
+  while (i < branch.length) {
+    const ch = branch[i];
+    let set;
+    let next;
+    if (ch === ".") {
+      set = DOT_SET;
+      next = i + 1;
+    } else if (ch === "\\") {
+      const tok = parseEscape2(branch, i);
+      if (!tok) return null;
+      set = tok.kind === "named" ? NAMED_CLASS_SETS[tok.name] ?? null : [[tok.cp, tok.cp]];
+      next = tok.next;
+    } else if (ch === "[") {
+      let end = i + 1;
+      if (branch[end] === "^") end++;
+      if (branch[end] === "]") end++;
+      while (end < branch.length && branch[end] !== "]") {
+        if (branch[end] === "\\") end++;
+        end++;
+      }
+      if (end >= branch.length) return null;
+      set = parseCharClass(branch.slice(i, end + 1));
+      next = end + 1;
+    } else if ("^$()*+?{|".includes(ch)) {
+      return null;
+    } else {
+      const cp = ch.codePointAt(0);
+      if (cp === void 0) return null;
+      set = [[cp, cp]];
+      next = i + 1;
+    }
+    if (set === null) return null;
+    const q = branch[next];
+    if (q === void 0) {
+      sets.push(set);
+      break;
+    }
+    if (q === "*" || q === "+" || q === "?") return null;
+    if (q === "{") {
+      const close = branch.indexOf("}", next);
+      if (close === -1) return null;
+      const body = branch.slice(next + 1, close);
+      if (!/^\d+$/.test(body)) return null;
+      const n = Number.parseInt(body, 10);
+      if (n < 1 || n > 16 || sets.length + n > 64) return null;
+      for (let k = 0; k < n; k++) sets.push(set);
+      i = close + 1;
+      continue;
+    }
+    sets.push(set);
+    i = next;
+  }
+  return sets.length > 0 && sets.length <= 64 ? sets : null;
+}
+function directChildGroupContents(s) {
+  const children = [];
+  let i = 0;
+  while (i < s.length) {
+    const ch = s[i];
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === "[") {
+      for (i++; i < s.length && s[i] !== "]"; i++) {
+        if (s[i] === "\\") i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch !== "(") {
+      i++;
+      continue;
+    }
+    let depth = 0;
+    let j = i;
+    for (; j < s.length; j++) {
+      const c = s[j];
+      if (c === "\\") {
+        j++;
+        continue;
+      }
+      if (c === "[") {
+        for (j++; j < s.length && s[j] !== "]"; j++) {
+          if (s[j] === "\\") j++;
+        }
+        continue;
+      }
+      if (c === "(") depth++;
+      else if (c === ")") {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    if (j >= s.length) break;
+    children.push(s.slice(i + 1, j));
+    i = j + 1;
+  }
+  return children;
+}
+function hasAmbiguousBranches(content) {
+  const branches = splitTopLevelBranches(content);
+  if (branches.length >= 2 && branchesOverlap(branches)) return true;
+  for (const branch of branches) {
+    for (const child of directChildGroupContents(branch)) {
+      if (hasAmbiguousBranches(stripGroupPrefix(child))) return true;
+    }
+  }
+  return false;
+}
 function hasAmbiguousQuantifiedAlternation(pattern) {
   let outerInClass = false;
   for (let i = 0; i < pattern.length; i++) {
@@ -54,47 +989,11 @@ function hasAmbiguousQuantifiedAlternation(pattern) {
     if (j >= pattern.length) return false;
     const next = pattern[j + 1];
     if (next !== "+" && next !== "*" && next !== "{") continue;
-    let inner = pattern.slice(i + 1, j);
-    inner = inner.replace(/^\?(?::|<?[=!])/u, "");
-    const branches = [];
-    let current = "";
-    let d = 0;
-    let cls = false;
-    for (let k = 0; k < inner.length; k++) {
-      const ch2 = inner[k];
-      if (ch2 === "\\") {
-        current += ch2 + (inner[k + 1] ?? "");
-        k++;
-        continue;
-      }
-      if (cls) {
-        if (ch2 === "]") cls = false;
-        current += ch2;
-        continue;
-      }
-      if (ch2 === "[") {
-        cls = true;
-        current += ch2;
-        continue;
-      }
-      if (ch2 === "(") d++;
-      if (ch2 === ")") d--;
-      if (ch2 === "|" && d === 0) {
-        branches.push(current);
-        current = "";
-        continue;
-      }
-      current += ch2;
+    if (hasAmbiguousBranches(stripGroupPrefix(pattern.slice(i + 1, j)))) {
+      return true;
     }
-    branches.push(current);
-    if (branches.length < 2) continue;
-    for (let a = 0; a < branches.length; a++) {
-      for (let b = a + 1; b < branches.length; b++) {
-        const x = branches[a];
-        const y = branches[b];
-        if (x === "" || y === "") return true;
-        if (x === y || x.startsWith(y) || y.startsWith(x)) return true;
-      }
+    if (detectQuantifiedAmbiguity(pattern.slice(i + 1, j)).verdict === "ambiguous") {
+      return true;
     }
   }
   return false;

package/dist/regex-ambiguity.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Step-budgeted regex ambiguity matcher — ADR-004.
+ *
+ * The final semantic layer of the ReDoS guard (packages/primitives/src/
+ * regex-guard.ts, wired additively after the static layers from rounds
+ * 11-14). It answers, for the CONTENT of a quantified group X:
+ *
+ *   does `(?:X)+` admit a string with two or more distinct parses?
+ *
+ * Two mechanisms, both bounded by a checker-side step budget:
+ *
+ *  1. PARSE AMBIGUITY (within one iteration) — build a Thompson NFA of X,
+ *    ε-eliminate onto CHAR-SOURCE states (states that own an outgoing
+ *    consuming edge; ε-closure is folded into transition targets), then run
+ *    the squared-product construction: product nodes are (p, q) source
+ *    pairs; steps consume one character synchronously through both tracks;
+ *    ambiguity = a divergent pair (p ≠ q — a different branch choice)
+ *    from which both tracks can still complete to acceptance. Keying the
+ *    product on SOURCE states is what removes the ε-timing false positives
+ *    that falsified the naive asynchronous-ε product in the ADR-004 spike:
+ *    the same parse paused at different ε-points never appears.
+ *
+ *  2. DECOMPOSITION AMBIGUITY (across iterations) — the Sardinas–Patterson
+ *    code question: `X+` is unambiguous iff L(X) is a code (uniquely
+ *    decodable). This is the only mechanism that can see `(a+)+`-style
+ *    self-decomposition, where the ambiguity lives BETWEEN iterations and
+ *    both iterations consume through the same edges. L(X) is approximated
+ *    by a finite word set W (all L-words up to WORD_MAX over a
+ *    representative alphabet) and the SP residual recurrence runs on W —
+ *    sound in the flagging direction: a non-code W proves L(X) not a code.
+ *    Beyond the word bound or the budget the stage UNDER-REJECTS.
+ *
+ * Verdict doctrine (guard-wide): rejection requires a proof — an 'ambiguous'
+ * verdict always carries a witness string with two decompositions. Budget
+ * exhaustion ('budget') and out-of-subset content ('unparsable') both
+ * ALLOW the pattern: the layer can only under-reject, never over-reject
+ * relative to its subset.
+ *
+ * Deliberately self-contained (its own CharSet/parser copies) so the guard
+ * file keeps its committed shape; the duplication is documented isolation,
+ * not drift — the parity test in tools/ pins the guard entry points, and
+ * this module has its own property test against a brute-force oracle.
+ *
+ * @module regex-ambiguity
+ * @see docs/adr/adr-004-step-budgeted-regex-ambiguity-matcher.md
+ */
+export interface AmbiguityResult {
+    readonly verdict: 'ambiguous' | 'unambiguous' | 'unparsable' | 'budget';
+    /** Present iff verdict === 'ambiguous': a string with ≥2 decompositions. */
+    readonly witness?: string | undefined;
+}
+/**
+ * Does `(?:content)+` admit a string with two or more distinct parses?
+ * 'ambiguous' is a proof (witness included); 'budget' and 'unparsable'
+ * both mean "allow" — the layer can only under-reject, never over-reject.
+ */
+export declare function detectQuantifiedAmbiguity(content: string): AmbiguityResult;
+//# sourceMappingURL=regex-ambiguity.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/primitives",
-  "version": "0.317.2",
+  "version": "0.319.0",
   "license": "MIT",
   "description": "Dependency-leaf primitives shared across WrongStack packages (regex guard, slugs, timestamps).",
   "repository": {