feat: add free-first model fallback policy

.github/workflows/model-fallback-policy-verify.yml

@@ -0,0 +1,80 @@
+name: Model fallback policy quality
+
+on:
+  pull_request:
+    paths:
+      - contextual_orchestrator/_fallback_*.py
+      - contextual_orchestrator/model_fallback.py
+      - tests/fallback_test_support.py
+      - tests/test_model_fallback_*.py
+      - docs/model-fallback-policy.md
+      - docs/doctoring/free-first-model-fallback.md
+      - .github/workflows/model-fallback-policy-verify.yml
+  push:
+    paths:
+      - contextual_orchestrator/_fallback_*.py
+      - contextual_orchestrator/model_fallback.py
+      - tests/fallback_test_support.py
+      - tests/test_model_fallback_*.py
+      - docs/model-fallback-policy.md
+      - docs/doctoring/free-first-model-fallback.md
+      - .github/workflows/model-fallback-policy-verify.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: model-fallback-policy-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Fallback statement, branch, docstring, and secret-boundary evidence
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - name: Harden the runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout exact source revision without credentials
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install hash-locked verification dependencies
+        run: |
+          python -m pip install --require-hashes -r fuzz/requirements-property.txt
+          python -m pip install --require-hashes -r requirements-opencode-review-ci.txt
+
+      - name: Run fallback behavior and quality gates
+        run: |
+          set -euo pipefail
+          python -m compileall -q contextual_orchestrator tests
+          python -m pytest -q \
+            tests/test_model_fallback_cli.py \
+            tests/test_model_fallback_manifest.py \
+            tests/test_model_fallback_plan.py
+          python -m coverage erase
+          python -m coverage run --branch --source=contextual_orchestrator -m pytest -q \
+            tests/test_model_fallback_cli.py \
+            tests/test_model_fallback_manifest.py \
+            tests/test_model_fallback_plan.py
+          python -m coverage report \
+            --include='contextual_orchestrator/_fallback_*.py,contextual_orchestrator/model_fallback.py' \
+            --show-missing \
+            --fail-under=100
+          python -m interrogate -f 100 \
+            contextual_orchestrator/_fallback_cli.py \
+            contextual_orchestrator/_fallback_manifest.py \
+            contextual_orchestrator/_fallback_plan.py \
+            contextual_orchestrator/_fallback_types.py \
+            contextual_orchestrator/model_fallback.py
+          git diff --check

CHANGELOG.md

@@ -6,6 +6,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+### Added
+
+- Add a transport-neutral, versioned model fallback policy that validates explicit cost tiers and deterministically exhausts eligible free candidates before any paid fallback.
+- Filter fallback candidates by repository visibility, required capability, and configured credential name without retaining or serializing secret values.
+- Add a standard-library CLI for immutable cross-repository workflow integration, with complete statement, branch, and public-docstring coverage for the fallback policy.
+
 ### Security
 
 - Restrict the private plain-HTTP provider seam to `localhost` or literal loopback IP addresses, reject URL userinfo before connection, dial directly without ambient proxy lookup, reject all redirect responses, and close failed resources deterministically.
@@ -19,6 +25,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - Reject malformed UTF-8/JSON, duplicate object names, Python non-finite-number extensions, finite-syntax exponents that overflow Python floats to non-finite values, and non-object top-level values in validated structured provider responses before application parsing; canonicalize valid JSON and strict Batch JSON Lines so later decoder failures cannot retain the original provider document.
 - Integrate DNS-pinned provider dispatch directly into `ModelClient` so package import performs no optional-adapter monkey-patching or order-dependent class mutation.
 - Reject provider hosts that resolve to any non-globally-routable address, including RFC 6598 shared address space, while retaining explicit multicast, private, loopback, link-local, and reserved-address protections.
+- Remove fallback-policy environment-value inspection; trusted callers now declare only validated available credential names, and the policy CLI rejects the former secret-bearing environment selector.
+- Reject boolean or floating-point schema versions, unsafe programmatic agent selectors, non-string candidate identifiers, and mutable credential-control collections as controlled validation errors instead of leaking Python type exceptions or permitting post-validation policy changes.
 - Document narrowly scoped Semgrep suppressions for parameter-bound database queries, the explicit development-only TLS verification opt-out, and provider URLs that pass the egress guard.
 
 ### Changed

contextual_orchestrator/__init__.py

@@ -41,6 +41,18 @@
 from .cost_router import CostRoutingCoordinator
 from .credentials import NotConfigured, get_credential, register_credential
 from .kv_config import InMemoryConfigStore, get_config_store
+from .model_fallback import (
+    CandidateValidationError,
+    CostTier,
+    FallbackCandidate,
+    FallbackContext,
+    FallbackManifestError,
+    FallbackPlan,
+    NoEligibleCandidateError,
+    SkippedCandidate,
+    build_fallback_plan,
+    load_fallback_manifest,
+)
 from .orchestrator import ModelAgent, TaskOrchestrator, WorkflowStep, load_agents
 from .token_counting import HeuristicTokenCounter, build_token_counter
 
@@ -91,4 +103,15 @@
     "build_embeddings_jsonl_body",
     "cheapest_upstream",
     "CostRoutingCoordinator",
+    # transport-neutral model fallback policy
+    "CandidateValidationError",
+    "CostTier",
+    "FallbackCandidate",
+    "FallbackContext",
+    "FallbackManifestError",
+    "FallbackPlan",
+    "NoEligibleCandidateError",
+    "SkippedCandidate",
+    "build_fallback_plan",
+    "load_fallback_manifest",
 ]

contextual_orchestrator/_fallback_cli.py

@@ -0,0 +1,103 @@
+"""Command-line adapter for the transport-neutral fallback policy."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from ._fallback_manifest import load_fallback_manifest
+from ._fallback_plan import build_fallback_plan
+from ._fallback_types import (
+    ALLOWED_VISIBILITIES,
+    FallbackContext,
+    FallbackManifestError,
+    validate_credentials,
+)
+
+
+def _load_manifest_path(path: Path) -> Mapping[str, Any]:
+    """Read a UTF-8 JSON manifest and normalize input errors."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise FallbackManifestError(
+            f"manifest could not be read: {path}"
+        ) from exc
+    try:
+        document = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise FallbackManifestError(
+            "manifest must contain valid JSON"
+        ) from exc
+    if not isinstance(document, Mapping):
+        raise FallbackManifestError("manifest must be an object")
+    return document
+
+
+def _declared_credentials(names: Sequence[str]) -> frozenset[str]:
+    """Validate and return credential names declared available by the caller."""
+    normalized = tuple(names)
+    validate_credentials(normalized)
+    return frozenset(normalized)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the parser for policy-only workflow integration."""
+    parser = argparse.ArgumentParser(prog="contextual-model-fallback")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    plan_parser = subparsers.add_parser("plan")
+    plan_parser.add_argument("--manifest", type=Path, required=True)
+    plan_parser.add_argument("--agent", required=True)
+    plan_parser.add_argument(
+        "--repository-visibility",
+        choices=sorted(ALLOWED_VISIBILITIES),
+        default="public",
+    )
+    plan_parser.add_argument(
+        "--available-credential", action="append", default=[]
+    )
+    plan_parser.add_argument(
+        "--required-capability", action="append", default=[]
+    )
+    plan_parser.add_argument("--deny-paid", action="store_true")
+    plan_parser.add_argument(
+        "--format",
+        choices=("json", "ids", "models"),
+        default="json",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Render one validated plan and return an exit code."""
+    args = _build_parser().parse_args(argv)
+    if args.command != "plan":  # pragma: no cover - argparse constrains it.
+        raise FallbackManifestError(
+            f"unsupported command: {args.command}"
+        )
+    document = _load_manifest_path(args.manifest)
+    candidates = load_fallback_manifest(document, args.agent)
+    context = FallbackContext(
+        repository_visibility=args.repository_visibility,
+        available_credentials=_declared_credentials(
+            args.available_credential
+        ),
+        required_capabilities=frozenset(args.required_capability),
+        allow_paid=not args.deny_paid,
+    )
+    plan = build_fallback_plan(candidates, context=context)
+    if args.format == "json":
+        print(
+            json.dumps(
+                plan.to_public_dict(),
+                sort_keys=True,
+                separators=(",", ":"),
+            )
+        )
+    elif args.format == "ids":
+        print(" ".join(plan.candidate_ids))
+    else:
+        print(" ".join(candidate.model for candidate in plan.candidates))
+    return 0