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

package/dist/index.js

@@ -20,12 +20,16 @@
  *   if (result.blocked) { ... }
  */
 import { evaluate } from "./core/evaluator.js";
-import { groundEvent, newGroundingState, collectContentAtoms, } from "./core/grounding.js";
+import { groundEvent, newGroundingState, collectContentAtoms, validateContentPatterns, numericArg, toolMatches, } from "./core/grounding.js";
 import { parseNl } from "./core/nl-parser.js";
+import { canonicalTool, toolAliases } from "./core/tool-names.js";
 import { loadSponsoConfig, } from "./core/config-loader.js";
 import { SessionLogger } from "./core/session-log.js";
-import { ContractCheckSpan, EnforcementSpan, GuaranteeSpan, SpanCollector, } from "./core/spans.js";
+import { AgentTurnSpan, ContractCheckSpan, EnforcementSpan, GuaranteeSpan, SpanCollector, } from "./core/spans.js";
 import { renderSession } from "./render/session-view.js";
+import { CloudClient, readProject } from "./cloud/client.js";
+import * as privacy from "./cloud/privacy.js";
+import { buildViewModel, newSessionId, } from "./cloud/view-model.js";
 // Re-exports
 export { evaluate } from "./core/evaluator.js";
 export * from "./core/formula.js";
@@ -36,7 +40,19 @@ export { groundEvent, newGroundingState, collectContentAtoms, } from "./core/gro
 export { loadSponsoConfig } from "./core/config-loader.js";
 export { SessionLogger, rotateSessions } from "./core/session-log.js";
 export { contract, ContractBuilder } from "./contract.js";
-export { createJudge, LlmJudgeEvaluator, ToneEvaluator, RelevanceEvaluator, SemanticPiiFreeEvaluator, HallucinationFreeEvaluator, ScopeRespectEvaluator, MetricIntegrityEvaluator, InjectionFreeEvaluator, parseScore, } from "./core/sto.js";
+export { parseScore, CloudFeatureError } from "./core/sto.js";
+export { CloudClient, CloudError, readApiKey, readProject, baseUrl, } from "./cloud/client.js";
+export { LEVELS as PRIVACY_LEVELS } from "./cloud/privacy.js";
+export { buildViewModel, newSessionId } from "./cloud/view-model.js";
+/** Actions after which the original tool call must NOT run. */
+export const STOPPING_ACTIONS = new Set([
+    "blocked",
+    "redirected",
+]);
+/** Parity with Python's ``is_stopping_action``. */
+export function isStoppingAction(action) {
+    return STOPPING_ACTIONS.has(action);
+}
 /**
  * Best-effort accessor for the agent-facing line. Prefers the
  * structured ``agentMsg`` field when populated; falls back to
@@ -54,13 +70,34 @@ export function selectAgentMessage(violations, fallback = "Contract violation")
     }
     return fallback;
 }
+/**
+ * Fill the derived half of a verdict from the violations' actions. One
+ * place, so a new `DetAction` cannot be handled inconsistently across
+ * the several sites that build a `CheckResult`.
+ */
+export function deriveVerdict(detViolations, stoViolations = []) {
+    const acted = detViolations.filter((v) => v.action !== undefined);
+    const redirect = acted.find((v) => v.action === "redirected");
+    return {
+        blocked: acted.some((v) => v.action === "blocked"),
+        escalated: acted.some((v) => v.action === "escalated"),
+        redirected: redirect !== undefined,
+        ...(redirect?.redirectedTo !== undefined
+            ? { redirectedTo: redirect.redirectedTo }
+            : {}),
+        stopOriginal: acted.some((v) => isStoppingAction(v.action)),
+        allViolations: [...detViolations, ...stoViolations],
+        needsRetry: false,
+    };
+}
 export class Sponsio {
     agentId;
     mode;
     _contracts;
+    // Sto state. Always empty/null in this build, the constructor
+    // rejects yaml sto contracts and inline `judge:` at config load.
+    // Kept as schema-stable surface for external composition / wrapping.
     _stoContracts;
-    _judge;
-    _judgeFallback;
     _stoContext;
     _trace;
     _state;
@@ -68,6 +105,14 @@ export class Sponsio {
     _violations;
     _logger;
     _turnSpans = [];
+    // The same turns with the violations they produced, which the span
+    // tree does not carry in a form the cloud can read: it records that a
+    // contract was violated, not which pattern and arguments, and the
+    // cloud groups findings by exactly those.
+    _runSpans = [];
+    _sessionId = newSessionId();
+    _startedAt = Date.now();
+    _rulebookStamp;
     constructor(options = {}) {
         this.agentId = options.agentId ?? "agent";
         this._trace = [];
@@ -75,8 +120,6 @@ export class Sponsio {
         this._violations = [];
         this._contracts = [];
         this._stoContracts = [];
-        this._judge = null;
-        this._judgeFallback = "allow";
         this._stoContext = {};
         // ── Gather contracts + yaml-derived settings ────────────────────
         let yamlMode;
@@ -98,6 +141,13 @@ export class Sponsio {
         // ── Resolve mode: env > ctor > yaml > default ────────────────────
         this.mode = resolveMode(options.mode, yamlMode);
         // ── Parse NL strings into det formulas ───────────────────────────
+        // A contract that does not parse is a rule that is not there. In
+        // observe mode that is a warning, because the point of observe is to
+        // keep running and surface what would fire. In enforce it is fatal:
+        // the alternative is an agent that reports success while enforcing a
+        // book with holes in it, and the operator has no way to know which
+        // holes. Python raises here; TypeScript logged one line and ran on.
+        const unparsed = [];
         for (const c of sources) {
             if (typeof c === "string") {
                 const parsed = parseNl(c);
@@ -105,48 +155,172 @@ export class Sponsio {
                     this._contracts.push(parsed);
                 }
                 else {
-                    console.warn(`[sponsio] Could not parse: "${c}"`);
+                    unparsed.push(c);
                 }
             }
             else {
                 this._contracts.push(c);
             }
         }
-        // ── Sto pipeline is a Sponsio Cloud feature ──────────────────────
+        if (unparsed.length > 0) {
+            const listed = unparsed.map((c) => `  - ${c}`).join("\n");
+            if (this.mode === "enforce") {
+                throw new Error(`sponsio: ${unparsed.length} contract(s) could not be parsed, and ` +
+                    `this guard is in enforce mode. THESE RULES ARE NOT ARMED. Fix ` +
+                    `them, or write them as structured \`pattern:\` blocks in a ` +
+                    `sponsio.yaml, which covers every pattern the library has.\n` +
+                    listed);
+            }
+            console.warn(`[sponsio] ${unparsed.length} contract(s) could not be parsed and ` +
+                `are NOT armed (observe mode, so the run continues):\n${listed}`);
+        }
+        // ── Sto pipeline is not part of this build ──────────────────────
         // The managed LLM-judge catalog (`tone` / `relevance` / `llm_judge`
-        // …) and the judge client live in `sponsio[cloud]`. The OSS
-        // engine logs-and-skips any yaml sto contracts and any inline
-        // `judge:` option, never constructs an evaluator, never contacts
-        // an LLM. The API surface (`guardAfter`, `setContext`, `judge`
-        // ctor option) is preserved so a shared yaml between Python+Cloud
-        // and TS+OSS doesn't refuse to load.
-        this._judge = null;
-        this._judgeFallback = "allow";
+        // ...) and the judge client are not part of this build (the
+        // deterministic engine provides no implementation). The engine
+        // logs-and-skips any yaml sto contracts and any inline `judge:`
+        // option, never constructs an evaluator, never contacts an LLM.
+        // The API surface (`guardAfter`, `setContext`, `judge` ctor
+        // option) is preserved so a shared yaml between deterministic
+        // builds and external sto implementations doesn't refuse to load.
         for (const spec of yamlStoSpecs) {
             yamlSkipped.push({
                 kind: "sto-contract",
-                detail: `${spec.desc} (sto pipeline is a Sponsio Cloud feature)`,
+                detail: `${spec.desc} (sto pipeline is not supported in this build)`,
             });
         }
         if (options.judge) {
             yamlSkipped.push({
                 kind: "sto-contract",
-                detail: "`judge:` option ignored (sto pipeline is a Sponsio Cloud feature; install sponsio[cloud])",
+                detail: "`judge:` option ignored (sto pipeline is not supported in this build)",
             });
         }
-        // Reference yamlJudge so unused-var lints don't fire — the field
-        // is parsed by the loader for shared-yaml compatibility but the
-        // OSS engine never builds a judge from it.
+        // Reference yamlJudge so unused-var lints don't fire: the field
+        // is parsed by the loader for shared-yaml compatibility but this
+        // build never constructs a judge from it.
         void yamlJudge;
         // ── Warn once about yaml features the TS runtime can't handle ───
         warnOnceAboutSkipped(yamlSkipped);
         this._contentAtoms = collectContentAtoms(this._contracts.map((c) => c.formula));
+        // A pattern that does not compile is a broken contract; refuse to
+        // arm it rather than let it never match at runtime.
+        validateContentPatterns(this._contentAtoms);
         // ── Session log ─────────────────────────────────────────────────
         const wantLog = options.sessionLog ?? true;
         this._logger = wantLog
             ? new SessionLogger(this.agentId, { baseDir: options.sessionLogBaseDir })
             : null;
     }
+    /**
+     * Predicates whose truth depends on the *contents* of a tool call's
+     * arguments. If a call arrives with no arguments, none of these keys is
+     * written and the evaluator reads a missing key as false, which makes
+     * ``argBlacklist`` (``!arg_field_has(...)``) report "satisfied" for a
+     * call nothing looked at. Mirrors Python's
+     * ``BaseGuard._ARG_SHAPED_PREDICATES``.
+     */
+    static ARG_SHAPED_PREDICATES = [
+        "arg_has",
+        "arg_field_has",
+        "arg_length_exceeds",
+        "arg_paths_within",
+        "arg_numeric",
+        "arg_value",
+    ];
+    /** Canonical names of the tools some contract reads the arguments of. */
+    _toolsNeedingArgs() {
+        const tools = new Set();
+        for (const pred of Sponsio.ARG_SHAPED_PREDICATES) {
+            for (const raw of this._contentAtoms[pred] ?? []) {
+                const tool = raw.split("|")[0];
+                if (tool)
+                    tools.add(canonicalTool(tool));
+            }
+        }
+        return tools;
+    }
+    /** ``[tool, field]`` pairs some ``arg_numeric`` rule reads. */
+    _numericRuleTargets() {
+        const pairs = [];
+        for (const raw of this._contentAtoms["arg_numeric"] ?? []) {
+            const parts = raw.split("|");
+            if (parts.length >= 2)
+                pairs.push([parts[0], parts[1]]);
+        }
+        return pairs;
+    }
+    /**
+     * Refuse a call whose argument rules cannot be evaluated.
+     *
+     * Two cases, both of which used to read as "not violated":
+     *
+     * - The call arrived with no arguments (``{}``, ``undefined``, ``null``)
+     *   but some rule reads this tool's arguments. An adapter that loses the
+     *   arguments, a partial streamed call or a malformed payload all land
+     *   here, and every argument check would pass vacuously.
+     * - A field an ``arg_numeric`` rule bounds is present but is not a
+     *   number (``"five thousand"``). Grounding leaves ``arg_numeric`` unset
+     *   and the evaluator reads the gap as 0, which passes every upper
+     *   bound. An absent field is left alone: CLI-flag and positional rules
+     *   on ``Bash`` legitimately see calls without their flag.
+     *
+     * ``SPONSIO_ALLOW_MISSING_ARGS=1`` restores the permissive behaviour.
+     * Mirrors Python ``BaseGuard._args_unevaluable`` and
+     * ``_unreadable_numeric_arg``; both block under rule id
+     * ``args:unevaluable``.
+     */
+    _unevaluableArgs(toolName, args) {
+        const env = typeof process !== "undefined" ? process.env : undefined;
+        if (env?.SPONSIO_ALLOW_MISSING_ARGS === "1")
+            return null;
+        const empty = args == null || (typeof args === "object" && Object.keys(args).length === 0);
+        if (empty) {
+            // Every spelling grounding binds the call under, so
+            // ``mcp__shell__Bash`` meets a rule written for ``Bash``.
+            const needed = this._toolsNeedingArgs();
+            if (!toolAliases(toolName).some((alias) => needed.has(alias)))
+                return null;
+            const message = `BLOCKED: ${this.agentId}.${toolName}. \`${toolName}\` was called ` +
+                `with no arguments, but a contract inspects its arguments. The ` +
+                `check cannot be evaluated, so the call is refused rather than ` +
+                `passed unchecked (set SPONSIO_ALLOW_MISSING_ARGS=1 to allow).`;
+            return {
+                desc: message,
+                message,
+                action: "blocked",
+                ruleId: "args:unevaluable",
+                agentMsg: `The action \`${toolName}\` was rejected because its arguments ` +
+                    `were missing and a policy needs to read them. Retry with the ` +
+                    `arguments included.`,
+            };
+        }
+        const aliases = toolAliases(toolName);
+        for (const [target, field] of this._numericRuleTargets()) {
+            if (!Object.prototype.hasOwnProperty.call(args, field))
+                continue;
+            if (!toolMatches(target, aliases))
+                continue;
+            const value = args[field];
+            if (value === null || value === undefined)
+                continue;
+            if (numericArg(value) !== undefined)
+                continue;
+            const shown = JSON.stringify(String(value).slice(0, 60));
+            const message = `BLOCKED: ${this.agentId}.${toolName}. \`${field}\`=${shown} is ` +
+                `not a number, but a contract bounds it numerically. The bound ` +
+                `cannot be checked, so the call is refused rather than passed ` +
+                `unchecked (set SPONSIO_ALLOW_MISSING_ARGS=1 to allow).`;
+            return {
+                desc: message,
+                message,
+                action: "blocked",
+                ruleId: "args:unevaluable",
+                agentMsg: `The action \`${toolName}\` was rejected because \`${field}\` ` +
+                    `must be a plain number. Retry with a numeric value.`,
+            };
+        }
+        return null;
+    }
     /**
      * Check a tool call against contracts before execution.
      *
@@ -165,6 +339,20 @@ export class Sponsio {
         return this._contracts.map((c) => c.desc);
     }
     guardBefore(toolName, args = {}) {
+        const unevaluable = this._unevaluableArgs(toolName, args);
+        if (unevaluable) {
+            const violations = [unevaluable.message];
+            this._violations.push(...violations);
+            this._logViolations(toolName, violations, [unevaluable.desc], "blocked");
+            return {
+                ...deriveVerdict([unevaluable]),
+                allowed: false,
+                message: unevaluable.message,
+                violations,
+                detViolations: [unevaluable],
+                stoViolations: [],
+            };
+        }
         const event = { tool: toolName, args };
         const snapshot = this._snapshotState();
         const valuation = groundEvent(event, this._state, this._contentAtoms);
@@ -176,9 +364,24 @@ export class Sponsio {
         const violations = [];
         const violatedDescs = [];
         const detViolations = [];
+        let anyStopping = false;
         for (const contract of this._contracts) {
             const checkSpan = new ContractCheckSpan(contract.desc, "hard");
             collector.push(checkSpan);
+            // Liveness obligations (``audit_after`` / ``deadline`` /
+            // ``required_steps_completion`` / ``always_followed_by``) cannot
+            // be discharged on a *prefix* of a finite trace — checking them
+            // mid-session would fire on every trigger before the obligated
+            // step has had a chance to run. Mirrors Python's
+            // ``RuntimeMonitor`` which skips ``liveness=True`` formulas
+            // during incremental checks and revisits them at session end
+            // (``finishSession``).
+            if (contract.liveness) {
+                const guaranteeSpan = new GuaranteeSpan(contract.desc, true);
+                collector.add(guaranteeSpan, "ok");
+                collector.pop("ok");
+                continue;
+            }
             const result = evaluate(contract.formula, this._trace);
             // The TS evaluator is currently a single-pass deterministic
             // check; it doesn't separately track assumption vs guarantee
@@ -187,37 +390,71 @@ export class Sponsio {
             const guaranteeSpan = new GuaranteeSpan(contract.desc, result);
             collector.add(guaranteeSpan, result ? "ok" : "violated");
             if (!result) {
-                const verb = this.mode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
+                // Per-contract `mode:` overrides the global mode for this one
+                // verdict — same routing as Python's RuntimeMonitor.
+                const effMode = contract.mode ?? this.mode;
+                // The contract's strategy decides which outcome this is, so a
+                // `redirect_to_safe` violation reports `redirected` with its
+                // substitute instead of collapsing into a plain block. Observe
+                // never stops, whatever the strategy says.
+                const action = effMode === "observe"
+                    ? "observed"
+                    : contract.strategy === "redirect"
+                        ? "redirected"
+                        : contract.strategy === "escalate"
+                            ? "escalated"
+                            : "blocked";
+                if (isStoppingAction(action))
+                    anyStopping = true;
+                const verb = effMode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
                 const msg = `${verb}: ${this.agentId}.${toolName} — det constraint violated: ${contract.desc}`;
                 violations.push(msg);
                 violatedDescs.push(contract.desc);
+                const safe = action === "redirected" ? contract.safeName : undefined;
                 detViolations.push({
                     desc: contract.desc,
                     message: msg,
+                    action,
+                    ...(safe !== undefined ? { redirectedTo: safe, alternatives: [safe] } : {}),
                     ruleId: contract.patternName || contract.desc,
                     agentMsg: `The action \`${toolName}\` was rejected by policy ` +
                         `(${contract.patternName || contract.desc}): ${contract.desc}. ` +
-                        `Choose a different approach.`,
+                        (safe !== undefined
+                            ? `Call \`${safe}\` instead.`
+                            : `Choose a different approach.`),
                 });
                 // Nest violation + enforcement spans under the failed
                 // guarantee so the renderer can pick up the verdict word.
-                const enforce = new EnforcementSpan("DetBlock", this.mode === "enforce" ? "blocked" : "blocked");
+                const strategyName = contract.strategy === "redirect"
+                    ? "RedirectToSafe"
+                    : contract.strategy === "escalate"
+                        ? "EscalateToHuman"
+                        : "DetBlock";
+                const enforce = new EnforcementSpan(strategyName, action);
                 guaranteeSpan.children.push(enforce);
                 enforce.finish("violated");
             }
             collector.pop(result ? "ok" : "violated");
         }
         const hasViolations = violations.length > 0;
-        const blocked = hasViolations && this.mode === "enforce";
-        this._turnSpans.push(collector.finishRoot(blocked, this._contracts.length, violations.length));
-        if (blocked) {
+        const stopping = anyStopping;
+        const turn = collector.finishRoot(stopping, this._contracts.length, violations.length);
+        this._turnSpans.push(turn);
+        this._runSpans.push({ span: turn, violations: [...detViolations] });
+        if (stopping) {
             this._trace.pop();
             this._state = snapshot;
             this._violations.push(...violations);
             this._logViolations(toolName, violations, violatedDescs, "blocked");
+            // `allowed` tracks `blocked` alone, not every stopping outcome:
+            // Python computes `not any(action == "blocked")`, so a redirect
+            // stays `allowed: true` because the agent flow continues down the
+            // safe path. `stopOriginal` is the field that says the original
+            // call must not run.
+            const derived = deriveVerdict(detViolations);
             return {
-                blocked: true,
-                allowed: false,
+                ...derived,
+                allowed: !derived.blocked,
                 message: violations[0],
                 violations,
                 detViolations,
@@ -236,7 +473,7 @@ export class Sponsio {
             this._logAllow(toolName);
         }
         return {
-            blocked: false,
+            ...deriveVerdict(detViolations),
             allowed: true,
             message: "",
             violations: [],
@@ -257,6 +494,63 @@ export class Sponsio {
     /** Drop accumulated turn spans (used between sessions in tests). */
     resetSession() {
         this._turnSpans = [];
+        this._runSpans = [];
+        this._sessionId = newSessionId();
+        this._startedAt = Date.now();
+    }
+    /**
+     * This run, in the shape the cloud stores.
+     *
+     * Exposed so a caller can see exactly what would be uploaded before
+     * uploading anything, which is the question a customer under a data
+     * agreement asks first.
+     */
+    viewModel() {
+        return buildViewModel({
+            agentId: this.agentId,
+            mode: this.mode,
+            sessionId: this._sessionId,
+            startedAt: this._startedAt,
+            contracts: this._contracts,
+            spans: this._runSpans,
+            privacyLevel: privacy.resolve(),
+            ...(this._rulebookStamp === undefined
+                ? {}
+                : { rulebookStamp: this._rulebookStamp }),
+        });
+    }
+    /**
+     * Upload this run.
+     *
+     * Best-effort by construction: it resolves false rather than throwing,
+     * because losing telemetry must never change what an agent does, and a
+     * rejected upload at the end of a run is not a reason to fail the run.
+     * Silent only about the network; a misconfiguration is worth saying
+     * once, since the symptom otherwise is a customer with no runs and no
+     * explanation.
+     */
+    async uploadSession(opts = {}) {
+        const client = opts.client ?? new CloudClient();
+        if (!client.configured)
+            return false;
+        // A per-customer key resolves to its own project and must not name
+        // another, so passing nothing is both correct and safest here.
+        const project = opts.project === undefined ? readProject() : opts.project;
+        try {
+            await client.ingestSession(project ?? null, {
+                key: this._sessionId,
+                live: false,
+                vm: this.viewModel(),
+            });
+            return true;
+        }
+        catch (err) {
+            if ((process.env.SPONSIO_QUIET ?? "") !== "1") {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`sponsio: run not uploaded (${msg})\n`);
+            }
+            return false;
+        }
     }
     /**
      * Render the end-of-session view to ``out`` (defaults to stderr) —
@@ -279,9 +573,183 @@ export class Sponsio {
             callCounts: { ...this._state.callCounts },
             callWithCounts: { ...this._state.callWithCounts },
             lastTool: this._state.lastTool,
+            lastToolAliases: [...this._state.lastToolAliases],
             consecutiveCounts: { ...this._state.consecutiveCounts },
             tokenCounts: { ...this._state.tokenCounts },
             delegationDepth: this._state.delegationDepth,
+            currentCtx: { ...this._state.currentCtx },
+            now: this._state.now,
+            lastTs: { ...this._state.lastTs },
+            trueAtPrev: new Set(this._state.trueAtPrev),
+        };
+    }
+    /**
+     * Push external facts into the grounding context. Mirrors Python's
+     * ``BaseGuard.observe_context`` — every subsequent event sees the
+     * keys as ``ctx(k, v)`` atoms, so contracts like
+     * ``ctx_required("wire", "caller_id", ["alice"])`` can fire.
+     *
+     * Emits a synthetic ``context_update`` event into the trace so
+     * patterns that anchor on the moment a fact was set (notably
+     * ``time_since(ctx(approval.role, alice))``) start their clock here.
+     */
+    observeContext(ctx) {
+        const event = {
+            tool: "",
+            event_type: "context_update",
+            args: ctx,
+        };
+        const valuation = groundEvent(event, this._state, this._contentAtoms);
+        this._trace.push(valuation);
+    }
+    /**
+     * Convenience helper for the approval-active gate: pushes
+     * ``approval.role`` / ``approval.decision`` (+ optional ``approver``
+     * / ``reason``) via ``observeContext``. Pairs with the
+     * ``approval_active`` pattern.
+     */
+    observeApproval(opts) {
+        const ctx = {
+            "approval.role": opts.role,
+            "approval.decision": opts.decision ?? "allow",
+        };
+        if (opts.approver)
+            ctx["approval.approver"] = opts.approver;
+        if (opts.reason)
+            ctx["approval.reason"] = opts.reason;
+        this.observeContext(ctx);
+    }
+    /**
+     * Record an LLM response into the trace. Drives ``max_length``,
+     * ``no_pii``, ``no_keywords`` (any pattern that grounds against
+     * ``llm_said`` / ``response_words`` / ``response_chars``). Mirrors
+     * the Python ``llm_response`` event path.
+     *
+     * Returns a ``CheckResult`` so callers can branch on observe-mode
+     * violations the same way they branch on ``guardBefore``. In
+     * enforce mode, ``blocked: true`` rolls back the synthetic event.
+     */
+    /**
+     * Record a claim-verification verdict in the trace and check the
+     * contracts that reference it.
+     *
+     * Grounds `claim_emitted(pred)`, `evidence_verdict(pred, V)` and
+     * `evidence_action(pred, a)` at one timestep, so contracts built from
+     * `claimRequiresEvidence` / `underdeterminedMustClarify` can decide.
+     * No verdict is computed here: the atoms restate what
+     * `/v1/evidence/verify` answered.
+     *
+     * Parity with feeding `EvidenceResult.to_event()` through Python's
+     * trace path.
+     */
+    observeEvidence(predicate, verdict, action) {
+        return this._checkSynthetic({
+            tool: "",
+            event_type: "evidence",
+            key: predicate,
+            args: { verdict, action },
+        }, `<evidence:${predicate}>`);
+    }
+    observeResponse(content, opts = {}) {
+        const args = {};
+        if (opts.segment)
+            args.segment = opts.segment;
+        return this._checkSynthetic({ tool: "", event_type: "llm_response", content, args }, "<llm_response>");
+    }
+    /**
+     * Check one synthetic (non-tool-call) event against every contract.
+     *
+     * The output lane and the evidence lane both push an event that is not
+     * a tool call and then judge the trace. Sharing the body keeps their
+     * verdicts identical: a second copy is how one lane ends up with a
+     * rollback the other lacks.
+     *
+     * `label` names the subject in violation messages and session logs.
+     */
+    _checkSynthetic(event, label) {
+        const snapshot = this._snapshotState();
+        const valuation = groundEvent(event, this._state, this._contentAtoms);
+        this._trace.push(valuation);
+        const violations = [];
+        const violatedDescs = [];
+        const detViolations = [];
+        let anyStopping = false;
+        for (const contract of this._contracts) {
+            const result = evaluate(contract.formula, this._trace);
+            if (!result) {
+                const effMode = contract.mode ?? this.mode;
+                // No substitution on the output lane: there is no call to swap,
+                // so a redirect strategy still stops here. `escalate` keeps its
+                // own action, which does not stop.
+                const action = effMode === "observe"
+                    ? "observed"
+                    : contract.strategy === "escalate"
+                        ? "escalated"
+                        : "blocked";
+                if (isStoppingAction(action))
+                    anyStopping = true;
+                const verb = effMode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
+                const msg = `${verb}: ${this.agentId}.${label} — det constraint violated: ${contract.desc}`;
+                violations.push(msg);
+                violatedDescs.push(contract.desc);
+                detViolations.push({
+                    desc: contract.desc,
+                    message: msg,
+                    action,
+                    ruleId: contract.patternName || contract.desc,
+                    agentMsg: `LLM response was rejected by policy ` +
+                        `(${contract.patternName || contract.desc}): ${contract.desc}.`,
+                });
+            }
+        }
+        const hasViolations = violations.length > 0;
+        const stopping = anyStopping;
+        // The output lane builds no span tree, so without this a rule that
+        // fires on what the model said was enforced locally and never
+        // uploaded: at `full` a TypeScript run showed half the run a Python
+        // one showed. A bare turn is enough for the cloud, which reads the
+        // step's type, tool and verdict and not the tree under it.
+        const outTurn = new AgentTurnSpan(this.agentId, label);
+        outTurn.totalContractsChecked = this._contracts.length;
+        outTurn.detViolations = violations.length;
+        outTurn.blocked = stopping;
+        outTurn.finish(hasViolations ? "violated" : "ok");
+        this._runSpans.push({
+            span: outTurn,
+            violations: [...detViolations],
+            type: "output",
+        });
+        if (stopping) {
+            this._trace.pop();
+            this._state = snapshot;
+            this._violations.push(...violations);
+            this._logViolations(label, violations, violatedDescs, "blocked");
+            // `allowed` tracks `blocked` alone, not every stopping outcome:
+            // Python computes `not any(action == "blocked")`, so a redirect
+            // stays `allowed: true` because the agent flow continues down the
+            // safe path. `stopOriginal` is the field that says the original
+            // call must not run.
+            const derived = deriveVerdict(detViolations);
+            return {
+                ...derived,
+                allowed: !derived.blocked,
+                message: violations[0],
+                violations,
+                detViolations,
+                stoViolations: [],
+            };
+        }
+        if (hasViolations) {
+            this._violations.push(...violations);
+            this._logViolations(label, violations, violatedDescs, "observed");
+        }
+        return {
+            ...deriveVerdict(detViolations),
+            allowed: true,
+            message: "",
+            violations: [],
+            detViolations,
+            stoViolations: [],
         };
     }
     _logViolations(toolName, messages, descs, action) {
@@ -312,122 +780,32 @@ export class Sponsio {
         });
     }
     /**
-     * Record tool output after execution and run the sto pipeline.
+     * Record tool output after execution.
      *
-     * Returns a ``CheckResult`` whose ``stoViolations`` carries any
-     * stochastic rule failures (``tone`` / ``llm_judge``). When no sto
-     * contracts are declared the method returns synchronously in
-     * effect (the ``Promise`` resolves on the microtask queue) and
-     * never contacts the judge LLM.
+     * This build ships **no sto pipeline** (the engine is deterministic-only).
+     * Stochastic (LLM-judged) atoms are the extension point that would
+     * populate ``stoViolations``; with no external implementation and no
+     * sto contracts loaded (sto entries in yaml are rejected at config
+     * load), ``stoViolations`` is always ``[]`` and ``allowed: true``.
      *
-     * In **observe mode** violations are logged but the method still
-     * reports ``allowed: true``. In **enforce mode** the first sto
-     * violation flips ``blocked: true`` — but the tool output has
-     * already executed, so the caller is responsible for routing the
-     * result (retry with feedback, redirect to safe, etc.).
+     * The method stays ``async`` for API parity: an external subclass
+     * or wrapper can run the judge pipeline and surface real
+     * ``stoViolations`` without changing the call site. In **enforce
+     * mode** such subclasses can flip ``blocked: true`` on the first
+     * sto violation; the tool output has already executed, so the
+     * caller is responsible for routing the result (retry with
+     * feedback, redirect to safe, etc.).
      */
-    async guardAfter(toolName, output = "") {
-        if (this._stoContracts.length === 0) {
-            return emptyAllow();
-        }
-        const stoViolations = [];
-        const flatMessages = [];
-        for (const sto of this._stoContracts) {
-            try {
-                const result = await sto.evaluator.evaluate({
-                    toolName,
-                    output,
-                    context: this._stoContext,
-                });
-                if (result.passed) {
-                    this._logSto(sto.desc, "allowed", result.score, result.evidence);
-                    continue;
-                }
-                const verb = this.mode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
-                const msg = `${verb}: ${this.agentId}.${toolName} — sto constraint ` +
-                    `violated: ${sto.desc} (score=${result.score.toFixed(2)})`;
-                // Sto outcomes default to retry-style phrasing — the model
-                // is being asked to regenerate addressing the failed
-                // property, not to abandon the action altogether. retryHint
-                // carries the evaluator's suggestion when available.
-                stoViolations.push({
-                    desc: sto.desc,
-                    message: msg,
-                    ruleId: sto.desc,
-                    agentMsg: `Your output failed the \`${sto.desc}\` check ` +
-                        `(score=${result.score.toFixed(2)}). Regenerate addressing the issue.`,
-                    retryHint: result.evidence || undefined,
-                });
-                flatMessages.push(msg);
-                this._logSto(sto.desc, this.mode === "observe" ? "observed" : "blocked", result.score, result.evidence);
-            }
-            catch (err) {
-                const errMsg = err instanceof Error ? err.message : String(err);
-                const handling = this._judgeFallback;
-                if (handling === "skip") {
-                    console.warn(`[sponsio] sto ${sto.desc}: judge error (${errMsg}) — skipping`);
-                    continue;
-                }
-                const verb = this.mode === "observe" ? "WOULD-BLOCK" : "BLOCKED";
-                if (handling === "deny") {
-                    const msg = `${verb}: ${this.agentId}.${toolName} — sto judge error ` +
-                        `(${errMsg}); fallback_mode=deny`;
-                    stoViolations.push({ desc: sto.desc, message: msg });
-                    flatMessages.push(msg);
-                    this._logSto(sto.desc, this.mode === "observe" ? "observed" : "blocked", undefined, `judge-error: ${errMsg}`);
-                }
-                else {
-                    // allow (default) — log a pass so the operator can see the
-                    // judge was exercised, but do not create a violation.
-                    console.warn(`[sponsio] sto ${sto.desc}: judge error (${errMsg}) — allowing`);
-                    this._logSto(sto.desc, "allowed", undefined, `judge-error-allowed: ${errMsg}`);
-                }
-            }
-        }
-        if (stoViolations.length === 0) {
-            return emptyAllow();
-        }
-        this._violations.push(...flatMessages);
-        if (this.mode === "enforce") {
-            return {
-                blocked: true,
-                allowed: false,
-                message: flatMessages[0],
-                violations: flatMessages,
-                detViolations: [],
-                stoViolations,
-            };
-        }
-        return {
-            blocked: false,
-            allowed: true,
-            message: "",
-            violations: [],
-            detViolations: [],
-            stoViolations,
-        };
-    }
-    _logSto(desc, action, score, evidence) {
-        if (!this._logger)
-            return;
-        const record = {
-            ts: Date.now() / 1000,
-            agent_id: this.agentId,
-            action,
-            pipeline: "sto",
-            constraint: desc,
-            result: {
-                action,
-                message: evidence ?? "",
-            },
-        };
-        if (score !== undefined) {
-            record.sto = evidence ? { score, evidence } : { score };
-        }
-        this._logger.log(record);
+    async guardAfter(_toolName, _output = "") {
+        // This build is deterministic-only, the sto pipeline is not
+        // implemented. Always return clean-pass; external subclasses can
+        // override.
+        return emptyAllow();
     }
     /**
-     * Reset guard state for a new session.
+     * Reset guard state for a new session. Clears the trace, the
+     * grounding accumulators (including ``currentCtx``, ``lastTs``,
+     * event clock), the violation log, and the sto-context snapshot.
      */
     reset() {
         this._trace = [];
@@ -437,11 +815,15 @@ export class Sponsio {
         this._contentAtoms = collectContentAtoms(this._contracts.map((c) => c.formula));
     }
     /**
-     * Stash per-turn context for the sto pipeline. Atoms that need
-     * grounding — ``relevance`` (``query``), ``hallucination_free``
-     * (``source``), ``scope_respect`` (``scope`` override),
-     * ``metric_integrity`` (``history``) — read from this snapshot on
-     * the next ``guardAfter`` call.
+     * Stash per-turn context for the sto pipeline.
+     *
+     * Not supported in this build (the engine is deterministic-only).
+     * Atoms that need grounding (``relevance`` -> ``query``,
+     * ``hallucination_free`` -> ``source``, ``scope_respect`` ->
+     * ``scope`` override, ``metric_integrity`` -> ``history``) would
+     * read from this snapshot on the next ``guardAfter`` call. This
+     * build accepts the call as a no-op so shared agent code can stay
+     * framework-neutral; the snapshot is never consumed.
      *
      * Merges with any previously-set context; pass ``{ query: undefined }``
      * to explicitly clear a field. ``reset()`` clears the whole snapshot.
@@ -499,12 +881,13 @@ function resolveMode(ctorMode, yamlMode) {
 }
 let _skippedWarned = false;
 // Note: ``resolveJudge`` / ``buildStoContract`` / ``isJudgeClient``
-// helpers were removed when the sto pipeline became Sponsio Cloud-only.
-// The OSS engine never constructs a judge or evaluator; yaml sto
-// specs flow through the ``yamlSkipped`` warning path in the ctor.
+// helpers were removed when the sto pipeline became an external
+// extension point. This build never constructs a judge or evaluator;
+// yaml sto specs flow through the ``yamlSkipped`` warning path in
+// the ctor.
 function emptyAllow() {
     return {
-        blocked: false,
+        ...deriveVerdict([]),
         allowed: true,
         message: "",
         violations: [],
@@ -533,8 +916,12 @@ function warnOnceAboutSkipped(skipped) {
     if (unknown > 0) {
         bits.push(`${unknown} unrecognised contract entr${unknown === 1 ? "y" : "ies"}`);
     }
+    const stoNote = sto > 0
+        ? " Sto (LLM-judge) contracts are not supported in this build (the engine is deterministic-only)."
+        : "";
     console.warn("[sponsio] skipped unsupported yaml items: " +
         bits.join("; ") +
-        ". These features are Python-only today; TS runtime will ship them in a future release.");
+        "." +
+        stoNote);
 }
 //# sourceMappingURL=index.js.map