@sponsio/sdk 0.1.0-alpha.3 → 0.2.0-alpha.10

package/dist/core/grounding.js

@@ -1,5 +1,5 @@
 /**
- * Grounding: convert tool-call events into per-timestep predicate valuations.
+ * Grounding: convert events into per-timestep predicate valuations.
  *
  * Port of sponsio/tracer/grounding.py (Det-relevant atoms).
  *
@@ -16,18 +16,61 @@
  *   arg_paths_within(tool, *prefixes)  — all paths in args within prefix set
  *   token_count(type)                  — cumulative tokens (from event.args.tokens)
  *   delegation_depth                   — depth of agent-to-agent delegation
+ *   ctx(key, value)                    — external fact pushed via observe_context
+ *   ctx_matches(key, pattern)          — current ctx[key] matches regex
+ *   llm_said(pattern)                  — llm_response content matches regex
+ *   response_words / response_chars    — response length on llm_response
+ *   time_since(predicate_key)          — event-clock delta since predicate last True
  */
 import { predKey } from "./formula.js";
+import { numericString } from "./evaluator.js";
+import { canonicalTool, toolAliases } from "./tool-names.js";
 export function newGroundingState() {
     return {
         callCounts: {},
         callWithCounts: {},
         lastTool: null,
+        lastToolAliases: [],
         consecutiveCounts: {},
         tokenCounts: {},
         delegationDepth: 0,
+        currentCtx: {},
+        now: 0,
+        lastTs: {},
+        trueAtPrev: new Set(),
     };
 }
+/**
+ * Predicates whose grounding requires the formula AST to tell
+ * grounding which arg tuples to check (regex on content, ctx_matches,
+ * time_since key targets, …). Mirrors Python's ``_CONTENT_PREDICATES``.
+ */
+const CONTENT_PREDICATES = new Set([
+    "called_with",
+    "count_with",
+    "arg_has",
+    "arg_field_has",
+    "arg_length_exceeds",
+    "arg_paths_within",
+    "arg_numeric",
+    "llm_said",
+    "ctx_matches",
+    "time_since",
+]);
+/**
+ * Var names that must be extracted from the formula tree for grounding.
+ * Includes both the atom-style content predicates and bare arithmetic
+ * Vars so ``Le(Var(count, x), Const(N))`` carries ``("x",)`` through.
+ */
+const VAR_PREDICATES = new Set([
+    "count_with",
+    "count",
+    "consecutive_count",
+    "arg_numeric",
+    "token_count",
+    "delegation_depth",
+    "time_since",
+]);
 /**
  * Collect content atoms from a formula tree.
  * These are atoms whose grounding depends on event content (arg patterns).
@@ -37,20 +80,14 @@ export function collectContentAtoms(formulas) {
     function walk(node) {
         if (node.kind === "Atom") {
             const pred = node.predicate;
-            if ([
-                "called_with", "count_with",
-                "arg_has", "arg_field_has", "arg_length_exceeds", "arg_paths_within",
-            ].includes(pred)) {
+            if (CONTENT_PREDICATES.has(pred)) {
                 if (!atoms[pred])
                     atoms[pred] = new Set();
                 atoms[pred].add(node.args.join("|"));
             }
         }
         else if (node.kind === "Var") {
-            if ([
-                "count_with", "count", "consecutive_count",
-                "arg_numeric", "token_count", "delegation_depth",
-            ].includes(node.name)) {
+            if (VAR_PREDICATES.has(node.name)) {
                 const pred = node.name;
                 if (!atoms[pred])
                     atoms[pred] = new Set();
@@ -69,172 +106,439 @@ export function collectContentAtoms(formulas) {
         walk(f);
     return atoms;
 }
+function escapeRegexLiteral(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Ground a single event into a predicate valuation dict.
+ *
+ * Routes by ``event.event_type``:
+ *   - ``tool_call`` (default) — emits the full tool-call atom set
+ *   - ``llm_response`` — emits ``llm_said(pattern)`` + length atoms
+ *   - ``context_update`` — merges ``event.args`` into ``state.currentCtx``
+ *
+ * Ctx atoms (``ctx(k, v)``), accumulator snapshots, and ``time_since``
+ * fire on every event regardless of type (matching Python parity).
+ */
+/**
+ * Is `path` inside `prefix`, as directories rather than as text?
+ *
+ * A plain `startsWith` answered two different questions wrong. It let
+ * `/safe/../etc/passwd` through, because the string does begin with
+ * `/safe` — the oldest escape there is, against a rule whose whole
+ * purpose is confinement. And it counted `/safeguard/evil.txt` as inside
+ * `/safe`, because a prefix of the text is not a prefix of the path.
+ *
+ * Parity with Python's `_path_within` in `sponsio/tracer/grounding.py`.
+ */
+function normalizePosix(input) {
+    const text = input.replace(/\\/g, "/");
+    const absolute = text.startsWith("/");
+    const out = [];
+    for (const segment of text.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (out.length && out[out.length - 1] !== "..")
+                out.pop();
+            else if (!absolute)
+                out.push("..");
+            continue;
+        }
+        out.push(segment);
+    }
+    const joined = out.join("/");
+    if (absolute)
+        return "/" + joined;
+    return joined || ".";
+}
+export function pathWithin(path, prefix) {
+    const normalized = normalizePosix(path);
+    const root = normalizePosix(prefix);
+    if (root === "/")
+        return normalized.startsWith("/");
+    return normalized === root || normalized.startsWith(root + "/");
+}
+/**
+ * Fail at construction on a contract pattern that is not a valid regular
+ * expression. Mirrors Python, where a malformed contract raises when the
+ * guard is built. Without this an ``llm_said`` / ``ctx_matches`` pattern
+ * that never compiles silently never matches (fail-open), and an
+ * ``arg_*`` pattern throws on the first tool call instead of at startup.
+ *
+ * Patterns are stored as ``args.join("|")``; each predicate knows which
+ * tail of that string is the regex, exactly as ``groundEvent`` reads it.
+ */
+export function validateContentPatterns(atoms) {
+    const regexTail = {
+        called_with: 1, // (tool, pattern)
+        count_with: 1, // (tool, pattern)
+        arg_has: 1, // (tool, pattern)
+        arg_field_has: 2, // (tool, field, pattern)
+        llm_said: 0, // (pattern)
+        ctx_matches: 1, // (key, pattern)
+    };
+    for (const [pred, skip] of Object.entries(regexTail)) {
+        const set = atoms[pred];
+        if (!set)
+            continue;
+        for (const raw of set) {
+            const parts = raw.split("|");
+            if (parts.length <= skip)
+                continue;
+            const pattern = parts.slice(skip).join("|");
+            try {
+                new RegExp(pattern);
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new Error(`sponsio: contract pattern for ${pred} is not a valid regular ` +
+                    `expression: ${JSON.stringify(pattern)} (${detail})`);
+            }
+        }
+    }
+}
+/**
+ * Read a tool argument as a number, the way a numeric cap needs it.
+ *
+ * ``"$5,000"``, ``"5,000"`` and ``"5000 USD"`` are the shapes a model
+ * writes for an amount. ``parseFloat`` read ``"5,000"`` as ``5`` and
+ * ``"$5,000"`` as nothing at all, and the evaluator reads a missing
+ * ``arg_numeric`` as ``0``, so ``argValueRange`` waved them through a cap
+ * that stopped ``5000``. The normalisation is the one ordered comparisons
+ * already use (``numericString`` in core/evaluator.ts), so both paths
+ * agree. Parity with Python ``numeric_arg`` in sponsio/tracer/grounding.py:
+ * a boolean reads as 0/1, a number as itself, anything else as undefined.
+ */
+export function numericArg(value) {
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string") {
+        const n = numericString(value);
+        return n === null ? undefined : n;
+    }
+    return undefined;
+}
 /**
- * Ground a single tool-call event into a predicate valuation dict.
+ * Does a contract's target tool name the tool this event called?
+ *
+ * The target is canonicalised and looked up among every spelling the
+ * event answers to (see core/tool-names.ts), so a rule on ``issue_refund``
+ * binds ``Issue_Refund``, ``"issue_refund "`` and
+ * ``mcp__finance__issue_refund``. Parity with Python ``_tool_matches``
+ * for plain names; the ``tool:argpattern`` form is split by the pattern
+ * factories before it reaches grounding in this runtime.
  */
+export function toolMatches(targetTool, aliases) {
+    const target = canonicalTool(targetTool);
+    for (const a of aliases)
+        if (a === target)
+            return true;
+    return false;
+}
 export function groundEvent(event, state, contentAtoms) {
     const v = {};
-    const tool = event.tool;
-    const argsStr = event.args ? JSON.stringify(event.args) : "";
-    // called(tool)
-    v[predKey("called", tool)] = true;
-    // called_any — fires whenever any tool is invoked. Used by
-    // ``tool_allowlist`` to encode "whenever any tool runs, it must
-    // be one of the allowed ones".
-    v[predKey("called_any")] = true;
-    // count(tool)
-    state.callCounts[tool] = (state.callCounts[tool] || 0) + 1;
-    v[predKey("count", tool)] = state.callCounts[tool];
-    // consecutive_count(tool)
-    if (tool === state.lastTool) {
-        state.consecutiveCounts[tool] = (state.consecutiveCounts[tool] || 1) + 1;
+    const eventType = event.event_type ?? "tool_call";
+    // Advance the event clock (mirrors ``state.now = float(event.ts)``).
+    if (typeof event.ts === "number") {
+        state.now = event.ts;
     }
     else {
-        if (state.lastTool)
-            state.consecutiveCounts[state.lastTool] = 0;
-        state.consecutiveCounts[tool] = 1;
+        state.now += 1;
     }
-    state.lastTool = tool;
-    v[predKey("consecutive_count", tool)] = state.consecutiveCounts[tool];
-    // called_with / count_with — regex on serialized args
-    if (contentAtoms) {
-        const cwPatterns = new Set();
-        for (const key of ["called_with", "count_with"]) {
-            const s = contentAtoms[key];
-            if (s)
-                for (const p of s)
-                    cwPatterns.add(p);
+    if (eventType === "tool_call") {
+        const tool = event.tool;
+        const argsStr = event.args ? JSON.stringify(event.args) : "";
+        // called(tool) — grounded under every spelling a contract could
+        // reasonably have named it by: exact, whitespace-stripped, case-folded,
+        // and the bare name behind an ``mcp__server__`` prefix. A rule written
+        // against ``issue_refund`` was otherwise inert against
+        // ``mcp__finance__issue_refund``, and with ``mustPrecede`` compiling to
+        // ``Or(order-holds, never-called)`` that read as "satisfied".
+        // Canonical spellings only: ``predKey`` collapses the case variants of
+        // a tool-keyed predicate, so a per-raw-spelling counter would have two
+        // entries landing on one key, the snapshot loop writing whichever came
+        // last.
+        const aliases = [...new Set(toolAliases(tool).map(canonicalTool))];
+        for (const alias of aliases)
+            v[predKey("called", alias)] = true;
+        // called_any — fires whenever any tool is invoked. Used by
+        // ``tool_allowlist`` to encode "whenever any tool runs, it must
+        // be one of the allowed ones".
+        v[predKey("called_any")] = true;
+        // count(tool) — one counter per alias, so ``rateLimit("issue_refund")``
+        // counts the MCP-prefixed and differently-cased calls too.
+        for (const alias of aliases) {
+            state.callCounts[alias] = (state.callCounts[alias] || 0) + 1;
+            v[predKey("count", alias)] = state.callCounts[alias];
         }
-        for (const raw of cwPatterns) {
-            const parts = raw.split("|");
-            if (parts.length >= 2) {
-                const targetTool = parts[0];
-                const pattern = parts.slice(1).join("|");
-                if (targetTool === tool) {
-                    const matched = new RegExp(pattern).test(argsStr);
-                    v[predKey("called_with", targetTool, pattern)] = matched;
-                    if (matched) {
-                        const cwKey = `${targetTool}|${pattern}`;
-                        state.callWithCounts[cwKey] = (state.callWithCounts[cwKey] || 0) + 1;
-                    }
-                    v[predKey("count_with", targetTool, pattern)] =
-                        state.callWithCounts[`${targetTool}|${pattern}`] || 0;
-                }
+        // consecutive_count(tool) — keyed per alias like ``count``; "same tool
+        // again" is decided on the canonical form.
+        // ``search`` then ``mcp__web__search`` is the same tool again: the run
+        // continues when the alias sets overlap, not only on equal canonicals.
+        const canonical = canonicalTool(tool);
+        const lastAliases = new Set(state.lastToolAliases);
+        if (canonical === state.lastTool || aliases.some((a) => lastAliases.has(a))) {
+            for (const alias of aliases) {
+                state.consecutiveCounts[alias] = (state.consecutiveCounts[alias] || 1) + 1;
+            }
+        }
+        else {
+            for (const stale of state.lastToolAliases)
+                state.consecutiveCounts[stale] = 0;
+            for (const alias of aliases)
+                state.consecutiveCounts[alias] = 1;
+        }
+        state.lastTool = canonical;
+        state.lastToolAliases = aliases;
+        for (const alias of aliases) {
+            v[predKey("consecutive_count", alias)] = state.consecutiveCounts[alias];
+        }
+        // arg_value(tool, field) — raw value for Term-based lookups.
+        // ``ArgValue(tool, field)`` reads state[predKey("arg_value", tool,
+        // field)] for runtime comparisons (e.g. Eq(ArgValue(tool, "amount"),
+        // CtxValue("approved_amount"))). Emit unconditionally for every arg
+        // field, every tool_call — Terms read by direct key lookup, not via
+        // contentAtoms extraction.
+        // Written under every alias (``predKey`` collapses the case variants),
+        // so ``ArgValue("issue_refund", "amount")`` reads a call that arrived as
+        // ``mcp__finance__issue_refund``.
+        if (event.args) {
+            for (const [field, val] of Object.entries(event.args)) {
+                for (const alias of aliases)
+                    v[predKey("arg_value", alias, field)] = val;
             }
         }
-        // arg_has(tool, pattern)
-        const argHasPatterns = contentAtoms["arg_has"];
-        if (argHasPatterns && argsStr) {
-            for (const raw of argHasPatterns) {
+        // called_with / count_with — regex on serialized args
+        if (contentAtoms) {
+            const cwPatterns = new Set();
+            for (const key of ["called_with", "count_with"]) {
+                const s = contentAtoms[key];
+                if (s)
+                    for (const p of s)
+                        cwPatterns.add(p);
+            }
+            for (const raw of cwPatterns) {
                 const parts = raw.split("|");
                 if (parts.length >= 2) {
                     const targetTool = parts[0];
                     const pattern = parts.slice(1).join("|");
-                    if (targetTool === tool) {
-                        v[predKey("arg_has", targetTool, pattern)] = new RegExp(pattern).test(argsStr);
+                    if (toolMatches(targetTool, aliases)) {
+                        const matched = new RegExp(pattern).test(argsStr);
+                        v[predKey("called_with", targetTool, pattern)] = matched;
+                        if (matched) {
+                            const cwKey = `${targetTool}|${pattern}`;
+                            state.callWithCounts[cwKey] = (state.callWithCounts[cwKey] || 0) + 1;
+                        }
+                        v[predKey("count_with", targetTool, pattern)] =
+                            state.callWithCounts[`${targetTool}|${pattern}`] || 0;
                     }
                 }
             }
-        }
-        // arg_field_has(tool, field, pattern)
-        const afhPatterns = contentAtoms["arg_field_has"];
-        if (afhPatterns && event.args) {
-            for (const raw of afhPatterns) {
-                const parts = raw.split("|");
-                if (parts.length >= 3) {
-                    const targetTool = parts[0];
-                    const field = parts[1];
-                    const pattern = parts.slice(2).join("|");
-                    if (targetTool === tool) {
-                        const fieldVal = event.args[field];
-                        const matched = fieldVal != null && new RegExp(pattern).test(String(fieldVal));
-                        v[predKey("arg_field_has", targetTool, field, pattern)] = matched;
+            // arg_has(tool, pattern)
+            const argHasPatterns = contentAtoms["arg_has"];
+            if (argHasPatterns && argsStr) {
+                for (const raw of argHasPatterns) {
+                    const parts = raw.split("|");
+                    if (parts.length >= 2) {
+                        const targetTool = parts[0];
+                        const pattern = parts.slice(1).join("|");
+                        if (toolMatches(targetTool, aliases)) {
+                            v[predKey("arg_has", targetTool, pattern)] = new RegExp(pattern).test(argsStr);
+                        }
                     }
                 }
             }
-        }
-        // arg_length_exceeds(tool, field, max_chars)
-        const ale = contentAtoms["arg_length_exceeds"];
-        if (ale && event.args) {
-            for (const raw of ale) {
-                const parts = raw.split("|");
-                if (parts.length >= 3) {
-                    const targetTool = parts[0];
-                    const field = parts[1];
-                    const maxChars = parseInt(parts[2], 10) || 500;
-                    if (targetTool === tool) {
-                        const fieldVal = event.args[field] ?? "";
-                        v[predKey("arg_length_exceeds", targetTool, field, String(maxChars))] =
-                            String(fieldVal).length > maxChars;
+            // arg_field_has(tool, field, pattern)
+            const afhPatterns = contentAtoms["arg_field_has"];
+            if (afhPatterns && event.args) {
+                for (const raw of afhPatterns) {
+                    const parts = raw.split("|");
+                    if (parts.length >= 3) {
+                        const targetTool = parts[0];
+                        const field = parts[1];
+                        const pattern = parts.slice(2).join("|");
+                        if (toolMatches(targetTool, aliases)) {
+                            const fieldVal = event.args[field];
+                            const matched = fieldVal != null && new RegExp(pattern).test(String(fieldVal));
+                            v[predKey("arg_field_has", targetTool, field, pattern)] = matched;
+                        }
                     }
                 }
             }
-        }
-        // arg_numeric(tool, field) — extract numeric value via 3 strategies:
-        //   1. Direct dict key
-        //   2. CLI flag "--field VALUE"
-        //   3. Positional token in command string
-        const anPatterns = contentAtoms["arg_numeric"];
-        if (anPatterns) {
-            for (const raw of anPatterns) {
-                const parts = raw.split("|");
-                if (parts.length >= 2) {
-                    const targetTool = parts[0];
-                    const field = parts[1];
-                    if (targetTool === tool) {
-                        let numericVal = null;
-                        // Strategy 1: direct dict key
-                        if (event.args && field in event.args) {
-                            const val = event.args[field];
-                            const n = typeof val === "number" ? val : parseFloat(String(val));
-                            if (!isNaN(n))
-                                numericVal = n;
+            // arg_length_exceeds(tool, field, max_chars)
+            const ale = contentAtoms["arg_length_exceeds"];
+            if (ale && event.args) {
+                for (const raw of ale) {
+                    const parts = raw.split("|");
+                    if (parts.length >= 3) {
+                        const targetTool = parts[0];
+                        const field = parts[1];
+                        const maxChars = parseInt(parts[2], 10) || 500;
+                        if (toolMatches(targetTool, aliases)) {
+                            const fieldVal = event.args[field] ?? "";
+                            v[predKey("arg_length_exceeds", targetTool, field, String(maxChars))] =
+                                String(fieldVal).length > maxChars;
                         }
-                        // Strategy 2: CLI --field VALUE
-                        if (numericVal == null && argsStr) {
-                            const flagRe = new RegExp(`--${field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+([+-]?\\d+(?:\\.\\d+)?)`);
-                            const m = argsStr.match(flagRe);
-                            if (m)
-                                numericVal = parseFloat(m[1]);
-                        }
-                        // Strategy 3: positional index
-                        if (numericVal == null && event.args && /^\d+$/.test(field)) {
-                            const cmdStr = String(event.args.command ?? "");
-                            const tokens = cmdStr.split(/\s+/);
-                            const pos = parseInt(field, 10);
-                            if (pos < tokens.length) {
-                                const n = parseFloat(tokens[pos]);
-                                if (!isNaN(n))
+                    }
+                }
+            }
+            // arg_numeric(tool, field) — extract numeric value via 3 strategies:
+            //   1. Direct dict key
+            //   2. CLI flag "--field VALUE"
+            //   3. Positional token in command string
+            const anPatterns = contentAtoms["arg_numeric"];
+            if (anPatterns) {
+                for (const raw of anPatterns) {
+                    const parts = raw.split("|");
+                    if (parts.length >= 2) {
+                        const targetTool = parts[0];
+                        const field = parts[1];
+                        if (toolMatches(targetTool, aliases)) {
+                            let numericVal = null;
+                            // Strategy 1: direct dict key, read with the same
+                            // normaliser ordered comparisons use ("$5,000" -> 5000).
+                            if (event.args && Object.prototype.hasOwnProperty.call(event.args, field)) {
+                                const n = numericArg(event.args[field]);
+                                if (n !== undefined)
                                     numericVal = n;
                             }
+                            // Strategy 2: CLI --field VALUE
+                            if (numericVal == null && argsStr) {
+                                const flagRe = new RegExp(`--${escapeRegexLiteral(field)}\\s+([+-]?\\d+(?:\\.\\d+)?)`);
+                                const m = argsStr.match(flagRe);
+                                if (m)
+                                    numericVal = parseFloat(m[1]);
+                            }
+                            // Strategy 3: positional index
+                            if (numericVal == null && event.args && /^\d+$/.test(field)) {
+                                const cmdStr = String(event.args.command ?? "");
+                                const tokens = cmdStr.split(/\s+/);
+                                const pos = parseInt(field, 10);
+                                if (pos < tokens.length) {
+                                    const n = parseFloat(tokens[pos]);
+                                    if (!isNaN(n))
+                                        numericVal = n;
+                                }
+                            }
+                            if (numericVal != null) {
+                                v[predKey("arg_numeric", targetTool, field)] = numericVal;
+                            }
                         }
-                        if (numericVal != null) {
-                            v[predKey("arg_numeric", targetTool, field)] = numericVal;
+                    }
+                }
+            }
+            // arg_paths_within(tool, *prefixes) — all /-paths in args within prefix set
+            const apw = contentAtoms["arg_paths_within"];
+            if (apw && argsStr) {
+                for (const raw of apw) {
+                    const parts = raw.split("|");
+                    if (parts.length >= 2) {
+                        const targetTool = parts[0];
+                        const prefixes = parts.slice(1);
+                        if (toolMatches(targetTool, aliases)) {
+                            const paths = argsStr.match(/(\/[^\s;|&>"']+)/g) ?? [];
+                            const allWithin = paths.length === 0 ||
+                                paths.every((p) => prefixes.some((pre) => pathWithin(p, pre)));
+                            v[predKey("arg_paths_within", targetTool, ...prefixes)] = allWithin;
                         }
                     }
                 }
             }
         }
-        // arg_paths_within(tool, *prefixes) — all /-paths in args within prefix set
-        const apw = contentAtoms["arg_paths_within"];
-        if (apw && argsStr) {
-            for (const raw of apw) {
-                const parts = raw.split("|");
-                if (parts.length >= 2) {
-                    const targetTool = parts[0];
-                    const prefixes = parts.slice(1);
-                    if (targetTool === tool) {
-                        const paths = argsStr.match(/(\/[^\s;|&>"']+)/g) ?? [];
-                        const allWithin = paths.length === 0 ||
-                            paths.every((p) => prefixes.some((pre) => p.startsWith(pre)));
-                        v[predKey("arg_paths_within", targetTool, ...prefixes)] = allWithin;
+    }
+    else if (eventType === "llm_response") {
+        // ── llm_said(pattern) ───────────────────────────────────────
+        const content = event.content ?? "";
+        if (content && contentAtoms && contentAtoms["llm_said"]) {
+            for (const raw of contentAtoms["llm_said"]) {
+                const pattern = raw;
+                if (!pattern)
+                    continue;
+                let matched = false;
+                try {
+                    matched = new RegExp(pattern).test(content);
+                }
+                catch {
+                    // Bad regex → never matches (parity with Python re.search → no match).
+                }
+                v[predKey("llm_said", pattern)] = matched;
+            }
+        }
+        // response_words / response_chars — unparameterized Vars consumed by max_length.
+        if (content) {
+            v["response_words"] = content.trim().length === 0 ? 0 : content.trim().split(/\s+/).length;
+            v["response_chars"] = content.length;
+        }
+        // ``args.segment`` convention: extended-thinking integrations tag
+        // segment="thinking" / "answer" so contracts can scope content
+        // checks to one segment only.
+        if (event.args && typeof event.args.segment === "string" && event.args.segment) {
+            v[predKey("segment", String(event.args.segment))] = true;
+        }
+    }
+    else if (eventType === "context_update") {
+        // Merge user-pushed facts into state.currentCtx so every
+        // subsequent event sees them as ctx(k, v) atoms. Apply BEFORE
+        // the ctx-emission loop so a contract at the same timestep as
+        // the update already observes the new keys.
+        if (event.args) {
+            for (const [k, val] of Object.entries(event.args)) {
+                if (k == null)
+                    continue;
+                state.currentCtx[String(k)] = val == null ? "" : String(val);
+            }
+        }
+    }
+    else if (eventType === "evidence" && event.key) {
+        // A cloud claim-verification verdict fed back into the trace.
+        // `key` is the predicate name; `args` carries the server's verdict
+        // and policy action verbatim. No verdict computation happens here —
+        // the atoms only restate what the service answered, so contracts
+        // (`claim_requires_evidence`, `underdetermined_must_clarify`) can
+        // reference it. Verdict upper-cased, action lower-cased, matching
+        // the server's own vocabulary and Python's grounding.
+        v[predKey("claim_emitted", event.key)] = true;
+        const verdict = String(event.args?.verdict ?? "").toUpperCase();
+        if (verdict)
+            v[predKey("evidence_verdict", event.key, verdict)] = true;
+        const action = String(event.args?.action ?? "").toLowerCase();
+        if (action)
+            v[predKey("evidence_action", event.key, action)] = true;
+    }
+    // ── ctx(k, v) / ctx_value(k) — emit per current_ctx entry, every event ─
+    // ctx(k, v) is the boolean atom (k==v). ctx_value(k) carries the raw
+    // value so Term-based comparisons can read it without hard-coding the
+    // expected value: e.g. Eq(CtxValue("approved_amount"),
+    // ArgValue("issue_refund", "amount")).
+    for (const [k, val] of Object.entries(state.currentCtx)) {
+        v[predKey("ctx", k, val)] = true;
+        v[predKey("ctx_value", k)] = val;
+    }
+    // ── ctx_matches(key, pattern) — regex against current_ctx[key] ──
+    if (contentAtoms && contentAtoms["ctx_matches"]) {
+        for (const raw of contentAtoms["ctx_matches"]) {
+            const parts = raw.split("|");
+            if (parts.length >= 2) {
+                const key = parts[0];
+                const pattern = parts.slice(1).join("|");
+                const cur = state.currentCtx[key];
+                let matched = false;
+                if (cur != null) {
+                    try {
+                        matched = new RegExp(pattern).test(cur);
+                    }
+                    catch {
+                        matched = false;
                     }
                 }
+                v[predKey("ctx_matches", key, pattern)] = matched;
             }
         }
     }
-    // token_count(type) — cumulative token count
-    // Extract from event.args.tokens if present (gen_ai.usage.* convention)
+    // token_count(type) — cumulative token count (only meaningful for events with usage)
     if (event.args) {
         const tokens = event.args.tokens;
         if (tokens) {
@@ -251,18 +555,56 @@ export function groundEvent(event, state, contentAtoms) {
     for (const [scope, cnt] of Object.entries(state.tokenCounts)) {
         v[predKey("token_count", scope)] = cnt;
     }
-    // delegation_depth — incremented by event.event_type === "delegation"
-    if (event.event_type === "delegation") {
+    // delegation_depth — incremented by event_type === "delegation"
+    if (eventType === "delegation") {
         state.delegationDepth += 1;
     }
     v[predKey("delegation_depth")] = state.delegationDepth;
-    // Emit count/count_with for all tracked vars
+    // Emit count snapshots for all tracked tools
     for (const [t, cnt] of Object.entries(state.callCounts)) {
         v[predKey("count", t)] = cnt;
     }
     for (const [key, cnt] of Object.entries(state.callWithCounts)) {
-        const [t, p] = [key.split("|")[0], key.split("|").slice(1).join("|")];
-        v[predKey("count_with", t, p)] = cnt;
+        const idx = key.indexOf("|");
+        if (idx > 0) {
+            v[predKey("count_with", key.slice(0, idx), key.slice(idx + 1))] = cnt;
+        }
+    }
+    // ── last_ts bookkeeping (fresh False→True transitions) ─────────
+    // A predicate that was True last event and still True now is
+    // "sustained" — we do NOT refresh its last_ts. Sustained covers
+    // ctx atoms re-emitted while held in scope; this is what makes
+    // time_since(ctx(approval.role, alice)) measure time since the
+    // approval was granted, not the trivial 0 from re-emission.
+    const trueNow = new Set();
+    for (const [key, val] of Object.entries(v)) {
+        if (val === true) {
+            trueNow.add(key);
+            if (!state.trueAtPrev.has(key)) {
+                state.lastTs[key] = state.now;
+            }
+        }
+    }
+    state.trueAtPrev = trueNow;
+    // ── time atoms (emitted last so they see fresh state.now) ─────
+    v["now"] = state.now;
+    if (contentAtoms && contentAtoms["time_since"]) {
+        for (const raw of contentAtoms["time_since"]) {
+            if (!raw)
+                continue;
+            const targetKey = raw;
+            let delta;
+            if (targetKey in state.lastTs) {
+                delta = state.now - state.lastTs[targetKey];
+            }
+            else {
+                // Sentinel — predicate has never fired. "Very long ago" is
+                // the right semantics for Le(time_since(P), N): if P never
+                // happened, the constraint must evaluate False.
+                delta = 1e18;
+            }
+            v[predKey("time_since", targetKey)] = delta;
+        }
     }
     return v;
 }