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

package/dist/core/patterns.js

@@ -18,24 +18,31 @@
  *     auditAfter, approvalFreshness, sanitizedBeforeSink, duplicateCallLimit
  */
 import { Atom, Not, And, Or, Implies, G, F, X, U, Le, Ge, Var, Const, } from "./formula.js";
+import { canonicalTool } from "./tool-names.js";
 // --- Helpers ---
+//
+// Tool names are canonicalised (see core/tool-names.ts) so a rule keys on
+// the same spelling grounding emits for every variant of the call:
+// ``Issue_Refund``, ``"issue_refund "`` and ``mcp__finance__issue_refund``
+// all bind a rule written on ``issue_refund``. Parity with Python's
+// ``_called`` / ``_count_var`` / ``_physical_tool``.
 function called(tool) {
     // Supports "tool:pattern" format — produces called_with atom.
     if (tool.includes(":")) {
         const [physical, pattern] = tool.split(":", 2);
-        return new Atom("called_with", [physical, pattern]);
+        return new Atom("called_with", [canonicalTool(physical), pattern]);
     }
-    return new Atom("called", [tool]);
+    return new Atom("called", [canonicalTool(tool)]);
 }
 function countVar(tool) {
     if (tool.includes(":")) {
         const [physical, pattern] = tool.split(":", 2);
-        return new Var("count_with", physical, pattern);
+        return new Var("count_with", canonicalTool(physical), pattern);
     }
-    return new Var("count", tool);
+    return new Var("count", canonicalTool(tool));
 }
 function physicalTool(tool) {
-    return tool.includes(":") ? tool.split(":", 1)[0] : tool;
+    return canonicalTool(tool.includes(":") ? tool.split(":", 1)[0] : tool);
 }
 /**
  * Reject empty / whitespace-only tool names at factory time.
@@ -112,6 +119,7 @@ export function mustPrecede(before, after) {
         formula: f,
         desc: `tool \`${before}\` must precede \`${after}\``,
         patternName: "must_precede",
+        args: [before, after],
         liveness: false,
     };
 }
@@ -122,9 +130,38 @@ export function alwaysFollowedBy(trigger, response) {
         formula: f,
         desc: `\`${trigger}\` must always be followed by \`${response}\``,
         patternName: "always_followed_by",
+        args: [trigger, response],
         liveness: true,
     };
 }
+/**
+ * Prescriptive next-step obligation: ``G(trigger -> X(next_action))``.
+ *
+ * When ``trigger`` holds at the current event, the agent must satisfy
+ * ``next_action`` at the very next event. Prescriptive counterpart to
+ * the block-style patterns (``never_together``, ``arg_blacklist``):
+ * instead of "you must not do X", a workflow_step says "you must do X
+ * next".
+ *
+ * Both arguments are arbitrary atoms (called(...), ctx(k, v),
+ * arg_field_has(...), etc.), so the same factory covers tool ordering,
+ * ctx-driven remediation, and arg-conditional follow-ups.
+ *
+ * NOT marked liveness: X is one-step bounded and the runtime can decide
+ * the obligation after a single event, unlike F.
+ */
+export function workflowStep(trigger, nextAction, desc) {
+    const f = new G(new Implies(trigger, new X(nextAction)));
+    const triggerStr = `${trigger.predicate}(${trigger.args.join(", ")})`;
+    const nextStr = `${nextAction.predicate}(${nextAction.args.join(", ")})`;
+    return {
+        formula: f,
+        desc: desc ?? `after ${triggerStr} the next event must satisfy ${nextStr}`,
+        patternName: "workflow_step",
+        args: [trigger, nextAction],
+        liveness: false,
+    };
+}
 export function noReversal(commitment, contradiction) {
     ensureDistinct(commitment, contradiction, "noReversal", "commitment", "contradiction");
     const f = new G(new Implies(called(commitment), new G(new Not(called(contradiction)))));
@@ -132,6 +169,7 @@ export function noReversal(commitment, contradiction) {
         formula: f,
         desc: `cannot call \`${contradiction}\` after \`${commitment}\``,
         patternName: "no_reversal",
+        args: [commitment, contradiction],
         liveness: false,
     };
 }
@@ -141,6 +179,7 @@ export function requiresPermission(tool, permission) {
         formula: f,
         desc: `\`${tool}\` requires permission \`${permission}\``,
         patternName: "requires_permission",
+        args: [tool, permission],
         liveness: false,
     };
 }
@@ -151,6 +190,7 @@ export function noDataLeak(source, external) {
         formula: f,
         desc: `no data leak from \`${source}\` to \`${external}\``,
         patternName: "no_data_leak",
+        args: [source, external],
         liveness: false,
     };
 }
@@ -161,6 +201,7 @@ export function mutualExclusion(a, b) {
         formula: f,
         desc: `tools \`${a}\` and \`${b}\` are mutually exclusive`,
         patternName: "mutual_exclusion",
+        args: [a, b],
         liveness: false,
     };
 }
@@ -170,11 +211,20 @@ export function rateLimit(tool, maxCalls) {
         formula: f,
         desc: `tool \`${tool}\` at most ${maxCalls} times`,
         patternName: "rate_limit",
+        args: [tool, maxCalls],
         liveness: false,
     };
 }
 export function idempotent(tool) {
-    return { ...rateLimit(tool, 1), patternName: "idempotent", desc: `\`${tool}\` at most once` };
+    // The spread would otherwise carry rate_limit's own args (tool, 1) into
+    // a rule whose identity is one tool, and the cloud groups findings by
+    // (patternName, args).
+    return {
+        ...rateLimit(tool, 1),
+        patternName: "idempotent",
+        args: [tool],
+        desc: `\`${tool}\` at most once`,
+    };
 }
 export function deadline(trigger, action, steps) {
     ensureDistinct(trigger, action, "deadline", "trigger", "action");
@@ -187,7 +237,12 @@ export function deadline(trigger, action, steps) {
         formula: f,
         desc: `\`${action}\` must occur within ${steps} steps of \`${trigger}\``,
         patternName: "deadline",
-        liveness: true,
+        args: [trigger, action, steps],
+        // Bounded-window liveness: ``X(boundedEventually(action, steps))``
+        // is decidable on a bounded prefix (steps + 1 events past the
+        // trigger), so it CAN fire mid-session — runtime parity with
+        // Python ``deadline.liveness == False``.
+        liveness: false,
     };
 }
 export function mustConfirm(action) {
@@ -197,6 +252,7 @@ export function mustConfirm(action) {
         formula: f,
         desc: `\`${action}\` requires confirmation (\`${confirm}\`)`,
         patternName: "must_confirm",
+        args: [action],
         liveness: false,
     };
 }
@@ -206,6 +262,7 @@ export function cooldown(action, steps) {
         formula: f,
         desc: `\`${action}\` has a cooldown of ${steps} steps`,
         patternName: "cooldown",
+        args: [action, steps],
         liveness: false,
     };
 }
@@ -217,6 +274,7 @@ export function segregationOfDuty(a, b) {
     return {
         ...me,
         patternName: "segregation_of_duty",
+        args: [a, b],
         desc: `\`${a}\` and \`${b}\` must be performed by different agents`,
     };
 }
@@ -224,8 +282,9 @@ export function boundedRetry(action, maxRetries) {
     const f = new G(new Le(countVar(action), new Const(maxRetries)));
     return {
         formula: f,
-        desc: `\`${action}\` limited to ${maxRetries} retries`,
+        desc: `\`${action}\` limited to ${maxRetries} ${maxRetries === 1 ? "retry" : "retries"}`,
         patternName: "bounded_retry",
+        args: [action, maxRetries],
         liveness: false,
     };
 }
@@ -236,6 +295,7 @@ export function loopDetection(action, maxConsecutive) {
         formula: f,
         desc: `\`${action}\` max ${maxConsecutive} consecutive calls`,
         patternName: "loop_detection",
+        args: [action, maxConsecutive],
         liveness: false,
     };
 }
@@ -246,6 +306,7 @@ export function dryRunBeforeCommit(dryRun, commit) {
         ...base,
         desc: `\`${dryRun}\` dry-run must precede \`${commit}\``,
         patternName: "dry_run_before_commit",
+        args: [dryRun, commit],
     };
 }
 export function backupBeforeDestructive(backup, action) {
@@ -254,6 +315,7 @@ export function backupBeforeDestructive(backup, action) {
         ...base,
         desc: `\`${backup}\` backup must precede destructive action \`${action}\``,
         patternName: "backup_before_destructive",
+        args: [backup, action],
     };
 }
 export function auditAfter(action, audit) {
@@ -262,6 +324,7 @@ export function auditAfter(action, audit) {
         ...base,
         desc: `\`${action}\` must be followed by audit step \`${audit}\``,
         patternName: "audit_after",
+        args: [action, audit],
         liveness: true,
     };
 }
@@ -278,6 +341,7 @@ export function approvalFreshness(approval, action, steps) {
         formula: f,
         desc: `\`${action}\` requires approval \`${approval}\` within ${steps} steps`,
         patternName: "approval_freshness",
+        args: [approval, action, steps],
         liveness: false,
     };
 }
@@ -290,6 +354,7 @@ export function sanitizedBeforeSink(source, sanitizer, sink) {
         formula: f,
         desc: `after \`${source}\`, \`${sanitizer}\` must precede \`${sink}\``,
         patternName: "sanitized_before_sink",
+        args: [source, sanitizer, sink],
         liveness: false,
     };
 }
@@ -304,6 +369,7 @@ export function duplicateCallLimit(tool, argsPattern, maxCount) {
         formula: f,
         desc: `\`${tool}\` calls matching ${JSON.stringify(argsPattern)} at most ${maxCount} times`,
         patternName: "duplicate_call_limit",
+        args: [tool, argsPattern, maxCount],
         liveness: false,
     };
 }
@@ -319,6 +385,7 @@ export function argBlacklist(tool, field, patterns) {
         formula: f,
         desc: `\`${tool}\`.${field} must not match ${JSON.stringify(patterns)}`,
         patternName: "arg_blacklist",
+        args: [tool, field, patterns],
         liveness: false,
     };
 }
@@ -338,6 +405,7 @@ export function argAllowlist(tool, field, patterns) {
         formula: f,
         desc: `\`${tool}\`.${field} must match one of ${JSON.stringify(patterns)}`,
         patternName: "arg_allowlist",
+        args: [tool, field, patterns],
         liveness: false,
     };
 }
@@ -348,6 +416,7 @@ export function scopeLimit(tool, allowedPaths) {
         formula: f,
         desc: `\`${tool}\` restricted to paths: ${allowedPaths.join(", ")}`,
         patternName: "scope_limit",
+        args: [tool, allowedPaths],
         liveness: false,
     };
 }
@@ -358,6 +427,7 @@ export function argLengthLimit(tool, param, maxChars) {
         formula: f,
         desc: `\`${tool}\`.${param} must not exceed ${maxChars} characters`,
         patternName: "arg_length_limit",
+        args: [tool, param, maxChars],
         liveness: false,
     };
 }
@@ -367,6 +437,7 @@ export function dataIntact(boundTool, originalPaths) {
         formula: f,
         desc: `\`${boundTool}\` must use only original data from ${originalPaths.join(", ")}`,
         patternName: "data_intact",
+        args: [boundTool, originalPaths],
         liveness: false,
     };
 }
@@ -379,6 +450,7 @@ export function destructiveActionGate(tool, approverRole = "approver") {
         formula: f,
         desc: `\`${tool}\` is destructive and requires \`${approverRole}\` approval`,
         patternName: "destructive_action_gate",
+        args: [tool, approverRole],
         liveness: false,
     };
 }
@@ -392,7 +464,7 @@ export function untrustedSourceGate(source, sink, confirm = "") {
             patternName: "untrusted_source_gate_assumption",
             liveness: false,
         },
-        enforcement: mustPrecede(confirmAction, sink),
+        guarantee: mustPrecede(confirmAction, sink),
     };
 }
 export function requiredStepsCompletion(trigger, steps) {
@@ -429,6 +501,7 @@ export function requiredStepsCompletion(trigger, steps) {
         formula: f,
         desc: `after \`${trigger}\`, all steps must complete: ${steps.join(", ")}`,
         patternName: "required_steps_completion",
+        args: [trigger, steps],
         liveness: true,
     };
 }
@@ -446,15 +519,111 @@ export function toolAllowlist(allowedTools) {
     const formula = new G(new Implies(new Atom("called_any"), disjunction));
     return {
         formula,
-        desc: `only allowed tools: ${allowedTools.join(", ")}`,
+        desc: `only [${allowedTools.join(", ")}] may be called`,
         patternName: "tool_allowlist",
+        args: [allowedTools],
         liveness: false,
     };
 }
+/**
+ * Substitute a forbidden tool call with a pre-approved safe one.
+ *
+ * Parity with Python ``sponsio.patterns.library.redirect_to_safe``:
+ * compiles to ``G(Not(called(unsafe)))``, so any call to ``unsafe`` is
+ * a violation.
+ *
+ * **Important runtime caveat.** The TS SDK is currently det-only and
+ * has no strategy / dispatch system. The formula side of
+ * ``redirectToSafe`` works here (a violation IS surfaced), but the TS
+ * SDK does NOT yet do the Python-side trick of bundling a
+ * ``RedirectToSafe`` strategy on the formula and having adapter
+ * ``wrap()`` paths substitute the call. The runtime outcome on TS is
+ * functionally a block: the unsafe tool is rejected, and the user's
+ * application loop has to decide whether to dispatch the safe
+ * substitute manually. Full strategy / dispatch parity is tracked as
+ * a separate work item. Users wiring redirect-style contracts who
+ * need transparent substitution should stay on the Python SDK
+ * (LangGraph adapter) until the TS strategy port lands.
+ */
+/**
+ * Every emitted claim of this predicate must verify as PASS.
+ *
+ * Compiles to `G(claim_emitted(pred) -> evidence_verdict(pred, PASS))`.
+ * Both atoms are grounded from the same `evidence` event, so the
+ * implication is decided at the timestep the verdict lands: a claim
+ * whose verdict is anything but PASS (MISMATCH, UNDERDETERMINED,
+ * NO_EVIDENCE, STALE, SOURCE_UNAVAILABLE, EXTRACTION_AMBIGUOUS)
+ * violates immediately.
+ *
+ * Parity with `sponsio.patterns.library.claim_requires_evidence`.
+ */
+export function claimRequiresEvidence(pred, desc) {
+    ensureNonEmpty(pred, "claimRequiresEvidence", "pred");
+    return {
+        formula: new G(new Implies(new Atom("claim_emitted", [pred]), new Atom("evidence_verdict", [pred, "PASS"]))),
+        desc: desc || `claims of ${pred} must verify against evidence (PASS)`,
+        patternName: "claim_requires_evidence",
+        args: [pred],
+        liveness: false,
+    };
+}
+/**
+ * An UNDERDETERMINED verdict must resolve to a clarify action.
+ *
+ * Compiles to `G(evidence_verdict(pred, UNDERDETERMINED) ->
+ * evidence_action(pred, clarify))`.
+ *
+ * Guards the policy wiring rather than the claim itself: when the
+ * evidence was ambiguous, the recorded action on that same event must be
+ * `clarify`. A project override that quietly releases or hard-blocks an
+ * ambiguous claim trips this contract.
+ *
+ * Parity with `sponsio.patterns.library.underdetermined_must_clarify`.
+ */
+export function underdeterminedMustClarify(pred, desc) {
+    ensureNonEmpty(pred, "underdeterminedMustClarify", "pred");
+    return {
+        formula: new G(new Implies(new Atom("evidence_verdict", [pred, "UNDERDETERMINED"]), new Atom("evidence_action", [pred, "clarify"]))),
+        desc: desc || `ambiguous ${pred} claims must be clarified, not released or blocked`,
+        patternName: "underdetermined_must_clarify",
+        args: [pred],
+        liveness: false,
+    };
+}
+export function redirectToSafe(unsafe, safe) {
+    ensureDistinct(unsafe, safe, "redirectToSafe", "unsafe", "safe");
+    return {
+        formula: new G(new Not(called(unsafe))),
+        desc: `redirect \`${unsafe}\` -> \`${safe}\``,
+        patternName: "redirect_to_safe",
+        args: [unsafe, safe],
+        liveness: false,
+        strategy: "redirect",
+        safeName: safe,
+    };
+}
+/**
+ * Recursive ``rm`` in any spelling: ``rm -rf``, ``rm -fr``, ``rm -Rf``,
+ * ``rm -r``, ``rm -f -r``, ``rm --recursive --force``, ``rm -v --recursive``.
+ * ``count_with`` is a regex over the serialized args, so a literal
+ * ``"rm -rf"`` only caught that one spelling. Mirrors
+ * ``RM_RECURSIVE_PATTERN`` in ``sponsio/patterns/library.py``; keep the
+ * two in sync.
+ */
+export const RM_RECURSIVE_PATTERN = "\\brm(?:\\s+(?:-[a-zA-Z]+|--[a-z-]+))*\\s+(?:-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)(?=\\s|$)";
 export function dangerousBashCommands(forbidden) {
+    // Same list and order as the Python default so the two runtimes emit
+    // identical descriptions and block the same commands.
     const defaults = [
-        "sed -i", "rm -rf", "cp /app/data", "mv /app/data",
-        "python -c", "chmod", "> /app", "tee /app",
+        RM_RECURSIVE_PATTERN,
+        "sudo",
+        "chmod",
+        "sed -i",
+        "python -c",
+        "> /app",
+        "cp /app/data",
+        "mv /app/data",
+        "tee /app",
     ];
     const cmds = forbidden ?? defaults;
     // G(count_with(bash, cmd) <= 0) for each cmd — AND them all
@@ -467,6 +636,7 @@ export function dangerousBashCommands(forbidden) {
         formula: f,
         desc: `bash commands [${cmds.join(", ")}] are banned`,
         patternName: "dangerous_bash_commands",
+        args: [cmds],
         liveness: false,
     };
 }
@@ -509,6 +679,7 @@ export function dangerousSqlVerbs(tool = "execute_sql", forbidden) {
         formula: f,
         desc: `\`${tool}\` must not use SQL verbs [${verbs.join(", ")}]`,
         patternName: "dangerous_sql_verbs",
+        args: [tool, verbs],
         liveness: false,
     };
 }
@@ -518,6 +689,7 @@ export function irreversibleOnce(action) {
         formula: f,
         desc: `\`${action}\` is irreversible and may be called at most once`,
         patternName: "irreversible_once",
+        args: [action],
         liveness: false,
     };
 }
@@ -529,9 +701,10 @@ export function confirmAfterSource(source, action) {
             formula: called(source),
             desc: `\`${source}\` has been called`,
             patternName: "confirm_after_source_assumption",
+            args: [source, action],
             liveness: false,
         },
-        enforcement: mustPrecede(confirm, action),
+        guarantee: mustPrecede(confirm, action),
     };
 }
 // --- Resource / delegation patterns ---
@@ -541,6 +714,7 @@ export function tokenBudget(maxTokens, scope = "total") {
         formula: f,
         desc: `session ${scope} tokens must not exceed ${maxTokens}`,
         patternName: "token_budget",
+        args: [maxTokens, scope],
         liveness: false,
     };
 }
@@ -570,6 +744,7 @@ export function argValueRange(tool, field, minVal, maxVal) {
         formula: f,
         desc: `\`${tool}\`.${field} must be in range ${rangeStr}`,
         patternName: "arg_value_range",
+        args: [tool, field, minVal, maxVal],
         liveness: false,
     };
 }
@@ -579,7 +754,219 @@ export function delegationDepthLimit(maxDepth) {
         formula: f,
         desc: `delegation chain must not exceed depth ${maxDepth}`,
         patternName: "delegation_depth_limit",
+        args: [maxDepth],
+        liveness: false,
+    };
+}
+// --- Layer 3 — Response content patterns ---
+/** Default PII regex set, mirrored from Python ``_DEFAULT_PII_PATTERNS``. */
+const DEFAULT_PII_PATTERNS = {
+    ssn: "\\b\\d{3}-\\d{2}-\\d{4}\\b",
+    credit_card: "\\b\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}\\b",
+    email: "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b",
+    phone: "\\b(?:\\+?1[-.\\s]?)?\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b",
+};
+/**
+ * Response length must stay within the given word / character budget.
+ *
+ * Grounded against ``response_words`` / ``response_chars`` populated on
+ * ``llm_response`` events with content. At non-response events both
+ * default to 0, so the constraint is vacuously satisfied.
+ */
+export function maxLength(opts) {
+    const { maxWords, maxChars, desc } = opts;
+    if (maxWords == null && maxChars == null) {
+        throw new Error("max_length requires maxWords or maxChars");
+    }
+    const parts = [];
+    if (maxWords != null)
+        parts.push(new Le(new Var("response_words"), new Const(maxWords)));
+    if (maxChars != null)
+        parts.push(new Le(new Var("response_chars"), new Const(maxChars)));
+    const body = parts.length === 1 ? parts[0] : new And(parts[0], parts[1]);
+    const f = new G(body);
+    let descStr;
+    if (desc)
+        descStr = desc;
+    else if (maxWords != null && maxChars != null)
+        descStr = `response ≤ ${maxWords} words and ≤ ${maxChars} chars`;
+    else if (maxWords != null)
+        descStr = `response ≤ ${maxWords} words`;
+    else
+        descStr = `response ≤ ${maxChars} chars`;
+    return {
+        formula: f,
+        desc: descStr,
+        patternName: "max_length",
+        liveness: false,
+    };
+}
+/**
+ * Response must not contain regex-detectable PII (SSN, CC, email, phone).
+ *
+ * Uses the ``llm_said`` grounding atom — the selected default patterns
+ * are joined with ``|`` and matched against each ``llm_response`` event.
+ * For semantic PII detection (names, contextual identifiers) use a sto
+ * atom; this pattern only covers syntactic PII.
+ */
+export function noPii(fields) {
+    const selected = fields ?? Object.keys(DEFAULT_PII_PATTERNS);
+    const unknown = selected.filter((f) => !(f in DEFAULT_PII_PATTERNS));
+    if (unknown.length > 0) {
+        throw new Error(`unknown PII field(s): ${JSON.stringify(unknown.sort())}. ` +
+            `Available: ${JSON.stringify(Object.keys(DEFAULT_PII_PATTERNS).sort())}`);
+    }
+    const pattern = selected.map((f) => DEFAULT_PII_PATTERNS[f]).join("|");
+    const f = new G(new Not(new Atom("llm_said", [pattern])));
+    return {
+        formula: f,
+        desc: `response must not contain PII (${selected.join(", ")})`,
+        patternName: "no_pii",
+        args: [selected],
+        liveness: false,
+    };
+}
+/**
+ * Response must not contain any of the given keywords. Keywords are
+ * escaped and joined into a word-boundary-anchored regex checked
+ * against each ``llm_response`` event via ``llm_said``.
+ *
+ * JS regex doesn't support inline ``(?i)`` flags — we lower-case the
+ * regex by expanding letters to ``[aA]``-style char classes, matching
+ * Python's ``(?i)`` semantics.
+ */
+export function noKeywords(words) {
+    if (!words || words.length === 0) {
+        throw new Error("no_keywords requires at least one keyword");
+    }
+    const pattern = `\\b(${words.map((w) => caseInsensitiveLiteral(w)).join("|")})\\b`;
+    const f = new G(new Not(new Atom("llm_said", [pattern])));
+    return {
+        formula: f,
+        desc: `response must not contain keywords: ${JSON.stringify(words)}`,
+        patternName: "no_keywords",
+        args: [words],
         liveness: false,
     };
 }
+// --- Layer 3 — External-fact (ctx) patterns ---
+/**
+ * When ``tool`` is called, ``ctx[key]`` must be one of ``allowedValues``.
+ * Fail-closed: missing context evaluates to violation, so forgetting
+ * to wire ``observeContext`` is loud rather than silent.
+ */
+export function ctxRequired(tool, key, allowedValues) {
+    ensureNonEmpty(tool, "ctxRequired", "tool");
+    ensureNonEmpty(key, "ctxRequired", "key");
+    if (!allowedValues || allowedValues.length === 0) {
+        throw new Error("ctx_required: 'allowed_values' must not be empty — an empty " +
+            "allowlist rejects every call to the tool. Use " +
+            "`tool_allowlist([])` if you really want to block everything.");
+    }
+    const cleanValues = allowedValues.map((v) => String(v));
+    let disjunction = new Atom("ctx", [key, cleanValues[0]]);
+    for (let i = 1; i < cleanValues.length; i++) {
+        disjunction = new Or(disjunction, new Atom("ctx", [key, cleanValues[i]]));
+    }
+    const f = new G(new Implies(called(tool), disjunction));
+    return {
+        formula: f,
+        desc: `${tool} requires ctx[${key}] ∈ [${cleanValues.join(", ")}]`,
+        patternName: "ctx_required",
+        args: [tool, key, cleanValues],
+        liveness: false,
+    };
+}
+/**
+ * When ``tool`` is called, ``ctx[key]`` must match the regex ``pattern``.
+ * Regex variant of :func:`ctxRequired` for cases where the allowed set
+ * is better expressed as a pattern than an exhaustive list.
+ */
+export function ctxMatchesRequired(tool, key, pattern) {
+    ensureNonEmpty(tool, "ctxMatchesRequired", "tool");
+    ensureNonEmpty(key, "ctxMatchesRequired", "key");
+    ensureNonEmpty(pattern, "ctxMatchesRequired", "pattern");
+    const f = new G(new Implies(called(tool), new Atom("ctx_matches", [key, pattern])));
+    return {
+        formula: f,
+        desc: `${tool} requires ctx[${key}] to match /${pattern}/`,
+        patternName: "ctx_matches_required",
+        args: [tool, key, pattern],
+        liveness: false,
+    };
+}
+// --- Time-window patterns (event-clock) ---
+/**
+ * Constrain how recently a predicate was last true. The argument is the
+ * grounded predicate key string (e.g. ``"called(refund)"`` or
+ * ``"ctx(approval.role, alice)"``) — same convention as Python's
+ * ``time_since`` factory.
+ */
+export function timeSince(predicateKey, maxSeconds) {
+    ensureNonEmpty(predicateKey, "timeSince", "predicate_key");
+    if (typeof maxSeconds !== "number" || !Number.isFinite(maxSeconds) || maxSeconds < 0) {
+        throw new Error(`time_since: max_seconds must be a non-negative number (got ${maxSeconds}).`);
+    }
+    const f = new G(new Le(new Var("time_since", predicateKey), new Const(maxSeconds)));
+    return {
+        formula: f,
+        desc: `${predicateKey} must have occurred within last ${maxSeconds}s`,
+        patternName: "time_since",
+        args: [predicateKey, maxSeconds],
+        liveness: false,
+    };
+}
+/**
+ * Gate ``action`` on a recent allow-decision approval from ``role``.
+ *
+ * Compiles to::
+ *   G(called(action) → (
+ *     ctx_matches("approval.role", role)
+ *     ∧ ctx_matches("approval.decision", "allow")
+ *     ∧ time_since("ctx(approval.role, role)") ≤ maxSeconds
+ *   ))
+ *
+ * Pairs with ``observeApproval({role, decision})`` on the integration
+ * side.
+ */
+export function approvalActive(action, role, maxSeconds) {
+    ensureNonEmpty(action, "approvalActive", "action");
+    ensureNonEmpty(role, "approvalActive", "role");
+    if (typeof maxSeconds !== "number" || !Number.isFinite(maxSeconds) || maxSeconds < 0) {
+        throw new Error(`approval_active: max_seconds must be a non-negative number (got ${maxSeconds}).`);
+    }
+    // Match Python: ``role_key = f"ctx(approval.role, {role})"`` — exact
+    // string used as the time_since target. predKey would escape spaces /
+    // commas; keep the unescaped form so the time_since extractor passes
+    // the right key through to grounding's ``state.last_ts`` lookup.
+    const roleKey = `ctx(approval.role, ${role})`;
+    const escaped = role.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const body = new And(new And(new Atom("ctx_matches", ["approval.role", escaped]), new Atom("ctx_matches", ["approval.decision", "allow"])), new Le(new Var("time_since", roleKey), new Const(maxSeconds)));
+    const f = new G(new Implies(called(action), body));
+    return {
+        formula: f,
+        desc: `${action} requires active ${role} approval (≤${maxSeconds}s old)`,
+        patternName: "approval_active",
+        args: [action, role, maxSeconds],
+        liveness: false,
+    };
+}
+/**
+ * @deprecated — use :func:`mutualExclusion` instead.
+ *
+ * In sequential traces, two tool calls are always at different
+ * timesteps, so the formula ``G(¬(called(A) ∧ called(B)))`` is
+ * trivially satisfied and can never detect violations. Delegates to
+ * ``mutualExclusion`` for correct behavior; kept so yaml authored
+ * against Python's deprecated entry still loads.
+ */
+export function neverTogether(a, b) {
+    const me = mutualExclusion(a, b);
+    return {
+        ...me,
+        patternName: "never_together",
+        args: [a, b],
+        desc: `${a} and ${b} must never occur together`,
+    };
+}
 //# sourceMappingURL=patterns.js.map