workflow_contracts.json

{
  "version": 1,
  "checks": {
    "no_large_tuple_results": {
      "description": "High-risk workflow helpers should use named result objects instead of positional tuples with more than two fields.",
      "allowlist": [
        {
          "path": "backend/utils/memory/legacy_backfill.py",
          "function": "_bucket_counts_and_samples",
          "reason": "Inventory helper; migrate when touching bucket reporting."
        },
        {
          "path": "backend/utils/memory/legacy_backfill.py",
          "function": "reconcile_backfill_counts",
          "reason": "Legacy contract from issue 8786; covered by backfill contract tests until migrated."
        },
        {
          "path": "backend/utils/memory/product_authorization.py",
          "function": "_lookup_app_key_grant",
          "reason": "Existing app-key grant lookup tuple; covered by memory authorization tests until the response contract is migrated."
        },
        {
          "path": "backend/utils/memory_ingestion/pipeline.py",
          "function": "_redact_input",
          "reason": "Existing pipeline stage contract; covered by memory ingestion contract tests until migrated."
        },
        {
          "path": "backend/utils/memory_ingestion/pipeline.py",
          "function": "_positive_secret_signals",
          "reason": "Existing redaction signal contract; covered by memory ingestion contract tests until migrated."
        },
        {
          "path": "backend/utils/memory_ingestion/pipeline.py",
          "function": "_compile_mutations",
          "reason": "Existing mutation compilation contract; covered by memory ingestion contract tests until migrated."
        },
        {
          "path": "backend/utils/memory/memory_service.py",
          "function": "read_scan_page",
          "reason": "Retired offset-scan stub (raises RuntimeError); retained only so accidental callers fail loudly. Annotated return type kept for the legacy call surface."
        }
      ]
    }
  },
  "workflows": [
    {
      "id": "task_candidate_resolution",
      "risk": "high",
      "sources": [
        "backend/database/candidates.py",
        "backend/utils/task_intelligence/candidate_service.py",
        "backend/utils/task_intelligence/staged_migration.py",
        "backend/routers/candidates.py"
      ],
      "tests": [
        "tests/unit/test_candidate_lifecycle.py",
        "tests/unit/test_staged_candidate_migration.py",
        "tests/unit/test_candidates_router.py"
      ],
      "checks": [],
      "invariants": [
        "candidate retries and concurrent acceptance create exactly one canonical task",
        "account generation mismatches fail closed without product mutation",
        "legacy terminal rows cannot reappear as pending candidates",
        "accepted-task integration dispatch is durably outboxed, leased once, and retryable after failure"
      ]
    },
    {
      "id": "goal_workstream_lifecycle",
      "risk": "high",
      "sources": [
        "backend/database/goals.py",
        "backend/database/workstreams.py",
        "backend/database/action_items.py",
        "backend/database/candidates.py",
        "backend/routers/goals.py",
        "backend/routers/workstreams.py",
        "backend/models/goal.py",
        "backend/models/workstream.py"
      ],
      "tests": [
        "tests/unit/test_workstream_core.py",
        "tests/unit/test_workstream_router_contract.py"
      ],
      "checks": [],
      "invariants": [
        "goal creation never implicitly changes another goal and focus overflow requires an explicit replacement",
        "workstream Candidate and explicit-intent retries create exactly one workstream and anchor linkage",
        "journal sequences and artifact versions are append-only and idempotent",
        "goal lifecycle disposition never cascade-deletes tasks, workstreams, artifacts, or evidence",
        "canonical writes are account-generation fenced and disabled in off or shadow mode",
        "task goal and workstream relationships are validated in the same transaction as task mutation",
        "task-goal migration receipts resume per-item outcomes and return stable reports"
      ]
    },
    {
      "id": "desktop_update_channel_promotion",
      "risk": "high",
      "sources": [
        "backend/database/desktop_update_channels.py",
        "backend/database/desktop_beta_breakglass.py",
        "backend/utils/beta_breakglass_evidence.py",
        "backend/utils/desktop_update_resolver.py",
        "backend/routers/updates.py",
        ".github/workflows/desktop_promote_beta.yml",
        ".github/workflows/desktop_rollback_beta.yml",
        ".github/workflows/desktop_breakglass_rollout_beta.yml",
        ".github/workflows/desktop_promote_prod.yml"
      ],
      "tests": [
        "tests/unit/test_desktop_update_channels.py",
        "tests/unit/test_desktop_update_resolver.py",
        "tests/unit/test_desktop_updates.py",
        "tests/unit/test_desktop_release_scripts.py"
      ],
      "checks": [],
      "invariants": [
        "stable never resolves or downloads a beta release",
        "appcast never exposes an untagged item when only beta resolves (#9528)",
        "validated pointer LKG precedes exact-channel legacy fallback",
        "immutable manifests are registered before atomic pointer promotion",
        "beta visibility requires exact-tag T2 qualification evidence"
      ]
    },
    {
      "id": "legacy_memory_backfill",
      "risk": "high",
      "sources": [
        "backend/utils/memory/legacy_backfill.py",
        "backend/utils/memory/legacy_backfill_support.py",
        "backend/utils/memory/legacy_backfill_inventory.py",
        "backend/scripts/backfill_legacy_memories.py"
      ],
      "tests": [
        "tests/unit/test_ws_c_backfill.py",
        "tests/unit/test_backfill_legacy_memories_cli.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "completed checkpoints recognize required-processing and quarantined pending-admission destinations without derived side effects",
        "partial checkpoints resume idempotently",
        "repair runs are explicitly UID-scoped, resumable, and dry-run by default",
        "inventory and structured summaries never return raw memory content",
        "legacy/domain timestamps are preserved while rows await required processing",
        "unreviewed bulk legacy rows remain hidden pending-admission candidates",
        "legacy rows never reach long-term, vector, keyword, or KG without processing admission"
      ]
    },
    {
      "id": "canonical_memory_fanout",
      "risk": "high",
      "sources": [
        "backend/utils/memory/canonical_memory_adapter.py"
      ],
      "tests": [
        "tests/unit/test_ws_j_delete_privacy.py",
        "tests/unit/test_canonical_kg_promotion.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "domain writes use injected stores",
        "derived keyword/vector/KG fanout is either durable or explicitly recoverable"
      ]
    },
    {
      "id": "canonical_memory_admission",
      "risk": "high",
      "sources": [
        "backend/models/memory_admission.py",
        "backend/models/memory_apply.py",
        "backend/utils/memory/canonical_required_processing.py",
        "backend/utils/memory/required_promotion.py",
        "backend/utils/memory/short_term_promotion.py",
        "backend/utils/memory/canonical_memory_adapter.py"
      ],
      "tests": [
        "tests/unit/test_ws_b_short_term_lifecycle.py",
        "tests/unit/test_memory_read_api.py",
        "tests/unit/test_developer_memory_adapter.py",
        "tests/unit/test_mcp_memory_adapter.py",
        "tests/unit/test_ws_m_atom_keyword_index.py",
        "tests/unit/test_ws_n_graph_traversal.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "explicit submissions remain pending short-term until a content-bound processing receipt exists",
        "pending text is visible only to the first-party memory list and never to agent, developer, MCP, search, vector, or KG reads",
        "processing, review, and promotion use revision/content CAS and rebase after unrelated head advances",
        "negative user review remains authoritative across all derived projection rebuilds"
      ]
    },
    {
      "id": "firestore_schema_readiness",
      "risk": "high",
      "sources": [
        "backend/database/firestore_index_registry.py",
        "backend/scripts/firestore_workflow_policy.py",
        "backend/scripts/reconcile_firestore_indexes.py",
        "config/deployment-setting-classification.json",
        "firestore.indexes.json",
        ".github/actions/release-eligibility/action.yml",
        ".github/workflows/gcp_backend.yml",
        ".github/workflows/gcp_backend_auto_dev.yml",
        ".github/workflows/gcp_firestore_indexes.yml",
        ".github/workflows/release-eligibility.yml",
        ".github/scripts/verify_release_eligibility.py",
        ".github/scripts/verify_backend_release_admission.py",
        ".github/scripts/verify_auto_backend_release_admission.py",
        ".github/scripts/check_backend_deploy_source_admission.py"
      ],
      "tests": [
        "tests/unit/test_reconcile_firestore_indexes.py",
        "tests/unit/test_backend_runtime_env_validator.py",
        "tests/unit/test_verify_backend_release_vector.py"
      ],
      "checks": [],
      "invariants": [
        "backend deploy workflows only perform read-only readiness checks against the serving Firestore project",
        "Firestore schema writes use only the manual main-scoped migration workflow and serialize with backend deployment readiness",
        "automatic dev and manual backend deploys use only exact main SHAs with a successful Release Eligibility proof; traffic-only repair is source-independent",
        "manual deploys cannot change the Firestore manifest, execute source-owned schema control code before admission, or move after the admitted SHA",
        "failed readiness gates upload only a locally revalidated create-only proposal bound to the source commit, target, manifest hash, and short TTL"
      ]
    },
    {
      "id": "sync_cloud_tasks",
      "risk": "high",
      "sources": [
        "backend/routers/sync.py",
        "backend/utils/sync/pipeline.py",
        "backend/database/sync_jobs.py",
        "backend/utils/sync/*.py",
        "backend/testing/sync_cloud_tasks_stack/**",
        ".github/workflows/backend-hermetic-e2e.yml",
        "package.json",
        "package-lock.json"
      ],
      "tests": [
        "tests/unit/test_sync_v2.py",
        "tests/unit/test_sync_cloud_tasks.py",
        "tests/unit/test_audio_merge_tasks.py",
        "tests/unit/test_sync_fair_use_gate.py",
        "tests/unit/test_sync_cloud_tasks_stack_ci_wiring.py"
      ],
      "checks": [],
      "invariants": [
        "task retries do not double-count usage or completed segments",
        "segment failures cannot be reported as completed work",
        "enqueued jobs retain staged blobs until handler completion",
        "fresh v2 Sync admission runs a credential-free local Firestore, Redis, storage, and separate Cloud Tasks-worker stack gauntlet in blocking PR CI"
      ]
    },
    {
      "id": "sync_ledger_fence_cutover",
      "risk": "high",
      "sources": [
        "backend/scripts/sync_ledger_fence_cutover.py",
        ".github/workflows/sync_ledger_fence_cutover.yml"
      ],
      "tests": [
        "tests/unit/test_sync_ledger_fence_cutover.py"
      ],
      "checks": [],
      "invariants": [
        "standby admission traffic reaches every sync surface before Cloud Tasks queues are paused",
        "the exact immutable candidate digest is proven through the tagged full transcription route before active traffic promotion",
        "failed stage or activation attempts preserve the first queue-origin artifact and leave queues paused"
      ]
    },
    {
      "id": "vector_repair_outbox",
      "risk": "high",
      "sources": [
        "backend/database/memory_vector_repair_outbox.py",
        "backend/database/memory_vector_repair_outbox_worker.py",
        "backend/scripts/vector_repair_outbox_worker_entrypoint.py"
      ],
      "tests": [
        "tests/unit/test_vector_repair_outbox_worker.py",
        "tests/unit/test_vector_repair_outbox_infra.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "leased work is recoverable after worker death",
        "completed and dead-lettered work is never reclaimed"
      ]
    },
    {
      "id": "account_deletion_wipe",
      "risk": "high",
      "sources": [
        "backend/database/users.py",
        "backend/services/users/account_deletion.py",
        "backend/routers/users.py",
        "backend/utils/cloud_tasks.py",
        "backend/main.py",
        "backend/deploy/runtime_env.yaml",
        "backend/scripts/validate-backend-runtime-env.py",
        ".github/workflows/gcp_backend.yml"
      ],
      "tests": [
        "tests/services/users/test_account_deletion.py",
        "tests/routers/test_users.py",
        "tests/unit/test_sync_cloud_tasks.py",
        "tests/unit/test_backend_runtime_env_validator.py",
        "tests/unit/test_claim_deletion_wipe_txn.py",
        "tests/unit/test_delete_account_purge_storage.py",
        "testing/e2e/test_account_deletion_cloud_tasks.py"
      ],
      "checks": [],
      "invariants": [
        "irreversible auth deletion has a durable recovery marker",
        "required derived-data purge failures cannot be marked completed",
        "production deletion requests can only dispatch through a complete Cloud Tasks configuration",
        "an account-deletion task identifies exactly one persisted wipe job and never exposes a user ID"
      ]
    },
    {
      "id": "projection_repair",
      "risk": "high",
      "sources": [
        "backend/database/projection_repair.py"
      ],
      "tests": [
        "tests/unit/test_memory_ledger.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "repair enqueue is idempotent",
        "repair processing uses injected stores and has retry/dead-letter accounting"
      ]
    },
    {
      "id": "short_term_lifecycle",
      "risk": "high",
      "sources": [
        "backend/database/memory_apply_store.py",
        "backend/database/memory_outbox_worker.py",
        "backend/models/memory_apply.py",
        "backend/models/memory_promotion.py",
        "backend/utils/memory/canonical_consolidation.py",
        "backend/jobs/short_term_lifecycle_worker.py",
        "backend/utils/memory/short_term_promotion.py",
        "backend/utils/memory/canonical_short_term_maintenance_cron.py"
      ],
      "tests": [
        "tests/unit/test_atomic_apply.py",
        "tests/unit/test_canonical_consolidation.py",
        "tests/unit/test_canonical_consolidation_apply.py",
        "tests/unit/test_short_term_lifecycle_firestore_store.py",
        "tests/unit/test_ws_b_short_term_lifecycle.py",
        "tests/unit/test_canonical_short_term_maintenance_cron.py",
        "tests/unit/test_memory_outbox_worker.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "every eligible short-term item receives exactly one terminal L2 route",
        "long-term admission and its graph assertion commit atomically against one exact short-term revision",
        "maintenance reruns are idempotent and never invoke a generic promotion pass",
        "projection delivery is leased, generation and revision fenced, retryable, and dead-letter bounded"
      ]
    },
    {
      "id": "webhook_delivery_health",
      "risk": "high",
      "sources": [
        "backend/utils/webhooks.py",
        "backend/database/webhook_health.py"
      ],
      "tests": [
        "tests/unit/test_async_webhooks.py",
        "tests/unit/test_webhook_auto_disable.py"
      ],
      "checks": [],
      "invariants": [
        "delivery failures are counted durably",
        "auto-disable state is endpoint-aware and race-safe"
      ]
    },
    {
      "id": "memory_ingestion_export_runner",
      "risk": "high",
      "sources": [
        "backend/utils/memory_ingestion/export_runner.py",
        "backend/utils/memory_ingestion/pipeline.py"
      ],
      "tests": [
        "tests/unit/test_memory_ingestion_pipeline.py",
        "tests/unit/test_production_like_memory_model.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "resume config mismatches fail closed",
        "failed shards remain visible in run summaries"
      ]
    },
    {
      "id": "listen_ws_session",
      "risk": "high",
      "sources": [
        "backend/utils/listen_session_bootstrap.py",
        "backend/routers/transcribe.py",
        "backend/utils/stt/live_failure.py",
        "backend/utils/transcribe_decisions.py"
      ],
      "tests": [
        "tests/unit/test_listen_session_bootstrap.py",
        "tests/unit/test_live_stt_failure.py",
        "tests/unit/test_transcribe_decisions.py",
        "tests/unit/test_listen_pipeline.py",
        "tests/unit/utils/test_listen_pusher_session.py",
        "testing/e2e/test_listen_stt.py"
      ],
      "checks": [],
      "invariants": [
        "connect-time Firestore reads run off the event loop",
        "translation and vocabulary decisions stay pinned by characterization tests"
      ]
    },
    {
      "id": "canonical_memory_pipeline",
      "risk": "high",
      "sources": [
        "backend/utils/memory/**",
        "backend/utils/memory_ingestion/**"
      ],
      "tests": [
        "testing/e2e/test_canonical_memory_pipeline.py"
      ],
      "checks": [
        "no_large_tuple_results"
      ],
      "invariants": [
        "capture\u2192consolidate\u2192promote\u2192read with archive excluded from default reads",
        "canonical fail-closed without legacy bleed"
      ]
    },
    {
      "id": "conversation_lifecycle",
      "risk": "high",
      "sources": [
        "backend/database/conversations.py",
        "backend/database/conversation_finalization_jobs.py",
        "backend/database/recording_sessions.py",
        "backend/services/conversation_finalization.py",
        "backend/utils/conversations/finalization_decision.py",
        "backend/utils/conversations/lifecycle.py",
        "backend/utils/conversations/finalizer.py",
        "backend/utils/conversations/meeting_receipt.py",
        "backend/routers/transcribe.py",
        "backend/routers/conversation_finalization.py",
        "backend/routers/pusher.py",
        "backend/routers/conversations.py",
        "backend/routers/sync.py",
        "backend/routers/developer.py",
        "backend/utils/sync/pipeline.py",
        "backend/utils/conversations/process_conversation.py",
        "backend/utils/app_integrations.py",
        "backend/utils/conversations/merge_conversations.py",
        "backend/utils/imports/limitless.py"
      ],
      "tests": [
        "tests/unit/test_conversation_lifecycle_contract.py",
        "tests/unit/test_finalization_decision.py",
        "tests/unit/test_check_conversation_lifecycle_writes.py",
        "tests/unit/test_conversation_finalization_jobs.py",
        "tests/unit/test_developer_from_segments_idempotency.py",
        "tests/unit/test_recording_sessions.py",
        "tests/unit/test_listen_finalization_cloud_tasks.py",
        "tests/services/test_conversation_finalization.py"
      ],
      "checks": [
        "conversation-lifecycle-write-guard"
      ],
      "invariants": [
        "only one finalizer claim succeeds for an in-progress conversation",
        "finalization outbox reconnects reuse one durable job and lease fences stale workers before any fanout",
        "meeting treatment has one durable job-backed verdict and missing Chat intents are reconciled idempotently",
        "only utils.conversations.lifecycle may invoke lifecycle persistence primitives",
        "a recording session binds exactly one user-scoped conversation and emits only monotonic lifecycle envelopes",
        "merge rejects sources that are still processing",
        "discard and generic status-write escape hatches remain characterized until the lifecycle service replaces them"
      ]
    },
    {
      "id": "listen_pusher_pipeline",
      "risk": "high",
      "sources": [
        "backend/routers/transcribe.py",
        "backend/routers/listen/**",
        "backend/routers/pusher.py",
        "backend/utils/listen_pusher_session.py",
        "backend/utils/pusher.py",
        "backend/utils/stt/live_failure.py",
        "backend/utils/stt/streaming.py",
        "backend/config/stt_provider_policy.py",
        "backend/charts/parakeet/**",
        "backend/utils/transcribe_decisions.py",
        "backend/pusher/main.py",
        "backend/utils/conversations/finalizer.py",
        "backend/utils/observability/finalization.py",
        "backend/utils/conversations/lifecycle.py",
        "backend/testing/listen_pusher_stack/**",
        ".github/workflows/backend-hermetic-e2e.yml",
        "package.json",
        "package-lock.json"
      ],
      "tests": [
        "tests/unit/test_listen_pipeline.py",
        "tests/unit/test_pusher_heartbeat.py",
        "tests/unit/test_pusher_conversation_retry.py",
        "tests/unit/test_pusher_static_capability_admission.py",
        "tests/unit/test_conversation_finalizer_failure_logging.py",
        "tests/unit/test_finalization_failure_observability.py",
        "tests/unit/test_live_stt_failure.py",
        "tests/unit/test_listen_runtime_regressions.py",
        "tests/unit/test_transcribe_decisions.py",
        "tests/unit/test_stt_provider_policy.py",
        "tests/unit/test_streaming_deepgram_backoff.py",
        "tests/unit/utils/test_listen_pusher_session.py",
        "tests/unit/test_transcribe_teardown_flush.py",
        "tests/unit/test_listen_pusher_stack_ci_wiring.py",
        "testing/e2e/test_listen_stt.py",
        "testing/e2e/test_listen_pusher_wire_contract.py"
      ],
      "checks": [],
      "invariants": [
        "teardown flushes tail audio before pusher close",
        "pending conversation requests retry until ack or give-up limit",
        "pusher heartbeat prevents idle connection drops",
        "a client Parakeet preference cannot route a live session to an incompatible model",
        "listen-to-pusher boundary changes run the credential-free local Firestore, Redis, and Parakeet-stub stack gauntlet in PR CI"
      ]
    },
    {
      "id": "desktop_backend_realtime_provider_proof",
      "risk": "high",
      "sources": [
        ".github/workflows/desktop_backend_auto_dev.yml",
        "backend/scripts/firebase_release_probe_token.py",
        "scripts/voice-provider-probe.sh"
      ],
      "tests": [
        "tests/unit/test_firebase_release_probe_token.py",
        "tests/unit/test_voice_provider_probe.py"
      ],
      "checks": [],
      "invariants": [
        "every deployed development desktop backend proves the managed OpenAI and Gemini mint-to-response paths",
        "the Firebase ID token audience and issuer match the deployed backend's explicit Firebase auth project",
        "the bypass is explicit in the workflow log and is limited to an operator-declared upstream outage",
        "probe credentials and provider responses never appear in workflow output"
      ]
    },
    {
      "id": "backend_cloud_run_deploy",
      "risk": "high",
      "sources": [
        ".github/actions/deploy-backend-stack/**",
        ".github/actions/transcription-release-candidate-probe/**",
        ".github/workflows/gcp_backend*.yml",
        ".github/workflows/gcp_llm_gateway.yml",
        ".github/workflows/gcp_memory_maintenance_job.yml",
        ".github/workflows/gcp_memory_maintenance_job_auto_dev.yml",
        ".github/workflows/gcp_notifications_job.yml",
        ".github/workflows/sync_ledger_fence_cutover.yml",
        "backend/deploy/runtime_env.yaml",
        "backend/scripts/preflight-cloud-run-deploy.py",
        "backend/scripts/resolve_cloud_run_tagged_url.py",
        "backend/scripts/sync_ledger_fence_cutover.py",
        "backend/scripts/verify_backend_release_vector.py",
        "backend/scripts/verify_sync_ledger_fence_transition.py",
        "backend/scripts/verify-llm-gateway-serving.py",
        "backend/scripts/probe-llm-gateway-from-cloud-run.sh",
        "backend/scripts/render_backend_runtime_env.py",
        "backend/scripts/repair_cloud_run_traffic.py",
        "backend/scripts/cloud_run_traffic_snapshot.py",
        "backend/scripts/firebase_release_probe_token.py",
        "backend/scripts/transcription_capability_probe.py",
        "backend/scripts/pre-deploy-check.sh",
        "backend/scripts/validate_memory_maintenance_scheduler.py",
        "backend/scripts/validate-backend-runtime-env.py"
      ],
      "tests": [
        "tests/unit/test_render_backend_runtime_env.py",
        "tests/unit/test_preflight_cloud_run_deploy.py",
        "tests/unit/test_verify_backend_release_vector.py",
        "tests/unit/test_resolve_cloud_run_tagged_url.py",
        "tests/unit/test_repair_cloud_run_traffic.py",
        "tests/unit/test_cloud_run_traffic_snapshot.py",
        "tests/unit/test_deploy_status_report.py",
        "tests/unit/test_backend_runtime_env_validator.py",
        "tests/unit/test_verify_llm_gateway_serving.py",
        "tests/unit/test_llm_gateway_deploy_contract.py",
        "tests/unit/test_sync_two_lane.py",
        "tests/unit/test_firebase_release_probe_token.py",
        "tests/unit/test_transcription_capability_probe.py",
        "tests/unit/test_validate_memory_maintenance_scheduler.py",
        "tests/unit/test_verify_sync_ledger_fence_transition.py"
      ],
      "checks": [],
      "invariants": [
        "preflight fails before revision creation when Secret Manager bindings are missing",
        "traffic shifts only after candidate revisions are Ready=True",
        "all four Cloud Run traffic specs are durably captured before promotion and restored automatically after a failed shift, serving-vector check, or production serving smoke",
        "GKE runtime config, backend secrets, and backend-listen mutate only after the no-traffic Cloud Run candidate is accepted",
        "spec.traffic mismatches are repaired or block deploy with an explicit command",
        "normal deploys cannot change the serving sync ledger fence mode",
        "production backend traffic shifts only after the Cloud Run-only candidate vector passes, then rolls back if the post-promotion serving route or known-audio smoke fails",
        "memory-maintenance job deploys fail unless the exact enabled hourly OAuth Scheduler trigger targets that deployed job",
        "gateway-first serving cannot be promoted until the ready workload, EndpointSlice, ingress/ILB attachment, and authenticated Cloud Run VPC route all pass"
      ]
    },
    {
      "id": "pusher_rollout_readiness",
      "risk": "high",
      "sources": [
        "backend/charts/pusher/**",
        ".github/workflows/gcp_backend_pusher.yml",
        ".github/workflows/gcp_backend_pusher_auto_deploy.yml",
        "backend/scripts/verify_pusher_rollout_budget.py",
        "backend/scripts/verify_pusher_live_deployment_gate.py",
        "backend/scripts/verify_pusher_promotion_evidence.py",
        "backend/scripts/pusher_release_receipt.py",
        "backend/scripts/pusher_semantic_probe.py",
        "backend/scripts/pusher_prod_canary.py",
        "backend/scripts/verify_pusher_live_alert_route.py",
        "backend/scripts/runtime_env_capability_contracts.py",
        "backend/testing/release_fixtures/transcription-release-probe.json",
        "backend/testing/release_fixtures/transcription-release-probe.wav",
        "backend/scripts/verify_pusher_dev_observability.py",
        "backend/scripts/verify_pusher_source_closure.py",
        "backend/scripts/verify_pusher_cohost_env_diff.py"
      ],
      "tests": [
        "tests/unit/test_verify_pusher_rollout_budget.py",
        "tests/unit/test_verify_pusher_live_deployment_gate.py",
        "tests/unit/test_verify_pusher_promotion_evidence.py",
        "tests/unit/test_verify_pusher_dev_observability.py",
        "tests/unit/test_pusher_deployment_control_workflow.py",
        "tests/unit/test_pusher_auto_deploy_paths.py",
        "tests/unit/test_pusher_semantic_probe.py",
        "tests/unit/test_verify_pusher_live_alert_route.py",
        "tests/unit/test_backend_runtime_env_validator.py",
        "tests/unit/test_pusher_static_capability_admission.py",
        "tests/unit/test_verify_pusher_cohost_env_diff.py",
        "tests/unit/test_conversation_notes_v2_beta_rollout.py"
      ],
      "checks": [],
      "invariants": [
        "Pusher's Kubernetes progress deadline and CI rollout wait both cover every configured healthy-availability wave at the committed HPA ceiling",
        "a chart change to Pusher startup/readiness/min-ready, HPA, or RollingUpdate inputs cannot silently make a healthy rollout appear failed",
        "production Pusher deploys only an exact digest attested by a successful automatic development rollout and never rebuilds that production artifact",
        "production Pusher promotion fails before any registry, config, or Helm mutation unless the exact source, image, rendered chart, live config, and live development deployment receipt agree",
        "development qualification exercises the deployed public listen route with the isolated Firebase release-probe principal and versioned real-audio fixture, then requires durable terminal finalization plus authenticated conversation read-back",
        "semantic-probe and separately protected attributable-canary outcomes must be explicit identity-bound PASS receipts with closed windows and samples; missing, NOT_RUN, failed, or contradictory evidence halts promotion",
        "post-rollout success is an exact live deployment and pod identity receipt, never the GitHub workflow conclusion",
        "the exact proposed production ConfigMap is isolated for the canary and its semantic hash must equal the final shared ConfigMap receipt",
        "publishing and promotion fail closed unless the committed finalization alert is live, unpaused, queryable through a healthy Prometheus datasource, and routed to the Telegram contact point",
        "rollback remains absent until a complete image, config, schema, and protocol compatibility receipt exists; the workflow never blindly rolls back to the prior revision",
        "the live deployment gate rejects missing matching-node surge capacity before Helm can mutate the release",
        "the prod freshness check compares the full Dockerfile COPY source closure so a post-qualification change to any shared backend module cannot ship a stale digest",
        "the live capacity gate has a confirm-and-reason break-glass hatch that records a tracking issue, matching the repo's gated-surface contract",
        "pusher and backend-listen explicit env key sets cannot gain an unexplained divergence; required process_conversation rollout flags must resolve identically"
      ]
    },
    {
      "id": "rendered_gke_deployment_identity",
      "risk": "high",
      "sources": [
        "backend/charts/backend-listen/**",
        "backend/charts/pusher/**",
        "backend/charts/llm-gateway/**",
        "backend/charts/diarizer/**",
        "backend/charts/parakeet/**",
        "backend/charts/nllb-translation/**",
        "backend/charts/vad/**",
        "backend/scripts/validate_rendered_deployment_contract.py"
      ],
      "tests": [
        "tests/unit/test_rendered_deployment_contract.py"
      ],
      "checks": [],
      "invariants": [
        "every first-party GKE workload renders an explicit immutable image identity",
        "rendered Deployments keep their environment-specific service account, secret references, port, and health probes",
        "chart defaults cannot fall back to an application-version or latest image tag"
      ]
    },
    {
      "id": "cloud_run_metrics_egress_deploy",
      "risk": "high",
      "sources": [
        ".github/workflows/gcp_cloud_run_metrics_egress.yml",
        "backend/charts/monitoring/prometheus-stackdriver-exporter/*_omi_cloud_run_metrics_exporter.yaml",
        "backend/charts/monitoring/kube-prometheus-stack/*_omi_monitoring_values.yaml"
      ],
      "tests": [
        "tests/unit/test_cloud_run_metrics_egress_workflow.py"
      ],
      "checks": [],
      "invariants": [
        "reviewed Cloud Run application exporter values are automatically installed in development after merge",
        "production metrics egress deploys only through an explicit protected-environment dispatch from main",
        "the isolated exporter and its Prometheus scrape configuration use pinned charts and atomic Helm upgrades"
      ]
    },
    {
      "id": "jit_qa_vertex_gateway",
      "risk": "high",
      "sources": [
        "scripts/dev-harness/dev_harness/jit_vertex_gateway.py"
      ],
      "tests": [
        "tests/unit/test_jit_qa_vertex_gateway.py"
      ],
      "checks": [],
      "invariants": [
        "only the local backend service identity can call the development Vertex broker",
        "BYOK headers, tool calls, multimodal content, oversized requests, and excess concurrency fail closed",
        "output tokens and response bytes remain bounded for streaming and non-streaming responses",
        "the broker accepts only development ADC with the development quota project"
      ]
    },
    {
      "id": "ci_changed_path_selection",
      "risk": "high",
      "sources": [
        ".gitignore",
        ".github/actions/detect-changes/**",
        ".github/workflows/backend-checks.yml",
        ".github/workflows/backend-unit-tests.yml",
        ".github/workflows/desktop-checks.yml",
        ".github/workflows/desktop-swift-ci.yml",
        ".github/workflows/repo-checks.yml",
        "scripts/changed-files",
        "scripts/install-git-hooks.sh",
        "scripts/pre-push",
        "scripts/pre-push-singleflight"
      ],
      "tests": [
        "tests/unit/test_changed_files_script.py",
        "tests/unit/test_workflow_contracts.py"
      ],
      "checks": [],
      "invariants": [
        "deletions and both sides of renames select the checks owned by the old and new paths",
        "unmapped backend production paths cannot be hidden by adding one direct test",
        "desktop-only pushes do not require a backend virtual environment"
      ]
    }
  ]
}