From 0d34628823f5f18bf77bcef14e4cfccb7d7bd757 Mon Sep 17 00:00:00 2001 From: khive Date: Mon, 17 Aug 2026 10:06:29 -0400 Subject: [PATCH 1/5] feat: freeze OpenRouter real-e2e confirmation contract --- INTERFACES.md | 43 + eval/README.md | 53 + eval/openrouter_real_e2e.py | 2713 +++++++++++++++++ eval/openrouter_real_e2e_authority.py | 456 +++ moodboard/openrouter.py | 15 +- tests/test_openrouter_adapter.py | 31 + tests/test_openrouter_real_e2e.py | 237 ++ tests/test_openrouter_real_e2e_authority.py | 291 ++ .../test_openrouter_real_e2e_confirmation.py | 1223 ++++++++ tests/test_openrouter_real_e2e_transport.py | 476 +++ 10 files changed, 5535 insertions(+), 3 deletions(-) create mode 100644 eval/openrouter_real_e2e.py create mode 100644 eval/openrouter_real_e2e_authority.py create mode 100644 tests/test_openrouter_real_e2e.py create mode 100644 tests/test_openrouter_real_e2e_authority.py create mode 100644 tests/test_openrouter_real_e2e_confirmation.py create mode 100644 tests/test_openrouter_real_e2e_transport.py diff --git a/INTERFACES.md b/INTERFACES.md index 9af3362..59b72f8 100644 --- a/INTERFACES.md +++ b/INTERFACES.md @@ -719,6 +719,49 @@ Content-Length before treating an envelope as complete, and returns no headers. data URLs, request bytes, response headers/body, and decoded output bytes are excluded from adapter representations and stable errors. +## `eval/openrouter_real_e2e.py`: confirmation-bound one-call evaluation + +The real-provider evaluation is deliberately outside the reusable adapter. Its first phase, +`prepare_openrouter_real_e2e`, is credential-free and dispatch-free. It freezes exact discovery, +source, authority, mask, visible overlay, compact-summary, packet projection, and wire identities +in an owner-only directory. Challenge and compact-summary versions are evaluation-local artifact +indexes; they do not expand the provider schema registry or claim a reusable Studio authority. + +`execute_openrouter_real_e2e` accepts that directory plus a separate closed confirmation context. +It validates the exact challenge/summary identities, canonical principal/session/time fields, +artifact SHA-256/counts, path/device/inode binding, expiry, reconstructed packet and wire, and a +fresh byte-identical discovery response before credential access. The self-hash on the context is +integrity, not authorization: a caller must also supply a trusted Studio confirmation consumer +that atomically verifies and durably spends that exact authorization, and the production default +rejects execution. The retired Boolean one-shot function cannot reach +I/O, and the evaluation CLI only reports the missing trusted-authority prerequisite. + +After validation, the caller-supplied confirmation consumer must atomically and durably spend the +authorization; this repository has no production Studio ledger. The local `O_EXCL` record proves +only same-directory concurrency behavior in the injected offline harness. The adapter journal +remains the authoritative non-idempotent send and provider-evidence boundary. `$0.05` is only an +exact discovery-quote admission limit, never a provider-side hard spend cap. Post-response cost is +non-gating telemetry. A terminal provider occurrence is not an aesthetic judgment; the sanitized +result separately reports media admission, raw structure/locality, localized-edit gate status, +workflow acceptance `not_recorded`, semantic/aesthetic `not_run`, and compositor `not_run`. + +The offline authority helper reads explicitly supplied board and Pixel-RAG artifacts through public validators +and derives content-bound collection-gate identities. It never repairs stale bytes. The current +local evidence belongs to a retired projection and fails when explicitly supplied to the current +reader. Evidence republication, trusted authority-to-session integration, a durable Studio +confirmation boundary, and a credential-free idempotent post-response finalizer are explicit +prerequisites to any paid run; this slice performs no provider call and makes no real-run claim. + +The helper's identity domains are evaluation-local. `eligible_corpus_sha256` hashes RFC 8785 of +`{schema_version, source_manifest:{catalog_sha256,dataset_id,manifest_sha256}, field, operator, +value, assets:[{asset_id,content_ref}]}` under +`moodboard.openrouter-real-e2e.eligible-corpus.v1`; `assets` is sorted by +`(asset_id, content_ref)`. `route_policy_id` hashes RFC 8785 of +`{schema_version, eligible_corpus_sha256, namespace, field, operator, value, +empty_result_policy, interpretation}` under `moodboard.openrouter-real-e2e.route-policy.v1`. +These hashes provide integrity only. A future trusted Studio integration must cross-bind them to +the exact validated board/Pixel bytes and enrolled creative session. + ## `report.py` ### The axis vocabulary diff --git a/eval/README.md b/eval/README.md index f1454d6..e05c39b 100644 --- a/eval/README.md +++ b/eval/README.md @@ -77,3 +77,56 @@ outcome, since the two differ by how far apart the styles are. It does not make worthless, and it does make the claim narrower. The rule is that the record is not accepted as written, the claim is narrowed to the domain that passed, and the narrowing goes in the README where a reader will see it rather than in a footnote. + +## OpenRouter real-provider evaluation is a two-stage confirmation + +`openrouter_real_e2e.py` is an opt-in evaluation harness, not a general provider CLI. Preparation +fetches and freezes exact discovery and public source bytes, compiles the authoritative rectangle +mask and visible overlay, binds the board/retrieval authority, computes the exact provider wire +identity, and writes an owner-only confirmation challenge. Preparation has no credential or +transport parameter and cannot dispatch. + +Execution requires a separate, closed confirmation context that names the exact challenge and +compact summary, one enrolled principal, one Studio session, the same creative session, and one +fresh explicit approval. A document hash alone is not Studio authority: the production API has no +default confirmer and fails `confirmation_authority_unavailable` until a trusted Studio boundary +that atomically verifies and consumes the authorization is supplied. The retired Boolean +`authorize_one_paid_call` entry point always fails +`two_phase_confirmation_required`; the command line only reports the missing trusted-authority +integration and cannot prepare or dispatch a live challenge. + +After all frozen bytes, identities, timestamps, directory inode, reconstructed wire, and a fresh +byte-identical discovery response agree, a caller-supplied Studio boundary must atomically and +durably consume the confirmation before Keychain access. This repository does not implement that +ledger: the default rejects execution, while the injected offline seam proves one-process CAS and +local `O_EXCL` concurrency behavior only. Credential-bearing work is contained in a non-raising +inner scope, core dumps are disabled before Keychain access, and private response and output bytes +remain in the owner-only journal/run directory. + +The fixed `$0.05` value is a **quote-admission limit**, not a provider-enforced spending cap. It is +checked against the exact live discovery pricing before source access. Reported cost is post-hoc +telemetry: missing, differently reported, or unexpectedly high telemetry cannot undo a charge and +therefore does not strand an otherwise valid provider response before terminal media admission. +Reports distinguish provider lifecycle state, media admission, raw structural/locality evidence, +localized-edit gate status, workflow acceptance (`not_recorded`), semantic/aesthetic judgment +(`not_run`), and compositor execution (`not_run`). + +No paid call is currently authorized. The available local Pixel-RAG evidence uses a retired +projection and fails the current public reader when supplied explicitly. A separately governed +evidence republication, a trusted authority-to-creative-session integration, a durable Studio +confirmation consumer, and a credential-free idempotent post-response finalizer are prerequisites +to a live run. Until those exist, the two-stage functions are an injected offline contract harness. + +The executable acceptance map for this slice is: + +| Condition | Evidence test | +| --- | --- | +| Prepare has no credential, transport, or Boolean authorization surface | `test_prepare_api_has_no_credential_or_transport_and_returns_frozen_challenge` | +| Exact discovery/source/authority/mask/overlay/summary bytes are bound | `test_prepare_freezes_exact_content_bound_snapshot_summary_and_overlay` and the artifact-drift matrix | +| Self-minted confirmation is insufficient without Studio authority | `test_production_default_rejects_self_minted_context_before_discovery_or_key` | +| Context, expiry, inode, fresh discovery, and rebuilt wire gate Keychain | confirmation-context, expiry, directory-swap, discovery-drift, and wire-drift tests | +| One injected in-process consumption winner can reach one fake POST | replay, ambiguity, and concurrent-executor tests | +| Quote arithmetic is exact and `$0.05` is pre-dispatch only | ambient-Decimal and over-quote tests | +| Missing post-paid cost telemetry does not strand valid media evidence | `test_missing_reported_cost_remains_terminal_success_after_paid_response` | +| Credentials cannot survive public exceptions or local artifacts | real-E2E transport exception-graph tests | +| Real board/retrieval identities are derived, never label hashes | `test_openrouter_real_e2e_authority.py` | diff --git a/eval/openrouter_real_e2e.py b/eval/openrouter_real_e2e.py new file mode 100644 index 0000000..3fcffc0 --- /dev/null +++ b/eval/openrouter_real_e2e.py @@ -0,0 +1,2713 @@ +#!/usr/bin/env python3 +"""Run one explicitly authorized, non-retrying OpenRouter localized-edit evaluation. + +This is an opt-in evaluation harness, not an ordinary test and not a general provider CLI. Its +model, route, output count, resolution, quote-admission limit, source, Keychain locator, and retry +policy are intentionally fixed. Private provider bytes live only in an owner-only run directory; +the small ``result.json`` is a sanitized index into the verified local journal. +""" + +from __future__ import annotations + +import argparse +import base64 +import contextlib +import copy +import hashlib +import http.client +import json +import math +import os +import resource +import signal +import ssl +import stat +import subprocess +import sys +import threading +import time +import uuid +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from datetime import UTC, datetime, timedelta +from decimal import Context, Decimal, InvalidOperation, localcontext +from pathlib import Path +from types import FrameType +from typing import Any, Final, NoReturn + +from blake3 import blake3 +from PIL import Image, ImageDraw + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from eval.openrouter_real_e2e_authority import ( # noqa: E402 + OpenRouterRealE2EAuthority, + OpenRouterRealE2EAuthorityError, +) +from moodboard.attempt_journal import AttemptJournal # noqa: E402 +from moodboard.contracts import ( # noqa: E402 + compute_document_identity, + compute_projection_identity, + is_canonical_utc_timestamp, +) +from moodboard.intent_packet import ( # noqa: E402 + IntentPacket, +) +from moodboard.intent_packet import ( # noqa: E402 + from_json_dict as intent_from_json, +) +from moodboard.intent_packet import ( # noqa: E402 + to_json_dict as intent_to_json, +) +from moodboard.judgment import to_json_dict as judgment_to_json # noqa: E402 +from moodboard.locality import ( # noqa: E402 + build_locality_not_run, + compile_canonical_raster, + compile_rectangle_mask, + verify_output_structure, + verify_outside_mask_rgb_exact, +) +from moodboard.locality_contracts import ( # noqa: E402 + EXACT_LOCALITY_VERIFIER_VERSION, + CanonicalMaskArtifact, + CanonicalRasterArtifact, +) +from moodboard.openrouter import ( # noqa: E402 + ADAPTER_REVISION, + OpenRouterAdapterAdmissionLimits, + OpenRouterDispatchResult, + OpenRouterHttpResponse, + OpenRouterPreparedRequest, + build_openrouter_capability_snapshot, + dispatch_openrouter_attempt, + prepare_openrouter_request, +) +from moodboard.provider_artifacts import ( # noqa: E402 + ATTEMPT_VERSION, + EVENT_VERSION, + RUN_VERSION, + GenerationAttempt, + GenerationRun, + OutputOccurrence, + ProviderCapabilitySnapshot, + build_normalized_request_ref, + compute_provider_request_key, + seal_provider_artifact, +) +from moodboard.provider_artifacts import ( # noqa: E402 + from_json_dict as provider_from_json, +) +from moodboard.provider_artifacts import ( # noqa: E402 + to_json_dict as provider_to_json, +) +from moodboard.provider_media import ProviderMediaAdmissionError # noqa: E402 + +JsonObject = dict[str, Any] + +QUOTE_ADMISSION_LIMIT_USD: Final = Decimal("0.05") +# Compatibility alias for the first RED contract. This is a quote-admission threshold, never a +# provider-enforced spending limit. +MAX_COST_USD: Final = QUOTE_ADMISSION_LIMIT_USD +_QUOTE_CONTEXT: Final = Context(prec=128) +MODEL: Final = "qwen/qwen-image-3" +PROVIDER_TAG: Final = "alibaba" +ROUTE_ID: Final = "openrouter-primary" +RESOLUTION: Final = "1K" +ASPECT_RATIO: Final = "4:3" +OUTPUT_COUNT: Final = 1 +SEED: Final = 20_260_817 + +KEYCHAIN_SERVICE: Final = "OPENROUTER_API_KEY" +KEYCHAIN_ACCOUNT: Final = "khive" +CREDENTIAL_PROFILE_ID: Final = "00000000-0000-4000-8000-000000000005" + +DISCOVERY_HOST: Final = "openrouter.ai" +DISCOVERY_PATH: Final = "/api/v1/images/models/qwen/qwen-image-3/endpoints" +DISPATCH_PATH: Final = "/api/v1/images" +SOURCE_HOST: Final = "upload.wikimedia.org" +SOURCE_PATH: Final = ( + "/wikipedia/commons/thumb/b/b5/Apple_tree_in_a_garden.JPG/" + "1280px-Apple_tree_in_a_garden.JPG" + "?utm_source=commons.wikimedia.org&utm_campaign=index&utm_content=thumbnail" +) +SOURCE_PAGE_URL: Final = "https://commons.wikimedia.org/wiki/File:Apple_tree_in_a_garden.JPG" +SOURCE_SHA256: Final = "3bda38b4304152f813f6bea37dc236f95670fbea5da4731903d9ce8cfaa8ae23" +SOURCE_CONTENT_REF: Final = "d9c1a0e3e6a5a72a9da252a0ea9fb4616c9099dd20cdc65ea00ffc29d14f23a8" +SOURCE_BYTE_COUNT: Final = 645_201 + +_PACKET_VERSION: Final = "moodboard.intent-packet.v1" +_OPERATION_VERSION: Final = "moodboard.operation.localized-edit.v1" +_POLICY_VERSION: Final = "moodboard.verification-policy.v1" +_E2E_ID_DOMAIN: Final = "moodboard.openrouter-real-e2e.fixture.v1" +_SUMMARY_VERSION: Final = "moodboard.openrouter-real-e2e-summary.v1" +_CHALLENGE_VERSION: Final = "moodboard.openrouter-real-e2e-confirmation-challenge.v1" +_CONFIRMATION_CONTEXT_VERSION: Final = "moodboard.openrouter-real-e2e-confirmation-context.v1" +_COMPACT_SUMMARY_VERSION: Final = "moodboard.openrouter-real-e2e-compact-summary.v1" +_CHALLENGE_TTL_SECONDS: Final = 30 * 60 +_REFERENCE_CONTENT_REF: Final = "cf72f06b425eb52039d6926e057f7f5720f16435341625ce2fc9b92f5b52069d" +_DISCOVERY_MAX_BYTES: Final = 4 * 1024 * 1024 +_SOURCE_MAX_BYTES: Final = 1024 * 1024 +_HTTP_RESPONSE_MAX_BYTES: Final = 23_418_200 +_JSON_MAX_DEPTH: Final = 32 +_JSON_MAX_NODES: Final = 10_000 +_JSON_STRUCTURAL_TOKEN_MAX: Final = 2 * _JSON_MAX_NODES + _JSON_MAX_DEPTH +_CONNECT_TIMEOUT_SECONDS: Final = 10.0 +_PREPARE_FETCH_TIMEOUT_SECONDS: Final = 30.0 +_TOTAL_TIMEOUT_SECONDS: Final = 210.0 +_SAFE_AUTHORITY_ERROR_CODES: Final = frozenset( + { + "artifact_snapshot_failed", + "authority_context_unavailable", + "board_artifact_invalid", + "board_artifact_unavailable", + "board_artifact_unverified", + "eligible_corpus_invalid", + "local_replace_references_invalid", + "local_replace_route_invalid", + "pixel_rag_artifact_invalid", + "pixel_rag_artifact_unavailable", + "pixel_rag_evidence_not_measured", + "pixel_rag_projection_invalid", + } +) + + +class OpenRouterRealE2EError(RuntimeError): + """The one-shot evaluation stopped at a stable, secret-free boundary.""" + + def __init__(self, code: str) -> None: + self.code = code + super().__init__(code) + + +@dataclass(frozen=True, slots=True) +class OpenRouterRealE2EResult: + generation_run_id: str + attempt_id: str + provider_receipt_id: str | None + output_occurrence_id: str | None + quoted_cost_usd: Decimal + reported_cost_usd: Decimal | None + cost_telemetry_status: str + states: tuple[str, ...] + generation_post_count: int + provider_media_admission_result: str + raw_structural_result: str + raw_structural_reason: str | None + raw_locality_result: str + + +@dataclass(frozen=True, slots=True) +class OpenRouterRealE2EChallenge: + """Public, secret-free handle for one credential-free confirmation bundle.""" + + challenge_id: str + compact_summary_id: str + prepared_at: str + expires_at: str + quoted_cost_usd: Decimal + quote_admission_limit_usd: Decimal + wire_body_sha256: str + wire_body_byte_count: int + directory: Path + + +@dataclass(frozen=True, slots=True) +class _AuthoritySnapshot: + document: JsonObject + payload: bytes = field(repr=False) + board_artifact_bytes: bytes | None = field(default=None, repr=False) + pixel_rag_artifact_bytes: bytes | None = field(default=None, repr=False) + + +def _fail(code: str) -> NoReturn: + raise OpenRouterRealE2EError(code) from None + + +def _call_sanitized(operation: Callable[[], Any]) -> tuple[bool, Any | None]: + """Run an untrusted boundary without retaining its exception in a public chain.""" + + try: + return True, operation() + except BaseException: + return False, None + + +def _enforce_no_core_dumps() -> None: + ok, _ = _call_sanitized(lambda: resource.setrlimit(resource.RLIMIT_CORE, (0, 0))) + if not ok: + _fail("core_dump_policy_unavailable") + ok, measured = _call_sanitized(lambda: resource.getrlimit(resource.RLIMIT_CORE)) + if not ok or measured != (0, 0): + _fail("core_dump_policy_unavailable") + + +def _bounded_decimal(token: str) -> Decimal: + if not isinstance(token, str) or not 1 <= len(token) <= 64: + _fail("quote_invalid") + try: + value = Decimal(token) + except (InvalidOperation, ValueError): + _fail("quote_invalid") + if not value.is_finite() or value < 0 or value.adjusted() > 20: + _fail("quote_invalid") + return value + + +def _bounded_integer(token: str) -> int: + if not isinstance(token, str) or not 1 <= len(token) <= 32: + _fail("discovery_invalid") + try: + return int(token) + except ValueError: + _fail("discovery_invalid") + + +def _unique_object(pairs: list[tuple[str, Any]]) -> JsonObject: + result: JsonObject = {} + for key, value in pairs: + if key in result: + _fail("discovery_invalid") + result[key] = value + return result + + +def _bounded_tree(value: Any, *, code: str = "discovery_invalid") -> None: + stack: list[tuple[Any, int]] = [(value, 1)] + nodes = 0 + while stack: + current, depth = stack.pop() + nodes += 1 + if nodes > _JSON_MAX_NODES or depth > _JSON_MAX_DEPTH: + _fail(code) + if isinstance(current, dict): + stack.extend((item, depth + 1) for item in current.values()) + elif isinstance(current, list): + stack.extend((item, depth + 1) for item in current) + elif isinstance(current, float): + if not math.isfinite(current): + _fail(code) + elif current is not None and not isinstance(current, (bool, int, Decimal, str)): + _fail(code) + + +def _preflight_json_structure(raw: bytes, *, code: str) -> None: + in_string = False + escaped = False + depth = 0 + structural_tokens = 0 + for byte in raw: + if in_string: + if escaped: + escaped = False + elif byte == 0x5C: + escaped = True + elif byte == 0x22: + in_string = False + continue + if byte == 0x22: + in_string = True + elif byte in {0x5B, 0x7B}: + depth += 1 + structural_tokens += 1 + if depth > _JSON_MAX_DEPTH: + _fail(code) + elif byte in {0x5D, 0x7D}: + depth -= 1 + structural_tokens += 1 + if depth < 0: + _fail(code) + elif byte in {0x2C, 0x3A}: + structural_tokens += 1 + if structural_tokens > _JSON_STRUCTURAL_TOKEN_MAX: + _fail(code) + if in_string or depth != 0: + _fail(code) + + +def _parse_json(raw: bytes, *, code: str, max_bytes: int) -> JsonObject: + if type(raw) is not bytes or not 1 <= len(raw) <= max_bytes: + _fail(code) + try: + _preflight_json_structure(raw, code=code) + text = raw.decode("utf-8", errors="strict") + value = json.loads( + text, + parse_float=_bounded_decimal, + parse_int=_bounded_integer, + parse_constant=lambda _: _fail(code), + object_pairs_hook=_unique_object, + ) + except OpenRouterRealE2EError: + raise + except Exception: + _fail(code) + _bounded_tree(value) + if not isinstance(value, dict): + _fail(code) + return value + + +def parse_openrouter_quote( + raw_body: bytes, + *, + input_count: int, + output_count: int, + resolution: str, +) -> Decimal: + """Derive the exact applicable image quote from one live endpoint response.""" + + if ( + type(input_count) is not int + or type(output_count) is not int + or input_count != 1 + or output_count != 1 + or resolution != RESOLUTION + ): + _fail("quote_unsupported") + document = _parse_json(raw_body, code="discovery_invalid", max_bytes=_DISCOVERY_MAX_BYTES) + endpoints = document.get("endpoints") + if document.get("id") != MODEL or not isinstance(endpoints, list): + _fail("quote_ambiguous") + selected = [ + endpoint + for endpoint in endpoints + if isinstance(endpoint, dict) and endpoint.get("provider_tag") == PROVIDER_TAG + ] + if len(selected) != 1: + _fail("quote_ambiguous") + pricing = selected[0].get("pricing") + if not isinstance(pricing, list) or not pricing: + _fail("quote_ambiguous") + input_prices: list[Decimal] = [] + output_prices: list[Decimal] = [] + for row in pricing: + if not isinstance(row, dict) or row.get("unit") != "image": + _fail("quote_ambiguous") + price = row.get("cost_usd") + if not isinstance(price, Decimal) or not price.is_finite() or price < 0: + _fail("quote_ambiguous") + billable = row.get("billable") + variant = row.get("variant") + if billable == "input_image" and variant is None: + if set(row) != {"billable", "unit", "cost_usd"}: + _fail("quote_ambiguous") + input_prices.append(price) + elif billable == "output_image" and variant in {"1k", "2k"}: + if set(row) != {"billable", "unit", "cost_usd", "variant"}: + _fail("quote_ambiguous") + if variant == resolution.lower(): + output_prices.append(price) + else: + _fail("quote_ambiguous") + if len(input_prices) != 1 or len(output_prices) != 1: + _fail("quote_ambiguous") + # Decimal arithmetic otherwise inherits process-global precision and rounding. A caller that + # lowered precision could round 0.051 down to the 0.05 admission threshold before comparison. + with localcontext(_QUOTE_CONTEXT): + return input_prices[0] * input_count + output_prices[0] * output_count + + +def _resolve_keychain_token_sanitized() -> tuple[bool, str | None]: + """Keep subprocess output and any diagnostic exception below a non-raising frame.""" + + ok, completed = _call_sanitized( + lambda: subprocess.run( + [ + "/usr/bin/security", + "find-generic-password", + "-s", + KEYCHAIN_SERVICE, + "-a", + KEYCHAIN_ACCOUNT, + "-w", + ], + capture_output=True, + check=False, + text=True, + timeout=15, + ) + ) + if not ok or not isinstance(completed, subprocess.CompletedProcess): + return False, None + if completed.returncode != 0: + return False, None + token = completed.stdout.strip() + if not 16 <= len(token) <= 4096 or any( + ord(character) < 33 or ord(character) > 126 for character in token + ): + return False, None + return True, token + + +def load_openrouter_keychain_token(credential_profile_id: str) -> str: + """Resolve the sole approved profile directly from macOS Keychain into memory.""" + + if credential_profile_id != CREDENTIAL_PROFILE_ID: + _fail("credential_profile_unsupported") + ok, token = _resolve_keychain_token_sanitized() + if not ok or token is None: + _fail("credential_unavailable") + return token + + +def _label_digest(label: str) -> str: + return compute_projection_identity({"label": label}, domain_tag=_E2E_ID_DOMAIN) + + +def _canonical_timestamp() -> str: + return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def _timestamp_value(value: object, *, code: str) -> datetime: + if not is_canonical_utc_timestamp(value): + _fail(code) + assert isinstance(value, str) + try: + return datetime.fromisoformat(value[:-1] + "+00:00") + except ValueError: + _fail(code) + + +def _timestamp_after(value: str, *, seconds: int) -> str: + measured = _timestamp_value(value, code="clock_invalid") + timedelta(seconds=seconds) + return measured.isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def _uuid_text(factory: Callable[[], str | uuid.UUID]) -> str: + try: + measured = str(uuid.UUID(str(factory()))) + except Exception: + _fail("uuid_source_invalid") + return measured + + +def _mime_for_bytes(payload: bytes) -> str: + if payload.startswith(b"\x89PNG\r\n\x1a\n"): + return "image/png" + if payload.startswith(b"\xff\xd8\xff"): + return "image/jpeg" + _fail("source_invalid") + + +def _raster_document(raster: CanonicalRasterArtifact) -> JsonObject: + return { + "schema_version": raster.schema_version, + "compiler_revision": raster.compiler_revision, + "width": raster.width, + "height": raster.height, + "mode": raster.mode, + "byte_count": raster.byte_count, + "source_content_sha256": raster.source_content_sha256, + "raster_sha256": raster.raster_sha256, + } + + +def _mask_document(mask: CanonicalMaskArtifact) -> JsonObject: + return { + "schema_version": mask.schema_version, + "compiler_revision": mask.compiler_revision, + "width": mask.width, + "height": mask.height, + "byte_count": mask.byte_count, + "editable_count": mask.editable_count, + "protected_count": mask.protected_count, + "source_raster_sha256": mask.source_raster_sha256, + "mask_sha256": mask.mask_sha256, + } + + +def _source_asset_id(source_sha256: str) -> str: + name = SOURCE_PAGE_URL if source_sha256 == SOURCE_SHA256 else f"urn:sha256:{source_sha256}" + return str(uuid.uuid5(uuid.NAMESPACE_URL, name)) + + +def _mask_bounds(raster: CanonicalRasterArtifact) -> tuple[int, int, int, int]: + if raster.width == 1280 and raster.height == 960: + return 230, 48, 1152, 912 + left = max(0, raster.width // 4) + top = max(0, raster.height // 6) + right = min(raster.width, max(left + 1, raster.width * 3 // 4)) + bottom = min(raster.height, max(top + 1, raster.height * 5 // 6)) + if left == 0 and top == 0 and right == raster.width and bottom == raster.height: + _fail("source_dimensions_unsupported") + return left, top, right, bottom + + +def _render_mask_overlay( + raster: CanonicalRasterArtifact, + bounds: tuple[int, int, int, int], +) -> bytes: + """Render the exact integer rectangle as a deterministic, inspectable PNG overlay.""" + + left, top, right, bottom = bounds + try: + source = Image.frombytes("RGB", (raster.width, raster.height), raster.rgb_bytes) + overlay = Image.new("RGBA", source.size, (0, 0, 0, 0)) + draw = ImageDraw.Draw(overlay) + line_width = max(2, min(raster.width, raster.height) // 240) + draw.rectangle( + (left, top, right - 1, bottom - 1), + fill=(255, 0, 128, 72), + outline=(255, 0, 128, 255), + width=line_width, + ) + rendered = Image.alpha_composite(source.convert("RGBA"), overlay).convert("RGB") + from io import BytesIO + + output = BytesIO() + rendered.save(output, format="PNG", compress_level=9, optimize=False) + payload = output.getvalue() + except Exception: + _fail("overlay_render_failed") + if not payload.startswith(b"\x89PNG\r\n\x1a\n"): + _fail("overlay_render_failed") + return payload + + +def _build_packet( + *, + source_bytes: bytes, + source_raster: CanonicalRasterArtifact, + mask: CanonicalMaskArtifact, + capability: ProviderCapabilitySnapshot, + authority: Mapping[str, Any], + creative_session_id: str, + confirmation_identity: Mapping[str, Any], +) -> IntentPacket: + source_sha256 = hashlib.sha256(source_bytes).hexdigest() + source_ref = blake3(source_bytes).hexdigest() + source_mime = _mime_for_bytes(source_bytes) + source_asset_id = _source_asset_id(source_sha256) + source_capability_id = _label_digest("source-capability") + mask_capability_id = _label_digest("mask-capability") + mask_content_ref = blake3(mask.mask_bytes).hexdigest() + mask_content_sha256 = hashlib.sha256(mask.mask_bytes).hexdigest() + + references = copy.deepcopy(authority["references"]) + operation_inputs: list[JsonObject] = [ + { + "role": "source_image", + "original_artifact": { + "asset_id": source_asset_id, + "content_ref": source_ref, + "content_sha256": source_sha256, + }, + "delivery_mode": "native_input", + "provider_field": "input_references[0]", + "provider_role": "source_image", + "capability_id": source_capability_id, + "delivered_artifact": { + "content_ref": source_ref, + "content_sha256": source_sha256, + "byte_count": len(source_bytes), + "width": source_raster.width, + "height": source_raster.height, + }, + "derivative": None, + "prompt_text": None, + }, + { + "role": "locality_mask", + "original_artifact": { + "mask_sha256": mask.mask_sha256, + "content_ref": mask_content_ref, + "content_sha256": mask_content_sha256, + }, + "delivery_mode": "not_sent", + "provider_field": None, + "provider_role": None, + "capability_id": mask_capability_id, + "delivered_artifact": None, + "derivative": None, + "prompt_text": None, + }, + ] + route_policy: JsonObject = { + "schema_version": "moodboard.provider-route-policy.v1", + "provider_route_policy_id": _label_digest("openrouter-alibaba-only-route"), + "permitted_routes": [ + { + "route_id": ROUTE_ID, + "provider": "openrouter", + "model": MODEL, + "upstream_provider_tag": PROVIDER_TAG, + "privacy_class": "external_public_demo", + "retention_class": "provider_terms_apply", + } + ], + "moodboard_fallback_permitted": False, + "undisclosed_upstream_routing_permitted": True, + } + destination: JsonObject = { + "privacy_class": "external_public_demo", + "retention_class": "provider_terms_apply", + "credential_profile_id": CREDENTIAL_PROFILE_ID, + } + options: JsonObject = { + "schema_version": "moodboard.openrouter-images-options.v1", + "seed": SEED, + "resolution": RESOLUTION, + "aspect_ratio": ASPECT_RATIO, + } + idempotency: JsonObject = { + "provider_accepts_key": False, + "deduplication_scope": None, + "retention_seconds": None, + "ambiguous_transport_retransmit_safe": False, + } + reconciliation: JsonObject = { + "supported": False, + "provider_handle_kind": None, + } + policy: JsonObject = { + "schema_version": _POLICY_VERSION, + "policy_id": "0" * 64, + "required_verifiers": [EXACT_LOCALITY_VERIFIER_VERSION], + } + policy["policy_id"] = compute_document_identity( + policy, + schema_version=_POLICY_VERSION, + identity_field="policy_id", + ) + generation_request: JsonObject = { + "requested_provider": "openrouter", + "requested_model": MODEL, + "adapter_revision": ADAPTER_REVISION, + "capability_snapshot_id": capability.capability_snapshot_id, + "output_count": OUTPUT_COUNT, + "options": options, + "operation_inputs": operation_inputs, + "provider_route_policy": route_policy, + "destination": destination, + "actual_model_policy": "requested_only_permitted", + "idempotency": idempotency, + "reconciliation": reconciliation, + } + left, top, right, bottom = _mask_bounds(source_raster) + operation_payload: JsonObject = { + "source_raster": _raster_document(source_raster), + "region": { + "selection_tool_revision": "studio.rectangle.v1", + "left": left, + "top": top, + "right": right, + "bottom": bottom, + }, + "mask": _mask_document(mask), + "raw_diagnostic_verifiers": [], + "insert_compiler_policy": "raw_crop_nearest.v1", + "compositor_policy": "source_backed_rect_replace.v1", + } + operation: JsonObject = { + "kind": "localized_edit", + "schema_version": _OPERATION_VERSION, + "payload_sha256": compute_projection_identity( + operation_payload, + domain_tag=_OPERATION_VERSION, + ), + "payload": operation_payload, + } + confirmation: JsonObject = { + "mode": "explicit", + "references_shown": copy.deepcopy(references), + "reference_use": [ + { + "reference_occurrence_id": reference["reference_occurrence_id"], + "provider_use": "prompt_context_only", + } + for reference in references + ], + "operation_inputs_shown": copy.deepcopy(operation_inputs), + "dispatch_shown": { + "requested_provider": "openrouter", + "requested_model": MODEL, + "output_count": OUTPUT_COUNT, + "destination": copy.deepcopy(destination), + "adapter_revision": ADAPTER_REVISION, + "capability_snapshot_id": capability.capability_snapshot_id, + "options": copy.deepcopy(options), + "provider_route_policy": copy.deepcopy(route_policy), + "actual_model_policy": "requested_only_permitted", + "idempotency": copy.deepcopy(idempotency), + "reconciliation": copy.deepcopy(reconciliation), + "verification_policy_id": policy["policy_id"], + "required_verifiers": [EXACT_LOCALITY_VERIFIER_VERSION], + }, + "compact_summary_id": confirmation_identity["compact_summary_id"], + "confirmed_at": confirmation_identity["confirmed_at"], + "studio_session_id": confirmation_identity["studio_session_id"], + "principal_id": confirmation_identity["principal_id"], + } + packet_document: JsonObject = { + "schema_version": _PACKET_VERSION, + "intent_packet_id": "0" * 64, + "creative_session_id": creative_session_id, + "operation": operation, + "board": { + "board_id": authority["board"]["board_id"], + "representation_id": authority["board"]["representation_id"], + "fit_policy_id": authority["board"]["fit_policy_id"], + }, + "source": { + "asset_id": source_asset_id, + "content_ref": source_ref, + "content_sha256": source_sha256, + "mime": source_mime, + "width": source_raster.width, + "height": source_raster.height, + }, + "instruction": ( + "Replace only the selected apple tree with a mature lemon tree; preserve the water, " + "ground, camera, lighting, and every pixel outside the selection." + ), + "retrieval_route": copy.deepcopy(authority["retrieval_route"]), + "references": references, + "generation_request": generation_request, + "verification_policy": policy, + "confirmation": confirmation, + } + packet_document["intent_packet_id"] = compute_document_identity( + packet_document, + schema_version=_PACKET_VERSION, + identity_field="intent_packet_id", + ) + try: + return intent_from_json(packet_document) + except Exception: + _fail("intent_packet_invalid") + + +def _build_run_and_attempt( + *, + packet: IntentPacket, + capability: ProviderCapabilitySnapshot, + prepared: OpenRouterPreparedRequest, + timestamp: str, + uuid4: Callable[[], str | uuid.UUID], + generation_run_id: str | None = None, + attempt_id: str | None = None, +) -> tuple[GenerationRun, GenerationAttempt]: + packet_document = intent_to_json(packet) + request = packet_document["generation_request"] + generation_run_id = generation_run_id or _uuid_text(uuid4) + attempt_id = attempt_id or _uuid_text(uuid4) + run_document: JsonObject = { + "schema_version": RUN_VERSION, + "generation_run_id": generation_run_id, + "creative_session_id": packet_document["creative_session_id"], + "intent_packet_id": packet_document["intent_packet_id"], + "requested_provider": request["requested_provider"], + "requested_model": request["requested_model"], + "provider_route_policy_id": request["provider_route_policy"]["provider_route_policy_id"], + "created_at": timestamp, + } + normalized = prepared.normalized_request + attempt_document: JsonObject = { + "schema_version": ATTEMPT_VERSION, + "attempt_id": attempt_id, + "generation_run_id": generation_run_id, + "intent_packet_id": packet_document["intent_packet_id"], + "ordinal": 1, + "retry_of": None, + "fallback_of": None, + "requested_provider": request["requested_provider"], + "requested_model": request["requested_model"], + "provider_route_policy_id": request["provider_route_policy"]["provider_route_policy_id"], + "selected_route_id": ROUTE_ID, + "adapter_revision": ADAPTER_REVISION, + "capability_snapshot_id": capability.capability_snapshot_id, + "normalized_request_id": normalized.normalized_request_id, + "normalized_request_ref": build_normalized_request_ref(normalized), + "request_key_sha256": compute_provider_request_key( + generation_run_id=generation_run_id, + attempt_id=attempt_id, + intent_packet_id=packet_document["intent_packet_id"], + adapter_revision=ADAPTER_REVISION, + normalized_request_id=normalized.normalized_request_id, + ), + "created_at": timestamp, + } + try: + run = provider_from_json(run_document) + attempt = provider_from_json(attempt_document) + except Exception: + _fail("attempt_artifact_invalid") + if not isinstance(run, GenerationRun) or not isinstance(attempt, GenerationAttempt): + _fail("attempt_artifact_invalid") + return run, attempt + + +def _tls_context() -> ssl.SSLContext: + for name in ("SSLKEYLOGFILE", "SSL_CERT_FILE", "SSL_CERT_DIR"): + if os.environ.get(name): + _fail("ambient_tls_configuration_forbidden") + context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) + context.verify_mode = ssl.CERT_REQUIRED + context.check_hostname = True + context.load_default_certs() + context.set_alpn_protocols(["http/1.1"]) + return context + + +def _response_framing(response: http.client.HTTPResponse) -> tuple[int | None, bool]: + content_lengths = [ + value for name, value in response.getheaders() if name.lower() == "content-length" + ] + transfer_encodings = [ + value for name, value in response.getheaders() if name.lower() == "transfer-encoding" + ] + content_encodings = [ + value for name, value in response.getheaders() if name.lower() == "content-encoding" + ] + if len(content_lengths) > 1 or len(transfer_encodings) > 1 or len(content_encodings) > 1: + raise RuntimeError("invalid HTTP response framing") + if content_lengths and transfer_encodings: + raise RuntimeError("invalid HTTP response framing") + if content_encodings and content_encodings[0].strip().lower() not in {"", "identity"}: + raise RuntimeError("encoded HTTP responses are forbidden") + expected: int | None = None + if content_lengths: + raw = content_lengths[0] + if not raw.isascii() or not raw.isdecimal(): + raise RuntimeError("invalid HTTP response length") + expected = int(raw) + chunked = False + if transfer_encodings: + chunked = transfer_encodings[0].strip().lower() == "chunked" + if not chunked: + raise RuntimeError("unsupported HTTP transfer encoding") + return expected, chunked + + +def _read_http_body(response: http.client.HTTPResponse, *, limit: int) -> bytes: + expected, _ = _response_framing(response) + if expected is not None and expected > limit: + raise RuntimeError("HTTP response exceeds the registered byte limit") + chunks: list[bytes] = [] + measured = 0 + while True: + chunk = response.read1(min(65_536, limit + 1 - measured)) + if not chunk: + break + chunks.append(chunk) + measured += len(chunk) + if measured > limit: + raise RuntimeError("HTTP response exceeds the registered byte limit") + body = b"".join(chunks) + if expected is not None and len(body) != expected: + raise RuntimeError("HTTP response ended before Content-Length") + return body + + +def _fixed_https_get(host: str, path: str, *, limit: int, code: str) -> bytes: + connection = http.client.HTTPSConnection( + host, + 443, + timeout=_CONNECT_TIMEOUT_SECONDS, + context=_tls_context(), + ) + connection.set_debuglevel(0) + try: + with _wall_deadline(_PREPARE_FETCH_TIMEOUT_SECONDS): + connection.connect() + connection.request( + "GET", + path, + headers={ + "Accept": "application/json" if host == DISCOVERY_HOST else "image/jpeg", + "Accept-Encoding": "identity", + "Connection": "close", + }, + ) + response = connection.getresponse() + if response.status != 200: + _fail(code) + return _read_http_body(response, limit=limit) + except OpenRouterRealE2EError: + raise + except Exception: + _fail(code) + finally: + with contextlib.suppress(Exception): + connection.close() + + +def fetch_live_discovery() -> bytes: + return _fixed_https_get( + DISCOVERY_HOST, + DISCOVERY_PATH, + limit=_DISCOVERY_MAX_BYTES, + code="discovery_unavailable", + ) + + +def _validate_pinned_source(payload: bytes) -> bytes: + if ( + type(payload) is not bytes + or len(payload) != SOURCE_BYTE_COUNT + or hashlib.sha256(payload).hexdigest() != SOURCE_SHA256 + or blake3(payload).hexdigest() != SOURCE_CONTENT_REF + ): + _fail("source_identity_mismatch") + return payload + + +def load_pinned_source() -> bytes: + local = ROOT / ".cache" / "openrouter-real-e2e" / "source" / "fruit_apple_garden.jpg" + if local.is_file(): + return _validate_pinned_source( + _secure_read_private_file( + local, + limit=_SOURCE_MAX_BYTES, + code="source_unavailable", + ) + ) + payload = _fixed_https_get( + SOURCE_HOST, + SOURCE_PATH, + limit=_SOURCE_MAX_BYTES, + code="source_unavailable", + ) + return _validate_pinned_source(payload) + + +class _DeadlineExpired(TimeoutError): + pass + + +@contextlib.contextmanager +def _wall_deadline(seconds: float): + if threading.current_thread() is not threading.main_thread(): + raise RuntimeError("one-shot transport requires the main thread") + previous_handler = signal.getsignal(signal.SIGALRM) + previous_timer = signal.getitimer(signal.ITIMER_REAL) + if previous_timer != (0.0, 0.0): + raise RuntimeError("one-shot transport refuses a pre-existing wall timer") + + def expired(_signum: int, _frame: FrameType | None) -> None: + raise _DeadlineExpired("OpenRouter transport deadline exceeded") + + signal.signal(signal.SIGALRM, expired) + signal.setitimer(signal.ITIMER_REAL, seconds) + try: + yield + finally: + signal.setitimer(signal.ITIMER_REAL, 0) + signal.signal(signal.SIGALRM, previous_handler) + + +def _preflight_direct_transport_environment() -> None: + """Reject deterministic local transport failures before authorization is consumed.""" + + if threading.current_thread() is not threading.main_thread(): + _fail("direct_transport_environment_invalid") + try: + if signal.getitimer(signal.ITIMER_REAL) != (0.0, 0.0): + _fail("direct_transport_environment_invalid") + _tls_context() + except OpenRouterRealE2EError: + raise + except BaseException: + _fail("direct_transport_environment_invalid") + + +def _direct_openrouter_https_transport_secret_scope( + body: bytes, + bearer_token: str, +) -> tuple[str, OpenRouterHttpResponse | None]: + """Run the credential-bearing socket work without propagating its exception object.""" + + if type(body) is not bytes or not body or not isinstance(bearer_token, str): + return "invalid", None + connection: http.client.HTTPSConnection | None = None + try: + started = time.monotonic() + connection = http.client.HTTPSConnection( + DISCOVERY_HOST, + 443, + timeout=_CONNECT_TIMEOUT_SECONDS, + context=_tls_context(), + ) + connection.set_debuglevel(0) + with _wall_deadline(_TOTAL_TIMEOUT_SECONDS): + connection.connect() + if connection.sock is None: + raise RuntimeError("OpenRouter TLS connection is unavailable") + remaining = _TOTAL_TIMEOUT_SECONDS - (time.monotonic() - started) + if remaining <= 0: + raise _DeadlineExpired("OpenRouter transport deadline exceeded") + connection.sock.settimeout(remaining) + connection.putrequest("POST", DISPATCH_PATH, skip_accept_encoding=True) + connection.putheader("Authorization", f"Bearer {bearer_token}") + connection.putheader("Content-Type", "application/json") + connection.putheader("Accept", "application/json") + connection.putheader("Accept-Encoding", "identity") + connection.putheader("Connection", "close") + connection.putheader("Content-Length", str(len(body))) + connection.endheaders(body) + response = connection.getresponse() + response_body = _read_http_body(response, limit=_HTTP_RESPONSE_MAX_BYTES) + content_type = response.getheader("Content-Type") + headers = {"content-type": content_type} if content_type is not None else {} + elapsed = max(0, math.ceil((time.monotonic() - started) * 1000)) + return ( + "ok", + OpenRouterHttpResponse( + status=response.status, + headers=headers, + body=response_body, + elapsed_milliseconds=elapsed, + ), + ) + except _DeadlineExpired: + return "timeout", None + except BaseException: + return "failed", None + finally: + if connection is not None: + with contextlib.suppress(Exception): + connection.close() + + +def direct_openrouter_https_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + """One fixed-origin POST with no proxy, redirect, retry, or resettable wall deadline.""" + + outcome, response = _direct_openrouter_https_transport_secret_scope(body, bearer_token) + # A raised public error must not retain credential-bearing arguments in traceback locals. + body = b"" + bearer_token = "" + if outcome == "timeout": + raise TimeoutError("OpenRouter transport deadline exceeded") from None + if outcome != "ok" or response is None: + raise RuntimeError("OpenRouter transport failed") from None + return response + + +def _ensure_new_output_dir(path: Path) -> None: + if not path.is_absolute(): + _fail("output_dir_must_be_absolute") + try: + os.mkdir(path, 0o700) + except FileExistsError: + _fail("output_dir_exists") + except OSError: + _fail("output_dir_unavailable") + try: + metadata = path.lstat() + except OSError: + _fail("output_dir_unavailable") + if ( + not stat.S_ISDIR(metadata.st_mode) + or metadata.st_uid != os.getuid() + or stat.S_IMODE(metadata.st_mode) != 0o700 + ): + _fail("output_dir_insecure") + + +def _directory_identity(path: Path, *, code: str) -> JsonObject: + try: + resolved = path.resolve(strict=True) + metadata = path.lstat() + except OSError: + _fail(code) + if ( + resolved != path + or not stat.S_ISDIR(metadata.st_mode) + or metadata.st_uid != os.getuid() + or stat.S_IMODE(metadata.st_mode) != 0o700 + ): + _fail(code) + return { + "absolute_path": str(path), + "device": metadata.st_dev, + "inode": metadata.st_ino, + } + + +def _secure_read_private_file(path: Path, *, limit: int, code: str) -> bytes: + """Read one owner-only, single-link regular file without following its final component.""" + + descriptor: int | None = None + try: + before = path.lstat() + if ( + not stat.S_ISREG(before.st_mode) + or before.st_uid != os.getuid() + or before.st_nlink != 1 + or stat.S_IMODE(before.st_mode) != 0o600 + or not 0 <= before.st_size <= limit + ): + _fail(code) + flags = os.O_RDONLY + if hasattr(os, "O_NOFOLLOW"): + flags |= os.O_NOFOLLOW + descriptor = os.open(path, flags) + opened = os.fstat(descriptor) + if (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + _fail(code) + chunks: list[bytes] = [] + measured = 0 + while True: + chunk = os.read(descriptor, min(65_536, limit + 1 - measured)) + if not chunk: + break + chunks.append(chunk) + measured += len(chunk) + if measured > limit: + _fail(code) + return b"".join(chunks) + except OpenRouterRealE2EError: + raise + except Exception: + _fail(code) + finally: + if descriptor is not None: + with contextlib.suppress(OSError): + os.close(descriptor) + + +def _strict_json_object(raw: bytes, *, limit: int, code: str) -> JsonObject: + if type(raw) is not bytes or not 1 <= len(raw) <= limit: + _fail(code) + + def unique(pairs: list[tuple[str, Any]]) -> JsonObject: + result: JsonObject = {} + for key, value in pairs: + if key in result: + raise ValueError("duplicate JSON key") + result[key] = value + return result + + def bounded_float(token: str) -> float: + if not 1 <= len(token) <= 64: + raise ValueError + measured = float(token) + if not math.isfinite(measured): + raise ValueError + return measured + + def bounded_int(token: str) -> int: + if not 1 <= len(token) <= 32: + raise ValueError + return int(token) + + _preflight_json_structure(raw, code=code) + + def parse() -> Any: + text = raw.decode("utf-8", errors="strict") + return json.loads( + text, + object_pairs_hook=unique, + parse_float=bounded_float, + parse_int=bounded_int, + parse_constant=lambda _: (_ for _ in ()).throw(ValueError("JSON constant")), + ) + + ok, value = _call_sanitized(parse) + if not ok or not isinstance(value, dict): + _fail(code) + _bounded_tree(value, code=code) + return value + + +def _write_private_bytes(path: Path, payload: bytes) -> None: + if type(payload) is not bytes: + _fail("artifact_write_failed") + descriptor: int | None = None + try: + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL + if hasattr(os, "O_NOFOLLOW"): + flags |= os.O_NOFOLLOW + descriptor = os.open(path, flags, 0o600) + with os.fdopen(descriptor, "wb", closefd=True) as stream: + descriptor = None + stream.write(payload) + stream.flush() + os.fsync(stream.fileno()) + if stat.S_IMODE(path.lstat().st_mode) != 0o600: + _fail("artifact_write_failed") + except OpenRouterRealE2EError: + raise + except Exception: + _fail("artifact_write_failed") + finally: + if descriptor is not None: + with contextlib.suppress(OSError): + os.close(descriptor) + + +def _json_bytes(document: Mapping[str, Any]) -> bytes: + try: + return ( + json.dumps(document, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n" + ).encode("utf-8") + except Exception: + _fail("artifact_serialization_failed") + + +def _write_private_json(path: Path, document: Mapping[str, Any]) -> None: + _write_private_bytes(path, _json_bytes(document)) + + +def _artifact_descriptor(payload: bytes, relative_path: str) -> JsonObject: + if type(payload) is not bytes or not payload or not relative_path: + _fail("challenge_artifact_invalid") + return { + "relative_path": relative_path, + "sha256": hashlib.sha256(payload).hexdigest(), + "byte_count": len(payload), + } + + +def _canonical_uuid(value: object, *, code: str) -> str: + if not isinstance(value, str): + _fail(code) + try: + measured = str(uuid.UUID(value)) + except (ValueError, AttributeError): + _fail(code) + if measured != value: + _fail(code) + return measured + + +def _verify_document_identity( + document: Mapping[str, Any], + *, + schema_version: str, + identity_field: str, + code: str, +) -> None: + identity = document.get(identity_field) + if not isinstance(identity, str) or len(identity) != 64: + _fail(code) + try: + expected = compute_document_identity( + document, + schema_version=schema_version, + identity_field=identity_field, + ) + except Exception: + _fail(code) + if identity != expected: + _fail(code) + + +def _validate_authority_document(document: Mapping[str, Any]) -> JsonObject: + expected_keys = { + "schema_version", + "authority_id", + "creative_session_id", + "board", + "retrieval_route", + "references", + } + if set(document) != expected_keys or document.get("schema_version") != ( + "moodboard.openrouter-real-e2e-authority.v1" + ): + _fail("authority_invalid") + _verify_document_identity( + document, + schema_version="moodboard.openrouter-real-e2e-authority.v1", + identity_field="authority_id", + code="authority_invalid", + ) + _canonical_uuid(document.get("creative_session_id"), code="authority_invalid") + board = document.get("board") + route = document.get("retrieval_route") + references = document.get("references") + if ( + not isinstance(board, dict) + or set(board) != {"board_id", "representation_id", "fit_policy_id"} + or not all(isinstance(board.get(name), str) and len(board[name]) == 64 for name in board) + or not isinstance(route, dict) + or set(route) + != { + "schema_version", + "route_policy_id", + "eligible_corpus_sha256", + "empty_result_policy", + "evidence_artifact_id", + } + or route.get("schema_version") != "moodboard.intent-route.collection-gate.v1" + or route.get("empty_result_policy") != "no_ungated_fallback" + or not all( + isinstance(route.get(name), str) and len(route[name]) == 64 + for name in ( + "route_policy_id", + "eligible_corpus_sha256", + "evidence_artifact_id", + ) + ) + or not isinstance(references, list) + or not 1 <= len(references) <= 32 + ): + _fail("authority_invalid") + # IntentPacket validation remains the authority for the closed per-reference shape. Here we + # only reject values that could make projection or copying unsafe before that validation. + if any(not isinstance(reference, dict) for reference in references): + _fail("authority_invalid") + return copy.deepcopy(dict(document)) + + +def _load_authority_snapshot( + authority_bundle: bytes | None, + authority_loader: Callable[[], OpenRouterRealE2EAuthority | _AuthoritySnapshot] | None, +) -> _AuthoritySnapshot: + if authority_bundle is not None: + if type(authority_bundle) is not bytes or not 1 <= len(authority_bundle) <= 4 * 1024 * 1024: + _fail("authority_invalid") + document = _strict_json_object( + authority_bundle, + limit=4 * 1024 * 1024, + code="authority_invalid", + ) + return _AuthoritySnapshot(_validate_authority_document(document), authority_bundle) + if authority_loader is None: + _fail("authority_unavailable") + authority_error_code: str | None = None + try: + loaded = authority_loader() + ok = True + except OpenRouterRealE2EAuthorityError as error: + authority_error_code = ( + error.code + if isinstance(error.code, str) and error.code in _SAFE_AUTHORITY_ERROR_CODES + else "authority_unavailable" + ) + loaded = None + ok = False + except BaseException: + loaded = None + ok = False + if not ok: + # Raise outside the exception handler so no authority-reader traceback or path is retained. + _fail(authority_error_code or "authority_unavailable") + if isinstance(loaded, _AuthoritySnapshot): + return _AuthoritySnapshot( + _validate_authority_document(loaded.document), + loaded.payload, + loaded.board_artifact_bytes, + loaded.pixel_rag_artifact_bytes, + ) + if isinstance(loaded, OpenRouterRealE2EAuthority): + # The board/Pixel-RAG helper deliberately does not invent an enrolled creative session. + # A trusted Studio boundary must wrap it in the closed authority bundle above. + _fail("authority_context_unavailable") + _fail("authority_invalid") + + +def _packet_projection(packet: IntentPacket) -> JsonObject: + document = intent_to_json(packet) + document.pop("intent_packet_id", None) + document.pop("confirmation", None) + return document + + +def _compact_confirmation_projection(packet_projection: Mapping[str, Any]) -> JsonObject: + """Project every confirmation-renewal authority shown in the compact summary.""" + + try: + operation = packet_projection["operation"] + references = packet_projection["references"] + request = packet_projection["generation_request"] + policy = packet_projection["verification_policy"] + if ( + not isinstance(operation, Mapping) + or not isinstance(references, list) + or not isinstance(request, Mapping) + or not isinstance(policy, Mapping) + ): + raise TypeError("confirmation projection authorities are not objects") + dispatch = { + name: copy.deepcopy(request[name]) + for name in ( + "requested_provider", + "requested_model", + "output_count", + "destination", + "adapter_revision", + "capability_snapshot_id", + "options", + "provider_route_policy", + "actual_model_policy", + "idempotency", + "reconciliation", + ) + } + dispatch["verification_policy_id"] = copy.deepcopy(policy["policy_id"]) + dispatch["required_verifiers"] = copy.deepcopy(policy["required_verifiers"]) + return { + "operation": { + "kind": copy.deepcopy(operation["kind"]), + "schema_version": copy.deepcopy(operation["schema_version"]), + }, + "reference_count": len(references), + "operation_inputs": copy.deepcopy(request["operation_inputs"]), + "dispatch_confirmation": dispatch, + } + except Exception: + _fail("challenge_artifact_drift") + + +def _build_capability(discovery_body: bytes, *, captured_at: str) -> ProviderCapabilitySnapshot: + try: + return build_openrouter_capability_snapshot( + discovery_body, + requested_model=MODEL, + selected_provider_tag=PROVIDER_TAG, + captured_at=captured_at, + adapter_revision=ADAPTER_REVISION, + source_capability_id=_label_digest("source-capability"), + locality_mask_capability_id=_label_digest("mask-capability"), + adapter_admission_limits=OpenRouterAdapterAdmissionLimits( + mime_types=("image/png", "image/jpeg"), + max_width=8192, + max_height=8192, + max_encoded_output_bytes=16_777_216, + ), + ) + except Exception: + _fail("discovery_capability_invalid") + + +def _prepare_request( + packet: IntentPacket, + capability: ProviderCapabilitySnapshot, + source_bytes: bytes, +) -> OpenRouterPreparedRequest: + source_ref = blake3(source_bytes).hexdigest() + + def resolve_content(content_ref: str) -> bytes: + if content_ref != source_ref: + _fail("unexpected_content_resolution") + return source_bytes + + try: + prepared = prepare_openrouter_request( + packet, + capability, + selected_route_id=ROUTE_ID, + resolve_content=resolve_content, + ) + except Exception: + _fail("request_preparation_failed") + _assert_wire(prepared) + return prepared + + +def _dummy_confirmation(prepared_at: str) -> JsonObject: + """A never-persisted placeholder used only to derive confirmation-neutral request bytes.""" + + return { + "compact_summary_id": "0" * 64, + "confirmed_at": prepared_at, + "studio_session_id": "00000000-0000-4000-8000-000000000001", + "principal_id": "00000000-0000-4000-8000-000000000002", + } + + +def prepare_openrouter_real_e2e( + challenge_dir: Path, + *, + _discovery_fetcher: Callable[[], bytes] = fetch_live_discovery, + _source_fetcher: Callable[[], bytes] = load_pinned_source, + _authority_bundle: bytes | None = None, + _authority_loader: Callable[[], OpenRouterRealE2EAuthority | _AuthoritySnapshot] | None = None, + _clock: Callable[[], str] = _canonical_timestamp, + _uuid4: Callable[[], str | uuid.UUID] = uuid.uuid4, +) -> OpenRouterRealE2EChallenge: + """Create one credential-free, content-bound confirmation challenge. + + This function cannot authorize or dispatch. It freezes the exact preview and proposal that a + trusted Studio boundary must show and confirm in a separate closed context document. + """ + + target = Path(challenge_dir) + if target.exists() or target.is_symlink(): + _fail("output_dir_exists") + if not target.is_absolute(): + _fail("output_dir_must_be_absolute") + if (_authority_bundle is None) == (_authority_loader is None): + _fail("authority_unavailable" if _authority_bundle is None else "authority_ambiguous") + if not all(callable(value) for value in (_discovery_fetcher, _source_fetcher, _clock, _uuid4)): + _fail("evaluation_callable_invalid") + if _authority_loader is not None and not callable(_authority_loader): + _fail("evaluation_callable_invalid") + + ok, discovery_body = _call_sanitized(_discovery_fetcher) + if not ok or type(discovery_body) is not bytes: + _fail("discovery_unavailable") + quote = parse_openrouter_quote( + discovery_body, + input_count=1, + output_count=OUTPUT_COUNT, + resolution=RESOLUTION, + ) + with localcontext(_QUOTE_CONTEXT): + if quote > QUOTE_ADMISSION_LIMIT_USD: + _fail("quote_exceeds_cap") + + ok, prepared_at_value = _call_sanitized(_clock) + if not ok or not isinstance(prepared_at_value, str): + _fail("clock_invalid") + prepared_at = prepared_at_value + _timestamp_value(prepared_at, code="clock_invalid") + expires_at = _timestamp_after(prepared_at, seconds=_CHALLENGE_TTL_SECONDS) + capability = _build_capability(discovery_body, captured_at=prepared_at) + + ok, source_value = _call_sanitized(_source_fetcher) + if not ok or type(source_value) is not bytes: + _fail("source_unavailable") + source_bytes = source_value + if not 1 <= len(source_bytes) <= _SOURCE_MAX_BYTES: + _fail("source_invalid") + source_sha256 = hashlib.sha256(source_bytes).hexdigest() + try: + source_raster = compile_canonical_raster( + source_bytes, + source_content_sha256=source_sha256, + ) + bounds = _mask_bounds(source_raster) + mask = compile_rectangle_mask( + source_raster, + left=bounds[0], + top=bounds[1], + right=bounds[2], + bottom=bounds[3], + ) + except Exception: + _fail("source_media_invalid") + overlay_bytes = _render_mask_overlay(source_raster, bounds) + authority = _load_authority_snapshot(_authority_bundle, _authority_loader) + creative_session_id = _canonical_uuid( + authority.document["creative_session_id"], code="authority_invalid" + ) + provisional_packet = _build_packet( + source_bytes=source_bytes, + source_raster=source_raster, + mask=mask, + capability=capability, + authority=authority.document, + creative_session_id=creative_session_id, + confirmation_identity=_dummy_confirmation(prepared_at), + ) + prepared = _prepare_request(provisional_packet, capability, source_bytes) + packet_projection = _packet_projection(provisional_packet) + generation_run_id = _uuid_text(_uuid4) + attempt_id = _uuid_text(_uuid4) + + _ensure_new_output_dir(target) + directory_binding = _directory_identity(target, code="challenge_binding_mismatch") + source_suffix = ".jpg" if _mime_for_bytes(source_bytes) == "image/jpeg" else ".png" + artifact_payloads: dict[str, tuple[str, bytes]] = { + "discovery": ("discovery.json", discovery_body), + "source": (f"source{source_suffix}", source_bytes), + "authority": ("authority.json", authority.payload), + "mask": ("mask.u8", mask.mask_bytes), + "overlay": ("overlay.png", overlay_bytes), + } + artifacts: JsonObject = { + name: _artifact_descriptor(payload, relative_path) + for name, (relative_path, payload) in artifact_payloads.items() + } + confirmation_projection = _compact_confirmation_projection(packet_projection) + compact_summary: JsonObject = { + "schema_version": _COMPACT_SUMMARY_VERSION, + "compact_summary_id": "0" * 64, + "instruction": packet_projection["instruction"], + "quoted_cost_usd": str(quote), + "quote_admission_limit_usd": str(QUOTE_ADMISSION_LIMIT_USD), + "spend_limit_kind": "quote_only_not_provider_enforced", + "requested_model_notice": "requested model only; actual model is not attested", + "upstream_route_notice": "request is pinned; serving upstream remains unknown", + "compositor_notice": "not authorized and not run", + "semantic_aesthetic_notice": ( + "not run; provider lifecycle success is not aesthetic acceptance" + ), + "source_preview": { + "content_sha256": source_sha256, + "width": source_raster.width, + "height": source_raster.height, + "mime": _mime_for_bytes(source_bytes), + }, + "mask_overlay": { + "mask_sha256": mask.mask_sha256, + "bounds": { + "left": bounds[0], + "top": bounds[1], + "right": bounds[2], + "bottom": bounds[3], + }, + "editable_count": mask.editable_count, + "protected_count": mask.protected_count, + }, + "board": copy.deepcopy(authority.document["board"]), + "retrieval_route": copy.deepcopy(authority.document["retrieval_route"]), + "references": copy.deepcopy(authority.document["references"]), + **confirmation_projection, + "dispatch": { + "provider": "openrouter", + "model": MODEL, + "provider_only": [PROVIDER_TAG], + "allow_fallbacks": False, + "n": OUTPUT_COUNT, + "resolution": RESOLUTION, + "aspect_ratio": ASPECT_RATIO, + "wire_body_sha256": prepared.wire_body_sha256, + "wire_body_byte_count": prepared.wire_body_byte_count, + }, + "artifacts": copy.deepcopy(artifacts), + } + compact_summary["compact_summary_id"] = compute_document_identity( + compact_summary, + schema_version=_COMPACT_SUMMARY_VERSION, + identity_field="compact_summary_id", + ) + summary_bytes = _json_bytes(compact_summary) + artifacts["compact_summary"] = _artifact_descriptor(summary_bytes, "compact-summary.json") + challenge: JsonObject = { + "schema_version": _CHALLENGE_VERSION, + "challenge_id": "0" * 64, + "compact_summary_id": compact_summary["compact_summary_id"], + "prepared_at": prepared_at, + "expires_at": expires_at, + "directory_binding": directory_binding, + "artifacts": copy.deepcopy(artifacts), + "quoted_cost_usd": str(quote), + "quote_admission_limit_usd": str(QUOTE_ADMISSION_LIMIT_USD), + "spend_limit_kind": "quote_only_not_provider_enforced", + "creative_session_id": creative_session_id, + "generation_run_id": generation_run_id, + "attempt_id": attempt_id, + "capability_snapshot_id": capability.capability_snapshot_id, + "wire_body_sha256": prepared.wire_body_sha256, + "wire_body_byte_count": prepared.wire_body_byte_count, + "packet_projection": packet_projection, + } + challenge["challenge_id"] = compute_document_identity( + challenge, + schema_version=_CHALLENGE_VERSION, + identity_field="challenge_id", + ) + for _name, (relative_path, payload) in artifact_payloads.items(): + _write_private_bytes(target / relative_path, payload) + _write_private_bytes(target / "compact-summary.json", summary_bytes) + _write_private_json(target / "challenge.json", challenge) + return OpenRouterRealE2EChallenge( + challenge_id=str(challenge["challenge_id"]), + compact_summary_id=str(compact_summary["compact_summary_id"]), + prepared_at=prepared_at, + expires_at=expires_at, + quoted_cost_usd=quote, + quote_admission_limit_usd=QUOTE_ADMISSION_LIMIT_USD, + wire_body_sha256=prepared.wire_body_sha256, + wire_body_byte_count=prepared.wire_body_byte_count, + directory=target, + ) + + +def _challenge_snapshot(target: Path) -> tuple[JsonObject, dict[str, bytes], JsonObject]: + consumed = target / "consumed.json" + if consumed.exists() or consumed.is_symlink(): + _fail("challenge_consumed") + try: + current_binding = _directory_identity(target, code="challenge_binding_mismatch") + except OpenRouterRealE2EError: + raise + challenge_bytes = _secure_read_private_file( + target / "challenge.json", + limit=4 * 1024 * 1024, + code="challenge_artifact_drift", + ) + challenge = _strict_json_object( + challenge_bytes, + limit=4 * 1024 * 1024, + code="challenge_artifact_drift", + ) + expected_keys = { + "schema_version", + "challenge_id", + "compact_summary_id", + "prepared_at", + "expires_at", + "directory_binding", + "artifacts", + "quoted_cost_usd", + "quote_admission_limit_usd", + "spend_limit_kind", + "creative_session_id", + "generation_run_id", + "attempt_id", + "capability_snapshot_id", + "wire_body_sha256", + "wire_body_byte_count", + "packet_projection", + } + if ( + set(challenge) != expected_keys + or challenge.get("schema_version") != _CHALLENGE_VERSION + or challenge.get("directory_binding") != current_binding + ): + _fail("challenge_binding_mismatch") + _verify_document_identity( + challenge, + schema_version=_CHALLENGE_VERSION, + identity_field="challenge_id", + code="challenge_artifact_drift", + ) + _canonical_uuid(challenge.get("creative_session_id"), code="challenge_artifact_drift") + _canonical_uuid(challenge.get("generation_run_id"), code="challenge_artifact_drift") + _canonical_uuid(challenge.get("attempt_id"), code="challenge_artifact_drift") + artifacts = challenge.get("artifacts") + required_artifacts = { + "discovery", + "source", + "authority", + "mask", + "overlay", + "compact_summary", + } + if not isinstance(artifacts, dict) or set(artifacts) != required_artifacts: + _fail("challenge_artifact_drift") + limits = { + "discovery": _DISCOVERY_MAX_BYTES, + "source": _SOURCE_MAX_BYTES, + "authority": 4 * 1024 * 1024, + "mask": 64 * 1024 * 1024, + "overlay": 64 * 1024 * 1024, + "compact_summary": 4 * 1024 * 1024, + } + payloads: dict[str, bytes] = {} + for name in sorted(required_artifacts): + descriptor = artifacts[name] + if not isinstance(descriptor, dict) or set(descriptor) != { + "relative_path", + "sha256", + "byte_count", + }: + _fail("challenge_artifact_drift") + relative_path = descriptor.get("relative_path") + if not isinstance(relative_path, str): + _fail("challenge_artifact_drift") + relative = Path(relative_path) + if relative.is_absolute() or len(relative.parts) != 1 or relative.name != relative_path: + _fail("challenge_artifact_drift") + payload = _secure_read_private_file( + target / relative, + limit=limits[name], + code="challenge_artifact_drift", + ) + if ( + descriptor.get("byte_count") != len(payload) + or descriptor.get("sha256") != hashlib.sha256(payload).hexdigest() + ): + _fail("challenge_artifact_drift") + payloads[name] = payload + summary = _strict_json_object( + payloads["compact_summary"], + limit=4 * 1024 * 1024, + code="challenge_artifact_drift", + ) + expected_summary_keys = { + "schema_version", + "compact_summary_id", + "instruction", + "quoted_cost_usd", + "quote_admission_limit_usd", + "spend_limit_kind", + "requested_model_notice", + "upstream_route_notice", + "compositor_notice", + "semantic_aesthetic_notice", + "source_preview", + "mask_overlay", + "board", + "retrieval_route", + "references", + "operation", + "reference_count", + "operation_inputs", + "dispatch_confirmation", + "dispatch", + "artifacts", + } + packet_projection = challenge.get("packet_projection") + if not isinstance(packet_projection, Mapping): + _fail("challenge_artifact_drift") + expected_confirmation = _compact_confirmation_projection(packet_projection) + if ( + set(summary) != expected_summary_keys + or summary.get("schema_version") != _COMPACT_SUMMARY_VERSION + or summary.get("compact_summary_id") != challenge.get("compact_summary_id") + or summary.get("artifacts") + != {name: artifacts[name] for name in required_artifacts if name != "compact_summary"} + or any(summary.get(name) != value for name, value in expected_confirmation.items()) + ): + _fail("challenge_artifact_drift") + _verify_document_identity( + summary, + schema_version=_COMPACT_SUMMARY_VERSION, + identity_field="compact_summary_id", + code="challenge_artifact_drift", + ) + return challenge, payloads, summary + + +def _confirmation_snapshot( + path: Path, + *, + challenge: Mapping[str, Any], + now: str, +) -> tuple[JsonObject, bytes]: + try: + path.lstat() + except FileNotFoundError: + _fail("confirmation_context_unavailable") + except OSError: + _fail("confirmation_context_invalid") + payload = _secure_read_private_file( + path, + limit=64 * 1024, + code="confirmation_context_invalid", + ) + context = _strict_json_object( + payload, + limit=64 * 1024, + code="confirmation_context_invalid", + ) + expected_keys = { + "schema_version", + "confirmation_context_id", + "challenge_id", + "compact_summary_id", + "decision", + "authorized_generation_post_count", + "principal_id", + "studio_session_id", + "creative_session_id", + "confirmed_at", + } + if ( + set(context) != expected_keys + or context.get("schema_version") != _CONFIRMATION_CONTEXT_VERSION + or context.get("challenge_id") != challenge.get("challenge_id") + or context.get("compact_summary_id") != challenge.get("compact_summary_id") + or context.get("decision") != "approve_one_paid_call" + or type(context.get("authorized_generation_post_count")) is not int + or context.get("authorized_generation_post_count") != 1 + or context.get("creative_session_id") != challenge.get("creative_session_id") + ): + _fail("confirmation_context_invalid") + _verify_document_identity( + context, + schema_version=_CONFIRMATION_CONTEXT_VERSION, + identity_field="confirmation_context_id", + code="confirmation_context_invalid", + ) + for name in ("principal_id", "studio_session_id", "creative_session_id"): + _canonical_uuid(context.get(name), code="confirmation_context_invalid") + prepared_at = _timestamp_value( + challenge.get("prepared_at"), code="confirmation_context_invalid" + ) + expires_at = _timestamp_value(challenge.get("expires_at"), code="confirmation_context_invalid") + confirmed_at = _timestamp_value( + context.get("confirmed_at"), code="confirmation_context_invalid" + ) + measured_now = _timestamp_value(now, code="clock_invalid") + if confirmed_at < prepared_at or confirmed_at > expires_at or confirmed_at > measured_now: + _fail("confirmation_context_invalid") + if measured_now > expires_at: + _fail("challenge_expired") + return context, payload + + +def _reported_cost_telemetry(dispatch: OpenRouterDispatchResult) -> tuple[Decimal | None, str]: + """Return honest post-hoc USD telemetry without turning it into an admission gate.""" + + if dispatch.decoded is None: + return None, "not_reported" + try: + receipt = provider_to_json(dispatch.decoded.receipt) + cost = receipt.get("cost") + if ( + not isinstance(cost, dict) + or cost.get("state") != "reported" + or not isinstance(cost.get("amount"), str) + ): + return None, "not_reported" + if cost.get("currency") != "USD": + return None, "reported_non_usd" + measured = Decimal(cost["amount"]) + if not measured.is_finite() or measured < 0: + return None, "not_reported" + return measured, "reported" + except Exception: + return None, "not_reported" + + +def _claim_challenge_consumption( + target: Path, + *, + challenge: Mapping[str, Any], + context: Mapping[str, Any], + consumed_at: str, +) -> None: + if _directory_identity(target, code="challenge_binding_mismatch") != challenge.get( + "directory_binding" + ): + _fail("challenge_binding_mismatch") + payload = _json_bytes( + { + "schema_version": "moodboard.openrouter-real-e2e-consumption.v1", + "challenge_id": challenge["challenge_id"], + "confirmation_context_id": context["confirmation_context_id"], + "consumed_at": consumed_at, + } + ) + descriptor: int | None = None + directory_descriptor: int | None = None + try: + directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) + if hasattr(os, "O_NOFOLLOW"): + directory_flags |= os.O_NOFOLLOW + directory_descriptor = os.open(target, directory_flags) + opened_directory = os.fstat(directory_descriptor) + binding = challenge["directory_binding"] + if ( + not stat.S_ISDIR(opened_directory.st_mode) + or opened_directory.st_uid != os.getuid() + or stat.S_IMODE(opened_directory.st_mode) != 0o700 + or opened_directory.st_dev != binding["device"] + or opened_directory.st_ino != binding["inode"] + ): + _fail("challenge_binding_mismatch") + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL + if hasattr(os, "O_NOFOLLOW"): + flags |= os.O_NOFOLLOW + descriptor = os.open("consumed.json", flags, 0o600, dir_fd=directory_descriptor) + view = memoryview(payload) + written = 0 + while written < len(view): + count = os.write(descriptor, view[written:]) + if count <= 0: + _fail("challenge_consumption_failed") + written += count + os.fsync(descriptor) + os.close(descriptor) + descriptor = None + os.fsync(directory_descriptor) + except FileExistsError: + _fail("challenge_consumed") + except OpenRouterRealE2EError: + raise + except BaseException: + _fail("challenge_consumption_failed") + finally: + if descriptor is not None: + with contextlib.suppress(OSError): + os.close(descriptor) + if directory_descriptor is not None: + with contextlib.suppress(OSError): + os.close(directory_descriptor) + + +def _execute_with_token( + *, + target: Path, + token: str, + packet: IntentPacket, + capability: ProviderCapabilitySnapshot, + prepared: OpenRouterPreparedRequest, + run: GenerationRun, + attempt: GenerationAttempt, + source_bytes: bytes, + source_raster: CanonicalRasterArtifact, + mask: CanonicalMaskArtifact, + quote: Decimal, + discovery_body: bytes, + expires_at: str, + directory_binding: Mapping[str, Any], + transport: Callable[..., OpenRouterHttpResponse], + clock: Callable[[], str], + uuid4_factory: Callable[[], str | uuid.UUID], +) -> tuple[str, OpenRouterRealE2EResult | None]: + """Keep every token-bearing object below a frame that never raises to the caller.""" + + journal: AttemptJournal | None = None + try: + if not isinstance(token, str): + return "credential_unavailable", None + if _directory_identity(target, code="challenge_binding_mismatch") != directory_binding: + return "challenge_binding_mismatch", None + sampled = clock() + if _timestamp_value(sampled, code="clock_invalid") > _timestamp_value( + expires_at, code="challenge_artifact_drift" + ): + return "challenge_expired", None + journal = AttemptJournal( + (target / "attempts.sqlite3").resolve(), + forbidden_secrets=(token,), + ) + journal.register_run(run) + registered_attempt = journal.register_attempt(attempt).artifact + if not isinstance(registered_attempt, GenerationAttempt): + return "journal_registration_failed", None + prepared_event = seal_provider_artifact( + { + "schema_version": EVENT_VERSION, + "attempt_id": attempt.attempt_id, + "sequence": 1, + "state": "prepared", + "recorded_at": attempt.created_at, + "detail": {"kind": "prepared"}, + } + ) + journal.append_event( + prepared_event, + expected_head_event_id=None, + expected_next_sequence=1, + ) + post_count = 0 + + if _directory_identity(target, code="challenge_binding_mismatch") != directory_binding: + return "challenge_binding_mismatch", None + immediately_before_claim = clock() + if _timestamp_value(immediately_before_claim, code="clock_invalid") > _timestamp_value( + expires_at, code="challenge_artifact_drift" + ): + return "challenge_expired", None + + def one_shot_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + nonlocal post_count + if post_count != 0: + raise RuntimeError("one-shot transport replay was refused") + post_count += 1 + return transport(body=body, bearer_token=bearer_token) + + dispatch = dispatch_openrouter_attempt( + journal, + attempt, + capability, + prepared, + credential_resolver=lambda profile: token if profile == CREDENTIAL_PROFILE_ID else "", + transport=one_shot_transport, + dispatch_claim_id=_uuid_text(uuid4_factory), + claimed_at=immediately_before_claim, + recorded_at=clock, + ) + receipt_id = ( + dispatch.decoded.receipt.provider_receipt_id if dispatch.decoded is not None else None + ) + reported_cost, cost_telemetry_status = _reported_cost_telemetry(dispatch) + if dispatch.kind != "response_received": + journal.verify_integrity() + result = _partial_result( + run=run, + attempt=attempt, + journal=journal, + quote=quote, + post_count=post_count, + receipt_id=receipt_id, + reported_cost=reported_cost, + cost_telemetry_status=cost_telemetry_status, + ) + _write_private_json( + target / "result.json", + _result_document( + result, + source_sha256=hashlib.sha256(source_bytes).hexdigest(), + source_content_ref=blake3(source_bytes).hexdigest(), + mask_sha256=mask.mask_sha256, + discovery_sha256=hashlib.sha256(discovery_body).hexdigest(), + wire_sha256=prepared.wire_body_sha256, + wire_byte_count=prepared.wire_body_byte_count, + ), + ) + _scan_private_artifacts(target, token) + return "ok", result + + if dispatch.state.head_event_id is None: + return "response_state_invalid", None + stored_response = journal.read_provider_response(attempt.attempt_id) + terminal_at = clock() + try: + success = journal.publish_provider_success( + attempt.attempt_id, + packet, + prepared.normalized_request, + succeeded_at=terminal_at, + expected_head_event_id=dispatch.state.head_event_id, + expected_next_sequence=dispatch.state.next_sequence, + ) + except ProviderMediaAdmissionError as admission_error: + structural_document: JsonObject | None = None + locality_document: JsonObject | None = None + structural_state = "not_run" + structural_reason: str | None = None + locality_state = "not_run" + if len(stored_response.output_bytes) == 1: + try: + structural = verify_output_structure( + source_raster, + provider_receipt=stored_response.receipt, + output_index=0, + output_bytes=stored_response.output_bytes[0], + output_occurrence=None, + ) + structural_document = judgment_to_json(structural.judgment) + structural_state = str(structural_document["result"]["state"]) + reason = structural_document["result"].get("reason") + structural_reason = reason if isinstance(reason, str) else None + locality = build_locality_not_run(structural.judgment, mask) + locality_document = judgment_to_json(locality) + locality_state = str(locality_document["result"]["state"]) + except Exception: + structural_document = None + locality_document = None + structural_state = "not_run" + structural_reason = None + locality_state = "not_run" + # ADR-0014 keeps media/provenance rejection at response_received. The structural + # judgment and locality not_run evidence remain visible without forging a terminal + # provider failure or a selectable output occurrence. + journal.verify_integrity() + result = OpenRouterRealE2EResult( + generation_run_id=run.generation_run_id, + attempt_id=attempt.attempt_id, + provider_receipt_id=stored_response.receipt.provider_receipt_id, + output_occurrence_id=None, + quoted_cost_usd=quote, + reported_cost_usd=reported_cost, + cost_telemetry_status=cost_telemetry_status, + states=tuple(event.state for event in journal.read_events(attempt.attempt_id)), + generation_post_count=post_count, + provider_media_admission_result=admission_error.code, + raw_structural_result=structural_state, + raw_structural_reason=structural_reason, + raw_locality_result=locality_state, + ) + _write_private_json( + target / "result.json", + _result_document( + result, + source_sha256=hashlib.sha256(source_bytes).hexdigest(), + source_content_ref=blake3(source_bytes).hexdigest(), + mask_sha256=mask.mask_sha256, + discovery_sha256=hashlib.sha256(discovery_body).hexdigest(), + wire_sha256=prepared.wire_body_sha256, + wire_byte_count=prepared.wire_body_byte_count, + structural=structural_document, + locality=locality_document, + ), + ) + _scan_private_artifacts(target, token) + return "ok", result + journal.verify_integrity() + if len(success.occurrences) != 1 or not isinstance( + success.occurrences[0], OutputOccurrence + ): + return "terminal_occurrence_invalid", None + occurrence = success.occurrences[0] + if len(stored_response.output_bytes) != 1: + return "terminal_occurrence_invalid", None + output_bytes = stored_response.output_bytes[0] + structural = verify_output_structure( + source_raster, + provider_receipt=stored_response.receipt, + output_index=0, + output_bytes=output_bytes, + output_occurrence=occurrence, + ) + structural_document = judgment_to_json(structural.judgment) + structural_state = structural_document["result"]["state"] + structural_reason: str | None = None + if structural_state == "pass": + if structural.output_raster is None: + return "structural_verification_invalid", None + locality_judgment = verify_outside_mask_rgb_exact( + source_raster, + structural.output_raster, + mask, + output_occurrence=occurrence, + structural_pass=structural.judgment, + ) + else: + locality_judgment = build_locality_not_run(structural.judgment, mask) + reason = structural_document["result"].get("reason") + structural_reason = reason if isinstance(reason, str) else None + locality_document = judgment_to_json(locality_judgment) + locality_result = str(locality_document["result"]["state"]) + states = tuple(event.state for event in journal.read_events(attempt.attempt_id)) + result = OpenRouterRealE2EResult( + generation_run_id=run.generation_run_id, + attempt_id=attempt.attempt_id, + provider_receipt_id=stored_response.receipt.provider_receipt_id, + output_occurrence_id=occurrence.output_occurrence_id, + quoted_cost_usd=quote, + reported_cost_usd=reported_cost, + cost_telemetry_status=cost_telemetry_status, + states=states, + generation_post_count=post_count, + provider_media_admission_result="pass", + raw_structural_result=str(structural_state), + raw_structural_reason=structural_reason, + raw_locality_result=locality_result, + ) + output_mime = str(occurrence.original["mime"]) + output_suffix = ".png" if output_mime == "image/png" else ".jpg" + _write_private_bytes(target / f"provider-output-0{output_suffix}", output_bytes) + _write_private_json( + target / "result.json", + _result_document( + result, + source_sha256=hashlib.sha256(source_bytes).hexdigest(), + source_content_ref=blake3(source_bytes).hexdigest(), + mask_sha256=mask.mask_sha256, + discovery_sha256=hashlib.sha256(discovery_body).hexdigest(), + wire_sha256=prepared.wire_body_sha256, + wire_byte_count=prepared.wire_body_byte_count, + structural=structural_document, + locality=locality_document, + ), + ) + _scan_private_artifacts(target, token) + return "ok", result + except BaseException: + return "execution_failed", None + finally: + journal = None + token = "" + + +def execute_openrouter_real_e2e( + challenge_dir: Path, + confirmation_context_path: Path, + *, + _discovery_fetcher: Callable[[], bytes] = fetch_live_discovery, + _credential_loader: Callable[[str], str] = load_openrouter_keychain_token, + _transport: Callable[..., OpenRouterHttpResponse] = direct_openrouter_https_transport, + _confirmation_consumer: Callable[[Mapping[str, Any], Mapping[str, Any]], bool] | None = None, + _clock: Callable[[], str] = _canonical_timestamp, + _uuid4: Callable[[], str | uuid.UUID] = uuid.uuid4, +) -> OpenRouterRealE2EResult: + """Execute exactly one previously prepared and independently confirmed challenge.""" + + target = Path(challenge_dir) + context_path = Path(confirmation_context_path) + if not all( + callable(value) + for value in (_discovery_fetcher, _credential_loader, _transport, _clock, _uuid4) + ): + _fail("evaluation_callable_invalid") + if _transport is direct_openrouter_https_transport: + _preflight_direct_transport_environment() + challenge, payloads, _summary = _challenge_snapshot(target) + ok, now_value = _call_sanitized(_clock) + if not ok or not isinstance(now_value, str): + _fail("clock_invalid") + now = now_value + context, context_bytes = _confirmation_snapshot(context_path, challenge=challenge, now=now) + if _confirmation_consumer is None: + _fail("confirmation_authority_unavailable") + + ok, fresh_discovery = _call_sanitized(_discovery_fetcher) + if not ok or type(fresh_discovery) is not bytes: + _fail("discovery_unavailable") + if fresh_discovery != payloads["discovery"]: + _fail("challenge_discovery_drift") + quote = parse_openrouter_quote( + fresh_discovery, + input_count=1, + output_count=OUTPUT_COUNT, + resolution=RESOLUTION, + ) + if str(quote) != challenge.get("quoted_cost_usd"): + _fail("challenge_discovery_drift") + with localcontext(_QUOTE_CONTEXT): + if quote > QUOTE_ADMISSION_LIMIT_USD: + _fail("quote_exceeds_cap") + + prepared_at = challenge["prepared_at"] + assert isinstance(prepared_at, str) + capability = _build_capability(fresh_discovery, captured_at=prepared_at) + if capability.capability_snapshot_id != challenge.get("capability_snapshot_id"): + _fail("challenge_discovery_drift") + source_bytes = payloads["source"] + source_sha256 = hashlib.sha256(source_bytes).hexdigest() + try: + source_raster = compile_canonical_raster( + source_bytes, + source_content_sha256=source_sha256, + ) + bounds = _mask_bounds(source_raster) + mask = compile_rectangle_mask( + source_raster, + left=bounds[0], + top=bounds[1], + right=bounds[2], + bottom=bounds[3], + ) + except Exception: + _fail("challenge_artifact_drift") + if mask.mask_bytes != payloads["mask"]: + _fail("challenge_artifact_drift") + authority_document = _validate_authority_document( + _strict_json_object( + payloads["authority"], + limit=4 * 1024 * 1024, + code="challenge_artifact_drift", + ) + ) + confirmation_identity = { + "compact_summary_id": context["compact_summary_id"], + "confirmed_at": context["confirmed_at"], + "studio_session_id": context["studio_session_id"], + "principal_id": context["principal_id"], + } + packet = _build_packet( + source_bytes=source_bytes, + source_raster=source_raster, + mask=mask, + capability=capability, + authority=authority_document, + creative_session_id=str(context["creative_session_id"]), + confirmation_identity=confirmation_identity, + ) + if _packet_projection(packet) != challenge.get("packet_projection"): + _fail("challenge_artifact_drift") + prepared = _prepare_request(packet, capability, source_bytes) + if prepared.wire_body_sha256 != challenge.get( + "wire_body_sha256" + ) or prepared.wire_body_byte_count != challenge.get("wire_body_byte_count"): + _fail("challenge_artifact_drift") + run, attempt = _build_run_and_attempt( + packet=packet, + capability=capability, + prepared=prepared, + timestamp=prepared_at, + uuid4=_uuid4, + generation_run_id=str(challenge["generation_run_id"]), + attempt_id=str(challenge["attempt_id"]), + ) + plan = { + "schema_version": "moodboard.openrouter-real-e2e-plan.v2", + "challenge_id": challenge["challenge_id"], + "confirmation_context_id": context["confirmation_context_id"], + "quoted_cost_usd": str(quote), + "quote_admission_limit_usd": str(QUOTE_ADMISSION_LIMIT_USD), + "spend_limit_kind": "quote_only_not_provider_enforced", + "intent_packet": intent_to_json(packet), + "capability": provider_to_json(capability), + "normalized_request": provider_to_json(prepared.normalized_request), + "generation_run": provider_to_json(run), + "generation_attempt": provider_to_json(attempt), + } + ok, preclaim_now_value = _call_sanitized(_clock) + if not ok or not isinstance(preclaim_now_value, str): + _fail("clock_invalid") + preclaim_now = preclaim_now_value + if _timestamp_value(preclaim_now, code="clock_invalid") > _timestamp_value( + challenge["expires_at"], code="challenge_artifact_drift" + ): + _fail("challenge_expired") + authority_ok, consumed = _call_sanitized( + lambda: _confirmation_consumer(copy.deepcopy(context), copy.deepcopy(challenge)) + ) + if not authority_ok or consumed is not True: + _fail("confirmation_authority_invalid") + ok, post_authority_now_value = _call_sanitized(_clock) + if not ok or not isinstance(post_authority_now_value, str): + _fail("clock_invalid") + post_authority_now = post_authority_now_value + if _timestamp_value(post_authority_now, code="clock_invalid") > _timestamp_value( + challenge["expires_at"], code="challenge_artifact_drift" + ): + _fail("challenge_expired") + _claim_challenge_consumption( + target, + challenge=challenge, + context=context, + consumed_at=post_authority_now, + ) + _write_private_json(target / "plan.json", plan) + _write_private_bytes(target / "confirmation-context.snapshot.json", context_bytes) + + _enforce_no_core_dumps() + ok, credential_boundary_now_value = _call_sanitized(_clock) + if not ok or not isinstance(credential_boundary_now_value, str): + _fail("clock_invalid") + if _timestamp_value(credential_boundary_now_value, code="clock_invalid") > _timestamp_value( + challenge["expires_at"], code="challenge_artifact_drift" + ): + _fail("challenge_expired") + credential_ok, token_value = _call_sanitized(lambda: _credential_loader(CREDENTIAL_PROFILE_ID)) + if not credential_ok or not isinstance(token_value, str): + _fail("credential_unavailable") + token = token_value + status, result = _execute_with_token( + target=target, + token=token, + packet=packet, + capability=capability, + prepared=prepared, + run=run, + attempt=attempt, + source_bytes=source_bytes, + source_raster=source_raster, + mask=mask, + quote=quote, + discovery_body=fresh_discovery, + expires_at=str(challenge["expires_at"]), + directory_binding=challenge["directory_binding"], + transport=_transport, + clock=_clock, + uuid4_factory=_uuid4, + ) + token = "" + token_value = None + if status != "ok" or result is None: + _fail(status) + return result + + +def _result_document( + result: OpenRouterRealE2EResult, + *, + source_sha256: str, + source_content_ref: str, + mask_sha256: str, + discovery_sha256: str, + wire_sha256: str, + wire_byte_count: int, + structural: Mapping[str, Any] | None = None, + locality: Mapping[str, Any] | None = None, +) -> JsonObject: + document: JsonObject = { + "schema_version": _SUMMARY_VERSION, + "generation_run_id": result.generation_run_id, + "attempt_id": result.attempt_id, + "provider_receipt_id": result.provider_receipt_id, + "output_occurrence_id": result.output_occurrence_id, + "quoted_cost_usd": str(result.quoted_cost_usd), + "quote_admission_limit_usd": str(QUOTE_ADMISSION_LIMIT_USD), + "spend_limit_kind": "quote_only_not_provider_enforced", + "reported_cost_usd": ( + str(result.reported_cost_usd) if result.reported_cost_usd is not None else None + ), + "cost_telemetry_status": ( + ( + "reported_above_quote_admission_limit" + if result.reported_cost_usd > QUOTE_ADMISSION_LIMIT_USD + else "reported" + ) + if result.cost_telemetry_status == "reported" and result.reported_cost_usd is not None + else result.cost_telemetry_status + ), + "states": list(result.states), + "provider_lifecycle_state": result.states[-1] if result.states else "not_started", + "generation_post_count": result.generation_post_count, + "provider_media_admission_result": result.provider_media_admission_result, + "raw_structural_result": result.raw_structural_result, + "raw_structural_reason": result.raw_structural_reason, + "raw_locality_result": result.raw_locality_result, + "localized_edit_gate_status": ( + "eligible_exact_pass" + if result.raw_structural_result == "pass" and result.raw_locality_result == "pass" + else ( + "not_run" + if result.raw_structural_result == "not_run" + and result.raw_locality_result == "not_run" + else "not_eligible" + ) + ), + "workflow_acceptance": "not_recorded", + "semantic_aesthetic_result": "not_run", + "compositor_result": "not_run", + "source": { + "asset_id": _source_asset_id(source_sha256), + "content_sha256": source_sha256, + "content_ref": source_content_ref, + }, + "mask_sha256": mask_sha256, + "discovery_sha256": discovery_sha256, + "wire_sha256": wire_sha256, + "wire_byte_count": wire_byte_count, + "actual_model": "undisclosed" if result.provider_receipt_id is not None else "not_reported", + "upstream_route": "unknown" if result.provider_receipt_id is not None else "not_reported", + "private_payloads": { + "committed_to_repository": False, + "publication": "withheld_private_local_evidence", + "provider_response": ( + "retained_private_local_evidence" + if result.provider_receipt_id is not None + else "absent" + ), + "outputs": ( + "retained_private_local_evidence" + if result.provider_receipt_id is not None + else "absent" + ), + }, + } + if structural is not None: + document["raw_structural_judgment"] = copy.deepcopy(dict(structural)) + if locality is not None: + document["raw_locality_judgment"] = copy.deepcopy(dict(locality)) + return document + + +def _secret_variants(token: str) -> tuple[bytes, ...]: + raw = token.encode("ascii") + values = { + raw, + base64.b64encode(raw), + base64.b64encode(raw).rstrip(b"="), + base64.urlsafe_b64encode(raw), + base64.urlsafe_b64encode(raw).rstrip(b"="), + raw.hex().encode("ascii"), + raw.hex().upper().encode("ascii"), + json.dumps(token, ensure_ascii=True)[1:-1].encode("ascii"), + } + return tuple(sorted(values, key=lambda item: (len(item), item))) + + +def _scan_private_artifacts(output_dir: Path, token: str) -> None: + variants = _secret_variants(token) + try: + entries = sorted(output_dir.iterdir(), key=lambda path: path.name) + total = 0 + for path in entries: + metadata = path.lstat() + if not stat.S_ISREG(metadata.st_mode): + _fail("artifact_secret_scan_failed") + payload = _secure_read_private_file( + path, + limit=128 * 1024 * 1024, + code="artifact_secret_scan_failed", + ) + total += len(payload) + if total > 256 * 1024 * 1024: + _fail("artifact_secret_scan_failed") + if any(variant and variant in payload for variant in variants): + _fail("credential_material_persisted") + except OpenRouterRealE2EError: + raise + except BaseException: + _fail("artifact_secret_scan_failed") + + +def _assert_wire(prepared: OpenRouterPreparedRequest) -> JsonObject: + try: + wire = json.loads(prepared.wire_body, object_pairs_hook=_unique_object) + except Exception: + _fail("wire_contract_mismatch") + if not isinstance(wire, dict): + _fail("wire_contract_mismatch") + if ( + wire.get("model") != MODEL + or wire.get("n") != OUTPUT_COUNT + or wire.get("resolution") != RESOLUTION + or wire.get("aspect_ratio") != ASPECT_RATIO + or wire.get("provider") != {"only": [PROVIDER_TAG], "allow_fallbacks": False} + or not isinstance(wire.get("input_references"), list) + or len(wire["input_references"]) != 1 + or prepared.wire_body_byte_count != len(prepared.wire_body) + or hashlib.sha256(prepared.wire_body).hexdigest() != prepared.wire_body_sha256 + ): + _fail("wire_contract_mismatch") + return wire + + +def _partial_result( + *, + run: GenerationRun, + attempt: GenerationAttempt, + journal: AttemptJournal, + quote: Decimal, + post_count: int, + receipt_id: str | None = None, + reported_cost: Decimal | None = None, + cost_telemetry_status: str = "not_reported", +) -> OpenRouterRealE2EResult: + states = tuple(event.state for event in journal.read_events(attempt.attempt_id)) + return OpenRouterRealE2EResult( + generation_run_id=run.generation_run_id, + attempt_id=attempt.attempt_id, + provider_receipt_id=receipt_id, + output_occurrence_id=None, + quoted_cost_usd=quote, + reported_cost_usd=reported_cost, + cost_telemetry_status=cost_telemetry_status, + states=states, + generation_post_count=post_count, + provider_media_admission_result="not_run", + raw_structural_result="not_run", + raw_structural_reason=None, + raw_locality_result="not_run", + ) + + +def run_openrouter_real_e2e( + output_dir: Path, + *, + authorize_one_paid_call: bool, + _discovery_fetcher: Callable[[], bytes] = fetch_live_discovery, + _source_fetcher: Callable[[], bytes] = load_pinned_source, + _credential_loader: Callable[[str], str] = load_openrouter_keychain_token, + _transport: Callable[..., OpenRouterHttpResponse] = direct_openrouter_https_transport, + _clock: Callable[[], str] = _canonical_timestamp, + _uuid4: Callable[[], str | uuid.UUID] = uuid.uuid4, +) -> OpenRouterRealE2EResult: + """Refuse the retired Boolean authorization API. + + A truthy command-line flag cannot stand in for an exact Studio confirmation. Only + :func:`prepare_openrouter_real_e2e` followed by :func:`execute_openrouter_real_e2e` may + reach dispatch. + """ + + del ( + output_dir, + authorize_one_paid_call, + _discovery_fetcher, + _source_fetcher, + _credential_loader, + _transport, + _clock, + _uuid4, + ) + _fail("two_phase_confirmation_required") + + +def _parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + subcommands = parser.add_subparsers(dest="command", required=True) + prepare = subcommands.add_parser( + "prepare", + help="report the currently blocked production-preparation prerequisites", + ) + prepare.add_argument("--challenge-dir", type=Path, required=True) + return parser + + +def main(argv: Sequence[str] | None = None) -> int: + args = _parser().parse_args(argv) + os.umask(0o077) + try: + if args.command != "prepare": + _fail("command_unsupported") + _fail("trusted_authority_integration_required") + except OpenRouterRealE2EError as error: + print(json.dumps({"ok": False, "code": error.code}, sort_keys=True)) + return 2 + except Exception: + print(json.dumps({"ok": False, "code": "unexpected_failure"}, sort_keys=True)) + return 2 + return 2 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/eval/openrouter_real_e2e_authority.py b/eval/openrouter_real_e2e_authority.py new file mode 100644 index 0000000..d400d31 --- /dev/null +++ b/eval/openrouter_real_e2e_authority.py @@ -0,0 +1,456 @@ +"""Load the immutable board and retrieval authority for the real OpenRouter evaluation. + +This module is deliberately offline. It does not discover artifacts, fetch media, or repair a +stale contract. Callers must provide one ``brand.mb`` and one Pixel-RAG JSON artifact explicitly. +Their exact bounded bytes are snapshotted, passed through the public Moodboard readers, and +reduced to the closed identities needed by an intent packet. Repository-adjacent delivery paths +are intentionally not embedded in this public helper. + +The retrieval identities below are content-derived, not labels: + +* the eligible-corpus identity binds the source-manifest identity, the exact collection gate, + and the complete filtered corpus as an order-independent set of asset/ContentRef pairs; and +* the route-policy identity binds that corpus identity, namespace, gate, no-fallback policy, and + the artifact's registered structural-routing interpretation. + +Both projections use RFC 8785 through :mod:`moodboard.contracts` and distinct domain tags. The +ordered generation references remain the validated top-three ``ranked_evidence`` projection; +they are not confused with the complete eligible corpus. +""" + +from __future__ import annotations + +import hashlib +import os +import stat +import tempfile +from collections.abc import Mapping, Sequence +from contextlib import suppress +from dataclasses import dataclass +from dataclasses import field as dataclass_field +from pathlib import Path +from typing import Any, Final, NoReturn + +from moodboard.board import ( + board_fit_policy_id, + board_representation_id, + read_board, +) +from moodboard.contracts import compute_projection_identity +from moodboard.pixel_rag import read_pixel_rag_artifact, validate_pixel_rag_artifact + +ELIGIBLE_CORPUS_IDENTITY_VERSION: Final = "moodboard.openrouter-real-e2e.eligible-corpus.v1" +ROUTE_POLICY_VERSION: Final = "moodboard.intent-route.collection-gate.v1" +ROUTE_POLICY_IDENTITY_VERSION: Final = "moodboard.openrouter-real-e2e.route-policy.v1" +EMPTY_RESULT_POLICY: Final = "no_ungated_fallback" +LOCAL_REPLACE_INTENT: Final = "local_replace" +LOCAL_REPLACE_COLLECTION: Final = "fruit-lemon" +ROUTING_INTERPRETATION: Final = "structural_routing_control_not_learned_retrieval_quality" + +_MAX_BOARD_ARTIFACT_BYTES: Final = 64 * 1024 * 1024 +_MAX_PIXEL_RAG_ARTIFACT_BYTES: Final = 16 * 1024 * 1024 +_READ_CHUNK_BYTES: Final = 1024 * 1024 + +__all__ = [ + "ELIGIBLE_CORPUS_IDENTITY_VERSION", + "EMPTY_RESULT_POLICY", + "EligibleCorpusMember", + "LOCAL_REPLACE_COLLECTION", + "LOCAL_REPLACE_INTENT", + "LocalReplaceReference", + "OpenRouterRealE2EAuthority", + "OpenRouterRealE2EAuthorityError", + "ROUTE_POLICY_VERSION", + "ROUTE_POLICY_IDENTITY_VERSION", + "ROUTING_INTERPRETATION", + "load_openrouter_real_e2e_authority", +] + + +class OpenRouterRealE2EAuthorityError(RuntimeError): + """The offline authority load failed at one stable, path-free boundary.""" + + def __init__(self, code: str) -> None: + self.code = code + super().__init__(code) + + +@dataclass(frozen=True, slots=True) +class EligibleCorpusMember: + """One member of the collection-gated corpus, in canonical identity order.""" + + manifest_asset_id: str + content_ref: str + + +@dataclass(frozen=True, slots=True) +class LocalReplaceReference: + """One ordered, fully identified Pixel-RAG reference card.""" + + manifest_asset_id: str + khive_record_id: str + content_ref: str + content_sha256: str + collection: str + title: str + routed_rank: int + source_search_rank: int + source_similarity: float + + +@dataclass(frozen=True, slots=True) +class OpenRouterRealE2EAuthority: + """Frozen real-artifact authority suitable for a later intent-packet freeze. + + Artifact bytes are retained so the confirmation/dispatch layer can byte-compare its frozen + authorities. They are intentionally absent from ``repr`` and their public identities are + available separately, so diagnostics never render a large or private payload by accident. + """ + + board_id: str + representation_id: str + fit_policy_id: str + evidence_artifact_id: str + eligible_corpus_sha256: str + route_policy_id: str + eligible_corpus: tuple[EligibleCorpusMember, ...] + references: tuple[LocalReplaceReference, ...] + board_artifact_sha256: str + pixel_rag_artifact_sha256: str + board_artifact_bytes: bytes = dataclass_field(repr=False, compare=False) + pixel_rag_artifact_bytes: bytes = dataclass_field(repr=False, compare=False) + + +def _fail(code: str) -> NoReturn: + raise OpenRouterRealE2EAuthorityError(code) from None + + +def _read_bounded_regular_file(path: Path, *, limit: int, code: str) -> bytes: + """Read one exact regular file without following a final-component symlink.""" + + descriptor: int | None = None + try: + source = Path(path) + before = source.lstat() + if not stat.S_ISREG(before.st_mode) or before.st_size < 1 or before.st_size > limit: + _fail(code) + flags = os.O_RDONLY + if hasattr(os, "O_CLOEXEC"): + flags |= os.O_CLOEXEC + if hasattr(os, "O_NOFOLLOW"): + flags |= os.O_NOFOLLOW + if hasattr(os, "O_NONBLOCK"): + flags |= os.O_NONBLOCK + descriptor = os.open(source, flags) + metadata = os.fstat(descriptor) + if ( + not stat.S_ISREG(metadata.st_mode) + or metadata.st_dev != before.st_dev + or metadata.st_ino != before.st_ino + or metadata.st_size != before.st_size + or metadata.st_size < 1 + or metadata.st_size > limit + ): + _fail(code) + chunks: list[bytes] = [] + total = 0 + while True: + chunk = os.read(descriptor, min(_READ_CHUNK_BYTES, limit + 1 - total)) + if not chunk: + break + chunks.append(chunk) + total += len(chunk) + if total > limit: + _fail(code) + if total != metadata.st_size: + _fail(code) + return b"".join(chunks) + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail(code) + finally: + if descriptor is not None: + with suppress(OSError): + os.close(descriptor) + + +def _write_snapshot(directory: Path, name: str, payload: bytes) -> Path: + path = directory / name + descriptor: int | None = None + try: + descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) + view = memoryview(payload) + written = 0 + while written < len(view): + count = os.write(descriptor, view[written:]) + if count <= 0: + _fail("artifact_snapshot_failed") + written += count + os.fsync(descriptor) + os.close(descriptor) + descriptor = None + return path + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail("artifact_snapshot_failed") + finally: + if descriptor is not None: + with suppress(OSError): + os.close(descriptor) + + +def _load_board(snapshot: Path) -> tuple[str, str, str]: + try: + board = read_board(snapshot) + if board.integrity_verified is not True: + _fail("board_artifact_unverified") + return ( + board.board_id, + board_representation_id(board), + board_fit_policy_id(board), + ) + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail("board_artifact_invalid") + + +def _load_pixel_rag(snapshot: Path) -> dict[str, Any]: + try: + artifact = read_pixel_rag_artifact(snapshot) + # Keep this explicit even though the reader currently closes the artifact itself. The + # helper's contract is to use both public read and validate boundaries and remains sound + # if the reader implementation is ever separated from semantic validation. + validate_pixel_rag_artifact(artifact) + return artifact + except Exception: + _fail("pixel_rag_artifact_invalid") + + +def _require_mapping(value: object) -> Mapping[str, Any]: + if not isinstance(value, Mapping): + _fail("pixel_rag_projection_invalid") + return value + + +def _require_sequence(value: object) -> Sequence[Any]: + if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)): + _fail("pixel_rag_projection_invalid") + return value + + +def _eligible_corpus_projection( + artifact: Mapping[str, Any], local: Mapping[str, Any] +) -> tuple[dict[str, Any], tuple[EligibleCorpusMember, ...]]: + try: + route = _require_mapping(local["route"]) + hard_filter = _require_mapping(route["hard_filter"]) + retrieval = _require_mapping(local["retrieval"]) + exact_rows = _require_sequence(retrieval["exact_score_order"]) + source_manifest = _require_mapping(artifact["source_manifest"]) + members = tuple( + sorted( + ( + EligibleCorpusMember( + manifest_asset_id=str(_require_mapping(row)["asset_id"]), + content_ref=str(_require_mapping(row)["content_ref"]), + ) + for row in exact_rows + ), + key=lambda member: (member.manifest_asset_id, member.content_ref), + ) + ) + if not members or len({member.manifest_asset_id for member in members}) != len(members): + _fail("eligible_corpus_invalid") + if len({member.content_ref for member in members}) != len(members): + _fail("eligible_corpus_invalid") + projection = { + "schema_version": ELIGIBLE_CORPUS_IDENTITY_VERSION, + "source_manifest": { + "catalog_sha256": source_manifest["catalog_sha256"], + "dataset_id": source_manifest["dataset_id"], + "manifest_sha256": source_manifest["manifest_sha256"], + }, + "field": hard_filter["field"], + "operator": hard_filter["operator"], + "value": hard_filter["value"], + "assets": [ + { + "asset_id": member.manifest_asset_id, + "content_ref": member.content_ref, + } + for member in members + ], + } + return projection, members + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail("pixel_rag_projection_invalid") + + +def _ordered_references(local: Mapping[str, Any]) -> tuple[LocalReplaceReference, ...]: + try: + retrieval = _require_mapping(local["retrieval"]) + cards = _require_sequence(retrieval["ranked_evidence"]) + references = tuple( + LocalReplaceReference( + manifest_asset_id=str(card["asset_id"]), + khive_record_id=str(_require_mapping(card["khive"])["record_id"]), + content_ref=str(_require_mapping(card["khive"])["content_ref"]), + content_sha256=str(card["sha256"]), + collection=str(card["collection"]), + title=str(card["title"]), + routed_rank=int(card["rank"]), + source_search_rank=int(card["source_search_rank"]), + source_similarity=float(_require_mapping(card["score"])["value"]), + ) + for raw_card in cards + for card in (_require_mapping(raw_card),) + ) + if not references: + _fail("local_replace_references_invalid") + if [reference.routed_rank for reference in references] != list( + range(1, len(references) + 1) + ): + _fail("local_replace_references_invalid") + if any(reference.collection != LOCAL_REPLACE_COLLECTION for reference in references): + _fail("local_replace_references_invalid") + if len({reference.khive_record_id for reference in references}) != len(references): + _fail("local_replace_references_invalid") + if len({reference.content_ref for reference in references}) != len(references): + _fail("local_replace_references_invalid") + return references + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail("pixel_rag_projection_invalid") + + +def _project_pixel_rag( + artifact: Mapping[str, Any], +) -> tuple[ + str, + str, + str, + tuple[EligibleCorpusMember, ...], + tuple[LocalReplaceReference, ...], +]: + try: + if artifact["evidence_status"] != "measured_run": + _fail("pixel_rag_evidence_not_measured") + intents = _require_sequence(artifact["intents"]) + local_matches = [ + _require_mapping(intent) + for intent in intents + if _require_mapping(intent).get("id") == LOCAL_REPLACE_INTENT + ] + if len(local_matches) != 1: + _fail("local_replace_route_invalid") + local = local_matches[0] + route = _require_mapping(local["route"]) + hard_filter = _require_mapping(route["hard_filter"]) + retrieval = _require_mapping(local["retrieval"]) + if dict(hard_filter) != { + "field": "collection", + "operator": "equals", + "value": LOCAL_REPLACE_COLLECTION, + }: + _fail("local_replace_route_invalid") + if retrieval["hard_filter_applied_before_rank_projection"] is not True: + _fail("local_replace_route_invalid") + if retrieval["metrics_interpretation"] != ROUTING_INTERPRETATION: + _fail("local_replace_route_invalid") + + eligible_projection, eligible_corpus = _eligible_corpus_projection(artifact, local) + eligible_digest = compute_projection_identity( + eligible_projection, + domain_tag=ELIGIBLE_CORPUS_IDENTITY_VERSION, + ) + route_projection = { + "schema_version": ROUTE_POLICY_VERSION, + "eligible_corpus_sha256": eligible_digest, + "namespace": route["namespace"], + "field": hard_filter["field"], + "operator": hard_filter["operator"], + "value": hard_filter["value"], + "empty_result_policy": EMPTY_RESULT_POLICY, + "interpretation": retrieval["metrics_interpretation"], + } + route_policy_id = compute_projection_identity( + route_projection, + domain_tag=ROUTE_POLICY_IDENTITY_VERSION, + ) + references = _ordered_references(local) + evidence_artifact_id = str(artifact["artifact_id"]) + return ( + evidence_artifact_id, + eligible_digest, + route_policy_id, + eligible_corpus, + references, + ) + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail("pixel_rag_projection_invalid") + + +def load_openrouter_real_e2e_authority( + *, + board_path: Path, + pixel_rag_path: Path, +) -> OpenRouterRealE2EAuthority: + """Load one exact offline authority or fail with a stable, detail-free code. + + The source paths are read-only. Private owner-only temporary files ensure the public readers + validate the exact bytes returned in the result rather than a later revision of either path. + No network or credential boundary is reachable from this function. + """ + + board_bytes = _read_bounded_regular_file( + board_path, + limit=_MAX_BOARD_ARTIFACT_BYTES, + code="board_artifact_unavailable", + ) + pixel_bytes = _read_bounded_regular_file( + pixel_rag_path, + limit=_MAX_PIXEL_RAG_ARTIFACT_BYTES, + code="pixel_rag_artifact_unavailable", + ) + try: + with tempfile.TemporaryDirectory(prefix="moodboard-real-e2e-authority-") as name: + snapshot_root = Path(name) + os.chmod(snapshot_root, 0o700) + board_snapshot = _write_snapshot(snapshot_root, "authority.brand.mb", board_bytes) + pixel_snapshot = _write_snapshot(snapshot_root, "pixel-rag-artifact.json", pixel_bytes) + board_id, representation_id, fit_policy_id = _load_board(board_snapshot) + artifact = _load_pixel_rag(pixel_snapshot) + except OpenRouterRealE2EAuthorityError: + raise + except Exception: + _fail("artifact_snapshot_failed") + + ( + evidence_artifact_id, + eligible_corpus_sha256, + route_policy_id, + eligible_corpus, + references, + ) = _project_pixel_rag(artifact) + return OpenRouterRealE2EAuthority( + board_id=board_id, + representation_id=representation_id, + fit_policy_id=fit_policy_id, + evidence_artifact_id=evidence_artifact_id, + eligible_corpus_sha256=eligible_corpus_sha256, + route_policy_id=route_policy_id, + eligible_corpus=eligible_corpus, + references=references, + board_artifact_sha256=hashlib.sha256(board_bytes).hexdigest(), + pixel_rag_artifact_sha256=hashlib.sha256(pixel_bytes).hexdigest(), + board_artifact_bytes=board_bytes, + pixel_rag_artifact_bytes=pixel_bytes, + ) diff --git a/moodboard/openrouter.py b/moodboard/openrouter.py index 9bb7df1..1e2de50 100644 --- a/moodboard/openrouter.py +++ b/moodboard/openrouter.py @@ -1462,7 +1462,7 @@ def _canonical_attempt(value: GenerationAttempt | Mapping[str, Any]) -> Generati return artifact -def _decimal_cost(value: Any) -> dict[str, Any]: +def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: if value is None: return { "state": "unavailable", @@ -1470,6 +1470,12 @@ def _decimal_cost(value: Any) -> dict[str, Any]: "currency": None, "provenance": "not_reported", } + measured_currency = "USD" if currency is None else currency + if ( + not isinstance(measured_currency, str) + or re.fullmatch(r"[A-Z]{3}", measured_currency) is None + ): + raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") if isinstance(value, bool) or not isinstance(value, (int, Decimal)): raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") try: @@ -1512,7 +1518,7 @@ def _decimal_cost(value: Any) -> dict[str, Any]: return { "state": "reported", "amount": amount, - "currency": "USD", + "currency": measured_currency, "provenance": "provider_receipt", } @@ -1637,7 +1643,10 @@ def decode_openrouter_response( usage = document.get("usage") if usage is not None and not isinstance(usage, dict): raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") - cost = _decimal_cost(None if usage is None else usage.get("cost")) + cost = _decimal_cost( + None if usage is None else usage.get("cost"), + None if usage is None else usage.get("currency"), + ) draft = { "schema_version": RECEIPT_VERSION, "attempt_id": descriptor.attempt_id, diff --git a/tests/test_openrouter_adapter.py b/tests/test_openrouter_adapter.py index ef5316b..015830e 100644 --- a/tests/test_openrouter_adapter.py +++ b/tests/test_openrouter_adapter.py @@ -386,6 +386,37 @@ def recorded_at() -> str: assert "b64_json" not in decoded_repr +def test_reported_cost_preserves_an_explicit_provider_currency(tmp_path: Path) -> None: + _journal, attempt, _capability, prepared = _seed_dispatch(tmp_path) + body = json.dumps( + { + "created": 1_786_930_000, + "data": [{"b64_json": base64.b64encode(_OUTPUT_BYTES).decode("ascii")}], + "usage": {"cost": 0.033, "currency": "EUR"}, + }, + separators=(",", ":"), + ).encode("utf-8") + + decoded = decode_openrouter_response( + attempt, + prepared, + OpenRouterHttpResponse( + status=200, + headers={"content-type": "application/json"}, + body=body, + elapsed_milliseconds=2450, + ), + received_at=_RECORDED_AT, + ) + + assert provider_to_json(decoded.receipt)["cost"] == { + "state": "reported", + "amount": "0.033", + "currency": "EUR", + "provenance": "provider_receipt", + } + + def test_concurrent_and_exact_dispatch_replay_send_the_attempt_at_most_once( tmp_path: Path, ) -> None: diff --git a/tests/test_openrouter_real_e2e.py b/tests/test_openrouter_real_e2e.py new file mode 100644 index 0000000..4d54ded --- /dev/null +++ b/tests/test_openrouter_real_e2e.py @@ -0,0 +1,237 @@ +"""Core offline contracts for the opt-in OpenRouter real-provider evaluation. + +The full lifecycle is exercised by ``test_openrouter_real_e2e_confirmation``. This module owns +shared deterministic media/response fixtures plus the quote, Keychain, and retired one-phase API +boundaries. No test accesses the network or macOS Keychain. +""" + +from __future__ import annotations + +import base64 +import json +import subprocess +from collections.abc import Callable +from decimal import Decimal +from io import BytesIO +from pathlib import Path +from typing import Any + +import pytest +from PIL import Image + +import eval.openrouter_real_e2e as real_e2e +from eval.openrouter_real_e2e import ( + MAX_COST_USD, + OpenRouterRealE2EError, + load_openrouter_keychain_token, + parse_openrouter_quote, + run_openrouter_real_e2e, +) +from moodboard.openrouter import OpenRouterHttpResponse +from tests.test_openrouter_discovery import _DISCOVERY_BODY + +_CREDENTIAL_PROFILE_ID = "00000000-0000-4000-8000-000000000005" +_TOKEN = "sk-or-v1-REAL-E2E-SECRET-SENTINEL-0123456789" + + +def _source_png() -> bytes: + """One small deterministic 4:3 source with nontrivial protected pixels.""" + + image = Image.new("RGB", (64, 48), (120, 185, 225)) + pixels = image.load() + assert pixels is not None + for y in range(24, 48): + for x in range(64): + pixels[x, y] = (74, 132, 70) + for y in range(12, 38): + for x in range(28, 36): + pixels[x, y] = (91, 62, 35) + encoded = BytesIO() + image.save(encoded, format="PNG", optimize=False) + return encoded.getvalue() + + +_SOURCE_BYTES = _source_png() +_OUTPUT_BYTES = _SOURCE_BYTES + + +def _response_body( + *, + cost: Decimal | None = Decimal("0.033"), + currency: str | None = None, +) -> bytes: + usage: dict[str, Any] = {} + if cost is not None: + usage["cost"] = int(cost) if cost == cost.to_integral() else float(str(cost)) + if currency is not None: + usage["currency"] = currency + document: dict[str, Any] = { + "created": 1_786_930_000, + "data": [ + { + "b64_json": base64.b64encode(_OUTPUT_BYTES).decode("ascii"), + "media_type": "image/png", + } + ], + } + if usage: + document["usage"] = usage + return json.dumps(document, separators=(",", ":")).encode("utf-8") + + +def _http_response( + *, + cost: Decimal | None = Decimal("0.033"), + currency: str | None = None, +) -> OpenRouterHttpResponse: + return OpenRouterHttpResponse( + status=200, + headers={"content-type": "application/json"}, + body=_response_body(cost=cost, currency=currency), + elapsed_milliseconds=3210, + ) + + +def _uuid_supplier() -> Callable[[], str]: + values = (f"70000000-0000-4000-8000-{index:012d}" for index in range(1, 100)) + return lambda: next(values) + + +def _assert_error_code(error: pytest.ExceptionInfo[OpenRouterRealE2EError], code: str) -> None: + assert error.value.code == code + assert _TOKEN not in str(error.value) + assert _TOKEN not in repr(error.value) + + +def test_live_discovery_quote_is_exact_decimal_and_has_a_frozen_admission_limit() -> None: + quote = parse_openrouter_quote( + _DISCOVERY_BODY, + input_count=1, + output_count=1, + resolution="1K", + ) + + assert Decimal("0.05") == MAX_COST_USD + assert type(MAX_COST_USD) is Decimal + assert quote == Decimal("0.033") + assert type(quote) is Decimal + assert quote.as_tuple() == Decimal("0.033").as_tuple() + + +def test_quote_requires_one_unambiguous_input_and_resolution_price() -> None: + document = json.loads(_DISCOVERY_BODY) + document["endpoints"][0]["pricing"].append( + {"billable": "output_image", "unit": "image", "cost_usd": 0.03, "variant": "1k"} + ) + + with pytest.raises(OpenRouterRealE2EError) as raised: + parse_openrouter_quote( + json.dumps(document, separators=(",", ":")).encode("utf-8"), + input_count=1, + output_count=1, + resolution="1K", + ) + + _assert_error_code(raised, "quote_ambiguous") + + +def test_keychain_lookup_uses_one_fixed_argv_without_shell_or_environment( + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[tuple[tuple[str, ...], dict[str, Any]]] = [] + + def fake_run(argv: list[str], **kwargs: Any) -> subprocess.CompletedProcess[str]: + calls.append((tuple(argv), kwargs)) + return subprocess.CompletedProcess(argv, 0, stdout=f"{_TOKEN}\n", stderr="") + + monkeypatch.setattr(real_e2e.subprocess, "run", fake_run) + + token = load_openrouter_keychain_token(_CREDENTIAL_PROFILE_ID) + + assert token == _TOKEN + assert len(calls) == 1 + argv, kwargs = calls[0] + assert argv == ( + "/usr/bin/security", + "find-generic-password", + "-s", + "OPENROUTER_API_KEY", + "-a", + "khive", + "-w", + ) + assert kwargs == { + "capture_output": True, + "check": False, + "text": True, + "timeout": 15, + } + + +def test_keychain_failures_and_diagnostics_are_sanitized( + monkeypatch: pytest.MonkeyPatch, +) -> None: + def failed(argv: list[str], **kwargs: Any) -> subprocess.CompletedProcess[str]: + del kwargs + return subprocess.CompletedProcess( + argv, + 44, + stdout=f"unusable {_TOKEN}", + stderr=f"security diagnostic carrying {_TOKEN}", + ) + + monkeypatch.setattr(real_e2e.subprocess, "run", failed) + + with pytest.raises(OpenRouterRealE2EError) as raised: + load_openrouter_keychain_token(_CREDENTIAL_PROFILE_ID) + + _assert_error_code(raised, "credential_unavailable") + assert raised.value.__cause__ is None + assert raised.value.__context__ is None + + +def test_wrong_credential_profile_never_invokes_keychain(monkeypatch: pytest.MonkeyPatch) -> None: + calls = 0 + + def unexpected(*args: Any, **kwargs: Any) -> subprocess.CompletedProcess[str]: + del args, kwargs + nonlocal calls + calls += 1 + raise AssertionError("unsupported profile reached Keychain") + + monkeypatch.setattr(real_e2e.subprocess, "run", unexpected) + + with pytest.raises(OpenRouterRealE2EError) as raised: + load_openrouter_keychain_token("00000000-0000-4000-8000-000000000099") + + _assert_error_code(raised, "credential_profile_unsupported") + assert calls == 0 + + +def test_retired_boolean_authorization_api_cannot_reach_any_external_boundary( + tmp_path: Path, +) -> None: + calls: list[str] = [] + + def unexpected(name: str) -> Callable[..., Any]: + def called(*args: Any, **kwargs: Any) -> Any: + del args, kwargs + calls.append(name) + raise AssertionError(f"retired API reached {name}") + + return called + + with pytest.raises(OpenRouterRealE2EError) as raised: + run_openrouter_real_e2e( + tmp_path / "retired", + authorize_one_paid_call=True, + _discovery_fetcher=unexpected("discovery"), + _source_fetcher=unexpected("source"), + _credential_loader=unexpected("credential"), + _transport=unexpected("transport"), + _clock=unexpected("clock"), + _uuid4=unexpected("uuid"), + ) + + _assert_error_code(raised, "two_phase_confirmation_required") + assert calls == [] diff --git a/tests/test_openrouter_real_e2e_authority.py b/tests/test_openrouter_real_e2e_authority.py new file mode 100644 index 0000000..2050a29 --- /dev/null +++ b/tests/test_openrouter_real_e2e_authority.py @@ -0,0 +1,291 @@ +"""Contracts for the offline real-artifact authority used by the OpenRouter E2E. + +The one-shot evaluation must not invent board or retrieval identities. These tests build closed +artifacts with the production writers, load them through the public readers, and independently +pin the two retrieval digests so the implementation cannot make a label look authoritative. +""" + +from __future__ import annotations + +import hashlib +import json +import os +from dataclasses import FrozenInstanceError +from pathlib import Path +from typing import Any + +import numpy as np +import pytest +import rfc8785 + +import eval.openrouter_real_e2e_authority as authority_module +from eval.openrouter_real_e2e_authority import ( + ELIGIBLE_CORPUS_IDENTITY_VERSION, + ROUTE_POLICY_IDENTITY_VERSION, + ROUTE_POLICY_VERSION, + OpenRouterRealE2EAuthorityError, + load_openrouter_real_e2e_authority, +) +from moodboard.board import ( + board_fit_policy_id, + board_representation_id, + build_board, + read_board, + write_board, +) +from moodboard.pixel_rag import ( + compile_pixel_rag_artifact, + write_pixel_rag_artifact, +) +from tests.test_pixel_rag import _add_evidence_bindings, _manifest, _measurements + + +def _identity(domain: str, projection: dict[str, Any]) -> str: + return hashlib.sha256(domain.encode("utf-8") + b"\0" + rfc8785.dumps(projection)).hexdigest() + + +def _artifacts(tmp_path: Path, *, measured: bool = True) -> tuple[Path, Path, dict[str, Any]]: + board_path = tmp_path / "authority.brand.mb" + board = build_board( + name="OpenRouter real E2E authority fixture", + reference_ids=("reference-a", "reference-b", "reference-c"), + reference_content_hashes=("a" * 64, "b" * 64, "c" * 64), + reference_embeddings=np.eye(3, dtype=np.float32), + model_repo="khive:qwen3.5-vlm-pooled-visual", + model_revision="0123456789abcdef" * 4, + metric="cosine", + k=2, + cluster_cut=0.35, + dup_cut=0.05, + n_eff=3.0, + built_at="2026-08-17T03:15:00Z", + ) + write_board(board, board_path) + + pixel_root = tmp_path / "pixel" + manifest_path, by_id = _manifest(pixel_root) + measurements_path = _measurements( + pixel_root / "measurements.json", + by_id, + status="measured_run" if measured else "contract_fixture", + ) + if measured: + measurements = json.loads(measurements_path.read_text(encoding="utf-8")) + for intent in measurements["intents"]: + intent["relevance_judgments"] = None + measurements_path.write_text( + json.dumps(measurements, sort_keys=True, separators=(",", ":")) + "\n", + encoding="utf-8", + ) + _add_evidence_bindings(measurements_path, pixel_root) + pixel = compile_pixel_rag_artifact( + manifest_path=manifest_path, + measurements_path=measurements_path, + ) + pixel_path = pixel_root / "pixel-rag-artifact.json" + write_pixel_rag_artifact(pixel, pixel_path) + return board_path, pixel_path, pixel + + +def _eligible_projection(pixel: dict[str, Any]) -> dict[str, Any]: + local = next(intent for intent in pixel["intents"] if intent["id"] == "local_replace") + hard_filter = local["route"]["hard_filter"] + return { + "schema_version": ELIGIBLE_CORPUS_IDENTITY_VERSION, + "source_manifest": { + "catalog_sha256": pixel["source_manifest"]["catalog_sha256"], + "dataset_id": pixel["source_manifest"]["dataset_id"], + "manifest_sha256": pixel["source_manifest"]["manifest_sha256"], + }, + "field": hard_filter["field"], + "operator": hard_filter["operator"], + "value": hard_filter["value"], + "assets": sorted( + ( + {"asset_id": row["asset_id"], "content_ref": row["content_ref"]} + for row in local["retrieval"]["exact_score_order"] + ), + key=lambda row: (row["asset_id"], row["content_ref"]), + ), + } + + +def test_loads_closed_artifacts_and_derives_exact_authority(tmp_path: Path) -> None: + board_path, pixel_path, pixel = _artifacts(tmp_path) + + authority = load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + board = read_board(board_path) + local = next(intent for intent in pixel["intents"] if intent["id"] == "local_replace") + assert authority.board_id == board.board_id + assert authority.representation_id == board_representation_id(board) + assert authority.fit_policy_id == board_fit_policy_id(board) + assert authority.evidence_artifact_id == pixel["artifact_id"] + assert authority.board_artifact_sha256 == hashlib.sha256(board_path.read_bytes()).hexdigest() + assert ( + authority.pixel_rag_artifact_sha256 == hashlib.sha256(pixel_path.read_bytes()).hexdigest() + ) + assert authority.board_artifact_bytes == board_path.read_bytes() + assert authority.pixel_rag_artifact_bytes == pixel_path.read_bytes() + + expected_cards = local["retrieval"]["ranked_evidence"] + assert [reference.manifest_asset_id for reference in authority.references] == [ + card["asset_id"] for card in expected_cards + ] + assert [reference.khive_record_id for reference in authority.references] == [ + card["khive"]["record_id"] for card in expected_cards + ] + assert [reference.content_ref for reference in authority.references] == [ + card["khive"]["content_ref"] for card in expected_cards + ] + assert [reference.content_sha256 for reference in authority.references] == [ + card["sha256"] for card in expected_cards + ] + assert [reference.routed_rank for reference in authority.references] == [1, 2, 3] + assert [reference.source_search_rank for reference in authority.references] == [ + card["source_search_rank"] for card in expected_cards + ] + assert [reference.source_similarity for reference in authority.references] == [ + card["score"]["value"] for card in expected_cards + ] + assert {reference.collection for reference in authority.references} == {"fruit-lemon"} + + eligible_projection = _eligible_projection(pixel) + eligible_digest = _identity(ELIGIBLE_CORPUS_IDENTITY_VERSION, eligible_projection) + assert authority.eligible_corpus_sha256 == eligible_digest + assert [member.manifest_asset_id for member in authority.eligible_corpus] == [ + row["asset_id"] for row in eligible_projection["assets"] + ] + route_projection = { + "schema_version": ROUTE_POLICY_VERSION, + "eligible_corpus_sha256": eligible_digest, + "namespace": local["route"]["namespace"], + "field": "collection", + "operator": "equals", + "value": "fruit-lemon", + "empty_result_policy": "no_ungated_fallback", + "interpretation": "structural_routing_control_not_learned_retrieval_quality", + } + assert authority.route_policy_id == _identity(ROUTE_POLICY_IDENTITY_VERSION, route_projection) + + +def test_result_and_nested_rows_are_frozen_and_raw_bytes_are_repr_safe(tmp_path: Path) -> None: + board_path, pixel_path, _pixel = _artifacts(tmp_path) + authority = load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + with pytest.raises(FrozenInstanceError): + authority.board_id = "f" * 64 # type: ignore[misc] + with pytest.raises(FrozenInstanceError): + authority.references[0].content_ref = "f" * 64 # type: ignore[misc] + rendered = repr(authority) + assert authority.board_artifact_bytes.hex() not in rendered + assert authority.pixel_rag_artifact_bytes.hex() not in rendered + assert "board_artifact_bytes=" not in rendered + assert "pixel_rag_artifact_bytes=" not in rendered + + +@pytest.mark.parametrize( + ("target", "payload", "code"), + [ + ("board", b"not a board", "board_artifact_invalid"), + ("pixel", b'{"not":"a pixel artifact"}\n', "pixel_rag_artifact_invalid"), + ], +) +def test_invalid_artifacts_fail_with_stable_secret_free_codes( + tmp_path: Path, + target: str, + payload: bytes, + code: str, +) -> None: + board_path, pixel_path, _pixel = _artifacts(tmp_path) + selected = board_path if target == "board" else pixel_path + selected.write_bytes(payload) + + with pytest.raises(OpenRouterRealE2EAuthorityError) as captured: + load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + assert captured.value.code == code + assert str(captured.value) == code + assert str(selected) not in str(captured.value) + assert "not a board" not in str(captured.value) + assert captured.value.__cause__ is None + assert captured.value.__suppress_context__ is True + + +def test_fifo_authority_path_is_rejected_without_blocking(tmp_path: Path) -> None: + board_path, pixel_path, _pixel = _artifacts(tmp_path) + board_path.unlink() + os.mkfifo(board_path, 0o600) + + with pytest.raises(OpenRouterRealE2EAuthorityError) as captured: + load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + assert captured.value.code == "board_artifact_unavailable" + + +def test_reader_exception_details_never_escape_the_public_error( + monkeypatch, tmp_path: Path +) -> None: + board_path, pixel_path, _pixel = _artifacts(tmp_path) + + def explode(_path: Path): + raise RuntimeError("credential-looking-private-sentinel") + + monkeypatch.setattr(authority_module, "read_board", explode) + with pytest.raises(OpenRouterRealE2EAuthorityError) as captured: + load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + assert captured.value.code == "board_artifact_invalid" + assert "sentinel" not in str(captured.value) + + +def test_contract_fixture_cannot_be_promoted_to_real_evidence(tmp_path: Path) -> None: + board_path, pixel_path, _pixel = _artifacts(tmp_path, measured=False) + + with pytest.raises(OpenRouterRealE2EAuthorityError) as captured: + load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + assert captured.value.code == "pixel_rag_evidence_not_measured" + + +def test_public_pixel_read_and_validation_are_both_used(monkeypatch, tmp_path: Path) -> None: + board_path, pixel_path, _pixel = _artifacts(tmp_path) + calls: list[str] = [] + original_read = authority_module.read_pixel_rag_artifact + original_validate = authority_module.validate_pixel_rag_artifact + + def observed_read(path: Path): + calls.append("read") + return original_read(path) + + def observed_validate(value): + calls.append("validate") + return original_validate(value) + + monkeypatch.setattr(authority_module, "read_pixel_rag_artifact", observed_read) + monkeypatch.setattr(authority_module, "validate_pixel_rag_artifact", observed_validate) + + load_openrouter_real_e2e_authority( + board_path=board_path, + pixel_rag_path=pixel_path, + ) + + assert calls == ["read", "validate"] diff --git a/tests/test_openrouter_real_e2e_confirmation.py b/tests/test_openrouter_real_e2e_confirmation.py new file mode 100644 index 0000000..46d4282 --- /dev/null +++ b/tests/test_openrouter_real_e2e_confirmation.py @@ -0,0 +1,1223 @@ +"""RED contracts for the two-phase OpenRouter real-provider confirmation boundary. + +Preparation is deliberately non-authorizing: it snapshots exact discovery, source, mask, Studio +authority, compact-summary, and overlay bytes into a private challenge directory. A separate, +trusted Studio boundary writes the closed confirmation context. Execution may refresh discovery +and resolve a credential only after it has proved that the challenge, context, path/inode binding, +and expiry still match. These tests inject every external byte and never access Keychain or the +network. + +The challenge and compact-summary records are their first artifact versions even though they form +the v2 evaluation API. Their selected wire versions are therefore ``*.v1``. +""" + +from __future__ import annotations + +import base64 +import dataclasses +import hashlib +import inspect +import json +import os +import shutil +import signal +import stat +import threading +from collections.abc import Callable +from concurrent.futures import ThreadPoolExecutor +from dataclasses import FrozenInstanceError +from decimal import ROUND_DOWN, Decimal, getcontext, localcontext +from io import BytesIO +from pathlib import Path +from typing import Any + +import pytest +from PIL import Image + +import eval.openrouter_real_e2e as real_e2e +from moodboard.attempt_journal import AttemptJournal +from moodboard.contracts import compute_document_identity, verify_document_identity +from moodboard.locality import compile_canonical_raster, compile_rectangle_mask +from moodboard.openrouter import OpenRouterHttpResponse +from tests.test_openrouter_discovery import _DISCOVERY_BODY +from tests.test_openrouter_real_e2e import ( + _SOURCE_BYTES, + _TOKEN, + _http_response, + _uuid_supplier, +) + +JsonObject = dict[str, Any] +_REAL_E2E: Any = real_e2e + +_CHALLENGE_VERSION = "moodboard.openrouter-real-e2e-confirmation-challenge.v1" +_SUMMARY_VERSION = "moodboard.openrouter-real-e2e-compact-summary.v1" +_CONTEXT_VERSION = "moodboard.openrouter-real-e2e-confirmation-context.v1" +_PREPARED_AT = "2026-08-17T03:15:00Z" +_CONFIRMED_AT = "2026-08-17T03:16:00Z" +_EXECUTED_AT = "2026-08-17T03:17:00Z" +_CREATIVE_SESSION_ID = "10000000-0000-4000-8000-000000000001" +_PRINCIPAL_ID = "20000000-0000-4000-8000-000000000002" +_STUDIO_SESSION_ID = "30000000-0000-4000-8000-000000000003" +_CONFIRMATION_LEDGER_LOCK = threading.Lock() +_CONSUMED_CONFIRMATIONS: set[tuple[str, str]] = set() + + +def _digest(character: str) -> str: + assert len(character) == 1 and character in "0123456789abcdef" + return character * 64 + + +def _authority_bytes() -> bytes: + """One already-authorized Studio projection; the harness may store but never mint it.""" + + document: JsonObject = { + "schema_version": "moodboard.openrouter-real-e2e-authority.v1", + "authority_id": "0" * 64, + "creative_session_id": _CREATIVE_SESSION_ID, + "board": { + "board_id": _digest("1"), + "representation_id": _digest("2"), + "fit_policy_id": _digest("3"), + }, + "retrieval_route": { + "schema_version": "moodboard.intent-route.collection-gate.v1", + "route_policy_id": _digest("4"), + "eligible_corpus_sha256": _digest("5"), + "empty_result_policy": "no_ungated_fallback", + "evidence_artifact_id": _digest("6"), + }, + "references": [ + { + "reference_occurrence_id": "40000000-0000-4000-8000-000000000004", + "role": "visual_context", + "asset_id": "50000000-0000-4000-8000-000000000005", + "content_ref": _digest("7"), + "source_search_rank": 1, + "routed_rank": 1, + "source_similarity": 0.843299582601, + "route_reason": "declared_collection_match", + "provider_use": "prompt_context_only", + "prompt_context": { + "compiler_revision": "moodboard.reference-prompt.v1", + "text_items": ["Mature lemon canopy", "Natural branching structure"], + }, + } + ], + } + document["authority_id"] = compute_document_identity( + document, + schema_version="moodboard.openrouter-real-e2e-authority.v1", + identity_field="authority_id", + ) + return _json_bytes(document) + + +def _json_bytes(document: JsonObject) -> bytes: + return ( + json.dumps(document, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n" + ).encode("utf-8") + + +_AUTHORITY_BYTES = _authority_bytes() + + +def _read_json(path: Path) -> JsonObject: + value = json.loads(path.read_bytes()) + assert isinstance(value, dict) + return value + + +def _prepare( + challenge_dir: Path, + *, + discovery_body: bytes = _DISCOVERY_BODY, + source_bytes: bytes = _SOURCE_BYTES, +) -> Any: + prepare = _REAL_E2E.prepare_openrouter_real_e2e + return prepare( + challenge_dir, + _discovery_fetcher=lambda: discovery_body, + _source_fetcher=lambda: source_bytes, + _authority_bundle=_AUTHORITY_BYTES, + _clock=lambda: _PREPARED_AT, + ) + + +def _artifact_path(challenge_dir: Path, name: str) -> Path: + challenge = _read_json(challenge_dir / "challenge.json") + descriptor = challenge["artifacts"][name] + assert isinstance(descriptor, dict) + relative = Path(descriptor["relative_path"]) + assert not relative.is_absolute() + assert ".." not in relative.parts + return challenge_dir / relative + + +def _context_document(challenge_dir: Path, **overrides: Any) -> JsonObject: + challenge = _read_json(challenge_dir / "challenge.json") + document: JsonObject = { + "schema_version": _CONTEXT_VERSION, + "confirmation_context_id": "0" * 64, + "challenge_id": challenge["challenge_id"], + "compact_summary_id": challenge["compact_summary_id"], + "decision": "approve_one_paid_call", + "authorized_generation_post_count": 1, + "principal_id": _PRINCIPAL_ID, + "studio_session_id": _STUDIO_SESSION_ID, + "creative_session_id": _CREATIVE_SESSION_ID, + "confirmed_at": _CONFIRMED_AT, + } + document.update(overrides) + document["confirmation_context_id"] = compute_document_identity( + document, + schema_version=_CONTEXT_VERSION, + identity_field="confirmation_context_id", + ) + return document + + +def _write_context( + challenge_dir: Path, + *, + name: str = "confirmation-context.json", + **overrides: Any, +) -> Path: + path = challenge_dir / name + flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL + if hasattr(os, "O_NOFOLLOW"): + flags |= os.O_NOFOLLOW + descriptor = os.open(path, flags, 0o600) + try: + os.write(descriptor, _json_bytes(_context_document(challenge_dir, **overrides))) + os.fsync(descriptor) + finally: + os.close(descriptor) + assert stat.S_IMODE(path.stat().st_mode) == 0o600 + return path + + +def _rewrite_context(path: Path, mutate: Callable[[JsonObject], None]) -> None: + document = _read_json(path) + mutate(document) + document["confirmation_context_id"] = compute_document_identity( + document, + schema_version=_CONTEXT_VERSION, + identity_field="confirmation_context_id", + ) + path.write_bytes(_json_bytes(document)) + path.chmod(0o600) + + +def _execute( + challenge_dir: Path, + context_path: Path, + *, + discovery_fetcher: Callable[[], bytes] | None = None, + credential_loader: Callable[[str], str] | None = None, + transport: Callable[..., OpenRouterHttpResponse] | None = None, + confirmation_consumer: Callable[[JsonObject, JsonObject], bool] | None = None, + clock: Callable[[], str] | None = None, +) -> Any: + def consume_once(context: JsonObject, challenge: JsonObject) -> bool: + key = (str(context["confirmation_context_id"]), str(challenge["challenge_id"])) + with _CONFIRMATION_LEDGER_LOCK: + if key in _CONSUMED_CONFIRMATIONS: + return False + _CONSUMED_CONFIRMATIONS.add(key) + return True + + execute = _REAL_E2E.execute_openrouter_real_e2e + return execute( + challenge_dir, + context_path, + _discovery_fetcher=discovery_fetcher or (lambda: _DISCOVERY_BODY), + _credential_loader=credential_loader or (lambda _: _TOKEN), + _transport=transport or (lambda **_: _http_response()), + _confirmation_consumer=confirmation_consumer or consume_once, + _clock=clock or (lambda: _EXECUTED_AT), + _uuid4=_uuid_supplier(), + ) + + +def _assert_error_code(error: pytest.ExceptionInfo[BaseException], code: str) -> None: + assert isinstance(error.value, real_e2e.OpenRouterRealE2EError) + assert error.value.code == code + assert _TOKEN not in str(error.value) + assert _TOKEN not in repr(error.value) + + +def _unexpected_calls() -> tuple[list[str], Callable[[str], Callable[..., Any]]]: + calls: list[str] = [] + + def unexpected(name: str) -> Callable[..., Any]: + def called(*args: Any, **kwargs: Any) -> Any: + del args, kwargs + calls.append(name) + raise AssertionError(f"{name} crossed a pre-dispatch rejection boundary") + + return called + + return calls, unexpected + + +def _descriptor(payload: bytes, relative_path: str) -> JsonObject: + return { + "relative_path": relative_path, + "sha256": hashlib.sha256(payload).hexdigest(), + "byte_count": len(payload), + } + + +def test_prepare_api_has_no_credential_or_transport_and_returns_frozen_challenge( + tmp_path: Path, +) -> None: + prepare = _REAL_E2E.prepare_openrouter_real_e2e + parameters = inspect.signature(prepare).parameters + assert "_credential_loader" not in parameters + assert "_transport" not in parameters + assert "authorize_one_paid_call" not in parameters + + challenge = _prepare(tmp_path / "challenge") + + assert dataclasses.is_dataclass(challenge) + frozen_challenge: Any = challenge + stored = _read_json(tmp_path / "challenge/challenge.json") + assert frozen_challenge.challenge_id == stored["challenge_id"] + assert frozen_challenge.compact_summary_id == stored["compact_summary_id"] + with pytest.raises(FrozenInstanceError): + frozen_challenge.challenge_id = _digest("f") + + +def test_prepare_requires_exactly_one_authority_source_before_external_io(tmp_path: Path) -> None: + calls, unexpected = _unexpected_calls() + prepare = _REAL_E2E.prepare_openrouter_real_e2e + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as missing: + prepare( + tmp_path / "missing-authority", + _discovery_fetcher=unexpected("discovery"), + _source_fetcher=unexpected("source"), + ) + _assert_error_code(missing, "authority_unavailable") + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as ambiguous: + prepare( + tmp_path / "ambiguous-authority", + _discovery_fetcher=unexpected("discovery"), + _source_fetcher=unexpected("source"), + _authority_bundle=_AUTHORITY_BYTES, + _authority_loader=unexpected("authority"), + ) + _assert_error_code(ambiguous, "authority_ambiguous") + assert calls == [] + + +def test_default_direct_transport_preflight_fails_before_authorization_or_key( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "unsafe-direct-transport-environment" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + calls, unexpected = _unexpected_calls() + monkeypatch.setenv("SSLKEYLOGFILE", "/tmp/credential-bearing-tls-log") + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + real_e2e.execute_openrouter_real_e2e( + challenge_dir, + context_path, + _discovery_fetcher=unexpected("discovery"), + _credential_loader=unexpected("credential"), + _transport=real_e2e.direct_openrouter_https_transport, + _confirmation_consumer=unexpected("confirmation"), + _clock=lambda: _EXECUTED_AT, + _uuid4=_uuid_supplier(), + ) + + _assert_error_code(raised, "ambient_tls_configuration_forbidden") + assert calls == [] + assert not (challenge_dir / "consumed.json").exists() + assert not (challenge_dir / "attempts.sqlite3").exists() + + +def test_direct_transport_preflight_rejects_active_timer_and_worker_thread( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(signal, "getitimer", lambda _which: (1.0, 0.0)) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as active_timer: + real_e2e._preflight_direct_transport_environment() + _assert_error_code(active_timer, "direct_transport_environment_invalid") + + monkeypatch.setattr(signal, "getitimer", lambda _which: (0.0, 0.0)) + with ThreadPoolExecutor(max_workers=1) as executor: + error = executor.submit(real_e2e._preflight_direct_transport_environment).exception( + timeout=10 + ) + assert isinstance(error, real_e2e.OpenRouterRealE2EError) + assert error.code == "direct_transport_environment_invalid" + + +def test_prepare_freezes_exact_content_bound_snapshot_summary_and_overlay(tmp_path: Path) -> None: + challenge_dir = tmp_path / "content-bound" + _prepare(challenge_dir) + challenge = _read_json(challenge_dir / "challenge.json") + summary_path = _artifact_path(challenge_dir, "compact_summary") + summary = _read_json(summary_path) + + assert challenge["schema_version"] == _CHALLENGE_VERSION + verify_document_identity( + challenge, + schema_version=_CHALLENGE_VERSION, + identity_field="challenge_id", + ) + assert summary["schema_version"] == _SUMMARY_VERSION + verify_document_identity( + summary, + schema_version=_SUMMARY_VERSION, + identity_field="compact_summary_id", + ) + assert challenge["compact_summary_id"] == summary["compact_summary_id"] + + packet = challenge["packet_projection"] + request = packet["generation_request"] + policy = packet["verification_policy"] + assert summary["operation"] == { + "kind": packet["operation"]["kind"], + "schema_version": packet["operation"]["schema_version"], + } + assert summary["reference_count"] == len(packet["references"]) + assert summary["operation_inputs"] == request["operation_inputs"] + assert summary["dispatch_confirmation"] == { + "requested_provider": request["requested_provider"], + "requested_model": request["requested_model"], + "output_count": request["output_count"], + "destination": request["destination"], + "adapter_revision": request["adapter_revision"], + "capability_snapshot_id": request["capability_snapshot_id"], + "options": request["options"], + "provider_route_policy": request["provider_route_policy"], + "actual_model_policy": request["actual_model_policy"], + "idempotency": request["idempotency"], + "reconciliation": request["reconciliation"], + "verification_policy_id": policy["policy_id"], + "required_verifiers": policy["required_verifiers"], + } + + expected_exact = { + "discovery": _DISCOVERY_BODY, + "source": _SOURCE_BYTES, + "authority": _AUTHORITY_BYTES, + } + source_sha256 = hashlib.sha256(_SOURCE_BYTES).hexdigest() + raster = compile_canonical_raster(_SOURCE_BYTES, source_content_sha256=source_sha256) + left, top, right, bottom = real_e2e._mask_bounds(raster) + mask = compile_rectangle_mask( + raster, + left=left, + top=top, + right=right, + bottom=bottom, + ) + expected_exact["mask"] = mask.mask_bytes + + for name, expected in expected_exact.items(): + path = _artifact_path(challenge_dir, name) + assert path.read_bytes() == expected + assert challenge["artifacts"][name] == _descriptor( + expected, challenge["artifacts"][name]["relative_path"] + ) + assert summary["artifacts"][name] == challenge["artifacts"][name] + + overlay_path = _artifact_path(challenge_dir, "overlay") + overlay_bytes = overlay_path.read_bytes() + assert challenge["artifacts"]["overlay"] == _descriptor( + overlay_bytes, challenge["artifacts"]["overlay"]["relative_path"] + ) + assert summary["artifacts"]["overlay"] == challenge["artifacts"]["overlay"] + with Image.open(BytesIO(overlay_bytes)) as overlay: + overlay.load() + assert overlay.format == "PNG" + assert overlay.size == (raster.width, raster.height) + assert overlay.convert("RGB").tobytes() != raster.rgb_bytes + + metadata = challenge_dir.stat() + assert challenge["directory_binding"] == { + "absolute_path": str(challenge_dir), + "device": metadata.st_dev, + "inode": metadata.st_ino, + } + assert challenge["expires_at"] > challenge["prepared_at"] == _PREPARED_AT + assert "confirmation" not in challenge + assert "confirmed_at" not in challenge + assert "decision" not in challenge + assert "principal_id" not in challenge + assert "studio_session_id" not in challenge + + +@pytest.mark.parametrize( + "artifact_name", + ["discovery", "source", "mask", "authority", "overlay", "compact_summary"], +) +def test_any_snapshot_byte_drift_rejects_before_live_discovery_key_or_transport( + tmp_path: Path, + artifact_name: str, +) -> None: + challenge_dir = tmp_path / artifact_name + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + path = _artifact_path(challenge_dir, artifact_name) + original = path.read_bytes() + assert original + path.write_bytes(bytes([original[0] ^ 1]) + original[1:]) + path.chmod(0o600) + calls, unexpected = _unexpected_calls() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + ) + + _assert_error_code(raised, "challenge_artifact_drift") + assert calls == [] + + +@pytest.mark.parametrize( + "mutate", + [ + lambda value: value.__setitem__("challenge_id", _digest("f")), + lambda value: value.__setitem__("compact_summary_id", _digest("e")), + lambda value: value.__setitem__("decision", "approve_two_paid_calls"), + lambda value: value.__setitem__("authorized_generation_post_count", 2), + lambda value: value.__setitem__( + "creative_session_id", "90000000-0000-4000-8000-000000000009" + ), + lambda value: value.__setitem__("confirmed_at", "2000-01-01T00:00:00Z"), + lambda value: value.__setitem__("confirmed_at", "2100-01-01T00:00:00Z"), + lambda value: value.__setitem__("unexpected", True), + ], +) +def test_missing_or_forged_context_rejects_before_discovery_key_or_transport( + tmp_path: Path, + mutate: Callable[[JsonObject], None], +) -> None: + challenge_dir = tmp_path / "forged" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + _rewrite_context(context_path, mutate) + calls, unexpected = _unexpected_calls() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + ) + + _assert_error_code(raised, "confirmation_context_invalid") + assert calls == [] + + +def test_missing_context_rejects_before_discovery_key_or_transport(tmp_path: Path) -> None: + challenge_dir = tmp_path / "missing-context" + _prepare(challenge_dir) + calls, unexpected = _unexpected_calls() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + challenge_dir / "does-not-exist.json", + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + ) + + _assert_error_code(raised, "confirmation_context_unavailable") + assert calls == [] + + +def test_production_default_rejects_self_minted_context_before_discovery_or_key( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "untrusted-context" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + calls, unexpected = _unexpected_calls() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _REAL_E2E.execute_openrouter_real_e2e( + challenge_dir, + context_path, + _discovery_fetcher=unexpected("discovery"), + _credential_loader=unexpected("credential"), + _transport=unexpected("transport"), + _clock=lambda: _EXECUTED_AT, + _uuid4=_uuid_supplier(), + ) + + _assert_error_code(raised, "confirmation_authority_unavailable") + assert calls == [] + + +def test_expired_challenge_context_rejects_before_discovery_key_or_transport( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "expired" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + calls, unexpected = _unexpected_calls() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + clock=lambda: "2100-01-01T00:00:00Z", + ) + + _assert_error_code(raised, "challenge_expired") + assert calls == [] + + +def test_fresh_discovery_must_equal_snapshot_bytes_before_key_or_claim(tmp_path: Path) -> None: + challenge_dir = tmp_path / "discovery-drift" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + credential_calls = 0 + sends: list[bytes] = [] + + def credential(_: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + def transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + assert bearer_token == _TOKEN + sends.append(body) + return _http_response() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + discovery_fetcher=lambda: _DISCOVERY_BODY + b"\n", + credential_loader=credential, + transport=transport, + ) + + _assert_error_code(raised, "challenge_discovery_drift") + assert credential_calls == 0 + assert sends == [] + + result = _execute( + challenge_dir, + context_path, + credential_loader=credential, + transport=transport, + ) + assert result.generation_post_count == 1 + assert credential_calls == 1 + assert len(sends) == 1 + + +def test_directory_swap_during_discovery_rejects_before_key_or_claim(tmp_path: Path) -> None: + challenge_dir = tmp_path / "directory-swap" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + moved_dir = tmp_path / "directory-swap-moved" + credential_calls = 0 + + def discovery() -> bytes: + challenge_dir.rename(moved_dir) + return _DISCOVERY_BODY + + def credential(_profile: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=lambda **_: _http_response(), + ) + + _assert_error_code(raised, "challenge_binding_mismatch") + assert credential_calls == 0 + assert not (moved_dir / "consumed.json").exists() + + +def test_challenge_expiring_during_discovery_rejects_before_key_or_claim( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "expires-during-discovery" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + expired = False + credential_calls = 0 + + def clock() -> str: + return "2100-01-01T00:00:00Z" if expired else _EXECUTED_AT + + def discovery() -> bytes: + nonlocal expired + expired = True + return _DISCOVERY_BODY + + def credential(_profile: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=lambda **_: _http_response(), + clock=clock, + ) + + _assert_error_code(raised, "challenge_expired") + assert credential_calls == 0 + assert not (challenge_dir / "consumed.json").exists() + + +def test_rebuilt_wire_identity_drift_rejects_before_key_or_claim( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "wire-drift" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + original = real_e2e._prepare_request + credential_calls = 0 + + def drift(*args: Any, **kwargs: Any) -> Any: + prepared = original(*args, **kwargs) + wire_body = prepared.wire_body + b" " + return dataclasses.replace( + prepared, + wire_body=wire_body, + wire_body_sha256=hashlib.sha256(wire_body).hexdigest(), + wire_body_byte_count=len(wire_body), + ) + + def credential(_profile: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + monkeypatch.setattr(real_e2e, "_prepare_request", drift) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + credential_loader=credential, + transport=lambda **_: _http_response(), + ) + + _assert_error_code(raised, "challenge_artifact_drift") + assert credential_calls == 0 + assert not (challenge_dir / "consumed.json").exists() + + +def test_context_values_are_projected_exactly_and_never_generated(tmp_path: Path) -> None: + challenge_dir = tmp_path / "exact-confirmation" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + context = _read_json(context_path) + + result = _execute(challenge_dir, context_path) + + plan = _read_json(challenge_dir / "plan.json") + confirmation = plan["intent_packet"]["confirmation"] + assert confirmation["mode"] == "explicit" + assert confirmation["compact_summary_id"] == context["compact_summary_id"] + assert confirmation["confirmed_at"] == context["confirmed_at"] + assert confirmation["principal_id"] == context["principal_id"] + assert confirmation["studio_session_id"] == context["studio_session_id"] + assert plan["intent_packet"]["creative_session_id"] == context["creative_session_id"] + assert result.generation_post_count == context["authorized_generation_post_count"] == 1 + + +def test_expiry_crossed_inside_trusted_consumer_stops_before_credential(tmp_path: Path) -> None: + challenge_dir = tmp_path / "consumer-crosses-expiry" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + measured_now = _EXECUTED_AT + credential_calls = 0 + + def clock() -> str: + return measured_now + + def consumer(_context: JsonObject, _challenge: JsonObject) -> bool: + nonlocal measured_now + measured_now = "2026-08-17T04:00:00Z" + return True + + def credential(_profile: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + confirmation_consumer=consumer, + credential_loader=credential, + clock=clock, + ) + + _assert_error_code(raised, "challenge_expired") + assert credential_calls == 0 + assert not (challenge_dir / "consumed.json").exists() + + +def test_expiry_crossed_after_local_consume_still_stops_before_credential( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "local-consume-crosses-expiry" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + measured_now = _EXECUTED_AT + credential_calls = 0 + original_claim = real_e2e._claim_challenge_consumption + + def clock() -> str: + return measured_now + + def claim(*args: Any, **kwargs: Any) -> None: + nonlocal measured_now + original_claim(*args, **kwargs) + measured_now = "2026-08-17T04:00:00Z" + + def credential(_profile: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + monkeypatch.setattr(real_e2e, "_claim_challenge_consumption", claim) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + credential_loader=credential, + clock=clock, + ) + + _assert_error_code(raised, "challenge_expired") + assert credential_calls == 0 + assert (challenge_dir / "consumed.json").is_file() + + +def test_challenge_directory_and_confirmation_path_are_inode_safe(tmp_path: Path) -> None: + challenge_dir = tmp_path / "bound" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + calls, unexpected = _unexpected_calls() + + moved_dir = tmp_path / "moved" + challenge_dir.rename(moved_dir) + moved_context = moved_dir / context_path.name + with pytest.raises(real_e2e.OpenRouterRealE2EError) as moved: + _execute( + moved_dir, + moved_context, + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + ) + _assert_error_code(moved, "challenge_binding_mismatch") + assert calls == [] + + second_dir = tmp_path / "context-symlink" + _prepare(second_dir) + real_context = _write_context(second_dir, name="trusted-context.json") + linked_context = second_dir / "confirmation-context.json" + linked_context.symlink_to(real_context.name) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as linked: + _execute( + second_dir, + linked_context, + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + ) + _assert_error_code(linked, "confirmation_context_invalid") + assert calls == [] + + copied_dir = tmp_path / "copied" + shutil.copytree(second_dir, copied_dir, symlinks=True) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as copied: + _execute( + copied_dir, + copied_dir / "trusted-context.json", + discovery_fetcher=unexpected("discovery"), + credential_loader=unexpected("credential"), + transport=unexpected("transport"), + ) + _assert_error_code(copied, "challenge_binding_mismatch") + assert calls == [] + + +def test_consumed_challenge_replay_never_refreshes_key_or_sends(tmp_path: Path) -> None: + challenge_dir = tmp_path / "one-use" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + calls: list[str] = [] + + def discovery() -> bytes: + calls.append("discovery") + return _DISCOVERY_BODY + + def credential(_: str) -> str: + calls.append("credential") + return _TOKEN + + def transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + assert body and bearer_token == _TOKEN + calls.append("transport") + return _http_response() + + first = _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=transport, + ) + assert first.generation_post_count == 1 + assert calls == ["discovery", "credential", "transport"] + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as replay: + _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=transport, + ) + + _assert_error_code(replay, "challenge_consumed") + assert calls == ["discovery", "credential", "transport"] + + +def test_trusted_confirmation_ledger_blocks_replay_after_local_rollback(tmp_path: Path) -> None: + challenge_dir = tmp_path / "rollback" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + sends = 0 + credential_calls = 0 + + def credential(_profile: str) -> str: + nonlocal credential_calls + credential_calls += 1 + return _TOKEN + + def transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + nonlocal sends + assert body and bearer_token == _TOKEN + sends += 1 + return _http_response() + + first = _execute( + challenge_dir, + context_path, + credential_loader=credential, + transport=transport, + ) + assert first.states[-1] == "succeeded" + for path in tuple(challenge_dir.iterdir()): + if path.name not in { + "challenge.json", + "compact-summary.json", + "discovery.json", + "source.png", + "source.jpg", + "authority.json", + "mask.u8", + "overlay.png", + context_path.name, + }: + path.unlink() + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as replay: + _execute( + challenge_dir, + context_path, + credential_loader=credential, + transport=transport, + ) + + _assert_error_code(replay, "confirmation_authority_invalid") + assert credential_calls == sends == 1 + + +def test_ambient_decimal_context_cannot_round_0051_quote_under_cap(tmp_path: Path) -> None: + document = json.loads(_DISCOVERY_BODY) + pricing = document["endpoints"][0]["pricing"] + pricing[0]["cost_usd"] = 0.001 + pricing[1]["cost_usd"] = 0.05 + over_cap = json.dumps(document, separators=(",", ":")).encode("utf-8") + source_calls = 0 + + def source() -> bytes: + nonlocal source_calls + source_calls += 1 + return _SOURCE_BYTES + + prepare = _REAL_E2E.prepare_openrouter_real_e2e + with localcontext(): + getcontext().prec = 1 + getcontext().rounding = ROUND_DOWN + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + prepare( + tmp_path / "decimal", + _discovery_fetcher=lambda: over_cap, + _source_fetcher=source, + _authority_bundle=_AUTHORITY_BYTES, + _clock=lambda: _PREPARED_AT, + ) + + _assert_error_code(raised, "quote_exceeds_cap") + assert source_calls == 0 + assert not (tmp_path / "decimal").exists() + assert Decimal("0.051") > real_e2e.MAX_COST_USD + + +def test_missing_reported_cost_remains_terminal_success_after_paid_response( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "cost-not-reported" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + sends: list[bytes] = [] + + def transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + assert bearer_token == _TOKEN + sends.append(body) + return _http_response(cost=None) + + result = _execute(challenge_dir, context_path, transport=transport) + + assert len(sends) == 1 + assert result.generation_post_count == 1 + assert result.reported_cost_usd is None + assert result.states == ("prepared", "submitted", "response_received", "succeeded") + journal = AttemptJournal((challenge_dir / "attempts.sqlite3").resolve()) + assert journal.read_state(result.attempt_id).state == "succeeded" + journal.verify_integrity() + + +def test_invalid_provider_media_is_retained_as_failed_structural_evidence( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "invalid-provider-media" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + invalid_payload = b"not-a-supported-raster" + body = json.dumps( + { + "created": 1_786_930_000, + "data": [ + { + "b64_json": base64.b64encode(invalid_payload).decode("ascii"), + "media_type": "image/png", + } + ], + "usage": {"cost": 0.033}, + }, + separators=(",", ":"), + ).encode("utf-8") + + result = _execute( + challenge_dir, + context_path, + transport=lambda **_: OpenRouterHttpResponse( + status=200, + headers={"content-type": "application/json"}, + body=body, + elapsed_milliseconds=3210, + ), + ) + + assert result.states == ("prepared", "submitted", "response_received") + assert result.output_occurrence_id is None + assert result.provider_media_admission_result == "unsupported_format" + assert result.raw_structural_result == "fail" + assert result.raw_structural_reason == "unsupported_format" + assert result.raw_locality_result == "not_run" + report = _read_json(challenge_dir / "result.json") + assert report["provider_lifecycle_state"] == "response_received" + assert report["provider_media_admission_result"] == "unsupported_format" + assert report["raw_structural_judgment"]["result"]["state"] == "fail" + assert report["raw_locality_judgment"]["result"]["state"] == "not_run" + assert report["localized_edit_gate_status"] == "not_eligible" + assert report["workflow_acceptance"] == "not_recorded" + assert report["private_payloads"]["provider_response"] == "retained_private_local_evidence" + assert report["private_payloads"]["outputs"] == "retained_private_local_evidence" + journal = AttemptJournal((challenge_dir / "attempts.sqlite3").resolve()) + journal.verify_integrity() + + +def test_post_paid_cost_above_quote_limit_is_reported_but_does_not_strand_success( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "cost-above-quote-limit" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + + result = _execute( + challenge_dir, + context_path, + transport=lambda **_: _http_response(cost=Decimal("0.051")), + ) + + assert result.reported_cost_usd == Decimal("0.051") + assert result.states[-1] == "succeeded" + report = _read_json(challenge_dir / "result.json") + assert report["spend_limit_kind"] == "quote_only_not_provider_enforced" + assert report["cost_telemetry_status"] == "reported_above_quote_admission_limit" + assert report["semantic_aesthetic_result"] == "not_run" + assert report["compositor_result"] == "not_run" + + +def test_non_usd_cost_is_never_mislabeled_as_reported_usd(tmp_path: Path) -> None: + challenge_dir = tmp_path / "non-usd-cost" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + + result = _execute( + challenge_dir, + context_path, + transport=lambda **_: _http_response(cost=Decimal("0.033"), currency="EUR"), + ) + + assert result.states[-1] == "succeeded" + assert result.reported_cost_usd is None + assert result.cost_telemetry_status == "reported_non_usd" + report = _read_json(challenge_dir / "result.json") + assert report["reported_cost_usd"] is None + assert report["cost_telemetry_status"] == "reported_non_usd" + journal = AttemptJournal((challenge_dir / "attempts.sqlite3").resolve()) + stored = journal.read_provider_response(result.attempt_id) + assert real_e2e.provider_to_json(stored.receipt)["cost"]["currency"] == "EUR" + + +def test_ambiguous_transport_consumes_challenge_and_can_never_retry(tmp_path: Path) -> None: + challenge_dir = tmp_path / "ambiguous" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + calls: list[str] = [] + + def discovery() -> bytes: + calls.append("discovery") + return _DISCOVERY_BODY + + def credential(_profile: str) -> str: + calls.append("credential") + return _TOKEN + + def transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + assert body and bearer_token == _TOKEN + calls.append("transport") + raise TimeoutError("ambiguous provider outcome") + + first = _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=transport, + ) + assert first.states == ("prepared", "submitted", "outcome_unknown") + assert first.generation_post_count == 1 + assert calls == ["discovery", "credential", "transport"] + report = _read_json(challenge_dir / "result.json") + assert report["actual_model"] == "not_reported" + assert report["private_payloads"]["provider_response"] == "absent" + assert report["private_payloads"]["outputs"] == "absent" + assert report["workflow_acceptance"] == "not_recorded" + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as replay: + _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=transport, + ) + + _assert_error_code(replay, "challenge_consumed") + assert calls == ["discovery", "credential", "transport"] + + +def test_concurrent_executors_atomically_admit_only_one_credential_and_send( + tmp_path: Path, +) -> None: + challenge_dir = tmp_path / "concurrent" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + discovery_barrier = threading.Barrier(2) + lock = threading.Lock() + credential_calls = 0 + sends = 0 + + def discovery() -> bytes: + discovery_barrier.wait(timeout=10) + return _DISCOVERY_BODY + + def credential(_profile: str) -> str: + nonlocal credential_calls + with lock: + credential_calls += 1 + return _TOKEN + + def transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpResponse: + nonlocal sends + assert body and bearer_token == _TOKEN + with lock: + sends += 1 + return _http_response() + + def invoke() -> tuple[str, Any]: + try: + return ( + "ok", + _execute( + challenge_dir, + context_path, + discovery_fetcher=discovery, + credential_loader=credential, + transport=transport, + ), + ) + except real_e2e.OpenRouterRealE2EError as error: + return "error", error.code + + with ThreadPoolExecutor(max_workers=2) as executor: + results = list(executor.map(lambda _index: invoke(), range(2))) + + assert sorted(kind for kind, _value in results) == ["error", "ok"] + assert [value for kind, value in results if kind == "error"] == [ + "confirmation_authority_invalid" + ] + successful = [value for kind, value in results if kind == "ok"] + assert len(successful) == 1 + assert successful[0].states[-1] == "succeeded" + assert credential_calls == sends == 1 diff --git a/tests/test_openrouter_real_e2e_transport.py b/tests/test_openrouter_real_e2e_transport.py new file mode 100644 index 0000000..bcf2951 --- /dev/null +++ b/tests/test_openrouter_real_e2e_transport.py @@ -0,0 +1,476 @@ +"""RED transport and credential-erasure contracts for the real OpenRouter harness. + +Every boundary in this module is replaced with an in-memory fake. These tests must never read +Keychain state or create a socket; they pin the exact one-shot HTTPS shape and require credential +material to be absent from the exception graph that a caller can inspect after a failure. +""" + +from __future__ import annotations + +import contextlib +import subprocess +import traceback +from collections.abc import Iterator, Mapping, Sequence +from io import BytesIO +from pathlib import Path +from types import TracebackType +from typing import Any + +import pytest +from PIL import Image + +import eval.openrouter_real_e2e as real_e2e +from eval.openrouter_real_e2e import ( + OpenRouterRealE2EError, + direct_openrouter_https_transport, + load_openrouter_keychain_token, +) +from tests.test_openrouter_real_e2e_confirmation import _execute, _prepare, _write_context + +_TOKEN = "sk-or-v1-TRANSPORT-SECRET-SENTINEL-0123456789" +_REQUEST_BODY = b'{"model":"qwen/qwen-image-3","n":1}' +_RESPONSE_BODY = b'{"created":1786930000,"data":[]}' +_PRODUCTION_ROOT = Path(real_e2e.__file__).resolve().parents[1] + + +class _FakeSocket: + def __init__(self, events: list[tuple[Any, ...]]) -> None: + self._events = events + + def settimeout(self, seconds: float) -> None: + self._events.append(("socket.settimeout", seconds)) + + +class _FakeResponse: + def __init__( + self, + *, + status: int, + body: bytes, + headers: Sequence[tuple[str, str]], + events: list[tuple[Any, ...]], + ) -> None: + self.status = status + self._body = body + self._headers = tuple(headers) + self._events = events + self._read = False + + def getheaders(self) -> list[tuple[str, str]]: + self._events.append(("response.getheaders",)) + return list(self._headers) + + def getheader(self, name: str) -> str | None: + self._events.append(("response.getheader", name)) + lowered = name.lower() + matches = [value for key, value in self._headers if key.lower() == lowered] + return matches[0] if matches else None + + def read1(self, amount: int) -> bytes: + self._events.append(("response.read1", amount)) + if self._read: + return b"" + self._read = True + return self._body + + +class _FakeConnection: + def __init__( + self, + *, + response: _FakeResponse, + events: list[tuple[Any, ...]], + connect_failure: BaseException | None = None, + ) -> None: + self.sock: _FakeSocket | None = _FakeSocket(events) + self._response = response + self._events = events + self._connect_failure = connect_failure + + def set_debuglevel(self, level: int) -> None: + self._events.append(("connection.set_debuglevel", level)) + + def connect(self) -> None: + self._events.append(("connection.connect",)) + if self._connect_failure is not None: + raise self._connect_failure + + def putrequest(self, method: str, path: str, **kwargs: Any) -> None: + self._events.append(("connection.putrequest", method, path, kwargs)) + + def putheader(self, name: str, value: str) -> None: + self._events.append(("connection.putheader", name, value)) + + def endheaders(self, body: bytes) -> None: + self._events.append(("connection.endheaders", body)) + + def getresponse(self) -> _FakeResponse: + self._events.append(("connection.getresponse",)) + return self._response + + def close(self) -> None: + self._events.append(("connection.close",)) + + +def _install_direct_https_fakes( + monkeypatch: pytest.MonkeyPatch, + *, + status: int = 200, + response_body: bytes = _RESPONSE_BODY, + response_headers: Sequence[tuple[str, str]] | None = None, + connect_failure: BaseException | None = None, +) -> tuple[list[tuple[Any, ...]], list[_FakeConnection], object]: + events: list[tuple[Any, ...]] = [] + connections: list[_FakeConnection] = [] + context = object() + headers = response_headers or ( + ("Content-Length", str(len(response_body))), + ("Content-Type", "application/json"), + ) + + def connection_factory( + host: str, + port: int, + *, + timeout: float, + context: object, + ) -> _FakeConnection: + events.append(("HTTPSConnection", host, port, timeout, context)) + response = _FakeResponse( + status=status, + body=response_body, + headers=headers, + events=events, + ) + connection = _FakeConnection( + response=response, + events=events, + connect_failure=connect_failure, + ) + connections.append(connection) + return connection + + @contextlib.contextmanager + def wall_deadline(seconds: float) -> Iterator[None]: + events.append(("wall_deadline.enter", seconds)) + try: + yield + finally: + events.append(("wall_deadline.exit", seconds)) + + monotonic_values = iter((100.0, 100.25, 100.5)) + monkeypatch.setattr(real_e2e, "_tls_context", lambda: context) + monkeypatch.setattr(real_e2e, "_wall_deadline", wall_deadline) + monkeypatch.setattr(real_e2e.time, "monotonic", lambda: next(monotonic_values)) + monkeypatch.setattr(real_e2e.http.client, "HTTPSConnection", connection_factory) + return events, connections, context + + +def _events_named(events: Sequence[tuple[Any, ...]], name: str) -> list[tuple[Any, ...]]: + return [event for event in events if event[0] == name] + + +def _safe_repr(value: object) -> str: + try: + return repr(value) + except Exception as error: # pragma: no cover - defensive inspection only + return f"" + + +def _exception_graph_material(error: BaseException) -> str: + """Render public exception state plus locals from production frames only. + + Test-frame locals necessarily contain the sentinel used by the assertion, so they are omitted. + Cause and context exception messages are still traversed regardless of their source frame. + """ + + material: list[str] = [] + pending: list[BaseException] = [error] + seen: set[int] = set() + while pending: + current = pending.pop() + if id(current) in seen: + continue + seen.add(id(current)) + material.extend( + ( + type(current).__name__, + str(current), + _safe_repr(current), + _safe_repr(current.args), + ) + ) + for linked in (current.__cause__, current.__context__): + if linked is not None: + pending.append(linked) + trace: TracebackType | None = current.__traceback__ + while trace is not None: + frame = trace.tb_frame + frame_path = Path(frame.f_code.co_filename).resolve() + if frame_path.is_relative_to(_PRODUCTION_ROOT) and "tests" not in frame_path.parts: + material.append(frame.f_code.co_name) + material.extend( + f"{name}={_safe_repr(value)}" for name, value in frame.f_locals.items() + ) + trace = trace.tb_next + return "\n".join(material) + + +def _source_png() -> bytes: + image = Image.new("RGB", (64, 48), (105, 160, 205)) + encoded = BytesIO() + image.save(encoded, format="PNG", optimize=False) + return encoded.getvalue() + + +def test_direct_transport_uses_one_exact_origin_post_and_one_body_write( + monkeypatch: pytest.MonkeyPatch, +) -> None: + events, connections, tls_context = _install_direct_https_fakes(monkeypatch) + + result = direct_openrouter_https_transport(body=_REQUEST_BODY, bearer_token=_TOKEN) + + assert result.status == 200 + assert result.headers == {"content-type": "application/json"} + assert result.body == _RESPONSE_BODY + assert result.elapsed_milliseconds == 500 + assert len(connections) == 1 + assert _events_named(events, "HTTPSConnection") == [ + ("HTTPSConnection", "openrouter.ai", 443, 10.0, tls_context) + ] + assert _events_named(events, "connection.connect") == [("connection.connect",)] + assert _events_named(events, "connection.putrequest") == [ + ( + "connection.putrequest", + "POST", + "/api/v1/images", + {"skip_accept_encoding": True}, + ) + ] + assert _events_named(events, "connection.putheader") == [ + ("connection.putheader", "Authorization", f"Bearer {_TOKEN}"), + ("connection.putheader", "Content-Type", "application/json"), + ("connection.putheader", "Accept", "application/json"), + ("connection.putheader", "Accept-Encoding", "identity"), + ("connection.putheader", "Connection", "close"), + ("connection.putheader", "Content-Length", str(len(_REQUEST_BODY))), + ] + assert _events_named(events, "connection.endheaders") == [ + ("connection.endheaders", _REQUEST_BODY) + ] + assert _events_named(events, "connection.getresponse") == [("connection.getresponse",)] + assert _events_named(events, "wall_deadline.enter") == [("wall_deadline.enter", 210.0)] + assert _events_named(events, "socket.settimeout") == [("socket.settimeout", 209.75)] + + +def test_direct_transport_returns_redirect_without_following_or_retrying( + monkeypatch: pytest.MonkeyPatch, +) -> None: + events, connections, _ = _install_direct_https_fakes( + monkeypatch, + status=307, + response_headers=( + ("Content-Length", str(len(_RESPONSE_BODY))), + ("Content-Type", "application/json"), + ("Location", "https://attacker.invalid/capture"), + ), + ) + + result = direct_openrouter_https_transport(body=_REQUEST_BODY, bearer_token=_TOKEN) + + assert result.status == 307 + assert len(connections) == 1 + assert len(_events_named(events, "connection.connect")) == 1 + assert len(_events_named(events, "connection.putrequest")) == 1 + assert len(_events_named(events, "connection.endheaders")) == 1 + assert len(_events_named(events, "connection.getresponse")) == 1 + + +@pytest.mark.parametrize( + "response_headers", + [ + (("Content-Length", "2"), ("Content-Length", "2")), + (("Content-Length", "2"), ("Transfer-Encoding", "chunked")), + (("Content-Length", "2"), ("Content-Encoding", "gzip")), + ], +) +def test_direct_transport_rejects_ambiguous_or_encoded_response_framing_after_one_send( + monkeypatch: pytest.MonkeyPatch, + response_headers: Sequence[tuple[str, str]], +) -> None: + events, connections, _ = _install_direct_https_fakes( + monkeypatch, + response_body=b"{}", + response_headers=response_headers, + ) + + with pytest.raises(RuntimeError, match="^OpenRouter transport failed$") as raised: + direct_openrouter_https_transport(body=_REQUEST_BODY, bearer_token=_TOKEN) + + assert raised.value.__cause__ is None + assert len(connections) == 1 + assert len(_events_named(events, "connection.connect")) == 1 + assert len(_events_named(events, "connection.endheaders")) == 1 + assert len(_events_named(events, "connection.getresponse")) == 1 + + +def test_direct_transport_classifies_wall_expiry_as_timeout_without_retry( + monkeypatch: pytest.MonkeyPatch, +) -> None: + events, connections, _ = _install_direct_https_fakes( + monkeypatch, + connect_failure=real_e2e._DeadlineExpired("synthetic wall expiry"), + ) + + with pytest.raises(TimeoutError, match="^OpenRouter transport deadline exceeded$") as raised: + direct_openrouter_https_transport(body=_REQUEST_BODY, bearer_token=_TOKEN) + + assert type(raised.value) is TimeoutError + assert raised.value.__cause__ is None + assert len(connections) == 1 + assert len(_events_named(events, "connection.connect")) == 1 + assert _events_named(events, "connection.putrequest") == [] + assert _events_named(events, "connection.endheaders") == [] + + +def test_keychain_nonzero_exit_drops_secret_from_exception_graph_and_traceback_locals( + monkeypatch: pytest.MonkeyPatch, +) -> None: + calls: list[tuple[tuple[str, ...], Mapping[str, Any]]] = [] + + def failed(argv: list[str], **kwargs: Any) -> subprocess.CompletedProcess[str]: + calls.append((tuple(argv), dict(kwargs))) + return subprocess.CompletedProcess( + argv, + 44, + stdout=f"unusable:{_TOKEN}", + stderr=f"security diagnostic:{_TOKEN}", + ) + + monkeypatch.setattr(real_e2e.subprocess, "run", failed) + + with pytest.raises(OpenRouterRealE2EError) as raised: + load_openrouter_keychain_token(real_e2e.CREDENTIAL_PROFILE_ID) + + assert raised.value.code == "credential_unavailable" + assert raised.value.__cause__ is None + assert raised.value.__context__ is None + assert _TOKEN not in _exception_graph_material(raised.value) + assert calls == [ + ( + ( + "/usr/bin/security", + "find-generic-password", + "-s", + "OPENROUTER_API_KEY", + "-a", + "khive", + "-w", + ), + { + "capture_output": True, + "check": False, + "text": True, + "timeout": 15, + }, + ) + ] + + +def test_injected_credential_failure_drops_secret_cause_context_and_production_locals( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +) -> None: + transport_calls = 0 + + def failing_credential_loader(_profile_id: str) -> str: + raise RuntimeError(f"injected credential diagnostic:{_TOKEN}") + + def forbidden_transport(**_kwargs: Any) -> Any: + nonlocal transport_calls + transport_calls += 1 + raise AssertionError("credential failure reached transport") + + # This is an additional tripwire: even an accidental default-boundary lookup must remain fake. + monkeypatch.setattr( + real_e2e.subprocess, + "run", + lambda *_args, **_kwargs: (_ for _ in ()).throw( + AssertionError("test attempted a real Keychain lookup") + ), + ) + + with pytest.raises(OpenRouterRealE2EError) as raised: + challenge_dir = tmp_path / "credential-failure" + _prepare(challenge_dir, source_bytes=_source_png()) + context_path = _write_context(challenge_dir) + _execute( + challenge_dir, + context_path, + credential_loader=failing_credential_loader, + transport=forbidden_transport, + ) + + assert raised.value.code == "credential_unavailable" + assert raised.value.__cause__ is None + assert raised.value.__context__ is None + assert _TOKEN not in _exception_graph_material(raised.value) + assert transport_calls == 0 + rendered = "".join(traceback.format_exception(raised.value)) + assert _TOKEN not in rendered + assert _TOKEN.encode() not in b"".join( + path.read_bytes() for path in (tmp_path / "credential-failure").rglob("*") if path.is_file() + ) + + +def test_transport_failure_drops_bearer_from_exception_graph_and_production_locals( + monkeypatch: pytest.MonkeyPatch, +) -> None: + events, connections, _ = _install_direct_https_fakes( + monkeypatch, + connect_failure=RuntimeError(f"socket diagnostic:{_TOKEN}"), + ) + + with pytest.raises(RuntimeError, match="^OpenRouter transport failed$") as raised: + direct_openrouter_https_transport(body=_REQUEST_BODY, bearer_token=_TOKEN) + + assert raised.value.__cause__ is None + assert raised.value.__context__ is None + assert _TOKEN not in _exception_graph_material(raised.value) + assert len(connections) == 1 + assert len(_events_named(events, "connection.connect")) == 1 + assert _events_named(events, "connection.putrequest") == [] + + +@pytest.mark.parametrize("exception_type", [RuntimeError, KeyboardInterrupt]) +def test_post_keychain_failure_never_reaches_public_exception_graph_or_artifacts( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, + exception_type: type[BaseException], +) -> None: + challenge_dir = tmp_path / f"post-key-{exception_type.__name__}" + _prepare(challenge_dir, source_bytes=_source_png()) + context_path = _write_context(challenge_dir) + + def explode(*_args: Any, **_kwargs: Any) -> Any: + raise exception_type(f"post-key diagnostic:{_TOKEN}") + + monkeypatch.setattr(real_e2e, "AttemptJournal", explode) + + with pytest.raises(OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + credential_loader=lambda _profile: _TOKEN, + transport=lambda **_kwargs: (_ for _ in ()).throw( + AssertionError("journal failure reached transport") + ), + ) + + assert raised.value.code == "execution_failed" + assert raised.value.__cause__ is None + assert raised.value.__context__ is None + assert _TOKEN not in _exception_graph_material(raised.value) + for path in challenge_dir.rglob("*"): + if path.is_file() and not path.is_symlink(): + assert _TOKEN.encode() not in path.read_bytes() From 7aba06ec7a604041f13907cc54386a95835a75d5 Mon Sep 17 00:00:00 2001 From: khive Date: Mon, 17 Aug 2026 13:19:14 -0400 Subject: [PATCH 2/5] fix: cost telemetry shape degrades to explicit unavailability, never response rejection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A paid provider response was stranded when usage carried a non-conforming currency or amount: decode raised invalid_provider_response after the charge, the receipt was never persisted, and the harness is non-retrying by construction — the opposite of the contract eval/README.md freezes on this branch. _decimal_cost now certifies telemetry into the receipt or returns the schema's unavailable state, a non-dict usage degrades the same way, and the raw response bytes keep whatever was actually reported. The digit bound still runs before format(), so a compact huge-exponent lexeme cannot expand. Authority references missing the key the packet build indexes now fail at the stable authority_invalid boundary instead of escaping as a KeyError. Co-Authored-By: Claude Fable 5 --- INTERFACES.md | 3 +- eval/README.md | 1 + eval/openrouter_real_e2e.py | 9 +- moodboard/openrouter.py | 43 ++++----- tests/test_openrouter_adapter.py | 88 ++++++++++++++++--- .../test_openrouter_real_e2e_confirmation.py | 23 +++++ 6 files changed, 129 insertions(+), 38 deletions(-) diff --git a/INTERFACES.md b/INTERFACES.md index 59b72f8..7bf0712 100644 --- a/INTERFACES.md +++ b/INTERFACES.md @@ -689,7 +689,8 @@ A 200 response is strict, bounded UTF-8 JSON with only `created`, `data`, and op exactly one `data` item. Base64 is decoded strictly and bounded to the registered 16 MiB encoded-image limit. The receipt records exact raw-response and output BLAKE3/SHA-256/count identities, optional provider media-type -claim, reported finite nonnegative USD cost when present, and measured adapter latency. The Image +claim, cost telemetry when it conforms to the receipt contract (explicit unavailability otherwise, +never response rejection), and measured adapter latency. The Image response does not attest the actual model or upstream provider, so receipts honestly record `actual_model:undisclosed` and `upstream_route:unknown`; a request pin is not rewritten as response provenance. diff --git a/eval/README.md b/eval/README.md index e05c39b..ab06dd0 100644 --- a/eval/README.md +++ b/eval/README.md @@ -128,5 +128,6 @@ The executable acceptance map for this slice is: | One injected in-process consumption winner can reach one fake POST | replay, ambiguity, and concurrent-executor tests | | Quote arithmetic is exact and `$0.05` is pre-dispatch only | ambient-Decimal and over-quote tests | | Missing post-paid cost telemetry does not strand valid media evidence | `test_missing_reported_cost_remains_terminal_success_after_paid_response` | +| Non-conforming cost telemetry degrades to explicit unavailability, never rejection | `test_nonconforming_cost_telemetry_degrades_to_unavailable_without_stranding` | | Credentials cannot survive public exceptions or local artifacts | real-E2E transport exception-graph tests | | Real board/retrieval identities are derived, never label hashes | `test_openrouter_real_e2e_authority.py` | diff --git a/eval/openrouter_real_e2e.py b/eval/openrouter_real_e2e.py index 3fcffc0..1ccc190 100644 --- a/eval/openrouter_real_e2e.py +++ b/eval/openrouter_real_e2e.py @@ -1347,8 +1347,13 @@ def _validate_authority_document(document: Mapping[str, Any]) -> JsonObject: ): _fail("authority_invalid") # IntentPacket validation remains the authority for the closed per-reference shape. Here we - # only reject values that could make projection or copying unsafe before that validation. - if any(not isinstance(reference, dict) for reference in references): + # only reject values that could make projection or copying unsafe before that validation, + # including the one key _build_packet indexes before IntentPacket validation runs. + if any( + not isinstance(reference, dict) + or not isinstance(reference.get("reference_occurrence_id"), str) + for reference in references + ): _fail("authority_invalid") return copy.deepcopy(dict(document)) diff --git a/moodboard/openrouter.py b/moodboard/openrouter.py index 1e2de50..7cd0739 100644 --- a/moodboard/openrouter.py +++ b/moodboard/openrouter.py @@ -1463,37 +1463,40 @@ def _canonical_attempt(value: GenerationAttempt | Mapping[str, Any]) -> Generati def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: + """Certify cost telemetry into the receipt, or state explicit unavailability. + + Cost is post-hoc telemetry: a shape this function cannot certify degrades to the + schema's unavailable state and must never reject the paid response carrying it. + The raw response bytes retain whatever the provider actually reported. + """ + unavailable = { + "state": "unavailable", + "amount": None, + "currency": None, + "provenance": "not_reported", + } if value is None: - return { - "state": "unavailable", - "amount": None, - "currency": None, - "provenance": "not_reported", - } + return unavailable measured_currency = "USD" if currency is None else currency if ( not isinstance(measured_currency, str) or re.fullmatch(r"[A-Z]{3}", measured_currency) is None ): - raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") + return unavailable if isinstance(value, bool) or not isinstance(value, (int, Decimal)): - raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") + return unavailable try: measured = Decimal(value) except (InvalidOperation, ValueError, TypeError): - raise OpenRouterAdapterError( - "invalid_provider_response", "provider response is invalid" - ) from None + return unavailable if not measured.is_finite() or measured < 0: - raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") + return unavailable if measured.is_zero(): amount = "0" else: _, digits, exponent = measured.as_tuple() if not isinstance(exponent, int): - raise OpenRouterAdapterError( - "invalid_provider_response", "provider response is invalid" - ) + return unavailable trailing_zeroes = 0 for digit in reversed(digits): if digit != 0: @@ -1504,9 +1507,7 @@ def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: integer_digits = max(1, effective_digits + effective_exponent) fractional_digits = max(0, -effective_exponent) if integer_digits > 21 or fractional_digits > 18: - raise OpenRouterAdapterError( - "invalid_provider_response", "provider response is invalid" - ) + return unavailable amount = format(measured, "f") if "." in amount: amount = amount.rstrip("0").rstrip(".") @@ -1514,7 +1515,7 @@ def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: amount = "0" integer, _, fraction = amount.partition(".") if len(integer) > 21 or len(fraction) > 18: - raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") + return unavailable return { "state": "reported", "amount": amount, @@ -1641,8 +1642,8 @@ def decode_openrouter_response( } ) usage = document.get("usage") - if usage is not None and not isinstance(usage, dict): - raise OpenRouterAdapterError("invalid_provider_response", "provider response is invalid") + if not isinstance(usage, dict): + usage = None cost = _decimal_cost( None if usage is None else usage.get("cost"), None if usage is None else usage.get("currency"), diff --git a/tests/test_openrouter_adapter.py b/tests/test_openrouter_adapter.py index 015830e..2c92672 100644 --- a/tests/test_openrouter_adapter.py +++ b/tests/test_openrouter_adapter.py @@ -417,6 +417,50 @@ def test_reported_cost_preserves_an_explicit_provider_currency(tmp_path: Path) - } +def test_nonconforming_cost_telemetry_degrades_to_unavailable_without_stranding( + tmp_path: Path, +) -> None: + """Telemetry shape must never reject the paid response carrying it (eval/README.md).""" + _journal, attempt, _capability, prepared = _seed_dispatch(tmp_path) + unavailable = { + "state": "unavailable", + "amount": None, + "currency": None, + "provenance": "not_reported", + } + for usage in ( + {"cost": 0.033, "currency": "usd"}, + {"cost": 0.033, "currency": "USDC"}, + {"cost": "0.033", "currency": "USD"}, + {"cost": -0.033}, + "not-a-telemetry-object", + ): + body = json.dumps( + { + "created": 1_786_930_000, + "data": [{"b64_json": base64.b64encode(_OUTPUT_BYTES).decode("ascii")}], + "usage": usage, + }, + separators=(",", ":"), + ).encode("utf-8") + + decoded = decode_openrouter_response( + attempt, + prepared, + OpenRouterHttpResponse( + status=200, + headers={"content-type": "application/json"}, + body=body, + elapsed_milliseconds=2450, + ), + received_at=_RECORDED_AT, + ) + + receipt = provider_to_json(decoded.receipt) + assert receipt["cost"] == unavailable + validate_provider_artifact(receipt) + + def test_concurrent_and_exact_dispatch_replay_send_the_attempt_at_most_once( tmp_path: Path, ) -> None: @@ -1099,25 +1143,41 @@ def test_dispatch_rejects_retrograde_evidence_time_before_claim(tmp_path: Path) assert [event.state for event in journal.read_events(attempt.attempt_id)] == ["prepared"] -@pytest.mark.parametrize("cost_lexeme", ("1e2000000", "0." + "1" * 1_000)) -def test_cost_number_is_bounded_before_decimal_expansion(tmp_path: Path, cost_lexeme: str) -> None: +def test_cost_number_is_bounded_before_decimal_expansion(tmp_path: Path) -> None: _, attempt, _, prepared = _seed_dispatch(tmp_path) - response = OpenRouterHttpResponse( - 200, - {}, - ( - '{"created":1786930000,"data":[{"b64_json":' - '"Z2VuZXJhdGVkLWltYWdlLXYx"}],"usage":{"cost":' - f"{cost_lexeme}" + "}}" - ).encode(), - 1, - ) - with pytest.raises(OpenRouterAdapterError) as raised: - decode_openrouter_response(attempt, prepared, response, received_at=_RECORDED_AT) + def _response(cost_lexeme: str) -> OpenRouterHttpResponse: + return OpenRouterHttpResponse( + 200, + {}, + ( + '{"created":1786930000,"data":[{"b64_json":' + '"Z2VuZXJhdGVkLWltYWdlLXYx"}],"usage":{"cost":' + f"{cost_lexeme}" + "}}" + ).encode(), + 1, + ) + # An oversized number lexeme dies at the bounded JSON parse, before any Decimal exists. + with pytest.raises(OpenRouterAdapterError) as raised: + decode_openrouter_response( + attempt, prepared, _response("0." + "1" * 1_000), received_at=_RECORDED_AT + ) assert raised.value.code == "invalid_provider_response" + # A compact lexeme with a huge exponent is cost telemetry, not media: the digit bound + # degrades it to explicit unavailability before format() could expand it, and the paid + # response is not stranded. + decoded = decode_openrouter_response( + attempt, prepared, _response("1e2000000"), received_at=_RECORDED_AT + ) + assert provider_to_json(decoded.receipt)["cost"] == { + "state": "unavailable", + "amount": None, + "currency": None, + "provenance": "not_reported", + } + def test_json_structural_budget_rejects_before_materializing_pairs( monkeypatch: pytest.MonkeyPatch, diff --git a/tests/test_openrouter_real_e2e_confirmation.py b/tests/test_openrouter_real_e2e_confirmation.py index 46d4282..a91207f 100644 --- a/tests/test_openrouter_real_e2e_confirmation.py +++ b/tests/test_openrouter_real_e2e_confirmation.py @@ -313,6 +313,29 @@ def test_prepare_requires_exactly_one_authority_source_before_external_io(tmp_pa assert calls == [] +def test_prepare_rejects_a_reference_missing_its_occurrence_id(tmp_path: Path) -> None: + """A wrong-key reference fails at the stable boundary, not as a KeyError in packet build.""" + document = json.loads(_AUTHORITY_BYTES.decode("utf-8")) + del document["references"][0]["reference_occurrence_id"] + document["authority_id"] = "0" * 64 + document["authority_id"] = compute_document_identity( + document, + schema_version="moodboard.openrouter-real-e2e-authority.v1", + identity_field="authority_id", + ) + prepare = _REAL_E2E.prepare_openrouter_real_e2e + + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + prepare( + tmp_path / "wrong-key-reference", + _discovery_fetcher=lambda: _DISCOVERY_BODY, + _source_fetcher=lambda: _SOURCE_BYTES, + _authority_bundle=_json_bytes(document), + _clock=lambda: _PREPARED_AT, + ) + _assert_error_code(raised, "authority_invalid") + + def test_default_direct_transport_preflight_fails_before_authorization_or_key( monkeypatch: pytest.MonkeyPatch, tmp_path: Path, From 1c483beb4710b2938d503ab7f35c6eca707d4c76 Mon Sep 17 00:00:00 2001 From: khive Date: Mon, 17 Aug 2026 13:36:45 -0400 Subject: [PATCH 3/5] fix: a reported cost the adapter cannot certify is recorded as reported_uncertifiable Degrading every uncertifiable telemetry shape to not_reported made the receipt claim the provider sent no cost when it did, and result.json could not distinguish a reported $12.50 against the $0.05 quote admission limit from absent telemetry. The receipt schema gains reported_uncertifiable, the adapter distinguishes absent cost from present-but-uncertifiable cost (including a non-object usage), and the summary carries the distinct status. The secret-scan verdicts (credential_material_persisted, artifact_secret_scan_failed) now survive the generic failure collapse as their own codes, the injected credential seam enforces the production token shape so an empty or non-ASCII token cannot make the artifact scan vacuous, and eval/README.md states that JSON structural budgets are a document-integrity bound distinct from telemetry judgment. Co-Authored-By: Claude Fable 5 --- eval/README.md | 5 ++ eval/openrouter_real_e2e.py | 21 +++++++- moodboard/openrouter.py | 43 ++++++++-------- .../schema/provider_receipt_v1.schema.json | 7 ++- tests/test_openrouter_adapter.py | 35 +++++++------ .../test_openrouter_real_e2e_confirmation.py | 49 +++++++++++++++++++ 6 files changed, 122 insertions(+), 38 deletions(-) diff --git a/eval/README.md b/eval/README.md index ab06dd0..e8b08a2 100644 --- a/eval/README.md +++ b/eval/README.md @@ -107,6 +107,11 @@ The fixed `$0.05` value is a **quote-admission limit**, not a provider-enforced checked against the exact live discovery pricing before source access. Reported cost is post-hoc telemetry: missing, differently reported, or unexpectedly high telemetry cannot undo a charge and therefore does not strand an otherwise valid provider response before terminal media admission. +A receipt distinguishes a provider that sent no cost (`not_reported`) from one that sent a cost +the adapter could not certify (`reported_uncertifiable`); the raw response bytes always retain the +original. This covers telemetry the adapter could parse: a response whose JSON number lexemes +exceed the adapter's structural budgets is rejected as a malformed document by the bounded parse, +which is a document-integrity bound, not a telemetry judgment. Reports distinguish provider lifecycle state, media admission, raw structural/locality evidence, localized-edit gate status, workflow acceptance (`not_recorded`), semantic/aesthetic judgment (`not_run`), and compositor execution (`not_run`). diff --git a/eval/openrouter_real_e2e.py b/eval/openrouter_real_e2e.py index 1ccc190..0177744 100644 --- a/eval/openrouter_real_e2e.py +++ b/eval/openrouter_real_e2e.py @@ -1938,6 +1938,12 @@ def _reported_cost_telemetry(dispatch: OpenRouterDispatchResult) -> tuple[Decima try: receipt = provider_to_json(dispatch.decoded.receipt) cost = receipt.get("cost") + if ( + isinstance(cost, dict) + and cost.get("state") == "unavailable" + and cost.get("provenance") == "reported_uncertifiable" + ): + return None, "reported_uncertifiable" if ( not isinstance(cost, dict) or cost.get("state") != "reported" @@ -2281,6 +2287,12 @@ def one_shot_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpRespo ) _scan_private_artifacts(target, token) return "ok", result + except OpenRouterRealE2EError as error: + # The secret-scan verdicts are the one diagnostic built to be unambiguous; every + # other failure still collapses to the generic code so no detail can carry a secret. + if error.code in {"credential_material_persisted", "artifact_secret_scan_failed"}: + return error.code, None + return "execution_failed", None except BaseException: return "execution_failed", None finally: @@ -2450,7 +2462,14 @@ def execute_openrouter_real_e2e( ): _fail("challenge_expired") credential_ok, token_value = _call_sanitized(lambda: _credential_loader(CREDENTIAL_PROFILE_ID)) - if not credential_ok or not isinstance(token_value, str): + # The injected seam honors the same token shape the production loader enforces; an empty + # or non-ASCII token would otherwise make the artifact secret scan vacuous. + if ( + not credential_ok + or not isinstance(token_value, str) + or not 16 <= len(token_value) <= 4096 + or any(ord(character) < 33 or ord(character) > 126 for character in token_value) + ): _fail("credential_unavailable") token = token_value status, result = _execute_with_token( diff --git a/moodboard/openrouter.py b/moodboard/openrouter.py index 7cd0739..9853009 100644 --- a/moodboard/openrouter.py +++ b/moodboard/openrouter.py @@ -1462,41 +1462,42 @@ def _canonical_attempt(value: GenerationAttempt | Mapping[str, Any]) -> Generati return artifact +def _unavailable_cost(provenance: str) -> dict[str, Any]: + return {"state": "unavailable", "amount": None, "currency": None, "provenance": provenance} + + def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: """Certify cost telemetry into the receipt, or state explicit unavailability. Cost is post-hoc telemetry: a shape this function cannot certify degrades to the schema's unavailable state and must never reject the paid response carrying it. - The raw response bytes retain whatever the provider actually reported. + ``not_reported`` states the provider sent no cost; ``reported_uncertifiable`` states it + sent one this adapter could not certify, so the receipt never inverts what the provider + did. The raw response bytes retain whatever was actually reported. """ - unavailable = { - "state": "unavailable", - "amount": None, - "currency": None, - "provenance": "not_reported", - } if value is None: - return unavailable + return _unavailable_cost("not_reported") + uncertifiable = _unavailable_cost("reported_uncertifiable") measured_currency = "USD" if currency is None else currency if ( not isinstance(measured_currency, str) or re.fullmatch(r"[A-Z]{3}", measured_currency) is None ): - return unavailable + return uncertifiable if isinstance(value, bool) or not isinstance(value, (int, Decimal)): - return unavailable + return uncertifiable try: measured = Decimal(value) except (InvalidOperation, ValueError, TypeError): - return unavailable + return uncertifiable if not measured.is_finite() or measured < 0: - return unavailable + return uncertifiable if measured.is_zero(): amount = "0" else: _, digits, exponent = measured.as_tuple() if not isinstance(exponent, int): - return unavailable + return uncertifiable trailing_zeroes = 0 for digit in reversed(digits): if digit != 0: @@ -1507,7 +1508,7 @@ def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: integer_digits = max(1, effective_digits + effective_exponent) fractional_digits = max(0, -effective_exponent) if integer_digits > 21 or fractional_digits > 18: - return unavailable + return uncertifiable amount = format(measured, "f") if "." in amount: amount = amount.rstrip("0").rstrip(".") @@ -1515,7 +1516,7 @@ def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: amount = "0" integer, _, fraction = amount.partition(".") if len(integer) > 21 or len(fraction) > 18: - return unavailable + return uncertifiable return { "state": "reported", "amount": amount, @@ -1642,12 +1643,12 @@ def decode_openrouter_response( } ) usage = document.get("usage") - if not isinstance(usage, dict): - usage = None - cost = _decimal_cost( - None if usage is None else usage.get("cost"), - None if usage is None else usage.get("currency"), - ) + if usage is None: + cost = _unavailable_cost("not_reported") + elif not isinstance(usage, dict): + cost = _unavailable_cost("reported_uncertifiable") + else: + cost = _decimal_cost(usage.get("cost"), usage.get("currency")) draft = { "schema_version": RECEIPT_VERSION, "attempt_id": descriptor.attempt_id, diff --git a/moodboard/schema/provider_receipt_v1.schema.json b/moodboard/schema/provider_receipt_v1.schema.json index de911e9..5111383 100644 --- a/moodboard/schema/provider_receipt_v1.schema.json +++ b/moodboard/schema/provider_receipt_v1.schema.json @@ -266,7 +266,12 @@ "amount": { "type": "null" }, "currency": { "type": "null" }, "provenance": { - "enum": ["not_reported", "redacted_by_provider", "not_applicable"] + "enum": [ + "not_reported", + "reported_uncertifiable", + "redacted_by_provider", + "not_applicable" + ] } }, "additionalProperties": false diff --git a/tests/test_openrouter_adapter.py b/tests/test_openrouter_adapter.py index 2c92672..f8e6bd7 100644 --- a/tests/test_openrouter_adapter.py +++ b/tests/test_openrouter_adapter.py @@ -420,20 +420,20 @@ def test_reported_cost_preserves_an_explicit_provider_currency(tmp_path: Path) - def test_nonconforming_cost_telemetry_degrades_to_unavailable_without_stranding( tmp_path: Path, ) -> None: - """Telemetry shape must never reject the paid response carrying it (eval/README.md).""" + """Telemetry shape must never reject the paid response carrying it (eval/README.md). + + A cost the provider did send but the adapter cannot certify is recorded as + reported_uncertifiable, never as not_reported: the receipt must not invert what the + provider did. + """ _journal, attempt, _capability, prepared = _seed_dispatch(tmp_path) - unavailable = { - "state": "unavailable", - "amount": None, - "currency": None, - "provenance": "not_reported", - } - for usage in ( - {"cost": 0.033, "currency": "usd"}, - {"cost": 0.033, "currency": "USDC"}, - {"cost": "0.033", "currency": "USD"}, - {"cost": -0.033}, - "not-a-telemetry-object", + for usage, provenance in ( + ({"cost": 0.033, "currency": "usd"}, "reported_uncertifiable"), + ({"cost": 0.033, "currency": "USDC"}, "reported_uncertifiable"), + ({"cost": "0.033", "currency": "USD"}, "reported_uncertifiable"), + ({"cost": -0.033}, "reported_uncertifiable"), + ("not-a-telemetry-object", "reported_uncertifiable"), + ({"note": "usage without a cost key"}, "not_reported"), ): body = json.dumps( { @@ -457,7 +457,12 @@ def test_nonconforming_cost_telemetry_degrades_to_unavailable_without_stranding( ) receipt = provider_to_json(decoded.receipt) - assert receipt["cost"] == unavailable + assert receipt["cost"] == { + "state": "unavailable", + "amount": None, + "currency": None, + "provenance": provenance, + } validate_provider_artifact(receipt) @@ -1175,7 +1180,7 @@ def _response(cost_lexeme: str) -> OpenRouterHttpResponse: "state": "unavailable", "amount": None, "currency": None, - "provenance": "not_reported", + "provenance": "reported_uncertifiable", } diff --git a/tests/test_openrouter_real_e2e_confirmation.py b/tests/test_openrouter_real_e2e_confirmation.py index a91207f..d727656 100644 --- a/tests/test_openrouter_real_e2e_confirmation.py +++ b/tests/test_openrouter_real_e2e_confirmation.py @@ -313,6 +313,55 @@ def test_prepare_requires_exactly_one_authority_source_before_external_io(tmp_pa assert calls == [] +def test_injected_credential_seam_enforces_the_production_token_shape(tmp_path: Path) -> None: + """An empty or non-ASCII token would make the artifact secret scan vacuous.""" + for bad_token in ("", "short", "token with spaces padded to length!!", "秘密" * 16): + challenge_dir = tmp_path / f"bad-token-{len(bad_token)}" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute( + challenge_dir, + context_path, + credential_loader=lambda _, token=bad_token: token, + ) + _assert_error_code(raised, "credential_unavailable") + + +def test_artifact_secret_scan_detects_a_persisted_token(tmp_path: Path) -> None: + scan_dir = tmp_path / "artifacts" + scan_dir.mkdir() + scan_dir.chmod(0o700) + clean = scan_dir / "result.json" + clean.write_bytes(b'{"ok": true}') + clean.chmod(0o600) + real_e2e._scan_private_artifacts(scan_dir, _TOKEN) + + leaky = scan_dir / "leak.json" + leaky.write_bytes(json.dumps({"token": _TOKEN}).encode("utf-8")) + leaky.chmod(0o600) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + real_e2e._scan_private_artifacts(scan_dir, _TOKEN) + _assert_error_code(raised, "credential_material_persisted") + + +def test_execution_reports_the_secret_scan_verdict_as_its_own_code( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """The one diagnostic built to be unambiguous must survive the generic failure collapse.""" + challenge_dir = tmp_path / "scan-verdict" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + + def planted_scan(output_dir: Path, token: str) -> None: + raise real_e2e.OpenRouterRealE2EError("credential_material_persisted") + + monkeypatch.setattr(real_e2e, "_scan_private_artifacts", planted_scan) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute(challenge_dir, context_path) + _assert_error_code(raised, "credential_material_persisted") + + def test_prepare_rejects_a_reference_missing_its_occurrence_id(tmp_path: Path) -> None: """A wrong-key reference fails at the stable boundary, not as a KeyError in packet build.""" document = json.loads(_AUTHORITY_BYTES.decode("utf-8")) From d4f74610ea2f3ffd223d14575814cc07863639f9 Mon Sep 17 00:00:00 2001 From: khive Date: Mon, 17 Aug 2026 13:59:54 -0400 Subject: [PATCH 4/5] fix: a non-object usage records not_reported; the uncertifiable status is pinned end to end MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A usage that is not an object carries no legible cost value, so recording reported_uncertifiable claimed a report that never happened — the same inversion in the other direction. reported_uncertifiable now means exactly a present cost value the adapter could not certify, the summary status is asserted end to end for a paid run, and every exit of the execute path that runs after provider evidence is durable scans the private artifacts for credential material, not only the returning ones. Co-Authored-By: Claude Fable 5 --- eval/README.md | 6 ++-- eval/openrouter_real_e2e.py | 7 +++++ moodboard/openrouter.py | 13 +++++---- tests/test_openrouter_adapter.py | 3 +- .../test_openrouter_real_e2e_confirmation.py | 28 +++++++++++++++++++ 5 files changed, 47 insertions(+), 10 deletions(-) diff --git a/eval/README.md b/eval/README.md index e8b08a2..28f13ad 100644 --- a/eval/README.md +++ b/eval/README.md @@ -107,9 +107,9 @@ The fixed `$0.05` value is a **quote-admission limit**, not a provider-enforced checked against the exact live discovery pricing before source access. Reported cost is post-hoc telemetry: missing, differently reported, or unexpectedly high telemetry cannot undo a charge and therefore does not strand an otherwise valid provider response before terminal media admission. -A receipt distinguishes a provider that sent no cost (`not_reported`) from one that sent a cost -the adapter could not certify (`reported_uncertifiable`); the raw response bytes always retain the -original. This covers telemetry the adapter could parse: a response whose JSON number lexemes +A receipt distinguishes the absence of a legible cost value (`not_reported`, covering absent or +non-object telemetry) from a present cost value the adapter could not certify +(`reported_uncertifiable`); the raw response bytes always retain the original. This covers telemetry the adapter could parse: a response whose JSON number lexemes exceed the adapter's structural budgets is rejected as a malformed document by the bounded parse, which is a document-integrity bound, not a telemetry judgment. Reports distinguish provider lifecycle state, media admission, raw structural/locality evidence, diff --git a/eval/openrouter_real_e2e.py b/eval/openrouter_real_e2e.py index 0177744..7d0f66e 100644 --- a/eval/openrouter_real_e2e.py +++ b/eval/openrouter_real_e2e.py @@ -2142,6 +2142,10 @@ def one_shot_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpRespo return "ok", result if dispatch.state.head_event_id is None: + # Provider evidence is already on disk past this point, so every exit scans the + # private artifacts: the frozen invariant is that credentials cannot survive + # local artifacts on any path, not only the returning ones. + _scan_private_artifacts(target, token) return "response_state_invalid", None stored_response = journal.read_provider_response(attempt.attempt_id) terminal_at = clock() @@ -2221,9 +2225,11 @@ def one_shot_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpRespo if len(success.occurrences) != 1 or not isinstance( success.occurrences[0], OutputOccurrence ): + _scan_private_artifacts(target, token) return "terminal_occurrence_invalid", None occurrence = success.occurrences[0] if len(stored_response.output_bytes) != 1: + _scan_private_artifacts(target, token) return "terminal_occurrence_invalid", None output_bytes = stored_response.output_bytes[0] structural = verify_output_structure( @@ -2238,6 +2244,7 @@ def one_shot_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpRespo structural_reason: str | None = None if structural_state == "pass": if structural.output_raster is None: + _scan_private_artifacts(target, token) return "structural_verification_invalid", None locality_judgment = verify_outside_mask_rgb_exact( source_raster, diff --git a/moodboard/openrouter.py b/moodboard/openrouter.py index 9853009..d2acb4d 100644 --- a/moodboard/openrouter.py +++ b/moodboard/openrouter.py @@ -1471,9 +1471,10 @@ def _decimal_cost(value: Any, currency: Any = None) -> dict[str, Any]: Cost is post-hoc telemetry: a shape this function cannot certify degrades to the schema's unavailable state and must never reject the paid response carrying it. - ``not_reported`` states the provider sent no cost; ``reported_uncertifiable`` states it - sent one this adapter could not certify, so the receipt never inverts what the provider - did. The raw response bytes retain whatever was actually reported. + ``not_reported`` states no cost value was legibly reported; ``reported_uncertifiable`` + states a cost value was present and this adapter could not certify it, so the receipt + never inverts what the provider did in either direction. The raw response bytes retain + whatever was actually reported. """ if value is None: return _unavailable_cost("not_reported") @@ -1643,10 +1644,10 @@ def decode_openrouter_response( } ) usage = document.get("usage") - if usage is None: + if not isinstance(usage, dict): + # A non-object usage carries no legible cost, so no cost was reported in the + # contract's terms; claiming one was would invert the fact the other way. cost = _unavailable_cost("not_reported") - elif not isinstance(usage, dict): - cost = _unavailable_cost("reported_uncertifiable") else: cost = _decimal_cost(usage.get("cost"), usage.get("currency")) draft = { diff --git a/tests/test_openrouter_adapter.py b/tests/test_openrouter_adapter.py index f8e6bd7..1e02a93 100644 --- a/tests/test_openrouter_adapter.py +++ b/tests/test_openrouter_adapter.py @@ -432,7 +432,8 @@ def test_nonconforming_cost_telemetry_degrades_to_unavailable_without_stranding( ({"cost": 0.033, "currency": "USDC"}, "reported_uncertifiable"), ({"cost": "0.033", "currency": "USD"}, "reported_uncertifiable"), ({"cost": -0.033}, "reported_uncertifiable"), - ("not-a-telemetry-object", "reported_uncertifiable"), + ("not-a-telemetry-object", "not_reported"), + ([], "not_reported"), ({"note": "usage without a cost key"}, "not_reported"), ): body = json.dumps( diff --git a/tests/test_openrouter_real_e2e_confirmation.py b/tests/test_openrouter_real_e2e_confirmation.py index d727656..d6be194 100644 --- a/tests/test_openrouter_real_e2e_confirmation.py +++ b/tests/test_openrouter_real_e2e_confirmation.py @@ -1191,6 +1191,34 @@ def test_non_usd_cost_is_never_mislabeled_as_reported_usd(tmp_path: Path) -> Non assert real_e2e.provider_to_json(stored.receipt)["cost"]["currency"] == "EUR" +def test_uncertifiable_cost_reaches_the_summary_as_its_own_status(tmp_path: Path) -> None: + """A reported cost the adapter cannot certify must not read as absent telemetry.""" + challenge_dir = tmp_path / "uncertifiable-cost" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + + result = _execute( + challenge_dir, + context_path, + transport=lambda **_: _http_response(cost=Decimal("12.50"), currency="usd"), + ) + + assert result.states[-1] == "succeeded" + assert result.reported_cost_usd is None + assert result.cost_telemetry_status == "reported_uncertifiable" + report = _read_json(challenge_dir / "result.json") + assert report["reported_cost_usd"] is None + assert report["cost_telemetry_status"] == "reported_uncertifiable" + journal = AttemptJournal((challenge_dir / "attempts.sqlite3").resolve()) + stored = journal.read_provider_response(result.attempt_id) + assert real_e2e.provider_to_json(stored.receipt)["cost"] == { + "state": "unavailable", + "amount": None, + "currency": None, + "provenance": "reported_uncertifiable", + } + + def test_ambiguous_transport_consumes_challenge_and_can_never_retry(tmp_path: Path) -> None: challenge_dir = tmp_path / "ambiguous" _prepare(challenge_dir) From ed9288cc4a48b8ddea702af8a91ed8b166ca609f Mon Sep 17 00:00:00 2001 From: khive Date: Mon, 17 Aug 2026 14:23:09 -0400 Subject: [PATCH 5/5] fix: an abnormal execute exit still scans the private artifacts The generic exception handlers collapsed every unanticipated post-response failure to execution_failed without running the artifact secret scan the surrounding code declares as an every-exit invariant. The terminal scan now runs in both handlers and its verdict outranks the collapse; a clean scan preserves the generic code. Also: _parse_json threads its stable error code into _bounded_tree, and the acceptance map names the number-lexeme document-integrity bound. --- eval/README.md | 2 + eval/openrouter_real_e2e.py | 27 ++++++++++++-- .../test_openrouter_real_e2e_confirmation.py | 37 +++++++++++++++++++ 3 files changed, 63 insertions(+), 3 deletions(-) diff --git a/eval/README.md b/eval/README.md index 28f13ad..856665e 100644 --- a/eval/README.md +++ b/eval/README.md @@ -134,5 +134,7 @@ The executable acceptance map for this slice is: | Quote arithmetic is exact and `$0.05` is pre-dispatch only | ambient-Decimal and over-quote tests | | Missing post-paid cost telemetry does not strand valid media evidence | `test_missing_reported_cost_remains_terminal_success_after_paid_response` | | Non-conforming cost telemetry degrades to explicit unavailability, never rejection | `test_nonconforming_cost_telemetry_degrades_to_unavailable_without_stranding` | +| A cost lexeme past the structural budget rejects the document (integrity bound, not telemetry) | `test_cost_number_is_bounded_before_decimal_expansion` | | Credentials cannot survive public exceptions or local artifacts | real-E2E transport exception-graph tests | +| An unanticipated post-response failure still scans the private artifacts | `test_post_response_failure_still_scans_the_private_artifacts` | | Real board/retrieval identities are derived, never label hashes | `test_openrouter_real_e2e_authority.py` | diff --git a/eval/openrouter_real_e2e.py b/eval/openrouter_real_e2e.py index 7d0f66e..15febc1 100644 --- a/eval/openrouter_real_e2e.py +++ b/eval/openrouter_real_e2e.py @@ -344,7 +344,7 @@ def _parse_json(raw: bytes, *, code: str, max_bytes: int) -> JsonObject: raise except Exception: _fail(code) - _bounded_tree(value) + _bounded_tree(value, code=code) if not isinstance(value, dict): _fail(code) return value @@ -2299,9 +2299,9 @@ def one_shot_transport(*, body: bytes, bearer_token: str) -> OpenRouterHttpRespo # other failure still collapses to the generic code so no detail can carry a secret. if error.code in {"credential_material_persisted", "artifact_secret_scan_failed"}: return error.code, None - return "execution_failed", None + return _terminal_scan_status(target, token), None except BaseException: - return "execution_failed", None + return _terminal_scan_status(target, token), None finally: journal = None token = "" @@ -2606,6 +2606,27 @@ def _secret_variants(token: str) -> tuple[bytes, ...]: return tuple(sorted(values, key=lambda item: (len(item), item))) +def _terminal_scan_status(target: Path, token: str) -> str: + """Scan the private artifacts on an abnormal exit; the scan verdict outranks the collapse. + + The frozen invariant is that credentials cannot survive local artifacts on any path. The + ordinary exits scan explicitly before returning; this covers the exits that unwound through + the generic handlers, where the artifacts on disk are exactly the ones nothing re-checked. + """ + + if not isinstance(token, str) or not token: + return "execution_failed" + try: + _scan_private_artifacts(target, token) + except OpenRouterRealE2EError as error: + if error.code in {"credential_material_persisted", "artifact_secret_scan_failed"}: + return error.code + return "artifact_secret_scan_failed" + except BaseException: + return "artifact_secret_scan_failed" + return "execution_failed" + + def _scan_private_artifacts(output_dir: Path, token: str) -> None: variants = _secret_variants(token) try: diff --git a/tests/test_openrouter_real_e2e_confirmation.py b/tests/test_openrouter_real_e2e_confirmation.py index d6be194..28beae8 100644 --- a/tests/test_openrouter_real_e2e_confirmation.py +++ b/tests/test_openrouter_real_e2e_confirmation.py @@ -362,6 +362,43 @@ def planted_scan(output_dir: Path, token: str) -> None: _assert_error_code(raised, "credential_material_persisted") +def test_post_response_failure_still_scans_the_private_artifacts( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """An exception after the paid response is journaled must not skip the artifact scan.""" + challenge_dir = tmp_path / "post-response-scan" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + planted = challenge_dir / "planted.bin" + planted.write_bytes(_TOKEN.encode("utf-8")) + planted.chmod(0o600) + + def raising_verifier(*_args: Any, **_kwargs: Any) -> Any: + raise RuntimeError("verifier crashed after the paid response was journaled") + + monkeypatch.setattr(real_e2e, "verify_output_structure", raising_verifier) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute(challenge_dir, context_path) + _assert_error_code(raised, "credential_material_persisted") + + +def test_post_response_failure_without_a_leak_stays_the_generic_code( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """The terminal scan must not widen a clean abnormal exit past the generic collapse.""" + challenge_dir = tmp_path / "post-response-clean" + _prepare(challenge_dir) + context_path = _write_context(challenge_dir) + + def raising_verifier(*_args: Any, **_kwargs: Any) -> Any: + raise RuntimeError("verifier crashed after the paid response was journaled") + + monkeypatch.setattr(real_e2e, "verify_output_structure", raising_verifier) + with pytest.raises(real_e2e.OpenRouterRealE2EError) as raised: + _execute(challenge_dir, context_path) + _assert_error_code(raised, "execution_failed") + + def test_prepare_rejects_a_reference_missing_its_occurrence_id(tmp_path: Path) -> None: """A wrong-key reference fails at the stable boundary, not as a KeyError in packet build.""" document = json.loads(_AUTHORITY_BYTES.decode("utf-8"))