psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/cross_model_codex_verify.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# Bash 3.2-compatible entry point for the #630 citation-only transport.
+set -u
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) || exit 1
+exec python3 "$SCRIPT_DIR/cross_model_codex_transport.py" verify

package/vendor/ars/scripts/cross_model_handoff.py

@@ -0,0 +1,359 @@
+#!/usr/bin/env python3
+"""Reference grammar + routing for the #527 cross-model handoff envelope.
+
+`shared/cross_model_verification.md` § Cross-model handoff envelope (#527)
+names this module as the NORMATIVE grammar: the prose describes the contract,
+this module decides it. A dispatcher (the main session running a skill, or
+`pipeline_orchestrator_agent` in pipeline Mode A) that consumes an owner's
+handoff block behaves exactly like `parse_handoff` + `route_result`; the
+deterministic owner → dispatcher → owner fixtures in
+`scripts/test_cross_model_handoff.py` pin that behavior with a fake
+transport (no external API, no manuscript upload).
+
+Design constraints inherited from #523/#518:
+
+- The owner's committed decision travels OUTSIDE the payload; only the
+  payload is ever forwarded to the cross-model (blindness).
+- Agreement → the dispatcher performs the mechanical fill and does NOT
+  re-invoke the owner. Divergence → the dispatcher re-invokes the original
+  owner with the minimum return context; it never authors the rebuttal.
+- Anything malformed (envelope or result) fails safely to `unavailable` —
+  the dispatcher never fabricates a judgment.
+"""
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from dataclasses import dataclass, field
+
+OPEN_FENCE = "[CROSS-MODEL-HANDOFF v1]"
+CLOSE_FENCE = "[/CROSS-MODEL-HANDOFF]"
+# Any handoff-shaped opener, any version. A v2 fence must be REJECTED as
+# malformed, never silently treated as an ordinary deliverable (fail-closed
+# on unknown versions — codex #527 round-1 P1).
+_ANY_OPEN_FENCE_RE = re.compile(r"^\[CROSS-MODEL-HANDOFF\b.*\]$")
+
+CHECKPOINT_KINDS = {
+    # kind -> (expected_result, decision enum or None)
+    "design_freeze": (
+        "enum_comparison",
+        ("sound", "revise_before_freeze", "fundamental_concern"),
+    ),
+    "editorial_decision": (
+        "enum_comparison",
+        ("accept", "minor_revision", "major_revision", "reject"),
+    ),
+    "da_critique": ("full_return", None),
+}
+# Closed kind -> owner binding: a design_freeze envelope claiming a different
+# owner would route the divergence re-invocation to the wrong agent,
+# violating "re-invoke the ORIGINAL owner" (codex #527 round-1 P1).
+EXPECTED_OWNERS = {
+    "design_freeze": "research_architect_agent",
+    "editorial_decision": "editorial_synthesizer_agent",
+    "da_critique": "devils_advocate_reviewer_agent",
+}
+EXPECTED_RESULTS = ("enum_comparison", "full_return")
+CONFIDENCE_VALUES = ("low", "medium", "high")
+MAX_DRIVERS = 3
+
+# Routing outcomes (the dispatcher's complete decision space).
+AGREEMENT_FILL = "agreement_fill_no_reinvoke"
+DIVERGENCE_REINVOKE = "divergence_reinvoke_owner"
+FULL_RETURN_REINVOKE = "full_return_reinvoke_owner"
+UNAVAILABLE = "unavailable"
+
+
+class HandoffError(ValueError):
+    """Malformed envelope or result. Dispatchers map this to
+    `[CROSS-MODEL-ERROR: <reason>]` + outcome `unavailable` — never a
+    fabricated judgment."""
+
+
+@dataclass
+class Handoff:
+    checkpoint_kind: str
+    owner_agent: str
+    correlation_id: str
+    expected_result: str
+    payload: str
+    decision_enum: tuple[str, ...] | None = None
+    owner_decision: dict | None = None
+
+
+@dataclass
+class Routing:
+    outcome: str  # one of AGREEMENT_FILL / DIVERGENCE_REINVOKE / FULL_RETURN_REINVOKE / UNAVAILABLE
+    error: str | None = None
+    # Minimum context the dispatcher MUST return to the owner on
+    # re-invocation (empty when no re-invocation happens).
+    return_context: dict = field(default_factory=dict)
+
+
+_HEADER_RE = re.compile(r"^([a-z_]+):[ \t]*(.*)$")
+_REQUIRED_HEADERS = ("checkpoint_kind", "owner_agent", "correlation_id", "expected_result")
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
+    """json.loads keeps the LAST duplicate key silently — an object with two
+    different `decision` values would be routed by the latter (codex #527
+    round-10 P1). Reject ambiguity instead."""
+    obj: dict = {}
+    for key, value in pairs:
+        if key in obj:
+            raise ValueError(f"duplicate JSON key {key!r}")
+        obj[key] = value
+    return obj
+
+
+def _reject_constant(name: str):
+    # NaN / Infinity / -Infinity are not standard JSON — a "strict" decision
+    # object must not smuggle them through (codex #527 round-13 P1).
+    raise ValueError(f"non-standard JSON constant {name!r}")
+
+
+def _loads_strict(raw: str):
+    return json.loads(
+        raw,
+        object_pairs_hook=_reject_duplicate_keys,
+        parse_constant=_reject_constant,
+    )
+
+
+def _is_blank(text: str) -> bool:
+    """Blank = nothing left after stripping whitespace AND Unicode format
+    (Cf) characters — an invisible-only payload or response must not count
+    as substance (codex #527 round-11 P1)."""
+    return not "".join(
+        c for c in text if unicodedata.category(c) != "Cf"
+    ).strip()
+
+
+def _fold_for_detection(line: str) -> str:
+    """Strip whitespace AND Unicode format (Cf) characters for fence
+    DETECTION only — a zero-width-prefixed fence must be detected (then
+    rejected by the raw-equality acceptance check), not skipped as an
+    ordinary deliverable (#524 fold-before-compare lesson). Acceptance
+    stays raw column-0 equality."""
+    return "".join(c for c in line if unicodedata.category(c) != "Cf").strip()
+
+
+def _is_fence_shaped(line: str) -> bool:
+    folded = _fold_for_detection(line)
+    return bool(_ANY_OPEN_FENCE_RE.match(folded)) or folded == CLOSE_FENCE
+
+
+def extract_handoff_block(text: str) -> str | None:
+    """Return the first fenced handoff block (fences included), or None.
+
+    Recognition rule: both fences must sit at the start of their own line.
+    An output with no block is an ordinary deliverable — the dispatcher
+    must not invent a transport for it.
+    """
+    lines = text.splitlines()
+    # Detection is generous (stripped match, any version) so nothing
+    # handoff-shaped can pass as an ordinary deliverable; ACCEPTANCE is
+    # strict (raw line equality at column 0, exact v1) so an indented or
+    # re-versioned fence is malformed, never transported (codex #527
+    # round-5 P1: indented fences).
+    opens = [i for i, l in enumerate(lines) if _ANY_OPEN_FENCE_RE.match(_fold_for_detection(l))]
+    closes = [i for i, l in enumerate(lines) if _fold_for_detection(l) == CLOSE_FENCE]
+    if not opens and not closes:
+        return None
+    if len(opens) > 1 or len(closes) > 1:
+        # A fence-shaped line inside the payload (or a second envelope)
+        # would silently truncate/confuse extraction — reject the whole
+        # output instead of guessing which fence is real (codex #527
+        # round-2 P1: closing-fence collision).
+        raise HandoffError(
+            "malformed_handoff: ambiguous fences — exactly one envelope per "
+            "output, and the payload must not contain a fence-shaped line"
+        )
+    if not opens:
+        raise HandoffError("malformed_handoff: closing fence without opening fence")
+    start = opens[0]
+    if lines[start] != OPEN_FENCE:
+        raise HandoffError(
+            f"malformed_handoff: fence {lines[start]!r} is not the exact "
+            f"column-0 {OPEN_FENCE!r} (indented or unknown-version fences "
+            f"are rejected, never transported)"
+        )
+    if not closes or closes[0] < start:
+        raise HandoffError("malformed_handoff: opening fence without closing fence")
+    if lines[closes[0]] != CLOSE_FENCE:
+        raise HandoffError("malformed_handoff: closing fence must sit at column 0")
+    return "\n".join(lines[start : closes[0] + 1])
+
+
+def parse_handoff(block: str) -> Handoff:
+    """Parse one fenced block into a validated Handoff.
+
+    Raises HandoffError on ANY deviation: unknown version fence, missing or
+    duplicate header, unknown checkpoint_kind, expected_result mismatch with
+    the kind, missing/invalid owner_decision for enum_comparison, missing
+    payload. Fail-closed: an envelope the dispatcher cannot fully validate
+    is a transport failure, not a best-effort guess.
+    """
+    lines = block.splitlines()
+    if not lines or lines[0] != OPEN_FENCE:
+        raise HandoffError("malformed_handoff: missing or unknown version fence")
+    if lines[-1] != CLOSE_FENCE:
+        raise HandoffError("malformed_handoff: missing closing fence")
+
+    headers: dict[str, str] = {}
+    payload_lines: list[str] | None = None
+    for raw in lines[1:-1]:
+        if _is_fence_shaped(raw):
+            # parse_handoff enforces the no-fence-inside rule itself, so a
+            # caller that skips extract_handoff_block gets the same
+            # rejection (codex #527 round-6 P1).
+            raise HandoffError(
+                "malformed_handoff: fence-shaped line inside the envelope "
+                "(the payload must not contain a fence-shaped line)"
+            )
+        if payload_lines is not None:
+            payload_lines.append(raw)
+            continue
+        if raw.strip() == "payload:":
+            payload_lines = []
+            continue
+        if not raw.strip():
+            continue
+        m = _HEADER_RE.match(raw)
+        if not m:
+            raise HandoffError(f"malformed_handoff: unparseable header line {raw!r}")
+        key, value = m.group(1), m.group(2).strip()
+        if key in headers:
+            raise HandoffError(f"malformed_handoff: duplicate header {key!r}")
+        headers[key] = value
+
+    for key in _REQUIRED_HEADERS:
+        # A value that is blank after Cf-folding (e.g. a zero-width-only
+        # correlation_id) is missing, not a stable token (codex #527
+        # round-13 P1).
+        if key not in headers or _is_blank(headers[key]):
+            raise HandoffError(f"malformed_handoff: missing header {key!r}")
+    unknown = set(headers) - set(_REQUIRED_HEADERS) - {"owner_decision"}
+    if unknown:
+        raise HandoffError(f"malformed_handoff: unknown header(s) {sorted(unknown)}")
+    if payload_lines is None or _is_blank("\n".join(payload_lines)):
+        raise HandoffError("malformed_handoff: missing payload")
+
+    kind = headers["checkpoint_kind"]
+    if kind not in CHECKPOINT_KINDS:
+        raise HandoffError(f"malformed_handoff: unknown checkpoint_kind {kind!r}")
+    expected, enum = CHECKPOINT_KINDS[kind]
+    if headers["expected_result"] != expected:
+        raise HandoffError(
+            f"malformed_handoff: checkpoint_kind {kind!r} requires "
+            f"expected_result {expected!r}, got {headers['expected_result']!r}"
+        )
+    if headers["owner_agent"] != EXPECTED_OWNERS[kind]:
+        raise HandoffError(
+            f"malformed_handoff: checkpoint_kind {kind!r} is owned by "
+            f"{EXPECTED_OWNERS[kind]!r}, not {headers['owner_agent']!r}"
+        )
+
+    owner_decision = None
+    if expected == "full_return" and "owner_decision" in headers:
+        raise HandoffError(
+            "malformed_handoff: owner_decision is REQUIRED iff enum_comparison "
+            "— a full_return envelope must not carry one"
+        )
+    if expected == "enum_comparison":
+        raw_decision = headers.get("owner_decision", "")
+        if not raw_decision:
+            raise HandoffError("malformed_handoff: enum_comparison requires owner_decision")
+        try:
+            owner_decision = _loads_strict(raw_decision)
+        except (json.JSONDecodeError, RecursionError, ValueError) as exc:
+            # RecursionError: pathologically nested JSON must fail closed
+            # like any other malformed input (codex #527 round-7 P1).
+            raise HandoffError(f"malformed_handoff: owner_decision is not JSON ({type(exc).__name__})") from exc
+        try:
+            _validate_structured_decision(owner_decision, enum, who="owner_decision")
+        except HandoffError as exc:
+            # Owner-side problems are envelope problems, not result problems.
+            raise HandoffError(str(exc).replace("malformed_result", "malformed_handoff", 1)) from exc
+
+    return Handoff(
+        checkpoint_kind=kind,
+        owner_agent=headers["owner_agent"],
+        correlation_id=headers["correlation_id"],
+        expected_result=expected,
+        payload="\n".join(payload_lines),
+        decision_enum=enum,
+        owner_decision=owner_decision,
+    )
+
+
+def _validate_structured_decision(obj: object, enum: tuple[str, ...], who: str) -> dict:
+    """The full #518 output contract: all three fields are REQUIRED —
+    `{"decision": "sound"}` alone must not route to a judgment (codex #527
+    round-1 P1)."""
+    if not isinstance(obj, dict):
+        raise HandoffError(f"malformed_result: {who} is not an object")
+    decision = obj.get("decision")
+    if decision not in enum:
+        raise HandoffError(f"malformed_result: {who} decision {decision!r} not in {enum}")
+    drivers = obj.get("drivers")
+    if (
+        not isinstance(drivers, list)
+        or len(drivers) > MAX_DRIVERS
+        or not all(isinstance(d, str) for d in drivers)
+    ):
+        raise HandoffError(
+            f"malformed_result: {who} drivers must be a list of <= {MAX_DRIVERS} strings"
+        )
+    confidence = obj.get("confidence")
+    if confidence not in CONFIDENCE_VALUES:
+        raise HandoffError(f"malformed_result: {who} confidence {confidence!r} invalid")
+    return obj
+
+
+def route_result(handoff: Handoff, transport_ok: bool, raw_result: str | None) -> Routing:
+    """The dispatcher's complete outcome routing.
+
+    - transport failure -> UNAVAILABLE (`[CROSS-MODEL-ERROR]`, single-model).
+    - enum_comparison: validated result with equal enums -> AGREEMENT_FILL
+      (mechanical fill, NO owner re-invocation); differing enums ->
+      DIVERGENCE_REINVOKE with the minimum return context; malformed /
+      unknown-enum result -> UNAVAILABLE, never fabricated.
+    - full_return: every successful response -> FULL_RETURN_REINVOKE (there
+      is no comparison the dispatcher could resolve itself).
+    """
+    if not transport_ok or raw_result is None or _is_blank(raw_result):
+        # A blank body is a failed transport, not a critique to hand back
+        # (codex #527 round-10 P1).
+        return Routing(UNAVAILABLE, error="transport_failure")
+
+    if handoff.expected_result == "full_return":
+        return Routing(
+            FULL_RETURN_REINVOKE,
+            return_context={
+                "correlation_id": handoff.correlation_id,
+                "owner_agent": handoff.owner_agent,
+                "cross_model_response": raw_result,
+            },
+        )
+
+    try:
+        result = _loads_strict(raw_result)
+        _validate_structured_decision(result, handoff.decision_enum or (), who="cross_model_result")
+    except (HandoffError, json.JSONDecodeError, RecursionError, ValueError) as exc:
+        return Routing(UNAVAILABLE, error=f"malformed_result: {type(exc).__name__}: {exc}")
+
+    assert handoff.owner_decision is not None  # guaranteed by parse_handoff
+    if result["decision"] == handoff.owner_decision["decision"]:
+        return Routing(AGREEMENT_FILL)
+    return Routing(
+        DIVERGENCE_REINVOKE,
+        return_context={
+            "correlation_id": handoff.correlation_id,
+            "owner_agent": handoff.owner_agent,
+            "owner_decision": handoff.owner_decision,
+            "cross_model_decision": result,
+            "original_payload": handoff.payload,
+        },
+    )

package/vendor/ars/scripts/cross_model_smoke_test.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# Live smoke test for the OpenAI grounded cross-model verifier route.
+#
+# Purpose: validate that a given OpenAI verifier model (ARS_CROSS_MODEL, gpt-* id)
+# behaves correctly against the documented call pattern in
+# shared/cross_model_verification.md BEFORE it is used in a real pipeline run.
+# Primary use case: vetting a newly released model id (e.g. gpt-5.6-sol, listed
+# as provisional) whose response shape / grounding behavior has no ARS operating
+# history yet.
+#
+# This is a LIVE test: it issues one real Responses API call (with hosted
+# web_search) against a stable, known-good reference. It costs a fraction of a
+# cent and needs OPENAI_API_KEY, so it is NOT wired into CI — run it manually:
+#
+#   export OPENAI_API_KEY="sk-..."
+#   export ARS_CROSS_MODEL="gpt-5.6-sol"            # model under test
+#   export ARS_CROSS_MODEL_REASONING_EFFORT="medium" # optional (default: medium)
+#   bash scripts/cross_model_smoke_test.sh
+#
+# Checks (exit 0 only if all hard checks pass):
+#   1. HTTP 2xx (transport)
+#   2. completed web_search_call present  — canonical jq guard, fail-closed
+#   3. non-empty verdict text carrying exactly ONE whole-word verdict token —
+#      single occurrence enforced (a substring hit inside e.g. "UNVERIFIED"
+#      does not count; a repeated token FAILS: the fixture prompt demands
+#      exactly one verdict, and a model that cannot comply with that
+#      instruction is itself a gate signal)
+#   4. a VERIFIED verdict carries at least one url_citation source
+#   5. response model echo matches the requested model id (prefix match on
+#      snapshot suffixes, e.g. gpt-5.5 -> gpt-5.5-2026-xx-xx)
+#   6. when ARS_CROSS_MODEL_REASONING_EFFORT is set: the response must echo the
+#      requested effort — a missing or mismatched echo FAILS (fail-closed; a
+#      provisional model silently ignoring the setting is exactly what this
+#      gate exists to catch). Skipped when the variable is unset (the request
+#      omits the field, so there is nothing to confirm).
+#
+# The known-good reference is deliberately famous and stable so a NOT_FOUND /
+# MISMATCH verdict indicates a broken search path or parser, not a bad fixture.
+set -u
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+GUARD="$REPO_ROOT/scripts/cross_model_verification"
+FAILURES=0
+
+note() { printf '%s\n' "$*"; }
+pass() { printf 'PASS: %s\n' "$*"; }
+fail() { printf 'FAIL: %s\n' "$*"; FAILURES=$((FAILURES + 1)); }
+
+# --- Preconditions -----------------------------------------------------------
+command -v jq >/dev/null 2>&1 || { echo "ERROR: jq is required"; exit 1; }
+command -v curl >/dev/null 2>&1 || { echo "ERROR: curl is required"; exit 1; }
+[ -n "${OPENAI_API_KEY:-}" ] || { echo "ERROR: OPENAI_API_KEY is not set"; exit 1; }
+[ -n "${ARS_CROSS_MODEL:-}" ] || { echo "ERROR: ARS_CROSS_MODEL is not set"; exit 1; }
+case "$ARS_CROSS_MODEL" in
+  gpt-*) : ;;
+  *) echo "ERROR: this smoke test covers the OpenAI grounded route only (gpt-* ids); got '$ARS_CROSS_MODEL'"; exit 1 ;;
+esac
+[ -f "$GUARD/openai_has_completed_web_search.jq" ] || {
+  echo "ERROR: canonical jq guards not found under $GUARD (run from a repo checkout)"; exit 1; }
+
+EFFORT="${ARS_CROSS_MODEL_REASONING_EFFORT:-}"
+note "model=$ARS_CROSS_MODEL effort=${EFFORT:-(provider default — reasoning field omitted)}"
+
+# --- One real call against a stable reference --------------------------------
+PROMPT='Verify this academic reference. Check: Does it exist? Are the author
+names, year, title, and venue correct? Search the web to confirm — do not
+answer from memory.
+
+Respond with exactly one verdict:
+- VERIFIED  — found online; include at least one source URL or DOI you found
+- MISMATCH  — found, but a field is wrong (state which); include the source
+- NOT_FOUND — searched, no matching record exists
+- NOT_SEARCHED — you could not actually search the web for this reference
+
+Reference: Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L.,
+Gomez, A. N., Kaiser, L., & Polosukhin, I. (2017). Attention is all you need.
+Advances in Neural Information Processing Systems, 30.
+— Context: cited as the origin of the Transformer architecture.'
+
+resp="$(curl -sS -w '\n%{http_code}' https://api.openai.com/v1/responses \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg model "$ARS_CROSS_MODEL" --arg prompt "$PROMPT" \
+        --arg effort "$EFFORT" '{
+    model: $model,
+    instructions: "You are a citation-verification assistant. Search the web before every verdict; never answer from memory. If you could not search, respond NOT_SEARCHED.",
+    input: $prompt,
+    tools: [{type: "web_search"}],
+    temperature: 0.1
+  } + (if $effort == "" then {} else {reasoning: {effort: $effort}} end)')")"
+
+http="${resp##*$'\n'}"; body="${resp%$'\n'*}"
+
+# --- Check 1: transport -------------------------------------------------------
+if [ "$http" -ge 200 ] 2>/dev/null && [ "$http" -lt 300 ]; then
+  pass "HTTP $http"
+else
+  fail "HTTP $http (transport/API error — body follows)"
+  printf '%s\n' "$body" | head -5
+  echo "RESULT: FAIL ($FAILURES check(s) failed)"
+  exit 1
+fi
+
+# --- Check 2: grounding guard (canonical, fail-closed) ------------------------
+if jq -e -f "$GUARD/openai_has_completed_web_search.jq" <<<"$body" >/dev/null; then
+  pass "completed web_search_call present (grounding guard)"
+else
+  fail "no completed web_search_call — the model did not search; a real run would emit NOT_SEARCHED"
+fi
+
+# --- Check 3: verdict text ----------------------------------------------------
+text="$(jq -r -f "$GUARD/openai_text.jq" <<<"$body")"
+if [ -z "$text" ]; then
+  fail "empty verdict text"
+else
+  # Whole-word match: a bare substring hit would extract VERIFIED out of
+  # "UNVERIFIED" and false-pass an invalid status.
+  all_hits="$(printf '%s' "$text" | grep -oE '\b(VERIFIED|MISMATCH|NOT_FOUND|NOT_SEARCHED)\b')"
+  verdicts="$(printf '%s' "$all_hits" | sort -u | grep . || true)"
+  distinct="$(printf '%s' "$verdicts" | grep -c . || true)"
+  total="$(printf '%s' "$all_hits" | grep -c . || true)"
+  if [ "$distinct" -eq 1 ] && [ "$total" -eq 1 ]; then
+    pass "verdict token: $verdicts"
+  elif [ "$distinct" -eq 1 ]; then
+    fail "verdict token '$verdicts' repeated $total times — the single-verdict contract requires exactly one occurrence (the prompt demands exactly one verdict; non-compliance is a gate signal)"
+    verdicts=""
+  elif [ "$distinct" -eq 0 ]; then
+    fail "no whole-word verdict token in response text (parser would reject) — text: $(printf '%s' "$text" | head -c 200)"
+    verdicts=""
+  else
+    fail "multiple distinct verdict tokens ($(printf '%s' "$verdicts" | tr '\n' ' ')) — ambiguous for the consumer"
+    verdicts=""
+  fi
+fi
+
+# --- Check 4: VERIFIED must carry a source ------------------------------------
+cites="$(jq -r -f "$GUARD/openai_sources.jq" <<<"$body")"
+if [ "${verdicts:-}" = "VERIFIED" ]; then
+  if [ -n "$cites" ]; then
+    pass "VERIFIED carries url_citation source(s): $(printf '%s' "$cites" | head -1)"
+  else
+    fail "VERIFIED with no url_citation source — a real run downgrades this to NOT_SEARCHED"
+  fi
+else
+  note "SKIP: source check (verdict was '${verdicts:-none}', not VERIFIED — expected VERIFIED for this fixture)"
+  # A famous, indexed reference should verify; anything else means the search
+  # or parse path is off even if individual guards passed.
+  [ "${verdicts:-}" = "" ] || fail "fixture reference did not come back VERIFIED (got '${verdicts}')"
+fi
+
+# --- Check 5: model echo -------------------------------------------------------
+resp_model="$(jq -r '.model // empty' <<<"$body")"
+case "$resp_model" in
+  "$ARS_CROSS_MODEL"|"$ARS_CROSS_MODEL"-*)
+    pass "model echo: $resp_model" ;;
+  "")
+    fail "response carries no model field" ;;
+  *)
+    fail "model echo '$resp_model' does not match requested '$ARS_CROSS_MODEL' (silent rerouting?)" ;;
+esac
+
+# --- Check 6: reasoning effort accepted (fail-closed when requested) -----------
+if [ -z "$EFFORT" ]; then
+  note "SKIP: effort echo check (ARS_CROSS_MODEL_REASONING_EFFORT unset — reasoning field omitted from the request)"
+else
+  resp_effort="$(jq -r '.reasoning.effort // empty' <<<"$body")"
+  if [ "$resp_effort" = "$EFFORT" ]; then
+    pass "reasoning effort echo: $resp_effort"
+  elif [ -z "$resp_effort" ]; then
+    fail "requested reasoning effort '$EFFORT' but the response carries no reasoning.effort echo — the setting may have been ignored or the response shape changed (fail-closed for a promotion gate)"
+  else
+    fail "reasoning effort echo '$resp_effort' does not match requested '$EFFORT'"
+  fi
+fi
+
+# --- Result --------------------------------------------------------------------
+if [ "$FAILURES" -eq 0 ]; then
+  echo "RESULT: PASS — $ARS_CROSS_MODEL behaves correctly against the documented verifier pattern"
+  exit 0
+else
+  echo "RESULT: FAIL ($FAILURES check(s) failed) — do not adopt $ARS_CROSS_MODEL for verification runs yet"
+  exit 1
+fi

package/vendor/ars/scripts/cross_model_smoke_test_codex.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Manual LIVE smoke test. CI must never invoke this file.
+# Uses public citation metadata only and the exact production detect/verify paths.
+set -u
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) || exit 1
+RUNTIME="$SCRIPT_DIR/cross_model_codex_transport.py"
+
+detect_output=$(python3 "$RUNTIME" detect) || {
+  status=$?
+  printf '%s\n' "$detect_output"
+  exit "$status"
+}
+printf '%s\n' "$detect_output"
+
+request='{"schema_version":"ars-codex-citation-request/1.0","request_id":"smoke-vaswani-2017","reference_text":"Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., Kaiser, L., and Polosukhin, I. (2017). Attention Is All You Need. Advances in Neural Information Processing Systems 30.","citation_context":"Cited as the source introducing the Transformer architecture."}'
+
+receipt=$(printf '%s' "$request" | "$SCRIPT_DIR/cross_model_codex_verify.sh") || {
+  status=$?
+  printf 'RESULT: FAIL (transport exit %s)\n' "$status"
+  exit "$status"
+}
+printf '%s\n' "$receipt"
+
+verdict=$(printf '%s' "$receipt" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])') || exit 1
+searched=$(printf '%s' "$receipt" | python3 -c 'import json,sys; print(str(json.load(sys.stdin)["searched"]).lower())') || exit 1
+sources=$(printf '%s' "$receipt" | python3 -c 'import json,sys; print(len(json.load(sys.stdin)["sources"]))') || exit 1
+
+if [ "$verdict" = "VERIFIED" ] && [ "$searched" = "true" ] && [ "$sources" -ge 1 ]; then
+  printf 'RESULT: PASS\n'
+  exit 0
+fi
+
+printf 'RESULT: FAIL (verdict=%s searched=%s sources=%s)\n' "$verdict" "$searched" "$sources"
+exit 1

package/vendor/ars/scripts/cross_model_verification/gemini_is_grounded.jq

@@ -0,0 +1,45 @@
+# Canonical grounding guard — Gemini generateContent (google_search tool).
+# CONTRACT (cross_model_verification.md, Gemini block): accept the verdict text only when BOTH
+#   - webSearchQueries  (length > 0) — the model actually issued a search, AND
+#   - groundingSupports (length > 0) — the verdict TEXT is tied to retrieved chunks.
+# webSearchQueries + groundingChunks alone is NOT enough: Gemini can run a search, return chunks,
+# then emit an unsupported from-memory verdict whose text references none of them.
+# groundingSupports[].groundingChunkIndices is what links answer spans to sources; without it a
+# VERIFIED is not actually grounded. Used with `jq -e`: exit 0 = grounded; non-0 = NOT_SEARCHED.
+#
+# GUARD DERIVES FROM THE EXTRACTOR — by construction, not by a re-implemented predicate. The guard
+# embeds the EXACT extraction `gemini_sources.jq` performs (same `candidates[0]` selection, same
+# valid-index predicate, same non-empty-string uri filter) and passes iff that extraction yields ≥1
+# url AND the model actually issued a search (a non-empty webSearchQueries array on the SAME
+# candidate). The safety invariant is **guard-pass ⟹ at least one source extractable**: deriving
+# the guard from the extractor — rather than asserting two parallel jq programs agree — makes it
+# hold for every input shape (a multi-candidate response where candidate 0 is unsupported, a
+# fractional/negative/string/out-of-range index, a non-string uri, AND a malformed NON-OBJECT at any
+# dereference point — `candidates[0]`, `groundingMetadata`, a `groundingSupports` element, a cited
+# `groundingChunks` element, or its `web` — all leave the extraction empty → guard fails closed →
+# an unsupported NOT_FOUND/MISMATCH, which the
+# blank-source downgrade does not rescue since it only touches VERIFIED, is never trusted). The
+# guard is strictly STRONGER than "has a source": a response carrying chunks but no webSearchQueries
+# (sources non-blank, no real search signal) still fails — the converse is intentionally not
+# required. Keep this extraction's LOGIC identical to gemini_sources.jq's `$srcs` body — same
+# candidate-0 selection, same valid-index predicate, same `obj(obj(chunk).web).uri` non-empty-string
+# filter, same order. (The two differ only in how the result is consumed: here it is bound to `$srcs`
+# inside a `([ … ]) as $srcs` wrap; there it is piped to `unique | join`, so leading whitespace is
+# not byte-for-byte equal — only the extraction operations must stay in lockstep.) Used with
+# `jq -e`: exit 0 = grounded; non-0 = NOT_SEARCHED.
+#
+# `arr/1` array-normalizes every container; `obj/1` object-normalizes every value that is then
+# field-dereferenced (`obj(candidates[0]).groundingMetadata`, `obj($meta)`, `obj(support).…Indices`,
+# `obj(obj(chunk).web).uri`). Without `obj/1`, a non-object at any of those points (e.g.
+# `groundingMetadata: 5`, a `web: 5`) would crash jq ("Cannot index number with string …") instead
+# of failing closed — a crash is loud but still violates the crash-free fail-closed contract.
+def arr($x): if ($x | type) == "array" then $x else [] end;
+def obj($x): if ($x | type) == "object" then $x else {} end;
+(obj(arr(obj(.).candidates)[0]).groundingMetadata | obj(.)) as $meta
+| arr($meta.groundingChunks) as $chunks
+| ([ arr($meta.groundingSupports)[]
+     | arr(obj(.).groundingChunkIndices)[]
+     | select(type == "number" and . == floor and . >= 0 and . < ($chunks | length)) ]
+   | unique
+   | [ .[] | obj(obj($chunks[.]).web).uri | select(type == "string" and length > 0) ]) as $srcs
+| ((arr($meta.webSearchQueries) | length) > 0) and (($srcs | length) > 0)