error_codes.yaml

# OKG substrate error-code registry.
#
# Every failure the substrate emits on stderr (with --json) or as a
# Python exception must have an entry here. This file is the
# authoritative list; if a code appears in a runbook, contract, or
# agent spec and is not here, that reference is a bug.
#
# Fields:
#   code:               stable string emitted in JSON error payloads
#   python_exception:   class name if the code maps to a Python exception
#   severity:           fatal | recoverable | user
#   raised_by:          command(s) and/or substrate phases that raise this
#   referenced_in:      docs that normatively mention this code
#   fix_hint_template:  string template (positional {0}, {1}, ...)
#                       that okg CLI may substitute into the fix_hint
#                       field of the JSON error. `null` = no hint.
#   data_shape:         required keys in the error's `data` field
#
# Documentation and Python contract checks keep emitted codes and their
# consumer references aligned with this registry.

version: 1

codes:

  - code: agent_connect_ephemeral_okg
    python_exception: null
    severity: user
    raised_by:
      - okg agent connect
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "install okg as a lasting tool first (`uv tool install <okg wheel or source>` or `pipx install <okg wheel or source>`), then re-run this command with that install's `okg`"
    data_shape: [interpreter, cache_root]

  - code: agent_connect_writes_need_role_passwords
    python_exception: null
    severity: user
    raised_by:
      - okg agent connect --writes
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "run `okg db role-passwords --apply --deployment {0}`, then re-run this command with --writes"
    data_shape: [deployment, roles]

  - code: agent_connect_server_failed
    python_exception: null
    severity: user
    raised_by:
      - okg agent connect
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "run `okg mcp-serve --deployment <name>` by hand and fix the error it prints"
    data_shape: [deployment, agent, stderr_tail, tools]

  - code: agent_connect_server_timeout
    python_exception: null
    severity: recoverable
    raised_by:
      - okg agent connect
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "re-run with a larger --probe-timeout, or run `okg mcp-serve --deployment <name>` by hand to see why it is slow"
    data_shape: [deployment, agent, stderr_tail, tools]

  - code: agent_connect_tools_missing
    python_exception: null
    severity: user
    raised_by:
      - okg agent connect
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "run `okg doctor --deployment <name>` and fix what it names"
    data_shape: [deployment, agent, stderr_tail, tools]

  - code: agent_connect_unknown_agent
    python_exception: null
    severity: user
    raised_by:
      - okg agent connect
      - okg agent disconnect
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "choose from claude-code, claude-desktop, cursor, codex"
    data_shape: []

  - code: agent_runtime_path_binding_invalid
    python_exception: null
    severity: user
    raised_by:
      - okg agent-runtime-launch
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "re-run `okg agent connect --deployment {0}` to rewrite this registration with the deployment's current paths"
    data_shape: [reason_code, trace]

  - code: add_source_refused
    python_exception: AddSourceError
    severity: user
    raised_by:
      - okg deployment add-source
    referenced_in:
      - docs/use/sources/index.md
    fix_hint_template: "correct the named step (type, settings, access, or deployment) and re-run the same command"
    data_shape: [step, cause, deployment]

  - code: remove_source_refused
    python_exception: RemoveSourceError
    severity: user
    raised_by:
      - okg deployment remove-source
    referenced_in:
      - docs/use/sources/index.md
    fix_hint_template: "run the command the refusal names, then re-run the same remove-source command"
    data_shape: [deployment, source, cause]

  - code: deployment_archived
    python_exception: DeploymentArchived
    severity: user
    raised_by: [deployment admission]
    referenced_in: []
    fix_hint_template: "inspect or stop the preserved deployment; obtain an authorized operator lifecycle decision before activation"
    data_shape: [deployment, manifest_path, lifecycle, archive_reason]

  - code: deployment_not_specified
    python_exception: DeploymentNotSpecified
    severity: user
    raised_by:
      - okg dogfood status|doctor|up|down|restart|service
      - okg deployment fork-worktree|gc-forks
      - okg doctor --check dsn-agreement
      - okg doctor --check vector-sets
      - okg jobs enqueue-source|find-source-run
      - okg pact coord setup plan
      - okg search|inspect|expand|filter|aggregate|map|query
    referenced_in: []
    fix_hint_template: "pass --deployment <name>, set OKG_DEPLOYMENT=<name>, or set graph_projection.deployment in .okg/coordination.yaml"
    data_shape: [command]

  - code: generation_compacted
    python_exception: GenerationCompacted
    severity: user
    raised_by:
      - okg generation describe
      - generation-pinned read surfaces
    referenced_in:
      - docs/runbooks/troubleshooting/storage.md
    fix_hint_template: "choose a retained generation from okg generation list"
    data_shape: [checkpoint_id, deployment_name, branch, plan_id, compacted_at, reason]

  - code: generation_not_found
    python_exception: GenerationNotFound
    severity: user
    raised_by:
      - MCP inspect(kind='generation')
    referenced_in:
      - docs/runbooks/troubleshooting/storage.md
    fix_hint_template: "list generations for this deployment and branch, then inspect one of those ids"
    data_shape: [requested_generation, deployment_name, branch_name]

  - code: generation_out_of_scope
    python_exception: GenerationOutOfScope
    severity: user
    raised_by:
      - MCP inspect(kind='generation')
      - MCP inspect(kind='node_history') and inspect(kind='subtype_diff'), for a generation off the session branch's history
    referenced_in:
      - docs/runbooks/troubleshooting/storage.md
    fix_hint_template: "read this generation from the deployment and branch that own it"
    data_shape: [requested_generation, deployment_name, branch_name, generation_deployment_name, generation_branch]

  - code: generation_pin_invalid
    python_exception: GenerationPinInvalid
    severity: user
    raised_by:
      - generation-pinned read surfaces (pinned_generation)
    referenced_in:
      - pact/changes/int-on-chronos-generation-ref/audit.md
    fix_hint_template: "set okg.pin_generation to a published Chronos checkpoint id, or RESET it to read the latest published generation"
    data_shape: [guc, value]

  # ---------- history reads (PACT okg-attribute-history-read) ----------

  - code: history_row_budget_exceeded
    python_exception: HistoryRowBudgetExceeded
    severity: user
    raised_by:
      - MCP inspect(kind='node_history')
      - MCP inspect(kind='subtype_diff')
    referenced_in:
      - docs/reference/mcp-results.md
    fix_hint_template: "diff two closer generations, or read the record at single generations"
    data_shape: [budget, budget_name, target_kind]

  - code: history_generation_unordered
    python_exception: HistoryGenerationUnordered
    severity: user
    raised_by:
      - MCP inspect(kind='node_history')
      - MCP inspect(kind='subtype_diff')
    referenced_in:
      - docs/reference/mcp-results.md
    fix_hint_template: "backfill the generation-ordinal registry for this branch, or pass a `from` after the named generations"
    data_shape: [generation_ids, unordered_count, branch, deployment_name]

  - code: history_range_invalid
    python_exception: HistoryRangeInvalid
    severity: user
    raised_by:
      - MCP inspect(kind='node_history')
      - MCP inspect(kind='subtype_diff')
    referenced_in:
      - docs/reference/mcp-results.md
    fix_hint_template: "swap the two generations, or omit `from` to start at the oldest"
    data_shape: [from_generation, to_generation]

  # ---------- extension / host problems ----------

  - code: extension_missing
    python_exception: ExtensionMissing
    severity: fatal
    raised_by:
      - okg migrate
      - okg doctor
    referenced_in:
      - src/okg/AGENTS.md
    fix_hint_template: "pick a managed host that supports {0}, or CREATE EXTENSION if you have privileges"
    data_shape: [missing, required]

  - code: extension_version_mismatch
    python_exception: ExtensionVersionMismatch
    severity: fatal
    raised_by:
      - okg migrate
    referenced_in:
      - docs/reference/alerts.yaml
    fix_hint_template: "upgrade {0} to {1} or pin substrate to the installed version"
    data_shape: [extension, installed, required]

  - code: postgres_version_too_old
    python_exception: PostgresVersionTooOld
    severity: fatal
    raised_by:
      - okg migrate
    fix_hint_template: "upgrade Postgres to {0} or later"
    data_shape: [observed_major, observed_version_num, required_major]

  - code: database_clone_error
    python_exception: DatabaseCloneError
    severity: fatal
    raised_by:
      - okg db clone
      - safe_recreate_database
    referenced_in:
      - pact/changes/harden-database-clone-path/design.md
    fix_hint_template: null
    data_shape: [stage, target_state, target_fenced]

  - code: spacy_model_not_installed
    python_exception: ModelNotInstalled
    severity: error
    raised_by:
      - SpacyNER.extract
    fix_hint_template: "python -m spacy download {0}"
    data_shape: [model]

  - code: gliner_model_not_installed
    python_exception: GLiNERModelNotInstalled
    severity: error
    raised_by:
      - GLiNERBackend.extract
    fix_hint_template: "pip install 'akmon[nlp]' / fetch model {0}"
    data_shape: [model]

  - code: extractor_chain_missing
    python_exception: ExtractorChainMissing
    severity: fatal
    raised_by:
      - okg.substrate.library.extraction.registry.load_extractors
    fix_hint_template: "fix the offending {0} entry in extractors.yaml"
    data_shape: [class, config_keys]

  - code: extractor_axis_missing
    python_exception: ExtractorAxisMissing
    severity: error
    raised_by:
      - okg.substrate.library.extraction.registry.load_extractors
    fix_hint_template: "add {0} block to extractors.yaml"
    data_shape: [axis]

  - code: overlay_generation_unmaterialized
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.attributes.require_overlay_generation_marker
      - okg.substrate.mcp.graph_read.require_graph_pin
    # The MCP readers send require_graph_pin's hint; with no marker table it is
    # "an operator runs `okg migrate --apply`, which also writes the markers".
    fix_hint_template: "pin an earlier generation that has its marker (see `okg generation list --deployment <name>`), or publish this branch again: a publish that succeeds writes the marker, and a read with no generation_id then pins it. That publish can itself be refused; its refusal names its own fix"
    # require_graph_pin adds `cause` (overlay_step_not_run or
    # marker_table_missing).
    data_shape: [generation_id, namespace, marker_table_present]

  - code: overlay_ranges_out_of_order
    python_exception: null
    severity: fatal
    raised_by:
      - okg.substrate.attributes.sync_overlay_ranges_for_generation
    fix_hint_template: "re-materialize only the branch's latest generation"
    data_shape: [generation_id, branch_id, ordinal, last_synced_ordinal]

  - code: enricher_load_error
    python_exception: EnricherLoadError
    severity: fatal
    raised_by:
      - okg.substrate.publisher.enricher_loader.load_enrichers
    fix_hint_template: "fix the offending enrichers entry in deployment.yaml"
    data_shape: [class, config_keys]

  - code: enricher_narrowings_missing
    python_exception: EnricherNarrowingsMissing
    severity: fatal
    raised_by:
      - okg.substrate.publisher.enricher_loader.validate_enricher_narrowings
    fix_hint_template: "declare the missing narrowings in the relevant ontology's EdgeNarrowings"
    data_shape: [catalog_version_id, missing]

  - code: enricher_envelope_missing
    python_exception: EnricherEnvelopeMissing
    severity: fatal
    raised_by:
      - okg.substrate.publisher.enricher_loader.derive_write_envelope
      - okg.substrate.publisher.enricher_loader.validate_enricher_envelopes
    fix_hint_template: "declare requires_narrowings / emits_typed_subtype (the envelope derives from them) or an explicit write_envelope mapping; a model-calling operator must declare nondeterministic = True"
    data_shape: [enricher, producer_id]

  - code: enricher_support_policy_invalid
    python_exception: EnricherSupportPolicyInvalid
    severity: fatal
    raised_by:
      - okg.substrate.publisher.enricher_loader.validate_enricher_support_policies
    fix_hint_template: "declare `support_policy: DerivedSupportPolicy = \"all_members\"` (or \"any_member\") on the node-writing enricher class; the derived-node liveness policy has no safe default"
    data_shape: [enricher, producer_id, support_policy, allowed]

  - code: enricher_backfill_selection_error
    python_exception: EnricherBackfillSelectionError
    severity: user
    raised_by:
      - okg enricher backfill
      - okg.substrate.enrichers.backfill.select_enricher
    fix_hint_template: "check the deployment's enrichers block and pass exactly one registered enricher name"
    data_shape: [deployment, enricher_name, matches]

  - code: enricher_backfill_branch_unsupported
    python_exception: EnricherBackfillBranchUnsupported
    severity: user
    raised_by:
      - okg enricher backfill
      - okg.substrate.enrichers.backfill.run_enricher_backfill
    fix_hint_template: "run targeted enricher backfill on the default branch; branch-scoped normal enricher progress is required before non-default branches are supported"
    data_shape: [deployment, enricher_name, branch_name]

  - code: enricher_backfill_unsafe_enricher
    python_exception: EnricherBackfillUnsafeEnricher
    severity: user
    raised_by:
      - okg enricher backfill
      - okg.substrate.enrichers.backfill.run_enricher_backfill
    fix_hint_template: "set targeted_backfill_chunk_safe only after the enricher strictly scopes work and emitted edge facts to incremental.dirty_node_ids"
    data_shape: [deployment, enricher_name, required_capability]

  - code: enricher_backfill_unsupported_output
    python_exception: EnricherBackfillUnsupportedOutput
    severity: user
    raised_by:
      - okg enricher backfill
      - okg.substrate.enrichers.backfill.run_enricher_backfill
    fix_hint_template: "use normal publish for node-emitting enrichers until targeted node-fact admission is implemented"
    data_shape: [deployment, enricher_name, unsupported_fields]

  - code: enricher_backfill_admission_rejected
    python_exception: EnricherBackfillAdmissionRejected
    severity: error
    raised_by:
      - okg enricher backfill
      - okg.substrate.enrichers.backfill.run_enricher_backfill
    fix_hint_template: "fix the enricher producer policy or emitted edge triples, then retry the chunk"
    data_shape: [deployment, enricher_name, chunk_index, input_node_ids, verdicts]

  - code: enricher_backfill_chunk_failed
    python_exception: EnricherBackfillChunkFailed
    severity: error
    raised_by:
      - okg enricher backfill
      - okg.substrate.enrichers.backfill.run_enricher_backfill
    fix_hint_template: "fix the enricher exception and retry; the failed chunk was not marked complete"
    data_shape: [deployment, enricher_name, chunk_index, input_node_ids, error]

  - code: consistency_gate_load_error
    python_exception: ConsistencyGateLoadError
    severity: fatal
    raised_by:
      - okg.substrate.consistency.sql_gate.load_consistency_gates
    fix_hint_template: "fix the offending consistency_gates entry in deployment.yaml"
    data_shape: [where, field, token]
  - code: ir_consistency_check_load_error
    python_exception: IrCheckLoadError
    severity: fatal
    raised_by:
      - okg.substrate.consistency.ir_check.load_ir_consistency_checks
    fix_hint_template: "fix the offending ir_consistency_checks entry (or its program_ref / surfaces) in deployment.yaml"
    data_shape: [where, field, check_id, program_ref, surface, missing, extras, errors]

  - code: undeclared_finding_identity
    python_exception: UndeclaredFindingIdentity
    severity: fatal
    raised_by:
      - okg.substrate.consistency.ir_executor._normalized_values
    fix_hint_template: "declare normalized_value_columns on the ir_consistency_checks entry (the closure that keys finding identity); the executor no longer falls back to the whole offender row"
    data_shape: [check_id]

  - code: post_publish_generation_unresolved
    python_exception: PostPublishGenerationUnresolved
    severity: fatal
    raised_by:
      - okg.substrate.consistency.chronos_sql_mirror.checkout_published_generation
    fix_hint_template: "pass the checkpoint id of a retained published generation (okg generation list); post-publish checks never read the live branch head"
    data_shape: [generation_id, purpose, error_type]

  - code: chronos_sql_mirror_mismatch
    python_exception: ChronosSqlMirrorMismatch
    severity: fatal
    raised_by:
      - okg.substrate.consistency.chronos_sql_mirror.ChronosSqlMirrorReads.reading
    fix_hint_template: "rerun the check with okg consistency-rerun --generation <id>"
    data_shape: [expected_checkpoint_id, held_checkpoint_id, reason]

  - code: doctor_check_load_error
    python_exception: DoctorCheckLoadError
    severity: user
    raised_by:
      - okg.substrate.doctor.load_deployment_doctor_checks
    referenced_in:
      - src/okg/substrate/doctor.py
    fix_hint_template: "fix the offending doctor_checks entry in deployment.yaml"
    data_shape: []

  - code: edge_ranking_changed_during_write
    python_exception: EdgeRankingChangedDuringWrite
    severity: recoverable
    raised_by:
      - okg.substrate.graph_store_internal.writes.ChronosGraphWriteMixin.apply_facts
    referenced_in:
      - docs/develop/architecture/pipeline.md
    fix_hint_template: "the edge ranking changed during this write; rerun it"
    data_shape: [branch, planned_edge_types, current_edge_types]

  - code: edge_ranking_change_busy
    python_exception: EdgeRankingChangeBusy
    severity: recoverable
    raised_by:
      - okg migrate --deployment
      - okg worker (start)
    referenced_in:
      - docs/develop/architecture/pipeline.md
    fix_hint_template: "graph writers are busy on branch {0}; retry the ranking change"
    data_shape: [branch, deployment]

  - code: graph_written_during_publish
    python_exception: null
    severity: recoverable
    raised_by:
      - okg.substrate.publisher.publisher.Publisher._chronos_refuse_writes_since_counted
    referenced_in: []
    fix_hint_template: "re-run the publish: the rows written during this one are still unpublished and the next cycle counts them"
    data_shape: [branch, stage, segment_signature_counted, segment_signature_now]

  - code: no_applied_catalog
    python_exception: null
    severity: error
    raised_by:
      - okg.substrate.cli.main._cmd_catalog_reconcile
    fix_hint_template: "run `okg catalog load --apply` first"
    data_shape: []

  - code: deployment_not_found
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.runtime.source_sync_workflow.okg_source_sync
      - okg.substrate.cli.main._cmd_mcp_serve
      - okg.substrate.cli.init.deployments_env_root_error
      - okg agent connect
    referenced_in:
      - pact/changes/mcp-serve-typed-deployment-error
      - pact/changes/s14-2127-install-release-shape
    fix_hint_template: "check deployments/<name>/ exists or OKG_DEPLOYMENTS_DIR"
    # `data_shape` lists the keys EVERY raiser sets, so it stays at two.
    # The scaffold raiser (`deployments_env_root_error`, used by okg install
    # and okg init) adds `env_var: OKG_DEPLOYMENTS_DIR`, and reports
    # `deployment: null` because it refuses before any deployment is
    # resolved -- the root itself is what could not be found.
    data_shape: [deployment, resolution_error]

  - code: source_sync_payload_invalid
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.runtime.source_sync_workflow.okg_source_sync
    fix_hint_template: "enqueue source-sync work through DBOS runtime APIs"
    data_shape: [job_id, payload]

  - code: source_sync_ingest_failed
    python_exception: null
    severity: recoverable
    raised_by:
      - okg.substrate.runtime.source_sync_workflow.okg_source_sync
    fix_hint_template: "inspect the failed source result and retry after repair"
    data_shape: [deployment, ordered, results, publishes, skipped]

  - code: latex_project_legacy_mismatch
    python_exception: LatexProjectLegacyMismatch
    severity: fatal
    raised_by:
      - okg.substrate.library.sources.scholarly.bib_references.assert_legacy_record_set_matches_graph
    referenced_in:
      - src/okg/substrate/library/sources/scholarly/bib_references.py
    fix_hint_template: "restore the exact legacy ownership id and files, or repair the live owned graph before migration"
    data_shape: [source_name]

  - code: latex_project_manifest_mismatch
    python_exception: LatexProjectManifestMismatch
    severity: fatal
    raised_by:
      - okg.substrate.library.sources.scholarly.latex_project.LatexProjectSource
    referenced_in:
      - src/okg/substrate/library/sources/scholarly/latex_project.py
    fix_hint_template: "run the manifest-aware SourceFile, document-corpus, and bibliography predecessors with the same project manifest before retrying"
    data_shape: [expected_manifest_digest, predecessor_digests, mismatches]

  - code: runtime_source_sync_active
    python_exception: null
    severity: recoverable
    raised_by:
      - okg.substrate.cli.main._cmd_ingest
    fix_hint_template: "wait for active source-sync DBOS work to drain or rerun without --inline; if the worker is stopped, start it or cancel the stranded workflow with `okg runtime cancel-workflow`"
    data_shape: [deployment, queue_name, active_count, active_rows]

  - code: runtime_source_sync_probe_failed
    python_exception: null
    severity: recoverable
    raised_by:
      - okg.substrate.cli.main._cmd_ingest
    fix_hint_template: "rerun without --inline so DBOS admits the work, or inspect `okg sync health --deployment <name> --json`"
    data_shape: [deployment, error]

  - code: deployment_runtime_config_unresolved
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.cli.main._deployment_runtime_enabled
    fix_hint_template: "fix deployment.yaml or run `uv run okg deployment ready <deployment> --json`"
    data_shape: [deployment, error]

  - code: deployment_environment_invalid
    python_exception: DeploymentEnvironmentInvalid
    severity: user
    raised_by:
      - okg.substrate.cli.environment._cmd_environment
    fix_hint_template: "fix the named environment descriptor, secret reference, database target, or colliding resource identity"
    data_shape: [environment, environments_root]

  - code: source_activation_probe_invalid
    python_exception: SourceActivationProbeInvalid
    severity: user
    raised_by:
      - okg.substrate.ingest.service._validate_deferred_source_activation
    fix_hint_template: "add a sound source-owned runtime change probe and supported poll selector before enabling or explicitly ingesting the source"
    data_shape: [sources]

  - code: source_configuration_authority_invalid
    python_exception: SourceConfigurationAuthorityInvalid
    severity: user
    raised_by:
      - okg.substrate.deployments.sync_root.require_usable_source_configuration_authority
    fix_hint_template: "repair the declared source-root authority so it names an existing authoritative directory; sealed processes repair launcher authority and long-lived workers restart after local-profile changes"
    data_shape: [configured_path, canonical_path, reason]

  - code: sealed_release_invalid
    python_exception: SealedReleaseInvalid
    severity: error
    raised_by:
      - okg.substrate.sealed_release.prepare_sealed_release
      - okg.substrate.sealed_release.verify_sealed_release
      - okg.substrate.release_activation.activate_environment_release
      - okg.substrate.runtime.release_authority.verify_worker_release_authority
      - okg.substrate.runtime.release_launcher.verify_launch
    fix_hint_template: "repair the declared revision/config inputs, active pointer, or trusted runtime root; remove incomplete artifacts and prepare again"
    data_shape: [artifact_id, artifact_root, expected, observed, command]

  - code: release_kind_invalid
    python_exception: ReleaseKindInvalid
    severity: user
    raised_by:
      - okg.substrate.deployment_release.declared_release_kind
      - okg.substrate.deployment_release.ReleaseArtifact.from_mapping
    referenced_in:
      - docs/operate/deployments/external.md
    fix_hint_template: "set `release.kind` to packaged or standalone, or remove the key for a deployment tracked in a Git checkout"
    data_shape: [deployment, observed, allowed]

  - code: installed_framework_modified
    python_exception: InstalledFrameworkModified
    severity: user
    raised_by:
      - okg.substrate.distributions.installed_framework.installed_framework_distribution
    referenced_in:
      - docs/operate/deployments/external.md
    fix_hint_template: "reinstall okg from its wheel so the installed files match the wheel's RECORD, then re-run the failed command"
    data_shape: [distribution, version, modified, modified_count]

  - code: framework_tree_unavailable
    python_exception: FrameworkTreeUnavailable
    severity: user
    raised_by:
      - okg.substrate.framework_tree.framework_tree_root
    referenced_in:
      - docs/operate/deployments/external.md
    fix_hint_template: "point OKG_FRAMEWORK_TREE at the directory that holds okg's src/okg, deployments/ and ops/ (/opt/okg in the runtime image), or unset it"
    data_shape: [env, value]

  - code: standalone_release_conflict
    python_exception: StandaloneReleaseConflict
    severity: user
    raised_by:
      - okg.substrate.publisher.factory.build_deployment_publisher
      - okg.substrate.deployment_release.current_release_artifact
      - okg.substrate.deployment_release.ReleaseArtifact.from_mapping
    referenced_in:
      - docs/operate/deployments/external.md
    fix_hint_template: "remove `release.kind: standalone` from the deployment.yaml, or stop publishing this deployment under the conflicting packaged or sealed release authority"
    data_shape: [deployment, deployment_dir, declared_kind, conflicting_authority]

  - code: standalone_upgrade_unsupported
    python_exception: StandaloneUpgradeUnsupported
    severity: user
    raised_by:
      - okg.substrate.deployment_upgrade.run_deployment_upgrade
      - okg.substrate.deployment_upgrade.run_deployment_backup_verify
    referenced_in:
      - docs/operate/lifecycle.md
      - docs/operate/deployments/external.md
    fix_hint_template: "take your own database backup with pg_dump before changing this deployment; if it really lives in a committed Git checkout, remove `release.kind: standalone` from its deployment.yaml. `okg up` no longer raises this: it upgrades a standalone deployment as an installed package"
    data_shape: [deployment, release_kind, operation, reason]

  - code: installed_upgrade_incompatible
    python_exception: InstalledUpgradeIncompatible
    severity: user
    raised_by:
      - okg.substrate.deployment_installed_upgrade.run_installed_upgrade
    referenced_in:
      - docs/operate/lifecycle.md
    fix_hint_template: "fix the deployment for the listed blockers and breaking changes (release notes link included when known), or go back by reinstalling the okg version you upgraded from; nothing was changed"
    data_shape: [step, contract_source, verdict, exit_code, from_version, to_version, breaking_affecting_this_deployment, blockers, unknowns, release_notes, go_back]

  - code: installed_upgrade_compat_unknown
    python_exception: InstalledUpgradeCompatUnknown
    severity: user
    raised_by:
      - okg.substrate.deployment_installed_upgrade.run_installed_upgrade
    referenced_in:
      - docs/operate/lifecycle.md
    fix_hint_template: "pass the previous release's contract with --from-contract FILE, or rerun with --accept-unknown-compat to upgrade without knowing; nothing was changed"
    data_shape: [step, contract_source, verdict, exit_code, from_version, to_version, reasons, go_back]

  - code: installed_upgrade_refused
    python_exception: InstalledUpgradeRefused
    severity: user
    raised_by:
      - okg.substrate.deployment_installed_upgrade.run_installed_upgrade
    referenced_in:
      - docs/operate/lifecycle.md
    fix_hint_template: "drop the okg up options that only apply to a Git-checkout deployment (including --dsn: the database is the one deployment.yaml names), or fix the named input (--from-contract file, --backup-dir inside a Git work tree, wheel install, unfinished-upgrade marker, deployment database); an okg older than the receipt's is refused: go back with okg deployment backup restore"
    data_shape: [deployment]

  - code: installed_upgrade_worker_unsupervised
    python_exception: InstalledUpgradeWorkerUnsupervised
    severity: user
    raised_by:
      - okg.substrate.deployment_installed_upgrade.run_installed_upgrade
    referenced_in:
      - docs/operate/lifecycle.md
      - docs/reference/cli.md
    fix_hint_template: "okg up cannot manage this deployment's runtime worker and changed nothing. With a systemd system worker service (an enabled okg-runtime-worker@<deployment>.service whose template okg renders for this deployment), run okg up as root. Without one, on Linux, install it as root first (okg dogfood service install --deployment <deployment> --adapter systemd --apply); on macOS install the launchd plist (--adapter launchd, no root). If the reload check is unavailable, fix what okg deployment ready reports for the apply check. Per-user systemd worker services are planned as the first follow-up after 2026-10-17"
    data_shape: [deployment, reason, runtime_enabled, pids, commands, service, worker_reload, upgrade_command, install_service_command, follow_up, resumed_upgrade]

  - code: installed_release_receipt_unreadable
    python_exception: InstalledReceiptUnreadable
    severity: user
    raised_by:
      - okg.substrate.deployment_installed_upgrade.read_installed_release_receipt
    referenced_in:
      - docs/operate/lifecycle.md
    fix_hint_template: "inspect ${OKG_USER_HOME:-$XDG_DATA_HOME/okg}/state/deployments/<deployment>/installed-release.json; if it is damaged or was written for another deployment directory, move it aside and pass the previous release's contract with --from-contract, or --accept-unknown-compat"
    data_shape: [path, reason]

  - code: installed_restore_refused
    python_exception: InstalledRestoreRefused
    severity: user
    raised_by:
      - okg.substrate.deployment_installed_restore.run_installed_restore
    referenced_in:
      - docs/operate/lifecycle.md
      - docs/reference/cli.md
    fix_hint_template: "restore only the pre_upgrade_archive `okg up` recorded for this installed deployment, with its owner-only <archive>.json sidecar, unchanged, from the same database, as a superuser (required with TimescaleDB) or, without TimescaleDB, a role with CREATEDB and membership in the database owner's role; restore any other archive into a separate database with okg db clone --restore-dump"
    data_shape: []

  - code: sealed_release_revision_missing
    python_exception: SealedReleaseRevisionMissing
    severity: error
    raised_by:
      - okg.substrate.sealed_release.prepare_environment_release
    fix_hint_template: "seal a release only from a committed Git checkout; a standalone or packaged deployment records no code revision and cannot be sealed"
    data_shape: [field, observed]

  - code: gh_cli_missing
    python_exception: GhCliMissing
    severity: error
    raised_by:
      - okg.substrate.library.sources.github.GitHubSource._fetch_via_gh
    fix_hint_template: "install gh (https://cli.github.com/) and run `gh auth login`"
    data_shape: [adapter, repo]

  - code: forge_references_unresolved
    python_exception: ForgeReferencesUnresolved
    severity: error
    raised_by:
      - okg.substrate.library.linkers.forge_references
    fix_hint_template: "reference tokens were found but none resolved; check the corpus bounds and the number vocabulary rather than reading zero resolutions as a repository nobody cross-referenced"
    data_shape: [adapter, repo, counts]

  - code: forge_discussion_empty
    python_exception: ForgeDiscussionError
    severity: error
    raised_by:
      - okg.substrate.library.sources.github.GitHubSource
    fix_hint_template: "the payload carried discussion or merge rows but the parse emitted none; check the fixture's comment/pull shape rather than reading zero as a quiet repository"
    data_shape: [adapter, repo, counts]

  - code: concept_aliases_path_missing
    python_exception: ConceptAliasesPathMissing
    severity: user
    raised_by:
      - okg.substrate.library.sources.concept_aliases
    fix_hint_template: "set params.aliases_path to an existing aliases YAML/JSON file"
    data_shape: []

  - code: concept_aliases_parse_error
    python_exception: ConceptAliasesParseError
    severity: user
    raised_by:
      - okg.substrate.library.sources.concept_aliases
    fix_hint_template: "fix the concept aliases file syntax"
    data_shape: [path]

  - code: concept_aliases_no_dsn
    python_exception: ConceptAliasesNoDsn
    severity: user
    raised_by:
      - okg.substrate.library.sources.concept_aliases
    fix_hint_template: "supply params.dsn with the deployment-resolved Postgres DSN"
    data_shape: []

  - code: engram_source_config_error
    python_exception: EngramSourceConfigError
    severity: user
    raised_by:
      - okg.substrate.library.sources.engram_runs._common
    fix_hint_template: "load the reasoning ontology module before enabling engram_runs sources"
    data_shape: [source_name, loaded_modules]

  - code: experiment_record_parse_error
    python_exception: ExperimentRecordParseError
    severity: user
    raised_by:
      - okg.substrate.library.sources.experimental.experiment_records
    fix_hint_template: "fix the experiment record YAML/JSON input"
    data_shape: [path]

  - code: result_schema_error
    python_exception: ResultSchemaError
    severity: user
    raised_by:
      - okg.substrate.library.sources.experimental.bench_outputs
    fix_hint_template: "fix the benchmark result record schema"
    data_shape: []

  - code: success_condition_predicate_parse_error
    python_exception: PredicateParseError
    severity: user
    raised_by:
      - okg.substrate.library.sources.experimental.experiment_records
      - okg.substrate.library.sources.experimental.predicates
    fix_hint_template: "fix the success-condition predicate expression"
    data_shape: []

  - code: cluster_pull_mode_not_implemented
    python_exception: ClusterPullModeError
    severity: user
    raised_by:
      - okg.substrate.library.sources.experimental.cluster_jobs
    fix_hint_template: "use operator-pulled cluster inputs until substrate-pulled mode is implemented"
    data_shape: []

  - code: transcript_fetch_error
    python_exception: TranscriptFetchError
    severity: recoverable
    raised_by:
      - okg.substrate.library.sources.scholarly.talks
    fix_hint_template: "verify the video URL, captions, and network access"
    data_shape: [youtube_id, underlying_error]

  - code: persona_load_error
    python_exception: PersonaLoadError
    severity: user
    raised_by:
      - okg.substrate.library.personas
    fix_hint_template: "fix the persona YAML file"
    data_shape: [path]

  - code: persona_slug_collision
    python_exception: PersonaSlugCollision
    severity: user
    raised_by:
      - okg.substrate.library.personas
    fix_hint_template: "rename the deployment persona slug"
    data_shape: [slug, path]

  - code: persona_unknown
    python_exception: PersonaUnknown
    severity: user
    raised_by:
      - okg.substrate.mcp.review_as
    fix_hint_template: "choose a registered persona slug"
    data_shape: [persona, slug]

  - code: persona_prompt_missing
    python_exception: PersonaPromptMissing
    severity: user
    raised_by:
      - okg.substrate.mcp.review_as
    fix_hint_template: "add the persona prompt file or update the prompt reference"
    data_shape: [path]

  - code: context_packet_definition_invalid
    python_exception: ContextPacketDefinitionError
    severity: fatal
    raised_by:
      - okg.substrate.library.ontologies.reasoning.derived_artifacts.context_packet
    fix_hint_template: "fix the substrate-shipped context_packet.yaml definition"
    data_shape: [path]

  - code: pre_join_tool_schema_error
    python_exception: PreJoinSchemaError
    severity: user
    raised_by:
      - okg.substrate.mcp.framework.resolvers
      - okg.substrate.mcp.framework.schema
    fix_hint_template: "fix the pre-join tool YAML schema"
    data_shape: []

  - code: pre_join_tool_step_kind_unknown
    python_exception: PreJoinStepKindUnknown
    severity: user
    raised_by:
      - okg.substrate.mcp.framework.schema
    fix_hint_template: "use a supported pre-join tool step kind"
    data_shape: [name, index, call]

  - code: pre_join_tool_traverse_hops_exceeded
    python_exception: PreJoinTraverseHopsExceeded
    severity: user
    raised_by:
      - okg.substrate.mcp.framework.schema
    fix_hint_template: "reduce traverse_path max_hops to the substrate limit"
    data_shape: [name, index]

  - code: pre_join_tool_resolver_unknown
    python_exception: PreJoinResolverUnknown
    severity: user
    raised_by:
      - okg.substrate.mcp.framework.resolvers
    fix_hint_template: "register the named resolver or update the pre-join tool YAML"
    data_shape: [name, resolver]

  - code: pre_join_tool_summary_template_error
    python_exception: PreJoinSummaryTemplateError
    severity: recoverable
    raised_by:
      - okg.substrate.mcp.framework.executor
    fix_hint_template: "fix the pre-join summary_template"
    # Executor logs a warning and returns the literal template; no structured error is raised.
    data_shape: []

  - code: pre_join_tool_error
    python_exception: PreJoinToolError
    severity: recoverable
    raised_by:
      - okg.substrate.mcp.fan_out
      - okg.substrate.mcp.framework.executor
      - okg.substrate.mcp.review_as
    fix_hint_template: "inspect the pre-join tool step failure"
    data_shape: []

  - code: alias_backend_load_error
    python_exception: AliasBackendLoadError
    severity: fatal
    raised_by:
      - okg.substrate.alias.loader.load_alias_resolver
    fix_hint_template: "fix the offending alias_resolver entry in deployment.yaml"
    data_shape: [class, config_keys]

  - code: alias_resolution_failed
    python_exception: AliasResolutionFailed
    severity: error
    raised_by:
      - okg.substrate.alias.cascade.CascadeAliasResolver.resolve
    fix_hint_template: "lower a backend threshold or set on_empty='drop'"
    data_shape: [needle, entity_type, per_backend_top_score]

  - code: entity_resolution_failed
    python_exception: EntityResolutionError
    severity: fatal
    raised_by:
      - okg.substrate.entity_resolution.EntityResolutionStage
    referenced_in:
      - docs/reference/database-schema.md
      - docs/develop/extensions/ontologies.md
    fix_hint_template: "inspect the chained resolution failure and retry; do not mint around the failed stage"
    data_shape: []

  - code: entity_resolution_rejected
    python_exception: EntityResolutionRejected
    severity: user
    raised_by:
      - okg.substrate.entity_resolution.EntityResolutionStage
      - okg.substrate.entity_resolution.mint_entity_id
    referenced_in:
      - docs/reference/database-schema.md
      - docs/develop/extensions/ontologies.md
    fix_hint_template: "correct the extracted identity or the deployment post-filter policy, then retry"
    data_shape: []

  - code: entity_resolution_ambiguous
    python_exception: EntityResolutionAmbiguous
    severity: recoverable
    raised_by:
      - okg.substrate.entity_resolution.EntityResolutionStage
    referenced_in:
      - docs/reference/database-schema.md
      - docs/develop/extensions/ontologies.md
    fix_hint_template: "resolve conflicting aliases or duplicate live identities before retrying"
    data_shape: []

  - code: entity_resolution_unavailable
    python_exception: EntityResolutionUnavailable
    severity: recoverable
    raised_by:
      - okg.substrate.entity_resolution.EntityResolutionStage
    referenced_in:
      - docs/reference/database-schema.md
      - docs/develop/extensions/ontologies.md
    fix_hint_template: "restore the required catalog, graph, policy, or escalation dependency before retrying"
    data_shape: []

  - code: embedding_backend_not_installed
    python_exception: EmbeddingBackendNotInstalled
    severity: error
    raised_by:
      - okg.substrate.alias.backends.embedding.EmbeddingAliasBackend
    fix_hint_template: "pass embedder= when constructing EmbeddingAliasBackend"
    data_shape: []

  - code: embedder_spec_invalid
    python_exception: null
    severity: error
    raised_by:
      # ONE parser as of PACT reachable-semantic-search; the CLI and the embed
      # workflow both delegate here. Two copies meant the WRITER of embeddings
      # and the READER could disagree about what a spec means.
      - okg.substrate.embeddings.identity.build_embedder
      - okg.substrate.embeddings.identity.model_id_for_spec
    fix_hint_template: "use 'hash' or 'sentence-transformers:<model>'"
    data_shape: []

  - code: embedder_identity_undeclared
    python_exception: null
    severity: error
    raised_by:
      - okg.substrate.embeddings.identity.embedder_model_id
    fix_hint_template: >-
      give the embedder a `model_id` property unique per MODEL (not per class),
      e.g. 'sentence-transformers:all-mpnet-base-v2'
    data_shape: [embedder_type]

  - code: embedder_api_key_missing
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.openrouter.OpenRouterEmbedder
    fix_hint_template: "export OPENROUTER_API_KEY"
    data_shape: [env_var]

  - code: embedding_cost_unreported
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.backfill.run_set_backfill
      - okg.substrate.embeddings.backfill.dry_run_backfill
    fix_hint_template: "check the bill for uncosted okg.llm_calls rows first"
    data_shape: [deployment, set_id, model_id, answered_uncosted_calls]

  - code: embedding_spend_cap_required
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.backfill.run_set_backfill
    fix_hint_template: "pass --max-usd <dollars> (see --dry-run for the estimate)"
    data_shape: [set, model_id]

  - code: embedding_spend_cap_unenforceable
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.backfill.run_set_backfill
    fix_hint_template: "omit --max-usd for a backend that makes no paid calls"
    data_shape: [set, model_id]

  - code: embedding_backfill_in_progress
    python_exception: null
    severity: recoverable
    raised_by:
      - okg.substrate.embeddings.backfill.run_set_backfill
    fix_hint_template: "wait for the other okg db embed-backfill of the set, then rerun"
    data_shape: [set_id]

  - code: embedding_set_not_configured
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.backfill.resolve_registered_set
    fix_hint_template: "name a set from deployment.yaml's embeddings.sets"
    data_shape: [set, configured]

  - code: embedding_set_inactive
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.backfill.resolve_registered_set
    fix_hint_template: "okg migrate --deployment <name> --apply with the set in deployment.yaml"
    data_shape: [set, set_id, reason]

  - code: embedder_egress_refused
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.openrouter.OpenRouterEmbedder
    fix_hint_template: "the central egress guard refused the endpoint; see OKG_EGRESS_ALLOW_HOSTS"
    data_shape: [model_id, endpoint]

  - code: embedding_header_field_masked
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.documents.check_templates
    fix_hint_template: "remove the field from the set's document.types header, or declare it non_pii"
    data_shape: [set, fields_by_subtype]

  - code: embedding_catalog_unreadable
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.store.load_classifications
    fix_hint_template: "repair the subtype's pii_classes declaration"
    data_shape: [subtype]

  - code: embedding_index_build_running
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.store.rebuild_set_index
    fix_hint_template: "wait for the running index build to finish, then rerun"
    data_shape: [set_id, pids, lock_held_elsewhere]

  - code: embedding_index_config_drift
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.cli.main._cmd_db_embed_index
    fix_hint_template: "okg migrate --deployment <name> --apply"
    data_shape: [set, set_id]

  - code: embedding_schema_outdated
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.store.record_templates
      - okg.substrate.embeddings.store.load_template_records
    fix_hint_template: "okg migrate --deployment <name> --apply"
    data_shape: [table]

  - code: embedding_set_unregistered
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.store.take_seq
      - okg.substrate.embeddings.store.write_vectors
      - okg.substrate.embeddings.backfill.resolve_registered_set
    fix_hint_template: "okg migrate --deployment <name> --apply"
    data_shape: [set_id]

  - code: embedding_vector_width_mismatch
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.store.write_vectors
    fix_hint_template: "embed with the set's own backend and width"
    data_shape: [set_id, width, doc_hashes]

  - code: embedding_set_storage_unknown
    python_exception: null
    severity: error
    raised_by:
      # The registered set names a storage type other than halfvec or
      # vector (PACT vector-set-pgvector-widths).
      - okg.substrate.embeddings.store.write_vectors
    fix_hint_template: "re-register the set with `okg migrate`"
    data_shape: [set_id, storage]

  - code: embedding_watermark_missing
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.embeddings.store.watermark_for
    fix_hint_template: "publish once more so the generation records its watermark"
    data_shape: [generation_id, set_id]

  - code: embedder_request_failed
    python_exception: null
    severity: recoverable
    raised_by:
      - okg.substrate.embeddings.openrouter.OpenRouterEmbedder
    fix_hint_template: "read `message`, fix the input or key, rerun"
    data_shape: [model_id, attempts, inputs]

  - code: semantic_unverified_provenance_unindexed
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.mcp.search._search_semantic
      - okg.substrate.mcp.search._search_semantic_vector_set
    # Node columns (_search_semantic): data {query_model_id}, re-embed the
    # rows with no recorded model. Vector set (_search_semantic_vector_set):
    # data {set, set_id}, search without the opt-in (a set holds only
    # vectors of its own documents).
    fix_hint_template: "search without the opt-in; for the node columns, re-embed rows with no recorded model"
    data_shape: [query_model_id, set, set_id]

  - code: semantic_index_unavailable
    python_exception: SemanticIndexUnavailable
    severity: user
    raised_by:
      - okg.substrate.semantic_ann.ann_rank
      - okg.substrate.semantic_ann.ensure_ann_index
      - okg.substrate.semantic_ann.prepare_set_read
    # A vector set's index is missing, building or invalid, or pgvector is
    # older than 0.8 (no iterative index scan); `okg migrate` builds each
    # set's index. The node-column index is built by `okg db semantic-index`.
    fix_hint_template: "okg migrate --deployment <name> --apply (vector set) or okg db semantic-index --deployment <name> --apply (node columns); pgvector 0.8 or newer"
    data_shape: [set, set_id, kind, status, index_name, pgvector_version]

  - code: semantic_scope_too_large
    python_exception: SemanticScopeTooLarge
    severity: user
    raised_by:
      - okg.substrate.semantic_ann.prepare_set_read
    fix_hint_template: "narrow the scope, or give the set `index: {kind: hnsw}`"
    data_shape: [set, bound]

  - code: semantic_query_embedding_failed
    python_exception: SemanticQueryEmbeddingFailed
    severity: recoverable
    raised_by:
      - okg.substrate.mcp.search._search_semantic_vector_set
    fix_hint_template: "retry shortly, or search with method='lexical' or 'grep'"
    data_shape: [set, model_id, attempts, inputs]

  - code: semantic_embedder_not_configured
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg.substrate.cli._read_side._resolve_embedder_spec
    fix_hint_template: >-
      enable deployment.yaml embeddings with an explicit compatible backend;
      for an unresolvable standalone query pass --embedder explicitly, or use
      --method lexical
    data_shape: [method]

  - code: read_args_invalid
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg inspect
      - okg expand
      - okg filter
      - okg aggregate
      - okg map
      - okg query
    fix_hint_template: "for example --args '{\"limit\": 10}'"
    data_shape: [source]

  - code: read_args_unreadable
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg inspect
      - okg expand
      - okg filter
      - okg aggregate
      - okg map
      - okg query
    fix_hint_template: "pass --args @<path to a JSON file>, --args '<json>' or --args -"
    data_shape: [path]

  - code: read_argument_given_twice
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg inspect
      - okg expand
      - okg filter
      - okg aggregate
      - okg map
      - okg query
    fix_hint_template: "give {0} once"
    data_shape: [arguments]

  - code: search_flags_conflict
    python_exception: null
    severity: user
    raised_by:
      - okg search
    fix_hint_template: "keep {0} and drop {1}"
    data_shape: [flags]

  - code: read_command_failed
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg inspect
      - okg expand
      - okg filter
      - okg aggregate
      - okg map
      - okg query
    fix_hint_template: null
    data_shape: [surface, exception]

  # The shell forms of the read commands (PACT read-shell-forms-3666). Each
  # is a refusal: exit 2, in a tool refusal's shape, with a `retry:` command
  # line when the call has one reading.
  - code: read_where_invalid
    python_exception: null
    severity: user
    raised_by: [okg search, okg expand, okg filter, okg aggregate, okg map]
    fix_hint_template: "write --where '<the condition as JSON>'"
    data_shape: [term]

  - code: read_input_unresolved
    python_exception: null
    severity: user
    raised_by: [okg filter, okg aggregate, okg map]
    fix_hint_template: "name a declared subtype, or the set as JSON"
    data_shape: [argument]

  - code: read_stdin_invalid
    python_exception: null
    severity: user
    raised_by: [okg inspect, okg expand, okg filter, okg map]
    fix_hint_template: "pipe one id per line, or JSON Lines that carry node_id"
    data_shape: []

  - code: read_all_incomplete
    python_exception: null
    severity: user
    raised_by: [okg search, okg inspect, okg expand, okg filter, okg aggregate, okg map, okg query]
    fix_hint_template: "narrow the set with --where, or read it page by page without --all"
    data_shape: []

  - code: read_select_text_unavailable
    python_exception: null
    severity: user
    raised_by: [okg filter, okg map]
    fix_hint_template: "read the texts: okg filter ... --ids --all | okg inspect texts -"
    data_shape: [argument]

  # okg inspect texts - (PACT read-shell-texts-3666).
  - code: read_lines_invalid
    python_exception: null
    severity: user
    raised_by: [okg inspect]
    fix_hint_template: "write --lines FIRST-LAST, comma-separated, with okg inspect texts -"
    data_shape: [argument]

  - code: read_output_flags_conflict
    python_exception: null
    severity: user
    raised_by: [okg search, okg inspect, okg expand, okg filter, okg aggregate, okg map, okg query]
    fix_hint_template: "keep one output flag"
    data_shape: []

  - code: semantic_index_empty
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.mcp.semantic_readiness.assert_rankable
    fix_hint_template: >-
      populate embeddings with the `okg_embed_batch` workflow, or use
      --method lexical
    data_shape: [embedded_nodes, unembedded_nodes, scoped_subtypes]

  - code: signature_grouping_inconsistent
    python_exception: SignatureGroupingInconsistent
    severity: fatal
    raised_by:
      - source admission
      - okg.substrate.producer_authority.evaluate_source_run_signature
    referenced_in: []
    fix_hint_template: >-
      a defect in the admission grouping
      (producer_authority._signature_group_plan): a rule reads a record
      property the grouping does not key on; the run was not admitted
    data_shape: [source, run_id, stage, record_kind, records, verdicts]

  - code: producer_deferred_edges_over_limit
    python_exception: null
    severity: user
    raised_by:
      - source admission
      - okg.substrate.producer_authority.evaluate_source_run_signature
    referenced_in:
      - docs/develop/architecture/waiting-edges.md
    fix_hint_template: >-
      the run defers more edges than consistency.deferred_cap_mode allows;
      check the id prefix of the edges named in the verdict's sample, run the
      source that owns the missing records, or raise
      consistency.max_deferred_edges_per_run
    data_shape: []

  - code: source_run_grouping_timeout
    python_exception: SourceRunGroupingTimeout
    severity: fatal
    raised_by:
      - source admission
      - okg.substrate.producer_authority.evaluate_source_run_signature
    referenced_in: []
    fix_hint_template: >-
      rerun the source; if it recurs, capture the statement's plan (EXPLAIN)
      and the graph tables' statistics (pg_stat_user_tables) for the run
    data_shape: [source, run_id, record_kind, stage, timeout_ms, limit_source, elapsed_ms]

  - code: embedding_model_skew
    python_exception: null
    severity: user
    raised_by:
      - okg.substrate.mcp.semantic_readiness.assert_rankable
      # data {query_model_id, set_model_id}: the query embedder is not the
      # vector set's registered model.
      - okg.substrate.mcp.search._search_semantic_vector_set
      # The backend built for a vector set's plan is another model.
      - okg.substrate.embeddings.config.build_vector_set_plan
    fix_hint_template: >-
      query with the embedder that wrote the corpus (for a vector set, the
      set's own backend), re-embed under the query embedder, or pass
      --allow-unverified-embedding-provenance when the only problem is rows
      with no recorded model
    data_shape: [query_model_id, corpus_models, unknown_provenance_rows, set_model_id]

  - code: semantic_coverage_unmeasurable
    python_exception: null
    severity: error
    raised_by:
      - okg.substrate.mcp.semantic_readiness.probe_semantic_readiness
      - okg.substrate.mcp.semantic_readiness.resolve_node_segment
    fix_hint_template: >-
      check that the deployment has a published generation and that the chronos
      node segment is registered (`okg doctor`)
    data_shape: []

  - code: tree_sitter_grammar_missing
    python_exception: GrammarMissing
    severity: error
    raised_by:
      - TreeSitterParser.parse
    fix_hint_template: "pip install tree_sitter_{0}"
    data_shape: [language, package]

  - code: parser_not_found
    python_exception: ParserNotFound
    severity: error
    raised_by:
      - okg.substrate.library.extraction.parse.parser_for
    fix_hint_template: "register {0} via register_parser, or pick a known format"
    data_shape: [format, available]

  - code: chunker_not_found
    python_exception: ChunkerNotFound
    severity: error
    raised_by:
      - okg.substrate.library.extraction.chunk.dispatch.chunker_for
    fix_hint_template: "register {0} via register_chunker, or pick a known name"
    data_shape: [name, available]

  - code: ner_backend_not_found
    python_exception: NerBackendNotFound
    severity: error
    raised_by:
      - okg.substrate.library.extraction.ner.dispatch.ner_for
    fix_hint_template: "register {0} via register_ner, or pick a known name"
    data_shape: [name, available]

  - code: validator_not_found
    python_exception: ValidatorNotFound
    severity: error
    raised_by:
      - okg.substrate.library.extraction.validators.validator_for
    fix_hint_template: "register {0} via register_validator, or pick a known kind"
    data_shape: [kind, available]

  - code: parse_failed
    python_exception: ParseFailed
    severity: error
    raised_by:
      - okg.substrate.library.extraction.parse.json_struct.JsonParser
      - okg.substrate.library.extraction.parse.yaml_struct.YamlParser
      - okg.substrate.library.extraction.parse.toml_struct.TomlParser
    fix_hint_template: "check the input is valid {0}"
    data_shape: [format, path]

  - code: doc_corpus_not_git_work_tree
    python_exception: DocCorpusNotGitWorkTree
    severity: error
    raised_by:
      - okg.substrate.library.sources.doc_corpus.DocCorpusSource._resolve_file_enumeration
    fix_hint_template: "point repo_root at a git checkout, or set `non_git_walk: true`"
    data_shape: [repo_root, reason]

  - code: doc_corpus_oversize
    python_exception: DocCorpusOversize
    severity: error
    raised_by:
      - okg.substrate.library.sources.doc_corpus.DocCorpusSource.run
    fix_hint_template: "tighten exclude_globs or raise max_files"
    data_shape: [discovered_so_far, max_files, repo_root]

  # PACT chat-upload-source. The two "unavailable" codes are siblings on
  # purpose: a caller must be able to catch the CATEGORY (this deployment
  # has no governed upload path) without treating either arm as a reason
  # to fall back to some other storage.
  - code: upload_source_unavailable
    python_exception: UploadSourceUnavailable
    severity: error
    raised_by:
      - okg.substrate.library.sources.upload.resolve_upload_registration
    fix_hint_template: "register a Nomos-classified upload source for {0}"
    data_shape: [deployment, source_registry]

  # Each source runs in its own
  # process. These four codes name why a source child did not run or was
  # stopped; the source fails, and its dependents are skipped as before.
  - code: source_connection_budget_exhausted
    python_exception: SourceConnectionBudgetExhausted
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.source_jobs.run_source_jobs
      - okg.substrate.ingest.service._ProcessSourceJobRuntime.connection_budget_exhausted
    fix_hint_template: >-
      stop idle database clients or raise max_connections, then re-run the
      source
    data_shape: [source, live, needed, allowed, waited_seconds]

  - code: source_memory_limit_exceeded
    python_exception: SourceMemoryLimitExceeded
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.source_jobs.run_source_jobs
      - okg.substrate.ingest.service._fail_source_job
    fix_hint_template: >-
      raise OKG_SOURCE_MEMORY_LIMIT_BYTES (whole bytes, one limit for all
      sources, default 16 GiB) or narrow this source's scope, then re-run the
      source
    data_shape: [source, peak_bytes, limit_bytes]

  - code: source_run_already_active
    python_exception: SourceRunAlreadyActive
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.source_jobs.ChildJobHooks.acquire_run_lock
    fix_hint_template: >-
      find the process holding the lock in pg_locks and let it finish or stop
      it, then re-run the source
    data_shape: [source, deployment, lock_key, waited_seconds]

  - code: source_process_binding_changed
    python_exception: SourceProcessBindingChanged
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.service._run_source
    fix_hint_template: >-
      the adapter code or registry changed while the step ran; re-run the
      source so parent and child load the same binding
    data_shape: [source, parent_fingerprint, child_fingerprint]

  - code: source_run_full_retraction_refused
    python_exception: SourceRunFullRetractionRefused
    severity: user
    raised_by:
      - okg.substrate.ingest.runner.SourceRunner.run
      - okg ingest
    referenced_in: []
    fix_hint_template: >-
      check why the source read returned nothing; if the source really is
      empty, rerun once with `okg ingest --allow-full-retraction {0} --inline`;
      to decommission the source, use `okg remediate retire-source` instead
    data_shape:
      - source_name
      - registry_name
      - kind
      - live_rows
      - override_flag

  - code: source_root_missing
    python_exception: SourceRootMissing
    severity: user
    raised_by:
      - okg.substrate.library.sources.test_reports.TestReportSource
      - okg.substrate.library.sources.junit_xml.JUnitXmlSource
      - okg.substrate.library.sources.code_graph_structure.CodeStructureSource
      - okg.substrate.library.sources.doc_corpus.DocCorpusSource
    fix_hint_template: "point repo_root at an existing directory, or remove the source from the registry"
    data_shape: [source, setting, path]

  - code: source_registry_selector_absent
    python_exception: SourceRegistrySelectorAbsent
    severity: error
    raised_by:
      - okg.substrate.ingest.service.run_ingest
    fix_hint_template: >-
      remove the stale selector from queued work or restore its
      source_registry.yaml declaration
    data_shape:
      - deployment
      - absent_selectors
      - declared_source_names
      - declared_ownership_ids

  - code: console_source_registry_unreadable
    python_exception: ConsoleSourceRegistryUnreadable
    severity: user
    raised_by:
      - okg.substrate.console_views.knowledge._fetch_sources
      - GET /viz/api/console/view?id=okg_workspace.sources
    referenced_in: []
    # One hint per data.stage, served verbatim as fix_hint:
    #   load: "check that the deployment directory resolves and that its
    #     source_registry.yaml parses and is admitted; cause_type names which failed"
    #   identity_overlap: "give each source in source_registry.yaml a name and
    #     ownership_id that no other source uses"
    fix_hint_template: >-
      check that the deployment directory resolves and that its
      source_registry.yaml parses and is admitted; cause_type names which failed
    data_shape: [deployment, stage, cause_type]

  - code: upload_source_not_registered
    python_exception: UploadSourceNotRegistered
    severity: error
    raised_by:
      - okg.substrate.library.sources.upload.resolve_upload_registration
      - okg.substrate.mcp.upload_admin.load_upload_registration
    fix_hint_template: >-
      add a source with module {0} and class {1} to the deployment's
      source_registry.yaml
    data_shape: [deployment, source_registry, required_module, required_class]

  - code: upload_source_unclassified
    python_exception: UploadSourceUnclassified
    severity: error
    raised_by:
      - okg.substrate.library.sources.upload.resolve_upload_registration
    fix_hint_template: >-
      declare sensitivity, data_classification, and store_raw on the entry's
      source_policy or in nomos.source_policy_defaults
    data_shape: [deployment, source_id, missing_fields, findings]

  - code: upload_rejected
    python_exception: UploadRejected
    severity: error
    raised_by:
      - okg.substrate.library.sources.upload.UploadStaging.stage_file
      - okg.substrate.library.sources.upload.UploadStaging.stage_url
    fix_hint_template: "supply a bare file name within the size limit"
    data_shape: [origin, byte_count, max_upload_bytes]

  # PACT chat-document-loader. One code with data['reason'] carrying the arm,
  # matching the sibling chat surfaces: the operator action is always the same
  # shape — read the reason and the named input, correct it, run again.
  - code: chat_document_loader_failed
    python_exception: DocumentLoaderError
    severity: error
    raised_by:
      - okg.substrate.chat.document_loader.DocumentLoaderPlan
      - okg.substrate.chat.document_loader.DocumentLoaderPlan.resolve_token
      - okg.substrate.chat.document_loader.loader_response
    fix_hint_template: >-
      declare a loader mode, a base_url, and the NAME of the environment
      variable holding the loader token
    data_shape: [reason, deployment, token_env, mode]

  - code: predecessor_not_run
    python_exception: PredecessorNotRun
    severity: error
    raised_by:
      - okg.substrate.library.sources.doc_corpus.DocCorpusSource.run
    fix_hint_template: "run {0} via SourceRunner before this adapter"
    data_shape: [predecessor]

  - code: alias_no_active_catalog
    python_exception: AliasNoActiveCatalog
    severity: error
    raised_by:
      - okg.substrate.catalog.aliases.active_catalog_version_id
    fix_hint_template: "okg catalog load --apply --deployment <dir>"
    data_shape: []

  - code: code_extractor_not_found
    python_exception: CodeExtractorNotFound
    severity: error
    raised_by:
      - okg.substrate.library.extraction.code.dispatch.code_extractor_for
    fix_hint_template: "register a CodeSymbolExtractor for {0} via register_code_extractor"
    data_shape: [language, available]

  - code: code_parse_failed
    python_exception: CodeParseFailed
    severity: error
    raised_by:
      - okg.substrate.library.extraction.code.python_ast.PythonAstSymbolExtractor.extract
    fix_hint_template: "fix the syntax error in {0} at line {1}"
    data_shape: [path, lineno, offset]

  - code: tree_sitter_not_installed
    python_exception: TreeSitterNotInstalled
    severity: error
    raised_by:
      - okg.substrate.library.extraction.code.treesitter.TreeSitterSymbolExtractor.__init__
    fix_hint_template: "pip install tree-sitter-language-pack"
    data_shape: [language]

  - code: tree_sitter_query_missing
    python_exception: TreeSitterQueryMissing
    severity: error
    raised_by:
      - okg.substrate.library.extraction.code.treesitter.TreeSitterSymbolExtractor.__init__
    fix_hint_template: "add code/queries/{0}.scm declaring @function/@class/@import/@call captures"
    data_shape: [language, query_path_searched, available]

  - code: lsp_server_unavailable
    python_exception: LspServerUnavailable
    severity: error
    raised_by:
      - okg.substrate.library.extraction.code.lsp
    fix_hint_template: "install/configure the language server ({0}) or disable the code-lsp-resolution source"
    data_shape: [server]

  - code: lsp_protocol_error
    python_exception: LspProtocolError
    severity: error
    raised_by:
      - okg.substrate.library.extraction.code.lsp
    fix_hint_template: null
    data_shape: []

  - code: embedder_dim_mismatch
    python_exception: EmbedderDimMismatch
    severity: fatal
    raised_by:
      - embedding execution-plan preflight
      - okg_embed_batch workflow
      - semantic search
      # data {set, width, length}: a vector is not the zero-padded shape of
      # the set's width (query or backfilled document).
      - okg.substrate.semantic_ann.query_vector_for_set
      # data {set, width}: a vector set's backend does not return the set's
      # own width (PACT vector-set-pgvector-widths).
      - okg.substrate.embeddings.config.build_vector_set_plan
    referenced_in:
      - history/openspec/changes/archive/2026-05-14-rearchitect-on-postgres/embedder-decision.md
    fix_hint_template: "configure a backend that returns vectors of the declared width (zero-padded to the 2560 column width); for a vector set, embed with the set's own backend"
    data_shape: [model_id, declared_dimension, observed_dimension, substrate_dimension, set, width, length]

  - code: embedder_model_missing
    python_exception: EmbedderModelMissing
    severity: fatal
    raised_by:
      - okg doctor
      - okg_embed_batch workflow
    referenced_in:
      - history/openspec/changes/archive/2026-05-14-rearchitect-on-postgres/embedder-decision.md
    fix_hint_template: "download the model (`python -m sentence_transformers download {0}`) or configure a pre-staged model cache"
    data_shape: [model, expected_cache_path]

  # ---------- publisher / leases ----------

  - code: publisher_lock_held
    python_exception: null
    severity: recoverable
    raised_by:
      - legacy publisher lock callers
    referenced_in: []
    fix_hint_template: "wait for current publisher to finish, or investigate with `okg status --deployment {0}`"
    data_shape: [deployment_name, advisory_key, holder_pid, holder_query]

  - code: publisher_lease_held
    python_exception: PublisherLeaseHeld
    severity: recoverable
    raised_by:
      - okg run --once
      - Publisher.reserve()
    referenced_in:
      - docs/runbooks/troubleshooting/publisher-lock.md
      - docs/reference/cli.md
    fix_hint_template: "wait for the active publisher or source-sync publication to finish, then inspect `okg status --deployment {0}` before retrying"
    data_shape: [deployment_name, coordination_mode]

  # No worker took an enqueued `okg run --once` cycle off an idle partition
  # queue within the dequeue window. The call cancels its own
  # ENQUEUED row before raising, so nothing is left queued.
  - code: publisher_cycle_not_dequeued
    python_exception: PublisherCycleNotDequeued
    severity: user
    raised_by:
      - okg run --once
      - okg.substrate.runtime.admin.client_enqueue_publisher_cycle
    referenced_in: []
    fix_hint_template: "start the deployment's worker with `okg runtime worker --deployment {0}` and retry, or rerun with --inline to publish in this process"
    data_shape: [deployment, workflow_id, queue_name, dequeue_timeout_seconds, cancelled]

  - code: source_sync_already_running
    python_exception: SourceSyncAlreadyRunning
    severity: recoverable
    raised_by:
      - okg ingest
      - okg.substrate.ingest.service.run_ingest
      - okg.substrate.runtime.source_sync_priority.source_sync_run_guard
    referenced_in: []
    fix_hint_template: "wait for the other ingest to finish, or, for a queued or running runtime workflow, start the worker or cancel the stranded workflow with `okg runtime cancel-workflow`; then rerun, or raise the wait with --sync-wait-seconds or OKG_SOURCE_SYNC_RUN_WAIT_SECONDS"
    data_shape: [deployment, wait_seconds, blocking_id, holder_pids]

  - code: source_sync_signal_lost
    python_exception: SourceSyncSignalLost
    severity: recoverable
    raised_by:
      - okg ingest
      - okg.substrate.runtime.source_sync_priority.source_sync_admission_intent_workflow_id_on_connection
    referenced_in: []
    fix_hint_template: "the database session holding the signal ended (killed backend, idle timeout, or network drop); rerun the ingest"
    data_shape: [deployment, own_pid, holder_pids]

  - code: viz_read_auth_required
    python_exception: VizReadAuthRequired
    severity: user
    raised_by:
      - okg ui
      - python -m okg.viz
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "set a token in an environment variable and pass its NAME: --auth-token-env VARIABLE_NAME"
    data_shape: [deployment, reason]

  - code: catalog_apply_lease_held
    python_exception: CatalogApplyLeaseHeld
    severity: recoverable
    raised_by:
      - catalog apply
    referenced_in:
      - history/openspec/changes/archive/add-publisher-leases-with-heartbeat/proposal.md
    fix_hint_template: "wait for the active catalog apply lease to finish, or inspect lease holder {0}"
    data_shape: [lease_kind, holder_id, holder_heartbeat_at, expires_at]

  - code: unauthorized_write
    python_exception: null
    severity: user
    raised_by:
      - MCP propose (write actions, rendered Nomos deny only)
      - MCP record (write actions, rendered Nomos deny only)
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "MCP write actions require explicit Nomos authority independent of tool visibility; supply a gateway-verified claim envelope or PermissionGrant for the action. Emitted only for a rendered policy verdict; failures to evaluate surface as authority_unavailable / authority_evaluation_failed"
    data_shape: [action, authority_evidence]

  - code: authority_unavailable
    python_exception: null
    severity: recoverable
    raised_by:
      - MCP record (write actions)
      - MCP propose (write actions)
      - MCP graph-read identity/runtime authority boundary
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "authority could not be evaluated because the deployment database connection failed (dead pooled connection or pool acquisition failure); this is an infrastructure failure, not a policy denial — check the deployment database and retry"
    data_shape: [action_or_surface, authority_evidence]

  - code: authority_evaluation_failed
    python_exception: null
    severity: recoverable
    raised_by:
      - MCP record (write actions)
      - MCP propose (write actions)
      - MCP graph-read identity/runtime authority boundary
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "Nomos authority evaluation failed before rendering a verdict (non-infrastructure cause; see the nested nomos evidence); no policy decision exists for this request"
    data_shape: [action_or_surface, authority_evidence]

  - code: mcp_pool_unavailable
    python_exception: MCPPoolUnavailable
    severity: recoverable
    raised_by:
      - MCP serve path (connection pool acquisition)
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "connections as {0} cannot be established: check the role's password/grants and that the deployment DSN's server is up — `okg dogfood status --deployment <d> --json` shows the runtime state"
    data_shape: [role, database, timeout_seconds, cause]

  - code: nomos_authority_unavailable
    python_exception: null
    severity: recoverable
    raised_by:
      - MCP record/propose authority evidence (nested nomos code)
      - MCP graph-read authority evidence (nested nomos code)
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "authority evaluation hit an infrastructure failure (dead/severed database connection or pool acquisition failure); no verdict was rendered"
    data_shape: [code, message]

  - code: nomos_reserved_fact_conflict
    python_exception: NomosReservedFactConflict
    severity: fatal
    raised_by:
      - nomos.store.evaluate_runtime_boundary_with_active_policy (every runtime Nomos boundary)
      - nomos.store policy and config activation
    referenced_in: []
    fix_hint_template: "remove the named key from the request resource or context; the Nomos boundary derives deployment, scope, subject, action, classification, principal_kind, nomos_surface and nomos_boundary itself and refuses a caller value that differs"
    data_shape: [key, location, surface, deployment, scope]

  - code: nomos_boundary_request_malformed
    python_exception: NomosBoundaryRequestMalformed
    severity: fatal
    raised_by:
      - nomos.store.evaluate_runtime_boundary_with_active_policy (every runtime Nomos boundary)
      - nomos.store policy and config activation
    referenced_in: []
    fix_hint_template: "pass the request resource and context as mappings (dicts); a list of key/value pairs is refused because it would bypass the reserved-fact check"
    data_shape: [location, value_type, surface, deployment, scope]

  - code: nomos_authority_evaluation_failed
    python_exception: null
    severity: recoverable
    raised_by:
      - MCP record/propose authority evidence (nested nomos code)
      - MCP graph-read authority evidence (nested nomos code)
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "authority evaluation failed before rendering a verdict for a non-infrastructure reason; inspect the nested message"
    data_shape: [code, message]

  # `okg nomos provider add|disable|list` and `okg nomos grant
  # add|disable|list`. The
  # refusals are ValueError subclasses in okg.substrate.nomos.identity_store
  # (IdentityProviderError, PermissionGrantError and their subclasses), not
  # SubstrateError classes, so python_exception is null. Each is emitted as
  # `error_code` in the command's JSON error with exit 1.
  - code: nomos.provider.refused
    python_exception: null
    severity: user
    raised_by: [okg nomos provider add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the command registers only active providers; see the error for the refused value"
    data_shape: []

  - code: nomos.provider.exists
    python_exception: null
    severity: user
    raised_by: [okg nomos provider add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "an add never rewrites or re-enables a registered provider; register it under a new provider id"
    data_shape: []

  - code: nomos.provider.not_found
    python_exception: null
    severity: user
    raised_by: [okg nomos provider disable]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "`okg nomos provider list` shows the registered providers"
    data_shape: []

  - code: nomos.provider.oidc_auth_mismatch
    python_exception: null
    severity: user
    raised_by: [okg nomos provider add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the MCP server's OIDC start check would refuse this row; align the flags with nomos.oidc_auth or pass --for-oidc-auth"
    data_shape: []

  - code: nomos.provider.oidc_auth_undeclared
    python_exception: null
    severity: user
    raised_by: [okg nomos provider add --for-oidc-auth]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "declare nomos.oidc_auth in the deployment manifest, or pass the provider fields as flags"
    data_shape: []

  - code: nomos.provider.database_error
    python_exception: null
    severity: recoverable
    raised_by: [okg nomos provider add, okg nomos provider disable, okg nomos provider list]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the transaction was rolled back and nothing changed; retry once the database is reachable"
    data_shape: [sqlstate]

  - code: nomos.provider.commit_outcome_unknown
    python_exception: null
    severity: recoverable
    raised_by: [okg nomos provider add, okg nomos provider disable]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the COMMIT failed, so the change may or may not be saved; run `okg nomos provider list`"
    data_shape: [sqlstate]

  - code: nomos.grant.refused
    python_exception: null
    severity: user
    raised_by: [okg nomos grant add, okg nomos grant disable]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "base code of the grant refusals; see the error"
    data_shape: []

  - code: nomos.grant.exists
    python_exception: null
    severity: user
    raised_by: [okg nomos grant add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "an add never rewrites or re-enables a grant; disable it and add a new grant id"
    data_shape: []

  - code: nomos.grant.not_found
    python_exception: null
    severity: user
    raised_by: [okg nomos grant disable]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "`okg nomos grant list` shows the grants"
    data_shape: []

  - code: nomos.grant.widens_access
    python_exception: null
    severity: user
    raised_by: [okg nomos grant disable, okg nomos grant add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the change would admit requests a deny grant blocks (a deny disabled, or an allow that decides first); pass --allow-widen if that is intended"
    data_shape: []

  - code: nomos.grant.shadowed
    python_exception: null
    severity: user
    raised_by: [okg nomos grant add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "an overlapping allow grant decides first; give the deny a higher --priority"
    data_shape: []

  - code: nomos.grant.unknown_match
    python_exception: null
    severity: user
    raised_by: [okg nomos grant add]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "a deny grant naming an unknown action or --match key would block nothing; correct the name"
    data_shape: []

  - code: nomos.grant.database_error
    python_exception: null
    severity: recoverable
    raised_by: [okg nomos grant add, okg nomos grant disable, okg nomos grant list]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the transaction was rolled back and nothing changed; retry once the database is reachable"
    data_shape: [sqlstate]

  - code: nomos.grant.commit_outcome_unknown
    python_exception: null
    severity: recoverable
    raised_by: [okg nomos grant add, okg nomos grant disable]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "the COMMIT failed, so the change may or may not be saved; run `okg nomos grant list`"
    data_shape: [sqlstate]

  - code: nomos_declared_classification_invalid
    python_exception: DeclaredClassificationInvalid
    severity: user
    raised_by:
      - MCP record/propose authority evidence (nested nomos code)
      - MCP graph-read identity authority boundary
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "authority.classification may only raise the server-side classification; omit it, or declare a known class ranked above the server's"
    data_shape: [surface, server_classification, declared_classification]

  - code: nomos_client_policy_override_refused
    python_exception: ClientPolicyOverrideRefused
    severity: user
    raised_by:
      - MCP record/propose authority evidence (nested nomos code)
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "drop authority.nomos_bundle_path / policy_bundle_path, and any nomos_scope or nomos_resource fact that differs from the server's; the server evaluates the deployment's active policy bundle with its own scope and resource facts"
    data_shape: [surface, fields]

  - code: schema_migration_checksum_mismatch
    python_exception: null
    severity: fatal
    raised_by:
      - okg doctor (schema_migrations check)
      - okg db status
    referenced_in:
      - docs/operate/deployments/database.md
    fix_hint_template: "a committed migration file's checksum no longer matches the ledger; inspect the migration files and ledger before migrating"
    data_shape: [database, observed, expected]

  - code: schema_migration_postcondition_drift
    python_exception: null
    severity: fatal
    raised_by:
      - okg doctor (schema_migrations check)
      - okg db status
      - okg db migrations
    referenced_in:
      - docs/operate/deployments/database.md
    fix_hint_template: "an applied destructive migration's recorded postcondition no longer holds against this database; reconcile the ledger before trusting migration status"
    data_shape: [database, observed, expected]

  - code: catalog_ownership_mismatch
    python_exception: CatalogOwnershipMismatch
    severity: fatal
    raised_by:
      - okg catalog load --apply
      - okg catalog ownership diagnose
      - okg run --once
      - Publisher.reserve()
    referenced_in:
      - pact/changes/harden-workspace-catalog-ownership/pact.md
    fix_hint_template: "use an isolated worktree DB, or run the catalog ownership repair/claim workflow intentionally"
    data_shape: [deployment_name, expected, observed]

  - code: catalog_writer_scope_required
    python_exception: null
    severity: fatal
    raised_by:
      - okg.substrate.catalog.ownership.catalog_identity_for
      - okg.substrate.catalog.ownership.resolve_catalog_for_publish
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "select deployment_root or environment writer authority explicitly"
    data_shape: [reason_code]

  - code: catalog_writer_scope_invalid
    python_exception: null
    severity: fatal
    raised_by:
      - okg.substrate.catalog.ownership.catalog_identity_for
      - okg.substrate.catalog.ownership.resolve_catalog_for_publish
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "select deployment_root or environment writer authority explicitly"
    data_shape: [reason_code]

  - code: catalog_environment_identity_required
    python_exception: null
    severity: fatal
    raised_by:
      - okg catalog load
      - okg catalog ownership diagnose
      - okg catalog ownership claim
      - okg.substrate.catalog.ownership.resolve_catalog_for_publish
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "pass an explicit environment id with environment writer scope"
    data_shape: [reason_code]

  - code: catalog_writer_scope_ambiguous
    python_exception: null
    severity: fatal
    raised_by:
      - okg catalog load
      - okg catalog ownership diagnose
      - okg catalog ownership claim
      - okg.substrate.catalog.ownership.resolve_catalog_for_publish
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "select exactly one writer scope and its required identity"
    data_shape: [reason_code, environment_id, writer_scope]

  - code: catalog_writer_scope_conflict
    python_exception: null
    severity: fatal
    raised_by:
      - okg.substrate.catalog.ownership.resolve_catalog_for_publish
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "build catalog identity from the same resolved deployment passed to the publisher"
    data_shape: [deployment_name, identity_deployment_name, provenance_deployment_name, reason_code]

  - code: catalog_writer_scope_change
    python_exception: null
    severity: fatal
    raised_by:
      - okg catalog load --apply
      - okg catalog ownership claim
      - Publisher.reserve()
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "use the recorded writer scope or explicitly authorize a reviewed scope change"
    data_shape: [deployment_name, expected, observed, reason_code]

  - code: catalog_ownership_unclaimed
    python_exception: null
    severity: fatal
    raised_by:
      - okg catalog load --apply
      - Publisher.reserve()
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "diagnose and explicitly claim catalog ownership before writing or publishing"
    data_shape: [deployment_name, expected, observed, reason_code]

  - code: catalog_ownership_foreign_writer
    python_exception: null
    severity: fatal
    raised_by:
      - okg catalog load --apply
      - okg catalog ownership claim
      - Publisher.reserve()
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "use an isolated database or repair ownership only after reviewing the recorded writer"
    data_shape: [deployment_name, expected, observed, reason_code]

  - code: catalog_manifest_drifted
    python_exception: null
    severity: fatal
    raised_by:
      - Publisher.reserve()
      - okg ingest (staged-source redrive)
    referenced_in:
      - pact/changes/staged-redrive-surfaces-cause/pact.yaml
    fix_hint_template: "re-claim catalog ownership from the publishing directory; okg catalog load --apply does not refresh a drifted manifest fingerprint"
    data_shape: [deployment_name, expected, observed, reason_code]

  - code: catalog_applied_version_absent
    python_exception: null
    severity: fatal
    raised_by:
      - Publisher.reserve()
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "apply the catalog with the same explicit writer authority before publishing"
    data_shape: [deployment_name, expected, observed, reason_code]

  - code: catalog_applied_version_incompatible
    python_exception: null
    severity: fatal
    raised_by:
      - Publisher.reserve()
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "resolve the competing writer before reapplying this catalog"
    data_shape: [deployment_name, expected, observed, reason_code]

  - code: catalog_environment_identity_ambiguous
    python_exception: null
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog ownership diagnose
      - okg catalog ownership claim
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "pass one environment id instead of a graph deployment name"
    data_shape: [reason_code, graph_deployment_name, environment_ids]

  - code: catalog_environment_invalid
    python_exception: null
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog ownership diagnose
      - okg catalog ownership claim
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "repair the environment descriptor before catalog access"
    data_shape: [reason_code, deployment_ref, resolution_error_type]

  - code: deployment_config_invalid
    python_exception: null
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog ownership diagnose
      - okg catalog ownership claim
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "repair the deployment manifest before catalog access"
    data_shape: [reason_code, deployment_ref, resolution_error_type]

  - code: identifier_kind_mismatch
    python_exception: null
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog ownership diagnose
      - okg catalog ownership claim
    referenced_in:
      - pact/changes/issue-1303-catalog-ownership-scope/pact.yaml
    fix_hint_template: "pass the environment id when environment writer authority is selected"
    data_shape: [reason_code, supplied_identifier_kind, expected_identifier_kind]

  - code: deployment_owner_mismatch
    python_exception: DeploymentOwnerMismatch
    severity: fatal
    raised_by:
      - okg run --once
      - Publisher.reserve()
    referenced_in:
      - pact/changes/enforce-db-owner-stamp-at-write-boundary/pact.yaml
    fix_hint_template: "publish into this deployment's OWN database (check OKG_DSN / the deployment manifest's postgres.dsn); never point a process at another deployment's DB"
    data_shape: [owner_deployment_name, claimed_deployment_name, resident_deployments]

  - code: lease_lost
    python_exception: LeaseLostError
    severity: fatal
    raised_by:
      - publisher heartbeat
      - catalog apply heartbeat
    referenced_in:
      - docs/runbooks/troubleshooting/publisher-lock.md
      - history/openspec/changes/archive/add-publisher-leases-with-heartbeat/proposal.md
    fix_hint_template: "abort the current worker and inspect the replacement lease holder before retrying"
    data_shape: [lease_kind, lease_id, holder_id, lease_seq]

  - code: phase_a_timeout
    python_exception: PhaseATimeout
    severity: recoverable
    raised_by:
      - Publisher.await_phase_a()
    referenced_in:
      - docs/develop/architecture/pipeline.md
    fix_hint_template: "inspect per_source_status for TIMED_OUT entries; pause the slow source or raise the timeout"
    data_shape: [per_source_status, timeout_seconds]

  - code: gate_timeout
    python_exception: GateTimeout
    severity: recoverable
    raised_by:
      - Publisher.run_gates()
    referenced_in:
      - src/okg/AGENTS.md
      - docs/develop/architecture/consistency.md
      - docs/reference/alerts.yaml
    fix_hint_template: "inspect graph_generations.blocked_reason for the offending invariant; tune its statement_timeout or SQL"
    data_shape: [invariant_name, elapsed_ms, budget_ms]

  # ---------- fact / projection correctness ----------

  - code: narrowing_violation
    python_exception: NarrowingViolation
    severity: recoverable
    raised_by:
      - ingest worker (writer path)
      - link worker (writer path)
      - enrich worker (writer path)
    referenced_in:
      - src/okg/AGENTS.md
      - docs/develop/architecture/consistency.md
    fix_hint_template: "add the triple to schemas/narrowings.yaml, or fix the source/extractor emitting it"
    data_shape: [src_subtype, edge_type, dst_subtype, catalog_version_id]

  # ---------- anonymization / privacy ----------

  - code: pseudonym_key_unavailable
    python_exception: PseudonymKeyUnavailable
    severity: user
    raised_by:
      - pseudonymization service (at-rest transform / read masking)
    referenced_in:
      - docs/develop/architecture/privacy.md
    fix_hint_template: "set OKG_PSEUDONYM_HMAC_KEY (>=16 bytes) from the deployment secret store; no default key is used"
    data_shape: []

  - code: unresolved_entity_held
    python_exception: UnresolvedEntityHeld
    severity: recoverable
    raised_by:
      - pseudonymization service (alias-cascade composition)
    referenced_in:
      - docs/develop/architecture/privacy.md
    fix_hint_template: "the alias cascade could not resolve the entity; the fact is held (never surface-keyed or stored raw) until resolution improves"
    data_shape: []

  - code: presidio_unavailable
    python_exception: PresidioUnavailable
    severity: user
    raised_by:
      - free-text PII detector (at-rest enricher pass)
    referenced_in:
      - docs/develop/architecture/privacy.md
    fix_hint_template: "install the `privacy` extra (presidio-analyzer) and its NLP model, or a not-store-raw source with free text will hold"
    data_shape: []

  - code: pii_facts_held
    python_exception: PiiFactsHeld
    severity: recoverable
    raised_by:
      - source runner at-rest transform (admission chokepoint)
    referenced_in:
      - docs/develop/architecture/privacy.md
    fix_hint_template: "a not-store-raw source emitted free text with no PII detector installed; the run held the source watermark (no raw stored) -- install the `privacy` extra, then the held facts re-process"
    data_shape:
      - held
      - reason

  - code: branch_not_registered
    python_exception: BranchNotRegistered
    severity: recoverable
    raised_by:
      - publisher (Publisher.reserve)
    referenced_in:
      - history/openspec/changes/archive/fix-akmon-design-mistakes/specs/okg-support/spec.md
    fix_hint_template: "create the branch first via `okg branch create <name> --deployment <deployment> --role <role>`; or check the suggested similar-named branches"
    data_shape: [deployment_name, branch_name, suggestions]

  - code: merge_refused
    python_exception: MergeRefused
    severity: recoverable
    raised_by:
      - ChronosGraphStore.merge (worktree-fork-merge-back safety gate)
    fix_hint_template: "forks must share a base with the target (do not `okg branch compact` then merge); merge into default requires a named-human accept from `okg admission decide`"
    data_shape: [source, target, reason]

  - code: retraction_not_permitted
    python_exception: RetractionNotPermitted
    severity: recoverable
    raised_by:
      - ingest worker
    referenced_in:
      - docs/develop/architecture/consistency.md
    fix_hint_template: "run in reconcile mode, or choose a profile with deletion_semantics that permits retraction"
    data_shape: [source, mode, deletion_semantics]

  - code: dedupe_collision
    python_exception: null   # not an exception; observable via metrics
    severity: user
    raised_by:
      - (noop; UNIQUE constraint on fact table)
    referenced_in:
      - src/okg/AGENTS.md
      - docs/runbooks/troubleshooting/source-poisoning.md
    fix_hint_template: null
    data_shape: [source, source_record_id, source_revision]

  - code: invariant_sample_unidentifiable
    python_exception: InvariantSampleUnidentifiable
    severity: recoverable
    raised_by:
      - Phase B evaluator
    referenced_in:
      - docs/develop/architecture/pipeline.md
    fix_hint_template: "ensure the invariant SQL body selects node_id or edge_id in every returned row"
    data_shape: [invariant_name, offending_row]

  - code: node_not_found
    python_exception: NodeNotFound
    severity: user
    raised_by:
      - MCP inspect
    referenced_in:
      - history/openspec/changes/archive/2026-04-26-debug-substrate-okg-self
    fix_hint_template: "node_id {0} is not visible at generation {1}; check the pin or the node id"
    data_shape: [node_id, generation_id]

  # ---------- authored-file validation ----------

  - code: profile_mismatch
    python_exception: ProfileMismatch
    severity: user
    raised_by:
      - okg catalog load
    referenced_in:
      - src/okg/AGENTS.md
    fix_hint_template: "inspect the source's adapter at src/okg/substrate/library/sources/{0}.py for its declared profile, or pick a profile matching your source's shape"
    data_shape: [source_name, offending_tuple, allowed_profiles]

  - code: library_ref_missing
    python_exception: LibraryRefMissing
    severity: user
    raised_by:
      - okg catalog load
    referenced_in:
      - src/okg/AGENTS.md
    fix_hint_template: "`okg library list` or `okg library show <ref>` for current inventory"
    data_shape: [reference, alternatives]

  - code: schema_validation_failed
    python_exception: SchemaValidationFailed
    severity: user
    raised_by:
      - okg catalog load
      - okg doctor --check schema
    referenced_in:
      - src/okg/AGENTS.md
    fix_hint_template: "fix the JSON/YAML at {0} or run `okg schema {1}` to see the schema"
    data_shape: [file, schema_name, errors]

  - code: bootstrap_plan_invalid
    python_exception: BootstrapPlanInvalid
    severity: user
    raised_by:
      - okg deployment bootstrap plan
      - okg deployment bootstrap inspect-source
      - okg deployment bootstrap draft
      - okg deployment bootstrap verify
      - okg deployment bootstrap apply
    referenced_in:
      - history/openspec/changes/archive/2026-05-19-add-deployment-bootstrapper
      - src/okg/AGENTS.md
    fix_hint_template: "fix bootstrap_plan.yaml at {0}; the schema is at src/okg/substrate/deployments/bootstrap_plan_schema.json"
    data_shape: [path, errors]

  - code: bootstrap_source_sample_failed
    python_exception: BootstrapSourceSampleFailed
    severity: user
    raised_by:
      - okg deployment bootstrap inspect-source
      - okg deployment bootstrap verify
    referenced_in:
      - history/openspec/changes/archive/2026-05-19-add-deployment-bootstrapper
      - src/okg/AGENTS.md
    fix_hint_template: "point source {0} at a bounded fixture/sample path, or explicitly enable live sampling"
    data_shape: [source_id, sample_path, reason]

  - code: bootstrap_draft_invalid
    python_exception: BootstrapDraftInvalid
    severity: user
    raised_by:
      - okg deployment bootstrap draft
      - okg deployment bootstrap verify
    referenced_in:
      - history/openspec/changes/archive/2026-05-19-add-deployment-bootstrapper
      - src/okg/AGENTS.md
    fix_hint_template: "fix staged artifact {0}, then rerun `okg deployment bootstrap draft --apply`"
    data_shape: [path, stage, errors]

  - code: bootstrap_catalog_rejected
    python_exception: BootstrapCatalogRejected
    severity: user
    raised_by:
      - okg deployment bootstrap verify
    referenced_in:
      - history/openspec/changes/archive/2026-05-19-add-deployment-bootstrapper
      - src/okg/AGENTS.md
    fix_hint_template: "fix ontology modules, subtypes, or bridge narrowings in the staged schemas"
    data_shape: [stage, path, error]

  - code: bootstrap_publish_blocked
    python_exception: BootstrapPublishBlocked
    severity: recoverable
    raised_by:
      - okg deployment bootstrap verify
    referenced_in:
      - history/openspec/changes/archive/2026-05-19-add-deployment-bootstrapper
      - src/okg/AGENTS.md
    fix_hint_template: "inspect generation {0}, fix the reported substrate stage, and rerun bootstrap verify"
    data_shape: [stage, generation_id, error]

  - code: bootstrap_unverified_apply
    python_exception: BootstrapUnverifiedApply
    severity: user
    raised_by:
      - okg deployment bootstrap apply
    referenced_in:
      - history/openspec/changes/archive/2026-05-19-add-deployment-bootstrapper
      - src/okg/AGENTS.md
    fix_hint_template: "rerun `okg deployment bootstrap verify` so staged file hashes match the verified plan"
    data_shape: [changed_files, missing_files]

  - code: external_deployments_dir_not_configured
    python_exception: ExternalDeploymentsDirNotConfigured
    severity: user
    raised_by:
      - okg deployment nomos-rollout-audit
      - okg deployment nomos-source-lineage-rollout-audit
    referenced_in:
      - pact/changes/deployment-config-hygiene
    fix_hint_template: "pass --deployment-dir, set OKG_DEPLOYMENTS_DIR, or run `okg fetch-deployments` to populate the cache"
    data_shape: [checked]

  # ---------- catalog migration ----------

  - code: catalog_migration_refused
    python_exception: CatalogMigrationRefused
    severity: user
    raised_by:
      - okg catalog load --apply
    referenced_in:
      - src/okg/AGENTS.md
    fix_hint_template: "review the {0} non-additive change(s) via a bare 'okg catalog load' (dry-run classification), then make them additive or follow docs/runbooks/troubleshooting/ontology-rollback.md"
    data_shape: [non_additive_changes, violator_counts]

  - code: catalog_migration_in_progress
    python_exception: CatalogMigrationInProgress
    severity: user
    raised_by:
      - okg catalog load --apply
    referenced_in:
      - docs/runbooks/troubleshooting/ontology-rollback.md
    fix_hint_template: "mark catalog_version {0} rolled_back via SQL, then re-run `okg catalog load --deployment <dir> --apply` (see docs/runbooks/troubleshooting/ontology-rollback.md)"
    data_shape: [catalog_version_id, applied_count, total_count]

  - code: catalog_module_missing
    python_exception: CatalogModuleMissing
    severity: user
    raised_by:
      - okg catalog load
    referenced_in:
      - history/openspec/changes/archive/2026-04-26-migrate-okg-self-to-substrate
    fix_hint_template: "module {0} has no schema at src/okg/substrate/library/ontologies/{0}/schema.yaml; check the deployment's modules: list"
    data_shape: [module_name, expected_path]

  - code: bridge_subtype_unknown
    python_exception: BridgeSubtypeUnknown
    severity: user
    raised_by:
      - okg catalog load
    referenced_in:
      - history/openspec/changes/archive/2026-04-26-migrate-okg-self-to-substrate
    fix_hint_template: "bridge narrowing references subtype {0} not declared by any loaded module or deployment schema"
    data_shape: [subtype_name, bridge_path, narrowing_name]

  - code: narrowing_schema_misplaced
    python_exception: NarrowingSchemaMisplaced
    severity: user
    raised_by:
      - okg catalog load
      - okg deployment lint
    referenced_in:
      - pact/changes/issue-1282-narrowing-placement-lint
    fix_hint_template: "move {schema_path} to {expected_path} as a direct bridge file without overwriting an existing target"
    data_shape: [schema_path, expected_path, schema_dir]

  - code: narrowing_bridge_directory_symlink
    python_exception: NarrowingBridgeDirectorySymlink
    severity: user
    raised_by:
      - okg catalog load
      - okg deployment lint
    referenced_in:
      - pact/changes/issue-1282-narrowing-placement-lint
    fix_hint_template: "replace the {bridges_path} symlink with a real directory and place canonical bridge YAML files directly inside it"
    data_shape: [bridges_path, schema_dir]

  - code: catalog_refinement_cycle
    python_exception: CircularRefinementError
    severity: user
    raised_by:
      - okg catalog load --apply
    referenced_in:
      - src/okg/substrate/catalog/modules_apply.py
    fix_hint_template: "remove or rewrite the subtype `is_a` link that forms cycle {cycle}"
    data_shape: [cycle]

  - code: module_manifest_invalid
    python_exception: ManifestError
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - history/openspec/changes/archive/add-module-manifests-and-composition
    fix_hint_template: "fix the `module.yaml` at {manifest_path} (missing or malformed key: {key})"
    data_shape: [manifest_path, key]

  - code: composition_resolver_error
    python_exception: ResolverError
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - history/openspec/changes/archive/add-module-manifests-and-composition
    fix_hint_template: "cross-link rule {rule_id} in {rule_file} references subtype {unresolved_subtype} provided by no loaded module; add the providing module to the deployment's modules: list or remove the rule"
    data_shape: [rule_file, rule_id, unresolved_subtype, endpoint, source_module, target_module]

  # ----- module providers -----
  # Catalog composition resolves each `modules:` entry against a provider
  # keyed by owner, so nothing falls through and no search order decides.

  - code: module_provider_unresolved
    python_exception: ModuleProviderError
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - pact/changes/module-providers-in-composition
    fix_hint_template: "spell the entry as `name` for a built-in module or `owner:name` for an installed owner, or install the owner's distribution"
    # The payload names whichever input was rejected, so no key is present at
    # every raise site: a reference carries `module_ref` (plus `owner` and
    # `available_owners` when the owner is unknown), a malformed provider
    # mapping carries `key`/`declared_owner` or `owner`, and passing both
    # inputs carries `owners`/`modules_root`.
    data_shape: []

  - code: duplicate_semantic_ownership
    python_exception: CrossOwnerSubtypeCollision
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - pact/changes/module-providers-in-composition
    fix_hint_template: "rename the subtype in one owner's module, or drop one of the two modules from the deployment's modules: list"
    # Two owners declare one subtype. The composition path raises the class
    # above before any catalog mutation; the typed-asset path in
    # deployment_product_composition.py spells the same code as a semantic
    # diagnostic row, so operators read one collision vocabulary. Same-owner
    # cross-declaration is NOT a collision and is not reported here.
    data_shape: [phase, subtype, owners, collisions]

  # ----- package-backed module provider ----- A verified distribution package supplies ontology modules by
  # declared id out of its content-addressed object store.

  - code: module_identity_not_nfc
    python_exception: ModuleIdentityNotNormalized
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - pact/changes/package-backed-module-provider
    fix_hint_template: "spell {field} in Unicode NFC ({nfc_form}); a decomposed spelling is a different identity here"
    # A packaged module id is sealed into the package release digest over the
    # bytes as written, so a non-NFC spelling is refused where it is declared
    # rather than folded away when two ids are compared.
    data_shape: [field, value, nfc_form]

  - code: module_path_escapes_provider_root
    python_exception: ModulePathEscapesProviderRoot
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - pact/changes/package-backed-module-provider
    fix_hint_template: "keep the module directory inside {provider_root}; a symlink out of the root is not followed"
    data_shape: [owner, module_name, provider_root, resolved_path]

  - code: package_module_undeclared
    python_exception: PackagedModuleUndeclared
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - pact/changes/package-backed-module-provider
    fix_hint_template: "declare {module_id} in the package manifest's module_declarations, or drop it from the deployment's modules: list"
    data_shape: [module_id, owner, module_name, declared_modules]

  - code: package_module_owner_collision
    python_exception: PackagedModuleOwnerCollision
    severity: user
    raised_by:
      - okg deployment install-plan
      - okg catalog load
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "give each declared {segment} a distinct identity; two that differ only by case collide on a case-insensitive filesystem"
    # Two declarations resolve to one staging directory: a repeated module
    # id, or two owners a case-insensitive filesystem folds together. The
    # manifest keeps them as distinct sealed identities, so staging them
    # into one tree would stop being injective with the declarations.
    data_shape: [segment, module_id, first, second, staging_path]

  # ----- install plan and lock ----- `okg deployment install-plan` turns a verified package and a
  # bundle into a plan and a lock. It composes the catalog in memory to
  # validate, writes only those two documents, and performs no runtime effect.
  # Every refusal below is raised before either document is written.

  - code: install_plan_refused
    python_exception: InstallPlanError
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: null
    # The base class every refusal below specializes. It is raised directly
    # only for a malformed instance config, and its payload differs by
    # branch: an unrecognized key carries `unknown_keys` and `accepted_keys`,
    # a non-mapping `secrets` carries neither. Nothing is present at every
    # raise site, so the shape is empty.
    data_shape: []

  - code: install_output_path_exists
    python_exception: InstallOutputPathExists
    severity: user
    raised_by:
      - okg deployment install-plan
      - okg deployment install-receipt
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
      - pact/changes/distribution-lifecycle-receipts
    fix_hint_template: "name an unused output directory, or point --output at a prior install of the same package"
    data_shape: [output_dir]

  - code: install_bundle_unknown
    python_exception: InstallBundleUnknown
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "select one of the bundles the package declares"
    data_shape: [bundle_id, declared_bundles]

  - code: install_okg_incompatible
    python_exception: InstallOkgIncompatible
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "install an OKG release inside the declared window"
    # `declared` is null when the package declares no window, which only a
    # package v1 or a v2 that omits okg_compatibility can do; in that case
    # the refusal came from an undeterminable running version instead.
    data_shape: [package_error_code, declared]

  - code: install_package_unverified
    python_exception: InstallPackageUnverified
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "re-fetch the package; its bytes do not match its digests"
    data_shape: [package_error_code, logical_path]

  - code: install_declared_asset_missing
    python_exception: InstallDeclaredAssetMissing
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "rebuild the package so every selected asset reference resolves"
    # Spelled to match the landed conformance code
    # conformance_distribution_declared_asset_missing, so a refusal here and
    # the receipt arm reporting it read as one vocabulary.
    data_shape: [bundle_id]

  - code: install_secret_reference_unresolved
    python_exception: InstallSecretReferenceUnresolved
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "export the referenced variable before planning; an absent reference is refused rather than defaulted"
    # Never carries a secret value. `reason` is environment_variable_absent
    # for an unset reference, which also carries `reference`, or
    # not_a_reference when the instance config supplied a literal instead --
    # that branch deliberately omits `reference`, because the value it would
    # name is the literal secret. Only the two keys below are always present.
    data_shape: [secret_name, reason]

  - code: install_secret_declaration_unselected
    python_exception: InstallSecretDeclarationUnselected
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/s14-1794-secretref-producer
    fix_hint_template: "bind the secret to a selected source or tool declaration, written as its owner-qualified id"
    # Never carries a secret value or the environment variable name.
    # `reason` is declaration_malformed when the declaration is not an
    # owner-qualified id (that branch knows no resolvable declaration and
    # so omits `declaration_ref`), declaration_unselected when the bundle
    # does not select it (adds `declaration_ref` and `selected_asset_refs`),
    # or declaration_kind_unsupported when it is selected but declares no
    # credential (adds `declaration_ref`, `declaration_kind` and
    # `accepted_kinds`). Only the two keys below are present at every
    # raise site.
    data_shape: [secret_name, reason]

  - code: install_lock_drift
    python_exception: InstallLockDrift
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/distribution-install-plan-and-lock
    fix_hint_template: "re-run with --replace-lock to accept the new resolution"
    data_shape: [output_dir, recorded_lock_digest, resolved_lock_digest]

  - code: install_postgres_dsn_unreachable
    python_exception: null
    severity: user
    raised_by:
      - okg install
    referenced_in:
      - pact/changes/fix-install-postgres-dsn-honored
    fix_hint_template: "start the database named by --postgres-dsn, or drop the flag to let the installer provision Docker Postgres"
    data_shape: [postgres_dsn, stage]

  - code: install_postgres_dsn_unusable
    python_exception: null
    severity: user
    raised_by:
      - okg install
    referenced_in:
      - pact/changes/fix-install-postgres-dsn-honored
    fix_hint_template: "grant the role CREATE on the database, and CREATE on schema public only when an extension still has to be installed there, grant CREATEROLE or ADMIN OPTION on the roles the migration creates and grants, install the required extensions, or drop --postgres-dsn to let the installer provision Docker Postgres"
    data_shape: [postgres_dsn, stage, missing_privileges, missing_extensions, missing_roles, missing_schema]

  - code: install_connector_asset_malformed
    python_exception: InstallConnectorAssetMalformed
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/sdk-range-at-install-resolve
    fix_hint_template: "rebuild the asset with as_asset_payload() from the SDK version the package declares"
    # One arm or the other, never both, so only `asset_ref` is present at
    # every raise site: unreadable bytes carry `reason` (the exception type),
    # and a body that parses but does not read back as a registration carries
    # `registration_error_code` (the declaration-time SDK code).
    data_shape: [asset_ref]

  - code: install_connector_vocabulary_unknown
    python_exception: InstallConnectorVocabularyUnknown
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/sdk-range-at-install-resolve
    fix_hint_template: "declare only capabilities and auth modes this OKG release implements"
    # `capability` or `auth_mode` carries the offending value, whichever
    # vocabulary refused -- one or the other, never both, so neither is
    # listed below. The four keys that are always present are.
    data_shape: [asset_ref, registration_error_code, connector_type, allowed]

  - code: install_connector_sdk_bound_invalid
    python_exception: InstallConnectorSdkBoundInvalid
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/sdk-range-at-install-resolve
    fix_hint_template: "declare plain release bounds; the running build is compared by its base release"
    data_shape: [asset_ref, registration_error_code, field, value]

  - code: install_connector_sdk_unsupported
    python_exception: InstallConnectorSdkUnsupported
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/sdk-range-at-install-resolve
    fix_hint_template: "install an OKG release inside the connector's declared window"
    data_shape: [asset_ref, connector_type, sdk_version, min_version, max_version_exclusive]

  - code: install_connector_required_module_missing
    python_exception: InstallConnectorRequiredModuleMissing
    severity: user
    raised_by:
      - okg deployment install-plan
    referenced_in:
      - pact/changes/sdk-range-at-install-resolve
    fix_hint_template: "select a bundle carrying the module, or name it in the instance config"
    data_shape: [asset_ref, connector_type, missing_modules, resolved_modules]

  - code: lifecycle_receipt_refused
    python_exception: LifecycleReceiptError
    severity: user
    raised_by:
      - okg deployment install-receipt
      - "okg.substrate.distributions.lifecycle_receipts (library)"
    referenced_in:
      - pact/changes/distribution-lifecycle-receipts
    fix_hint_template: "pair the receipts written for one upgrade-and-revert event"
    # Every branch names why the inputs contradict each other and nothing
    # else is common: a baseline or candidate side that disagrees between
    # the two receipts, a rollback receipt that does not record the
    # baseline package as present, a drift comparison where either lock
    # carries no digest, or a legacy inventory entry missing an input id,
    # carrying a disposition other than migrated or refused, or naming an
    # input the inventory already declared.
    data_shape: [reason]

  - code: upgrade_okg_range_broken
    python_exception: UpgradeOkgRangeBroken
    severity: user
    raised_by:
      - okg deployment install-receipt
    referenced_in:
      - pact/changes/distribution-lifecycle-receipts
    fix_hint_template: "upgrade OKG into the candidate's window first, or select a candidate package whose window covers this build"
    data_shape: [okg_version, declared, reason]

  - code: rollback_baseline_package_missing
    python_exception: RollbackBaselinePackageMissing
    severity: user
    raised_by:
      - okg deployment install-receipt
    referenced_in:
      - pact/changes/distribution-lifecycle-receipts
    fix_hint_template: "restore the baseline package bytes before recording the rollback; the receipt must name a release that can still be verified"
    data_shape: [expected_filename, observed_name, present, reason]

  - code: rollback_candidate_not_distinct
    python_exception: RollbackCandidateNotDistinct
    severity: user
    raised_by:
      - okg deployment install-receipt
    referenced_in:
      - pact/changes/distribution-lifecycle-receipts
    fix_hint_template: "name the release that was activated, not the one it replaced"
    data_shape: [sealed_release_artifact_id, reason]

  - code: conformance_profile_refused
    python_exception: ConformanceProfileError
    severity: user
    raised_by:
      - "okg deployment conformance validate (reported as valid: false, exit 1)"
      - "okg.substrate.distributions.conformance_diagnostics (library)"
    referenced_in:
      - pact/changes/s14-1794-conformance-rules
    fix_hint_template: "produce the diagnostic with the settled profile helper; a contract-valid receipt that mixes a credential failure with a missing environment or a deferred binding is refused"
    # A receipt that passes the wire contract but breaks a settled profile
    # (issue 1794): a credential failure outside first_publish/apply or naming
    # an unselected or deferred declaration, an unknown failure or gap token,
    # a runtime gap owned by the distribution or consumer, or a reference
    # wider than the wire identifier shape.
    data_shape: [code, path, reason]

  - code: conformance_evidence_refused
    python_exception: ConformanceEvidenceError
    severity: user
    raised_by:
      - "okg.substrate.distributions.conformance_evidence (library)"
    referenced_in:
      - pact/changes/s14-1185-hermetic-evidence-producers
    fix_hint_template: "measure the value and pass it, or report the arm's real outcome; the evidence producers have no default and will not derive a count they were not given"
    # A conformance evidence block could not be built from the run's
    # measurements: an absent measurement, a claimed count that does not equal
    # the read-back count, a publish that never published, a reapply that
    # moved a row, a generation or pointer, a readiness block claiming ready
    # while its doctor is not clean, or a materialized asset that is missing,
    # undeclared or byte-different from the verified package's.
    data_shape: [block, path, reason]

  - code: legacy_inventory_not_supplied
    python_exception: LegacyInventoryNotSupplied
    severity: user
    raised_by:
      - "okg.substrate.distributions.lifecycle_receipts (library)"
    referenced_in:
      - pact/changes/distribution-lifecycle-receipts
    fix_hint_template: "supply the real legacy deployment's declared inputs, each with a migrated or refused disposition, or leave the legacy_authority arm unclaimed"
    data_shape: [reason]

  - code: release_module_provenance_mismatch
    python_exception: ReleaseModuleProvenanceMismatch
    severity: user
    raised_by:
      - okg environment activate-release
    referenced_in:
      - pact/changes/module-provider-release-provenance
    fix_hint_template: "install the package the release was sealed from, or seal a new release against the package that is installed now"
    # The payload differs by branch, so nothing is present at every raise
    # site and the shape is empty. The comparison branch carries `phase`,
    # `command`, `module_id`, a `reason` of module_not_in_release,
    # module_no_longer_supplied or provider_digest_changed, and the
    # recorded/resolved release-digest and object-digest pairs, null on
    # the side with no entry. The parse branch -- recorded provenance that
    # is not a list of entries naming a module -- carries `observed` only,
    # because a malformed record names no module to report.
    data_shape: []

  - code: upgrade_module_provider_owner_dropped
    python_exception: UpgradeModuleProviderDropped
    severity: user
    raised_by:
      - okg deployment up
    referenced_in:
      - pact/changes/module-provider-release-provenance
    fix_hint_template: "keep the owner's distribution installed for the target revision, or remove its modules from the deployment manifest first so the drop is declared"
    data_shape: [phase, dropped_owners, dropped_modules, changes]

  - code: package_module_unavailable
    python_exception: PackagedModuleUnavailable
    severity: user
    raised_by:
      - okg catalog load
      - okg catalog load --apply
    referenced_in:
      - pact/changes/package-backed-module-provider
    fix_hint_template: "rebuild the package so {module_id}'s declaration names an asset of a module file kind"
    # The declaration exists but the bytes behind it do not. `module_id` and
    # `reason` are present at every raise site; the remaining keys name
    # whichever input was rejected (`asset_ref`, `asset_kind`, `supplied`).
    data_shape: [module_id, reason]

  - code: profile_invalid
    python_exception: ProfileError
    severity: user
    raised_by:
      - okg init
      - okg doctor
    referenced_in:
      - history/openspec/changes/archive/add-okg-init-and-module-scaffold-cli
    fix_hint_template: "fix the `profile.yaml` at {profile_path} (missing/malformed key: {key}) or supply the missing init answer"
    data_shape: [profile_path, key, question_id, variable, value]

  - code: profile_fetch_failed
    python_exception: ProfileFetchError
    severity: user
    raised_by:
      - okg init
    referenced_in:
      - pact/changes/deployment-fetch-resolver
    fix_hint_template: "run `okg fetch-deployments` to populate {cache_root} from the external reference-deployments repo (check repo access), then re-run --profile {profile_name}"
    data_shape: [profile_name, condition, searched, cache_root]

  # A profile name removed from the library. Checked before the profile
  # search, with no compatibility alias; `replacement` is null when nothing
  # replaces the retired profile.
  - code: profile_retired
    python_exception: ProfileRetiredError
    severity: user
    raised_by:
      - okg install
      - okg init
      - okg doctor
    referenced_in:
      - pact/changes/remove-git-code-systems-research-profiles
    fix_hint_template: "re-run with --profile {replacement}, or choose another profile when replacement is null"
    data_shape: [profile_name, replacement, reason]

  # Two files in one profile's source-defaults/ declare one source id. The
  # scaffold used to merge them last-wins and drop a source silently.
  - code: source_default_duplicate_id
    python_exception: DuplicateSourceIdError
    severity: user
    raised_by:
      - okg init
      - okg install
    referenced_in:
      - pact/changes/fix-install-refuses-duplicate-source-id
    fix_hint_template: "keep exactly one source-default file per source id; {files} both declare {source_id}: remove or rename the file you do not want (an alternative mode replaces the default, it is not added beside it), or give the second source a distinct id"
    data_shape: [profile_path, key, source_id, files]

  # ---------- migration apply-time hardening ----------

  - code: migration_lock_timeout
    python_exception: MigrationLockTimeout
    severity: recoverable
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "another session holds a conflicting lock; find and release it (pg_locks/pg_stat_activity), or raise OKG_MIGRATE_LOCK_TIMEOUT_MS / OKG_MIGRATE_LOCK_ATTEMPTS and re-run"
    data_shape: [attempts, lock_timeout_ms, statement_timeout_ms, sqlstate]

  - code: migration_manifest_entry_missing
    python_exception: MigrationManifestEntryMissing
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "add a migrations/manifest.yaml entry for {migration_id} before shipping it"
    data_shape: [migration_id]

  - code: migration_manifest_checksum_mismatch
    python_exception: MigrationManifestChecksumMismatch
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "the shipped file for {migration_id} does not match its manifest checksum_sha256; never edit a shipped migration — add a new ordered migration and update the manifest together"
    data_shape: [migration_id, file_checksum, manifest_checksum]

  - code: migration_manifest_destructive_disagreement
    python_exception: MigrationManifestDestructiveDisagreement
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "manifest destructive={manifest_destructive} but the filename heuristic says {heuristic_destructive} for {migration_id}; reconcile the manifest entry and the filename"
    data_shape: [migration_id, manifest_destructive, heuristic_destructive]

  - code: migration_manifest_prerequisite_unmet
    python_exception: MigrationManifestPrerequisiteUnmet
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "apply {prerequisite_id} first (it is missing from the ledger and not scheduled earlier in this batch), or reconcile the manifest prerequisites for {migration_id}"
    data_shape: [migration_id, prerequisite_id, prerequisite]

  - code: migration_class_invalid
    python_exception: MigrationClassInvalid
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "manifest entry for {migration_id} declares class={declared_class}; use single_transaction or multi_phase (and a multi-phase migration cannot also be destructive)"
    data_shape: [migration_id, declared_class]

  - code: migration_class_undeclared
    python_exception: MigrationClassUndeclared
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "{migration_id} contains {data_motion_statements} top-level data-motion statements; declare `class: multi_phase` in migrations/manifest.yaml (and ship a phase spec) or restructure it as a single-transaction migration"
    data_shape: [migration_id, data_motion_statements, statement_count]

  - code: multiphase_migration_invalid
    python_exception: MultiphaseMigrationInvalid
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "multi-phase driver refused for {migration_id}: {detail}"
    data_shape: [migration_id, detail]

  - code: migrate_authority_unresolvable
    python_exception: MigrateAuthorityUnresolvable
    severity: fatal
    raised_by:
      - okg migrate
      - okg up
    referenced_in:
      - pact/changes/schema-migration-hardening
    fix_hint_template: "fix the DSN or the deployments root ({detail}); the authority gate fails closed and never proceeds ungated"
    data_shape: [detail, root, manifest]

  # ---------- operator safety ----------

  - code: requires_confirm
    python_exception: null   # CLI-level, not raised in code
    severity: user
    raised_by:
      - any write command without --apply, under OKG_AGENT=1
    referenced_in:
      - src/okg/AGENTS.md
    fix_hint_template: "re-run with --apply once you've reviewed the dry-run output"
    data_shape: [command]

  - code: primary_overload   # placeholder for v2+ replica tier
    python_exception: PrimaryOverload
    severity: recoverable
    raised_by:
      - MCP server (v2+ replica routing fallback)
    referenced_in:
      - docs/reference/alerts.yaml
    fix_hint_template: "wait for replica lag to recover or shed read load"
    data_shape: [deployment, concurrent_fallback_count, cap]

  # ---------- LLM-judge invariant runner (per
  # `add-semantic-llm-judge-invariants`, 2026-04-29) ----------
  #
  # These four codes are emitted as warn-severity rows inside
  # `graph_generations.invariant_summary->'llm_judge'->'results[]'`,
  # NOT as Python exceptions. They are stable identifiers an
  # operator (or downstream view) can switch on; the runner
  # never crashes the publish on them.

  - code: judge_parse_error
    python_exception: null
    severity: recoverable
    raised_by:
      - okg run --include-llm-invariants
    referenced_in:
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/proposal.md
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/specs/graph-ingestion/spec.md
    fix_hint_template: "judge response was malformed JSON or missing required keys; re-run, lower temperature, or tighten prompt"
    data_shape: [candidate_id, raw, error]

  - code: judge_call_failure
    python_exception: null
    severity: recoverable
    raised_by:
      - okg run --include-llm-invariants
    referenced_in:
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/proposal.md
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/specs/graph-ingestion/spec.md
    fix_hint_template: "litellm transport error or timeout; check provider status and rate-limit headroom"
    data_shape: [candidate_id, error, error_kind]

  - code: evidence_span_invalid
    python_exception: null
    severity: recoverable
    raised_by:
      - okg run --include-llm-invariants
    referenced_in:
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/proposal.md
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/specs/graph-ingestion/spec.md
    fix_hint_template: "judge cited byte ranges that don't exist in the node's body; tighten prompt or trim payload truncation"
    data_shape: [candidate_id, invalid_spans]

  - code: candidates_sql_shape_invalid
    python_exception: null
    severity: recoverable
    raised_by:
      - okg run --include-llm-invariants
    referenced_in:
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/proposal.md
      - history/openspec/changes/archive/2026-04-29-add-semantic-llm-judge-invariants/specs/graph-ingestion/spec.md
    fix_hint_template: "candidates_sql must return columns (candidate_id TEXT, payload JSONB) — fix the SELECT shape"
    data_shape: [name]

  - code: select_unknown_field
    python_exception: SelectUnknownField
    severity: recoverable
    raised_by:
      - MCP tools that accept a `select` field-projection list
    referenced_in:
      - src/okg/substrate/mcp/envelope.py
    fix_hint_template: "remove unknown field(s) {unknown_fields} from `select`; valid fields are {valid_fields}"
    data_shape: [tool, unknown_fields, valid_fields]

  - code: search_query_conflict
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg.substrate.cli._read_side._resolve_search_query
    fix_hint_template: pass the query once, either as QUERY or as --query
    data_shape: [positional, option]

  - code: search_query_missing
    python_exception: null
    severity: user
    raised_by:
      - okg search
      - okg.substrate.cli._read_side._resolve_search_query
    fix_hint_template: >-
      pass the query as QUERY, for example
      okg search --deployment <name> 'words'
    data_shape: []

  - code: unknown_operator_argument
    python_exception: UnknownOperatorArgument
    severity: user
    raised_by:
      - MCP graph-read tools
    referenced_in:
      - pact/changes/typed-operator-inputs/pact.yaml
    fix_hint_template: "remove the named argument, or re-read the tool's inputSchema in tools/list"
    data_shape: [tool, unknown_arguments]

  # Also raised by the operators' own checks of caller arguments:
  # those name the field in the message, send `validation_kinds:
  # [argument_check]` with empty `invalid_fields`, and hint "correct the
  # argument the message names, then retry".
  - code: invalid_operator_arguments
    python_exception: InvalidOperatorArguments
    severity: user
    raised_by:
      - MCP graph-read tools
      - search, expand, inspect and aggregate checks of caller arguments
    referenced_in:
      - pact/changes/typed-operator-inputs/pact.yaml
      - pact/changes/release-read-refusals/pact.yaml
    # PACT read-live-handles: a read-grammar refusal may name `reason`
    # (`handle_as_condition`: a handle id inside a compound condition or a
    # scope's filter; `values_from_handle_need_handle_input`).
    # PACT read-map-compute: `map(compute=...)` refuses by `reason` before any
    # upstream call or graph read: an expression refusal of the formula
    # language (`unknown_function`, `unknown_column`, `compute_cycle`,
    # `too_many_columns`, a parse error, ...), `compute_under_access_rules`,
    # `compute_on_stored_set`, `compute_on_edges`, `compute_with_projection`,
    # `record_column_on_raw_rows`, `date_on_live_rows`, `reserved_key`,
    # `reserved_column_name`, `column_shadows_field`, `key_absent_on_every_row`,
    # `calc_column_unknown` (a later read names a `calc.` column the set
    # lacks); while computing, `too_many_rows`, `evaluation_budget`,
    # `regex_budget` and `map_output_too_large`, never a partial answer.
    # PACT read-stored-metrics: `map(compute)` and a stored sum, min or max
    # refuse `unknown_type` (a type that is neither a catalog type nor a live
    # type, with data.closest). A stored sum, min or max refuses, in order,
    # `stored_metric_under_access_rules` (before any graph read),
    # `stored_metric_by`, `stored_metric_field`, `stored_metric_input`,
    # `stored_metric_text_condition`, `unknown_type`,
    # `stored_metric_needs_number` (an attribute declared text, bool or ts),
    # then `stored_set_too_large` (over 50,000 records, after one bounded
    # count, data.records) and `stored_read_over_budget` (the call's 5 s SQL
    # budget, data.phase and data.elapsed_ms); every one serves zero values.
    fix_hint_template: "correct the named field(s), or re-read the tool's inputSchema in tools/list"
    data_shape: [tool, invalid_fields, validation_kinds]

  # A read that carries a date condition did not finish its date work inside
  # one time budget. The arguments are valid: the call reads
  # too many records for a date condition no index serves. The hint says what
  # to add; no retry call is named.
  - code: date_call_over_budget
    python_exception: DateCallOverBudget
    severity: recoverable
    raised_by:
      - MCP filter, map, aggregate and expand with a date condition
    referenced_in:
      - pact/changes/read-dates-everywhere-3666/pact.yaml
    fix_hint_template: "name a type, or add a narrower condition that is not on a date"
    data_shape: [reason, fields, budget_ms, typed, date_index]

  # A step of `run` used its time budget (5,000 ms a step, 15,000 ms a run).
  # The arguments are valid.
  - code: run_over_budget
    python_exception: RunOverBudget
    severity: recoverable
    raised_by:
      - MCP run steps
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "narrow the step's condition, or split the run"
    data_shape: []

  # A printed `run` step would print more than 200 rows (records, or groups
  # for aggregate), or a search step's whole match set holds more than 200
  # records. The refusal states the exact count and offers served calls.
  - code: run_step_too_many_rows
    python_exception: RunStepTooManyRows
    severity: recoverable
    raised_by:
      - MCP run steps
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "pass the set on without its rows (show false), or count it with aggregate"
    data_shape: [count, groups, cap, retry_calls]

  # A `run` step's exact count did not finish inside the step's time budget.
  # The count is never estimated.
  - code: run_count_not_finished
    python_exception: RunCountNotFinished
    severity: recoverable
    raised_by:
      - MCP run steps
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "narrow the step's condition, or split the run"
    data_shape: []

  # A read named a set kept past its run call (`$r<n>`) or asked
  # `retain=true` where only such a set name answered it. A set lasts for one
  # run call.
  - code: set_names_removed
    python_exception: SetNamesRemoved
    severity: recoverable
    raised_by:
      - MCP read tools
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "put both reads in one run(steps=[...])"
    data_shape: []

  # The operator turned `run`'s live steps off (OKG_MCP_RUN_LIVE_STEPS=0).
  # A live call sent on its own is unaffected.
  - code: run_live_steps_off
    python_exception: RunLiveStepsOff
    severity: recoverable
    raised_by:
      - MCP run steps
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "send the expand(live=...) call on its own"
    data_shape: []

  # This session already has a run whose live step calls once per value,
  # or its reader has two.
  - code: run_live_busy
    python_exception: RunLiveBusy
    severity: recoverable
    raised_by:
      - MCP run steps
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "send this run again when the other one has answered"
    data_shape: []

  # A `run` live step refused: its relation's gate denied it, it would pass
  # a run's limit, the column it reads holds no value, or its one call (no
  # `each`) gave no answer.
  - code: run_live_step_refused
    python_exception: RunLiveStepRefused
    severity: recoverable
    raised_by:
      - MCP run steps
    referenced_in:
      - pact/changes/run-composed-3666/pact.yaml
    fix_hint_template: "the message names the limit, the column, or the gate's reason"
    data_shape: [step, column, columns, values, cap, calls, made, relation, reason]

  # A write or admin MCP tool refused because `okg mcp-serve` runs read-only:
  # the database is behind this code only by migrations that are safe to read
  # behind (release verdict `read_only`), so nothing may write through it.
  - code: schema_behind_read_only
    python_exception: SchemaBehindReadOnly
    severity: recoverable
    raised_by:
      - MCP write and admin tools (mcp-serve read-only behind reads-safe migrations)
    referenced_in:
      - pact/changes/unknown-s8-mcp-readonly/pact.yaml
    fix_hint_template: "run `okg up {0}` to apply the pending migrations, then restart mcp-serve"
    data_shape: [tool, schema_behind_by, behind_migrations]

  - code: query_off_under_access_rules
    python_exception: QueryOffUnderAccessRules
    severity: user
    raised_by:
      - MCP `query` on a deployment whose access rules (Nomos) are audit or enforce; the tool is not served there
    referenced_in:
      - src/okg/substrate/mcp/response_bounds.py
    fix_hint_template: "use search, filter, map, inspect, expand or aggregate, which apply the access rules"
    data_shape: [tool, access_rules]

  - code: tool_not_served
    python_exception: ToolNotServed
    severity: user
    raised_by:
      - MCP call to a tool name the server does not register (a deployment whose `agent_surface.served` omits it, or a name no deployment has)
    referenced_in:
      - src/okg/substrate/mcp/session_tool_surface.py
    fix_hint_template: "call one of the served tools, or ask the operator to add the tool to `agent_surface.served`"
    data_shape: [tool, served]

  - code: cross_link_rule_parse_error
    python_exception: RuleParseError
    severity: recoverable
    raised_by:
      - declarative cross-source linker (rules YAML loader)
    referenced_in:
      - src/okg/substrate/library/linkers/rules.py
    fix_hint_template: "fix the offending rule in the linker YAML"
    data_shape: [rule, reason]

  # A derive_from_path rule read a field holding an object, or a list holding
  # an object or a nested list. The linker skips that node for
  # that rule and logs this code; under the publisher it quarantines the node
  # in okg.enricher_input_quarantines (failure_class = this code, reported by
  # okg doctor) and the watermark advances. It does not raise.
  - code: cross_link_field_shape_unsupported
    python_exception: CrossLinkFieldShapeError
    severity: recoverable
    raised_by:
      - declarative cross-source linker (derive_from_path matcher; logged and quarantined)
    referenced_in:
      - src/okg/substrate/library/linkers/declarative.py
    fix_hint_template: "point the rule at a string field or a list of strings, or emit one string attribute per value"
    data_shape: [rule_id, node_id, field, value_type, item_type]

  - code: cross_link_pair_limit_exceeded
    python_exception: CrossLinkPairLimitExceeded
    severity: recoverable
    raised_by:
      - declarative cross-source linker (a matcher step that compares every candidate with every value, before it starts)
    referenced_in:
      - src/okg/substrate/library/linkers/declarative.py
    fix_hint_template: "name the rule's field with letters, digits and underscores so the match runs in the database, or raise the linker's max_pair_comparisons"
    data_shape: [rule_id, step, n_left, n_right, limit]

  - code: run_sql_invalid
    python_exception: RunSqlInvalid
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool (validation layer)
    referenced_in:
      - src/okg/substrate/mcp/sql_safety.py
    fix_hint_template: "fix the SQL: {reason}"
    data_shape: [reason]

  - code: run_sql_non_select
    python_exception: RunSqlNonSelect
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — only SELECT statements are accepted
    referenced_in:
      - src/okg/substrate/mcp/sql_safety.py
    fix_hint_template: "rewrite as a SELECT; mutating statements are forbidden via `run_sql`"
    data_shape: [statement_type]

  - code: run_sql_multi_statement
    python_exception: RunSqlMultiStatement
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — exactly one statement per call
    referenced_in:
      - src/okg/substrate/mcp/sql_safety.py
    fix_hint_template: "split into separate calls; one statement per `run_sql`"
    data_shape: [statement_count]

  - code: run_sql_disallowed_relation
    python_exception: RunSqlDisallowedRelation
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — only the documented public views are queryable
    referenced_in:
      - src/okg/substrate/mcp/sql_safety.py
    fix_hint_template: "use one of the documented `okg.v_*` public views"
    data_shape: [relation, allowed_relations]

  - code: run_sql_forbidden_function
    python_exception: RunSqlForbiddenFunction
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — deny-list of side-effecting / privileged functions
    referenced_in:
      - src/okg/substrate/mcp/sql_safety.py
    fix_hint_template: "remove the forbidden function call: {function}"
    data_shape: [function]

  - code: run_sql_timeout
    python_exception: RunSqlTimeout
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — Postgres `query_canceled` after exceeding `statement_timeout`
    referenced_in:
      - src/okg/substrate/mcp/run_sql.py
    fix_hint_template: "tighten the WHERE clause or increase timeout_ms (max 60000)"
    data_shape: [timeout_ms, sql_prefix]

  - code: run_sql_graph_literal_refused
    python_exception: RunSqlGraphLiteralRefused
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — graph-backed SQL with an E'...' or U&'...' string (a backslash in a plain '...' string is served). An E'...' string whose only escapes are a doubled backslash or a backslash-quote gets a `retry_call` with it written as $$...$$
    referenced_in:
      - src/okg/substrate/mcp/graph_sql_splice.py
    fix_hint_template: "write the value as a plain '...' string (a backslash there is an ordinary character) or as a dollar-quoted string such as $$...$$"
    data_shape: [form, offset]

  - code: run_sql_graph_string_mode_refused
    python_exception: RunSqlGraphStringModeRefused
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — graph-backed SQL on a connection where standard_conforming_strings is not on
    referenced_in:
      - src/okg/substrate/mcp/graph_sql_splice.py
    fix_hint_template: "run SET standard_conforming_strings = on on this connection"
    data_shape: [standard_conforming_strings]

  - code: run_sql_graph_form_unsupported
    python_exception: RunSqlGraphFormUnsupported
    severity: user
    raised_by:
      - MCP `run_sql` tool — graph-backed SQL names a graph relation as `ONLY <relation>`, `<relation> *` or `TABLE <relation>`, which the splice cannot replace
    referenced_in:
      - src/okg/substrate/mcp/graph_sql_splice.py
    fix_hint_template: "write SELECT ... FROM {relation} instead"
    data_shape: [form, relation]

  - code: run_sql_graph_splice_mismatch
    python_exception: RunSqlGraphSpliceMismatch
    severity: internal
    raised_by:
      - MCP `run_sql` tool — the executed graph-backed SQL changed or moved a caller token outside a replaced table reference
    referenced_in:
      - src/okg/substrate/mcp/graph_sql_splice.py
    fix_hint_template: "simplify the query and report it; this is a run_sql defect"
    data_shape: [reason, offset]

  - code: run_sql_graph_view_unplanned
    python_exception: RunSqlGraphViewUnplanned
    severity: recoverable
    raised_by:
      - MCP `run_sql` tool — graph-backed SQL names a composite view whose body could not be fully planned against the pinned snapshot; refused rather than reading the live view (PACT sql-safety-without-pglast)
    referenced_in:
      - src/okg/substrate/mcp/graph_sql_splice.py
    fix_hint_template: "query the graph views directly, and report this view"
    data_shape: [view, name, offset]

  - code: derived_dirty_rule_load_error
    python_exception: DirtyRuleLoadError
    severity: user
    raised_by:
      - okg.substrate.derived_artifacts.dirty_rules.execute_sql_dirty_rule
    referenced_in:
      - src/okg/substrate/derived_artifacts/dirty_rules.py
    fix_hint_template: "fix the dirty-rule SQL or timeout configuration"
    data_shape: [timeout_ms, field, token]

  - code: derived_dirty_rule_execution_error
    python_exception: DirtyRuleExecutionError
    severity: recoverable
    raised_by:
      - okg.substrate.derived_artifacts.dirty_rules.execute_sql_dirty_rule
    referenced_in:
      - src/okg/substrate/derived_artifacts/dirty_rules.py
    fix_hint_template: "fix the dirty-rule query so it returns a non-null scope_key for each row"
    data_shape: [definition_id, target_generation_id, where, row]

  # ----- deployment search profiles -----
  # Every one of these exists so a scoping failure cannot present as an empty
  # or unscoped page, which no caller can tell apart from "nothing matched".

  # MCP tool profiles. Every one
  # of these exists so a narrowing cannot present as a smaller served surface
  # with no signal, which the operator cannot tell apart from a typo obeyed.

  - code: tool_profile_config_invalid
    python_exception: ToolProfileConfigInvalid
    severity: user
    raised_by: [okg.substrate.mcp.tool_profiles, okg.substrate.deployments]
    fix_hint_template: "fix the `mcp:` block in the deployment manifest; accepted keys are {0}"
    data_shape: [unknown_keys, accepted_keys]

  - code: unknown_tool_profile
    python_exception: UnknownToolProfile
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.tool_profiles]
    fix_hint_template: "pass --tools with one of {0}, or declare it under `mcp.tool_profiles`"
    data_shape: [requested, known]

  - code: tool_profile_tool_absent
    python_exception: ToolProfileToolAbsent
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.tool_profiles]
    fix_hint_template: "fix the spelling, drop the name, or relaunch with --allow-writes"
    data_shape: [profile, requested, served, unrecognized, withheld_by_launch]

  - code: tool_surface_selection_conflict
    python_exception: ToolSurfaceSelectionConflict
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.tool_profiles]
    fix_hint_template: "drop --tools, or unset OKG_MCP_TOOL_ALLOWLIST"
    data_shape: [requested_profile, env_allowlist]

  - code: mcp_instruction_surface_mismatch
    python_exception: InstructionSurfaceMismatch
    severity: internal
    raised_by: [okg.substrate.mcp.server]
    fix_hint_template: "report this as an okg substrate defect"
    data_shape: [rendered_for, served]

  # The declared agent surface.
  - code: agent_surface_invalid
    python_exception: AgentSurfaceInvalid
    severity: user
    raised_by: [okg.substrate.mcp.effective_surface, deployment.yaml load]
    fix_hint_template: "fix the key spelling or value under `agent_surface`"
    data_shape: [unknown_keys, accepted_keys]

  - code: surface_text_invalid
    python_exception: SurfaceTextInvalid
    severity: user
    raised_by: [okg.substrate.mcp.surface_text, okg mcp-serve build]
    fix_hint_template: "fix the surface_text file; see okg.substrate.mcp.surface_text"
    data_shape: [file, key, unknown, placeholders, unknown_codes, unpublished, published_tools]

  - code: agent_surface_projection_wider_than_served
    python_exception: AgentSurfaceProjectionWiderThanServed
    severity: user
    raised_by: [okg.substrate.mcp.effective_surface, deployment.yaml load]
    fix_hint_template: "add the tools to `agent_surface.served`, or remove them from the projection"
    data_shape: [projection, wider_than_served, projection_tools, served]

  - code: agent_surface_response_bytes_out_of_range
    python_exception: AgentSurfaceResponseBytesOutOfRange
    severity: user
    raised_by: [okg.substrate.mcp.effective_surface, deployment.yaml load]
    fix_hint_template: "set `response_bytes` between the substrate minimum and the declared ceiling"
    data_shape: [default, ceiling, min, max, upper]

  - code: agent_surface_legacy_key_present
    python_exception: AgentSurfaceLegacyKeyPresent
    severity: user
    raised_by: [okg.substrate.mcp.effective_surface, deployment.yaml load]
    fix_hint_template: "move the legacy key into `agent_surface` and delete it"
    data_shape: [legacy_key, replacement]

  - code: agent_surface_conflicts_with_mcp_block
    python_exception: AgentSurfaceConflictsWithMcpBlock
    severity: user
    raised_by: [okg.substrate.mcp.effective_surface, deployment.yaml load]
    fix_hint_template: "move `mcp.tool_profiles` into `agent_surface.served` and delete the `mcp:` block"
    data_shape: [legacy_key, replacement]

  # Images as a first-class value.
  - code: images_config_invalid
    python_exception: ImagesConfigInvalid
    severity: user
    raised_by: [okg.substrate.images.config]
    fix_hint_template: "fix the key or value under `agent_surface.images` named in data.field"
    data_shape: [field]

  - code: image_value_forged
    python_exception: ImageValueForged
    severity: user
    raised_by: [okg.substrate.images.values, source runner, emit_node_fact, update_node_attrs]
    fix_hint_template: "emit ImageRef.file(path) or ImageRef.url(url) and let ingest render it"
    data_shape: [keys]

  # Also raised by agent record writes (MCP record and propose, CLI
  # admission submit) for a `file` reference: file images come only from a
  # connector's ingest run (data.problem = file_ref_outside_ingest).
  - code: image_ref_invalid
    python_exception: ImageRefInvalid
    severity: user
    raised_by:
      - okg.substrate.images.values
      - source runner
      - emit_node_fact
      - update_node_attrs
      - MCP record and propose
      - okg admission submit
    fix_hint_template: "build the value with ImageRef.file(path) or ImageRef.url(url)"
    data_shape: [field]

  - code: blob_prune_grace_too_short
    python_exception: BlobPruneGraceTooShort
    severity: user
    raised_by: [okg db prune-blobs, okg.substrate.db.blob_prune]
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "pass --grace-seconds 3600 or more (default 86400)"
    data_shape: [argument, grace_seconds, minimum_seconds]

  - code: blob_prune_no_graph
    python_exception: BlobPruneNoGraph
    severity: user
    raised_by: [okg db prune-blobs --apply, okg.substrate.db.blob_prune]
    referenced_in:
      - docs/reference/cli.md
    fix_hint_template: "publish a generation first, then re-run the cleanup"
    data_shape: [kind, blobs_total, candidate_count]

  - code: image_root_invalid
    python_exception: ImageRootInvalid
    severity: user
    raised_by: [okg.substrate.images.render]
    fix_hint_template: "set ConnectorRun.image_root to the existing directory the run's image paths are relative to"
    data_shape: [source_name]

  - code: agent_surface_write_launch_unserved
    python_exception: WriteLaunchUnservedByDeclaration
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.effective_surface]
    fix_hint_template: "add the write tools to `agent_surface.served`, or drop --allow-writes"
    data_shape: [deployment, served, write_admin_tools]

  - code: agent_surface_inspect_kind_unserved
    python_exception: InspectKindNotServed
    severity: user
    raised_by: [okg.substrate.mcp.server.inspect]
    fix_hint_template: "call a served kind, or relaunch with what serves it"
    data_shape: [kind, served_kinds, known_kind, serves_it]

  - code: invalid_image_inspection
    python_exception: InvalidImageInspection
    severity: user
    raised_by: [okg.substrate.mcp.server.inspect]
    fix_hint_template: "pass node_id, and panel as an integer within the stated bounds, or omit it"
    data_shape: [field, value, minimum, maximum]

  - code: image_not_available
    python_exception: NoImageForNode
    severity: user
    raised_by: [okg.substrate.mcp.server.inspect]
    fix_hint_template: "inspect a node of a subtype the deployment declares images for"
    data_shape: [node_id, subtype, attr]

  - code: image_withheld
    python_exception: ImageWithheld
    severity: user
    raised_by: [okg.substrate.mcp.server.inspect]
    fix_hint_template: "read the node with inspect(kind='node') to see what is visible"
    data_shape: [node_id, generation_id]

  - code: agent_surface_text_names_unserved_operator
    python_exception: SurfaceTextNamesUnservedOperator
    severity: user
    raised_by: [okg deployments lint, okg chat sync, okg mcp-serve]
    fix_hint_template: "add the operator to `agent_surface.served`, or remove the name from the text"
    data_shape: [deployment, source, unserved, served, mentions]

  - code: agent_surface_served_set_mismatch
    python_exception: ServedSetMismatch
    severity: user
    raised_by: [okg chat sync]
    fix_hint_template: "restart mcp-serve so it registers the declared set, or change `agent_surface.served`"
    data_shape: [deployment, endpoint, allow_writes, expected, observed, served_not_listed, listed_not_served, projected_not_listed]

  - code: live_bindings_not_implemented
    python_exception: LiveBindingsNotImplemented
    severity: user
    raised_by: [okg.substrate.mcp.effective_surface, deployment.yaml load]
    fix_hint_template: "this code is retired: a well-formed `live_bindings` declaration now loads; see the live relations guide"
    data_shape: [declared, issue]

  - code: inspect_schema_unreachable
    python_exception: InspectSchemaUnreachable
    severity: internal
    raised_by: [okg.substrate.mcp.operator_models.publish_narrowed_inspect_target]
    fix_hint_template: "an MCP SDK upgrade likely renamed these internals; update publish_narrowed_inspect_target"
    data_shape: [has_tool_manager, has_tools, has_inspect, has_parameters]

  # Start-time capability probe. The server publishes
  # only the search methods and rank_by values it can run, and refuses the
  # rest by name before any database work. A probe read that errors refuses
  # the start, naming the read; a read that times out publishes the
  # capability as unknown (refused like unavailable).
  - code: agent_surface_probe_failed
    python_exception: CapabilityProbeFailed
    severity: fatal
    raised_by: [okg mcp-serve, okg.substrate.mcp.capability_probe.probe_capabilities]
    fix_hint_template: "fix the database error the read names, then restart mcp-serve"
    data_shape: [read, error_type]

  - code: agent_surface_capability_fixture_invalid
    python_exception: CapabilityFixtureInvalid
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.capability_probe.capabilities_for_surface_probe]
    fix_hint_template: "name a known fixture (none, full) on a hermetic build, or unset OKG_MCP_CAPABILITY_FIXTURE on a live server"
    data_shape: [fixture, known]

  - code: agent_surface_generated_instructions_over_budget
    python_exception: GeneratedInstructionsOverBudget
    severity: internal
    raised_by: [okg.substrate.mcp.capability_probe.render_unavailable_lines]
    fix_hint_template: "shorten the capability reasons in capability_probe.py"
    data_shape: [bytes, budget]

  - code: search_method_unavailable
    python_exception: SearchMethodUnavailable
    severity: user
    raised_by: [okg.substrate.mcp.server.search]
    fix_hint_template: "call one of available_methods; restart mcp-serve after adding the capability"
    data_shape: [method, status, reason, available_methods]

  - code: search_rank_by_unavailable
    python_exception: SearchRankByUnavailable
    severity: user
    raised_by: [okg.substrate.mcp.server.search]
    fix_hint_template: "omit rank_by or pass one of available_rank_by; restart mcp-serve after declaring a rollup"
    data_shape: [rank_by, status, reason, available_rank_by]

  - code: search_schema_unreachable
    python_exception: SearchSchemaUnreachable
    severity: internal
    raised_by: [okg.substrate.mcp.capability_probe.compile_tool_surface]
    fix_hint_template: "an MCP SDK or pydantic upgrade likely changed the schema shape; update compile_tool_surface"
    data_shape: [has_parameters, has_method_enum, has_select_array, has_rank_by_enum]

  # Client-readable tool schemas. Raised at server launch when a
  # registered tool's input schema cannot be republished without `$ref`: a
  # non-local or dangling pointer, a sibling keyword that would change the
  # definition, or MCP SDK internals that no longer expose the tools. The
  # server refuses to start rather than publish a schema that says something
  # different from the model, or leave the unreadable one in place.
  - code: tool_schema_unpublishable
    python_exception: ToolSchemaUnpublishable
    severity: internal
    raised_by:
      - okg mcp-serve
      - okg.substrate.mcp.operator_models.inline_schema_refs
      - okg.substrate.mcp.operator_models.publish_client_readable_schemas
    fix_hint_template: "fix the tool's input model so its schema uses only local `$defs` pointers, or update publish_client_readable_schemas after an MCP SDK upgrade"
    data_shape: [ref, defined, keyword, has_tool_manager]

  - code: tool_result_shape_changed
    python_exception: ToolResultShapeChanged
    severity: internal
    raised_by: [okg.substrate.mcp.response_bounds.ByteBoundedFastMCP._okg_serve_result]
    referenced_in: []
    fix_hint_template: "check response_bounds._RawResultFastMCP against the pinned SDK's ToolManager.call_tool"
    data_shape: [tool, result_type]

  - code: invalid_result_format
    python_exception: InvalidResultFormat
    severity: user
    raised_by: [okg.substrate.mcp.response_bounds.ByteBoundedFastMCP.call_tool]
    referenced_in: [docs/reference/mcp-results.md]
    fix_hint_template: "send request _meta 'okg/result_format'='json' for compact JSON, or omit the key for text"
    data_shape: []

  # In-session tool-surface expansion. A session may widen
  # itself up to a launch-set ceiling; every refusal below keeps a server
  # from advertising an expansion that could never happen.

  - code: tool_prose_invalid
    python_exception: ToolProseInvalid
    severity: internal
    raised_by: [okg.substrate.mcp.tool_prose]
    fix_hint_template: "fix the [[if ...]] / [[tools ...]] / [[subtype]] markup in the named okg tool docstring; it names only known tools, inspect kinds and `live`"
    # okg's own tool descriptions carry surface markup rendered at server
    # build from the served tools, inspect kinds and live relations. Bad
    # markup in okg's code refuses the build; deployment tool text is never
    # rendered.
    data_shape: []

  - code: tool_surface_expansion_invalid
    python_exception: ToolSurfaceExpansionInvalid
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.tool_profiles]
    fix_hint_template: "choose a ceiling that is strictly wider than the base profile and contains it, keep `inspect` in the base, or drop --tools-ceiling"
    data_shape: [base_profile, ceiling_profile, base_tools, ceiling_tools]

  - code: tool_surface_expansion_allowlist_conflict
    python_exception: ToolSurfaceExpansionAllowlistConflict
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.tool_profiles]
    fix_hint_template: "unset OKG_MCP_TOOL_ALLOWLIST and narrow with --tools instead, or drop --tools-ceiling"
    data_shape: [requested_ceiling, base_profile, base_source, env_allowlist]

  - code: mcp_tool_surface_expansion_stateless_http
    python_exception: StatelessHttpExpansionUnsupported
    severity: user
    raised_by: [okg mcp-serve, okg.substrate.mcp.session_tool_surface]
    fix_hint_template: "serve stateful streamable-http or stdio, or drop --tools-ceiling and launch with the wider --tools"
    data_shape: [base_profile, ceiling_profile, stateless_http]

  - code: mcp_tool_not_in_session_surface
    python_exception: ToolNotVisibleInSession
    severity: user
    raised_by: [okg.substrate.mcp.session_tool_surface]
    fix_hint_template: "call inspect(target={\"kind\": \"surface\", \"action\": \"expand\"}), then re-list tools"
    data_shape: [tool, visible_tools, expandable_tools]

  - code: mcp_tool_surface_expansion_unavailable
    python_exception: ToolSurfaceExpansionUnavailable
    severity: user
    raised_by: [okg.substrate.mcp.session_tool_surface, okg.substrate.mcp.server]
    fix_hint_template: "use stdio or a stateful streamable-http session, or relaunch with the wider --tools"
    data_shape: []

  - code: mcp_tool_list_changed_not_advertised
    python_exception: ToolListChangedNotAdvertised
    severity: internal
    raised_by: [okg.substrate.mcp.session_tool_surface]
    fix_hint_template: "report this as an okg substrate defect against the pinned mcp SDK"
    data_shape: [mcp_sdk_capabilities]

  - code: mcp_session_projection_unsupported
    python_exception: SessionProjectionUnsupported
    severity: internal
    raised_by: [okg.substrate.mcp.session_tool_surface]
    fix_hint_template: "report this as an okg substrate defect against the pinned mcp SDK"
    data_shape: []

  # A request named its benchmark question or try (X-OKG-Question /
  # X-OKG-Try headers or _meta okg/question / okg/try) in a shape the call
  # log cannot hold, or ambiguously; the call is refused and still logged.
  - code: mcp_question_label_invalid
    python_exception: QuestionLabelInvalid
    severity: user
    raised_by: [okg.substrate.mcp.tracing]
    referenced_in:
      - docs/reference/observability.md
    fix_hint_template: "send the question as one printable-ASCII token of at most 200 characters with no '#' or ',', and the try as a whole number from 1 to 999999, or send neither"
    data_shape: [field, channel]

  - code: search_profile_config_invalid
    python_exception: SearchProfileConfigInvalid
    severity: user
    raised_by: [okg.substrate.mcp.search_profiles, okg.substrate.deployments]
    fix_hint_template: "fix the `search:` block in the deployment manifest; accepted keys are {0}"
    data_shape: [unknown_keys, accepted_keys]

  - code: unknown_search_profile
    python_exception: UnknownSearchProfile
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "pass profile (CLI --scope) with one of {0}, or 'all'"
    data_shape: [requested, declared]

  - code: profile_subtype_absent
    python_exception: ProfileSubtypeAbsent
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "fix the subtype spelling in `search.profiles`, or add the subtype to the ontology and recompose"
    data_shape: [profile, absent, catalog_version_id]

  - code: subtype_outside_profile
    python_exception: SubtypeOutsideProfile
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "drop the subtype filter, choose one inside the profile, or pass profile 'all' (CLI --scope all)"
    data_shape: [subtype, profile, scope]

  - code: subtype_closure_incomplete
    python_exception: SubtypeClosureIncomplete
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "recompile the catalog so okg.subtype_ancestors is repopulated"
    data_shape: [catalog_version_id, missing]

  # ----- source-family authority, diversity, preview budget -----
  # Same argument as the profile codes above: an authority or diversity control
  # that silently did not apply is indistinguishable from one that did, so each
  # of these refuses instead of degrading to an unfiltered or empty page.

  - code: source_family_config_invalid
    python_exception: SourceFamilyConfigInvalid
    severity: user
    raised_by: [okg.substrate.mcp.search_profiles, okg.substrate.deployments]
    fix_hint_template: "fix the `search.source_families` block in the deployment manifest"
    data_shape: [family]

  - code: unknown_source_family
    python_exception: UnknownSourceFamily
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "pass --source-family with one of {0}, or declare the family in `search.source_families`"
    data_shape: [requested, declared]

  - code: source_family_empty_intersection
    python_exception: SourceFamilyEmptyIntersection
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "choose a family the profile selects ({0}), or pass profile 'all' (CLI --scope all)"
    data_shape: [requested, profile, profile_families]

  - code: source_family_source_absent
    python_exception: SourceFamilySourceAbsent
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "fix the producer id in `search.source_families`, or register the producer profile for that source"
    data_shape: [families, absent, deployment, registered_producers]

  - code: source_family_not_applicable
    python_exception: SourceFamilyNotApplicable
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "drop the source_family argument, or use one of {0}"
    data_shape: [method, supported_methods, requested]

  # ----- deployment-declared concept groups for lexical query expansion -----
  # Each refuses at manifest load rather than at the first search: a group a
  # deployment believes it declared, but which expands nothing, is
  # indistinguishable from a query that genuinely found no other vocabulary.

  - code: concept_group_config_invalid
    python_exception: ConceptGroupConfigInvalid
    severity: user
    raised_by: [okg.substrate.mcp.concept_expansion, okg.substrate.deployments]
    fix_hint_template: "fix the `search.concept_groups` block in the deployment manifest; list literal terms, never a pattern"
    data_shape: [canonical, role, term, value, got, unknown_keys, accepted_keys, unsupported]

  - code: concept_term_duplicated
    python_exception: ConceptTermDuplicated
    severity: user
    raised_by: [okg.substrate.mcp.concept_expansion, okg.substrate.deployments]
    fix_hint_template: "declare each concept term in exactly one group"
    data_shape: [term, canonical, duplicate_of, groups]

  - code: concept_canonical_shadowed
    python_exception: ConceptCanonicalShadowed
    severity: user
    raised_by: [okg.substrate.mcp.concept_expansion, okg.substrate.deployments]
    fix_hint_template: "merge the two groups, or rename the variant that shadows another group's canonical"
    data_shape: [canonical, variant, shadowed_canonical]

  - code: exclude_path_glob_invalid
    python_exception: PathGlobInvalid
    severity: user
    raised_by: [okg.substrate.mcp.search_profiles, okg.substrate.deployments]
    fix_hint_template: "rewrite the pattern using only `*`, `**` and `?`"
    data_shape: [pattern, unsupported]

  - code: invalid_max_per_parent
    python_exception: DiversityBoundInvalid
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search_profiles]
    fix_hint_template: "set {0} to an integer >= 1, or omit it"
    data_shape: [origin, value]

  - code: diversity_not_applicable
    python_exception: DiversityNotApplicable
    severity: user
    raised_by: [okg search, okg.substrate.mcp.result_diversity]
    fix_hint_template: "drop max_per_parent, or use method='lexical' with rank_by='self'"
    data_shape: [method, max_per_parent]

  - code: diversity_relation_budget_exceeded
    python_exception: DiversityRelationBudgetExceeded
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.result_diversity]
    fix_hint_template: "narrow the query, or correct unexpected passage-to-parent fan-out"
    data_shape: [edge_types, relation_cap]

  - code: invalid_preview_char_budget
    python_exception: InvalidPreviewCharBudget
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search]
    fix_hint_template: "pass max_chars between {0} and {1}"
    data_shape: [max_chars, min, max]

  - code: passage_rollup_undeclared
    python_exception: PassageRollupUndeclared
    severity: user
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: "declare okg_passage_rollup on the parent subtype and recompose the catalog, or drop rank_by='passages'"
    data_shape: [subtype, catalog_version_id, subtypes_with_passage_rollup, declared]

  - code: passage_rollup_declaration_invalid
    python_exception: PassageRollupDeclarationInvalid
    severity: user
    raised_by: [okg catalog load, okg.substrate.catalog.modules_compose]
    fix_hint_template: "declare exactly edge_type and child_subtype as non-empty strings"
    data_shape: [schema_path, class_name, unknown_keys, field]

  - code: catalog_field_declaration_invalid
    python_exception: CatalogFieldDeclarationInvalid
    severity: user
    raised_by: [okg catalog load, okg.substrate.catalog.modules_compose]
    fix_hint_template: "set okg_title_from, okg_path_from, okg_created_at_from or okg_last_modified_at_from to one of the subtype's attributes, declare the attribute, or remove the annotation"
    data_shape: [reason, subtype, annotation, declared]

  - code: deployment_subtype_overlay_refused
    python_exception: DeploymentSubtypeOverlayRefused
    severity: user
    raised_by: [okg catalog load, okg.substrate.catalog.modules_compose]
    fix_hint_template: "add okg_extends: <module> to the class to add to the library's value, drop the key or entry from the deployment schema file, or make it agree with the file named in conflict_source; masking can be added, never loosened"
    data_shape: [reason, subtype, key, schema_file, library_origin, library_modules, conflict_source, conflict_schema_file]

  - code: coverage_config_invalid
    python_exception: CoverageConfigInvalid
    severity: user
    raised_by: [okg.substrate.deployments, okg.substrate.mcp.source_coverage]
    fix_hint_template: "fix the key spelling under `coverage:`; each known gap is {source, description}"
    data_shape: [unknown_keys, accepted_keys, index, field, source, got_type]

  - code: coverage_counts_unavailable
    python_exception: CoverageCountsUnavailable
    severity: user
    raised_by: [okg.substrate.mcp.source_coverage]
    fix_hint_template: "narrow the question with search/filter, which stay exact at any size, or run coverage where the enforcement mode is off/audit"
    data_shape: [row_budget, deployment, generation_id]

  - code: rank_by_not_applicable
    python_exception: RankByNotApplicable
    severity: user
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: "drop rank_by, or use a method that supports it ('records' for grep; 'passages'/'records' for lexical)"
    data_shape: [method, rank_by]

  - code: passage_rollup_subtype_required
    python_exception: PassageRollupSubtypeRequired
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search]
    fix_hint_template: "pass subtype_filter naming the parent subtype, or drop rank_by='passages'"
    data_shape: [rank_by, filter]

  - code: where_unsupported
    python_exception: WhereUnsupported
    severity: user
    raised_by: [okg.substrate.mcp.search_where, okg.substrate.mcp.server]
    fix_hint_template: "name one of id, type, source, path or attrs.<key>, with the operand the op takes"
    data_shape: []

  - code: search_scope_unsupported
    python_exception: SearchScopeUnsupported
    severity: user
    raised_by: [okg.substrate.mcp.search_where, okg.substrate.mcp.search, okg.substrate.mcp.server]
    fix_hint_template: "scope={\"record\": <id>} or {\"records\": [...]} with query text on method='lexical'"
    data_shape: []

  - code: search_view_unsupported
    python_exception: SearchViewUnsupported
    severity: user
    raised_by: [okg.substrate.mcp.search_views, okg.substrate.mcp.server]
    fix_hint_template: "view='list' needs method='lexical' with rank_by='records' (limit <= 100, a non-empty select within node_id/subtype/handle/parent, no passage-type subtype_filter) or method='grep' (limit <= 100); omit view for cards"
    data_shape: [view, list_served_on]

  - code: passage_rollup_offset_unordered
    python_exception: PassageRollupOffsetUnordered
    severity: user
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: "page within the ordered documents, or narrow the query so the passage budget covers the requested page"
    data_shape: [offset, total_count, subtype, chunk_cap, rollup_chunk_cap_reached]

  - code: records_offset_beyond_exact_order
    python_exception: RecordsOffsetBeyondExactOrder
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search]
    referenced_in: [docs/use/search/index.md]
    fix_hint_template: "page within the exactly ordered records, or narrow the query so fewer records match"
    data_shape: [offset, ordered_exactly_through, subtype]

  - code: grep_query_invalid
    python_exception: GrepQueryInvalid
    severity: user
    raised_by: [okg.substrate.mcp.grep_query, okg.substrate.mcp.grep_search]
    referenced_in: []
    fix_hint_template: "write words, \"quoted phrases\", a NEAR/<n> b, -term to exclude, or re:/<pattern>/"
    data_shape: [reason, query]

  - code: grep_regex_unindexable
    python_exception: GrepRegexUnindexable
    severity: user
    raised_by: [okg.substrate.mcp.grep_query]
    referenced_in: []
    fix_hint_template: "add a run of 3 or more literal letters or digits, or scope the call with path_prefix, subtype_filter, profile, source_family or filter.source"
    data_shape: [terms, min_literal_run]

  - code: grep_pattern_too_short
    python_exception: GrepPatternTooShort
    severity: user
    raised_by: [okg.substrate.mcp.grep_query]
    referenced_in: []
    fix_hint_template: "add a term of 3 or more letters or digits, or scope the call with path_prefix, subtype_filter, profile, source_family or filter.source"
    data_shape: [terms, min_literal_run]

  - code: text_match_scan_limit
    python_exception: TextMatchScanLimit
    severity: user
    raised_by: [okg.substrate.mcp.text_match, okg.substrate.mcp.server]
    referenced_in: []
    fix_hint_template: "add a type or an attrs.<key> condition that leaves at most 10,000 records, or put 3 literal letters or digits in the value"
    data_shape: [scan_limit, indexable, text_over_limit, rest_over_limit]

  - code: path_prefix_not_applicable
    python_exception: GrepPathNotApplicable
    severity: recoverable
    raised_by: [okg.substrate.mcp.grep_search, okg.substrate.mcp.server]
    referenced_in: [docs/reference/mcp.md]
    fix_hint_template: "drop path_prefix and path: terms; scope with subtype_filter, source_family or filter.source instead (or use method='grep' when another method was given)"
    data_shape: [path_prefix, path_terms]

  - code: continuation_token_not_applicable
    python_exception: null
    severity: user
    raised_by: [okg.substrate.mcp.server]
    referenced_in: []
    fix_hint_template: "page with offset, or drop continuation_token"
    data_shape: []

  - code: window_continuity_unknown
    python_exception: WindowContinuityUnknown
    severity: recoverable
    raised_by: [okg.substrate.mcp.record_windows]
    referenced_in: []
    fix_hint_template: "use passage matching or provide proven source continuity"
    data_shape: []

  - code: window_work_incomplete
    python_exception: WindowWorkIncomplete
    severity: recoverable
    raised_by: [okg.substrate.mcp.record_windows]
    referenced_in: []
    fix_hint_template: "finish the readable occurrence scan before deciding record membership"
    data_shape: []

  - code: window_work_bound
    python_exception: WindowWorkBound
    severity: recoverable
    raised_by: [okg.substrate.mcp.record_windows]
    referenced_in: []
    fix_hint_template: "narrow the record set or query to remain within actual work bounds"
    data_shape: []

  - code: window_argument_unsupported
    python_exception: WindowArgumentUnsupported
    severity: recoverable
    raised_by: [okg.substrate.mcp.record_window_search]
    referenced_in: []
    fix_hint_template: "use method='grep' with a record scope and only the arguments windows serve"
    data_shape: [argument, view]

  - code: window_budget_too_small
    python_exception: WindowBudgetTooSmall
    severity: recoverable
    raised_by: [okg.substrate.mcp.record_window_pages]
    referenced_in: []
    fix_hint_template: "increase max_bytes"
    data_shape: [max_bytes]

  - code: grep_timeout
    python_exception: GrepTimeout
    severity: recoverable
    raised_by: [okg.substrate.mcp.grep_search]
    referenced_in: []
    fix_hint_template: "narrow the call with path_prefix, subtype_filter, profile, source_family or filter.source, or add a longer literal"
    data_shape: [timeout_ms, scopes]

  - code: search_fold_read_check_mismatch
    python_exception: SearchFoldReadCheckMismatch
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.record_fold]
    referenced_in: [docs/use/search/index.md]
    fix_hint_template: "retry the search; if it repeats, check the active Nomos policy bundle for rules that treat counting and reading differently"
    data_shape: [hidden_node_rows, hidden_edge_rows]

  - code: passage_rollup_edge_segment_unavailable
    python_exception: PassageRollupEdgeSegmentUnavailable
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: null
    data_shape: []

  # A winning passage the rollup's narrow scan ranked was not found when its
  # full row was read at the same pinned branch point: the pin did not hold
  # still. The search refuses rather than serve a passage with no text.
  - code: passage_rollup_chunk_rows_unavailable
    python_exception: PassageRollupChunkRowsUnavailable
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: "retry the search; run `okg doctor` if it repeats"
    data_shape: [chunk_ids, subtype]

  - code: lexical_index_scan_cap
    python_exception: LexicalIndexScanCapRefused
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.search]
    fix_hint_template: "narrow the query scope with subtype, source, or record selections"
    data_shape: [reason, scoped_candidates, work_row_limit, timeout_ms, index]

  - code: search_completeness_refused
    python_exception: SearchCompletenessRefused
    severity: user
    raised_by: [okg search, okg.substrate.mcp.search]
    fix_hint_template: "omit completeness, search with method='lexical' or 'grep', or narrow the search so one page holds every match"
    data_shape: [completeness, method]

  - code: passage_rollup_policy_scan_exhausted
    python_exception: PassageRollupPolicyScanExhausted
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: "narrow the query or reduce policy-hidden matches; a policy-distorted partial page is not returned"
    data_shape: [subtype, chunk_cap, policy_scan_cap]

  - code: passage_rollup_relation_budget_exceeded
    python_exception: PassageRollupRelationBudgetExceeded
    severity: recoverable
    raised_by: [okg search, okg.substrate.mcp.passage_rollup]
    fix_hint_template: "narrow the query or correct unexpected passage-to-parent fan-out before retrying"
    data_shape: [edge_type, child_subtype, relation_cap]

  - code: search_profile_not_applicable
    python_exception: ProfileNotApplicable
    severity: user
    raised_by: [okg.substrate.mcp.server, okg.substrate.mcp.search_profiles]
    fix_hint_template: "drop the profile argument, or use one of {0}"
    data_shape: [method, supported_methods, requested]

  # ----- deployment chat block (PACT chat-manifest-block) -----
  # The `chat:` manifest block declares a deployment's governed chat site.
  # Both codes exist so a typo or an unproven knob cannot degrade into a
  # default-configured site: a chat surface that is silently misconfigured
  # answers confidently from the wrong scope.

  - code: chat_manifest_invalid
    python_exception: ChatManifestError
    severity: user
    raised_by: [okg.substrate.deployments.chat_block, okg lint deployments]
    fix_hint_template: "fix the `chat:` block in the deployment manifest at {0}"
    data_shape: [path, unknown, known]

  # PACT chat-sync-projection. One code for every `okg chat sync` refusal,
  # because the operator action is always the same shape: read the named
  # surface, the expected value and the observed value out of `data` and fix
  # the disagreement. Registered here (the class predates this row) because
  # the parity check only sees a class once something imports its module, and
  # nothing did until the chat suites ran alongside it.
  #
  # PACT chat-mcp-connection-credential adds two `data['reason']` arms to this
  # same code, because the operator action is the same shape:
  # `mcp_connection_credential_unresolved` (chat.mcp.auth_token_env is declared
  # but the variable did not resolve; the run refuses before the endpoint probe
  # rather than registering an unauthenticated connection) and
  # `mcp_connection_credential_rejected` (the instance's own
  # tool_servers/verify answered 400 on the connection it stored; the payload
  # carries both candidate causes, the auth_type and the instance-side URL
  # alongside the probe URL, because this run did not separate them). A 404
  # from a version WITHOUT that route raises nothing: it measures nothing
  # about the credential and is reported as an unavailable probe. Neither
  # payload carries the credential — only the VARIABLE name, the auth_type,
  # the URLs and the HTTP status.
  - code: chat_sync_failed
    python_exception: ChatSyncError
    severity: user
    raised_by: [okg.substrate.chat.sync, okg chat sync]
    fix_hint_template: "fix the disagreement on the named surface, then re-run `okg chat sync`"
    data_shape: [reason, surface, key, expected, observed]

  # `okg chat setup` is the one guided entry point: instance,
  # admin credential, provider, model, graph endpoint, sync, conversation.
  # One code; `data['step']` names where the run stopped and
  # `data['reason']` why: admin_credential_missing / admin_credential_rejected
  # / admin_credential_not_admin / admin_signup_failed, provider_credential_
  # unresolved / provider_credential_rejected / provider_unreachable /
  # provider_entry_ambiguous / provider_readback_mismatch,
  # provider_model_missing, mcp_port_undeclared / mcp_credential_unresolved /
  # mcp_endpoint_dead / mcp_serve_not_answering, model_reply_failed /
  # model_reply_empty, probe_chat_not_created, probe_readback_failed (the
  # stored answer could not be read back), probe_turn_timeout (the turn
  # was still running when setup stopped waiting), tool_use_unobserved (the
  # preset replied but its stored turn records no graph tool call:
  # convergence without conversation readiness), graph_tool_calls_refused
  # (the graph refused every call it received; data names the refusal
  # codes), graph_tool_calls_failed (it called graph tools and none reached
  # the graph). No
  # payload carries a password, session token, API key or provider key —
  # only variable names, an email and HTTP statuses.
  - code: chat_setup_failed
    python_exception: ChatSetupError
    severity: user
    raised_by: [okg.substrate.chat.setup, okg chat setup]
    fix_hint_template: "fix the named input, then re-run `okg chat setup --deployment <d>`"
    data_shape: [step, reason]

  # PACT chat-codex-cli-provider-shim. `okg chat codex-shim` refused to
  # start. data.reason names why: shim_token_env_invalid / shim_token_unset /
  # shim_token_too_short (the bearer every caller must send), codex_not_
  # installed / codex_not_runnable / codex_version_untested, codex_home_
  # missing / codex_home_not_dedicated (the shim's own Codex home holds no
  # AGENTS.md, config.toml or skills), isolation_unverified / isolation_leak
  # (`codex debug prompt-input` still showed operator context), workdir_
  # inside_repository, mcp_url_invalid / mcp_token_env_invalid / mcp_token_
  # unset / mcp_tools_undeclared / mcp_url_missing / mcp_unreachable /
  # mcp_tools_exceed_declared (the MCP server exposes a tool outside
  # --mcp-tools), limits_invalid, port_unavailable. Per-request refusals are
  # HTTP bodies with their own codes (codex_not_signed_in,
  # codex_rate_limited, codex_containment_breach, codex_version_changed,
  # ...), not this exception. No payload carries a token value.
  - code: codex_shim_refused
    python_exception: CodexShimError
    severity: user
    raised_by: [okg.substrate.chat.codex_shim, okg chat codex-shim]
    fix_hint_template: "fix the named input, then start `okg chat codex-shim` again"
    data_shape: [reason]

  # `okg chat setup` writes a missing `chat:` block into the
  # deployment manifest from its answers (block_scaffold.ensure_chat_block).
  # One code; `data['reason']` names why the answers cannot become a valid
  # block (provider_missing, model_missing, mcp_port_missing,
  # provider_key_env_not_a_name, search_profile_undeclared,
  # chat_block_answer_conflicts, manifest_unparseable, ...) and
  # `data['flag']` names the flag to supply or correct where one exists.
  # No payload carries a key value, only variable names and shape codes.
  - code: chat_block_scaffold_refused
    python_exception: ChatBlockScaffoldError
    severity: user
    raised_by: [okg.substrate.chat.block_scaffold, okg chat setup]
    fix_hint_template: "supply or correct the named flag, then re-run `okg chat setup --deployment <d>`"
    data_shape: [reason]

  # PACT chat-plan-apply-readback. The plan/apply/readback contract for the
  # chat surface: `okg chat plan` derives the desired state from the manifest
  # without contacting the instance, `okg chat sync --plan` refuses to apply a
  # plan that no longer describes that manifest, and `okg chat readback`
  # compares a live instance against one.
  - code: chat_plan_refused
    python_exception: ChatPlanError
    severity: user
    raised_by: [okg.substrate.chat.plan_apply, okg chat plan, okg chat readback]
    fix_hint_template: "re-run `okg chat plan`"
    # The base class, raised directly for a declared-but-unset credential
    # reference (which adds `variable` and `deployment`), an unreadable or
    # non-plan document (which adds `path`), a plan edited after it was
    # written (which adds `recorded` and `computed`), and the same
    # self-digest check inside readback (which adds nothing). Only `reason`
    # is present at every raise site.
    data_shape: [reason]

  - code: chat_plan_output_path_exists
    python_exception: ChatPlanOutputPathExists
    severity: user
    raised_by: [okg.substrate.chat.plan_apply, okg chat plan, okg chat readback]
    fix_hint_template: "name an unused output directory"
    data_shape: [reason, path]

  - code: chat_plan_drift
    python_exception: ChatPlanDrift
    severity: user
    raised_by: [okg.substrate.chat.plan_apply, okg chat sync]
    fix_hint_template: "re-run `okg chat plan`, review it, then apply that plan"
    data_shape: [reason, deployment, plan_digest, manifest_digest]

  # Carried in the readback document's `code` field and used as the CLI's
  # non-zero exit reason. It is a class rather than an ad-hoc code so the
  # constant has one definition, and the readback verb reports every
  # deviating surface rather than raising on the first.
  # `data['reason']` arms on a deviation include
  # `mcp_connection_credential_stale`: the connection the site STORED
  # carries a different credential (`differing` names the fields: key,
  # auth_type, headers) from the one the operator's environment resolves,
  # for example after a token rotation without `okg chat sync`. The verify
  # probe cannot see it because it dials with the environment's credential.
  # Compared by keyed digest within one process; no value or digest is
  # written. Two more arms fail closed where that comparison cannot run:
  # `mcp_connection_credential_unmeasured` (the Open WebUI version hides the
  # stored key, so readback cannot verify it; run `okg chat sync` after any
  # rotation) and `mcp_connection_duplicate_id` (more than one connection
  # carries the server id, so which credential a chat turn sends is unknown;
  # remove the extra entries, then sync).
  - code: chat_readback_deviation
    python_exception: ChatReadbackDeviation
    severity: user
    raised_by: [okg.substrate.chat.plan_apply, okg chat readback]
    fix_hint_template: "re-run `okg chat sync` to reapply the plan, then read back again"
    data_shape: []

  # Bundle chat composition. A bundle's chat contribution is a
  # typed asset in a verified package; these refuse BEFORE any plan digest
  # exists, so a composition nobody could review never gets applied.
  - code: chat_bundle_composition_refused
    python_exception: ChatBundleCompositionError
    severity: user
    raised_by: [okg.substrate.chat.bundle_composition]
    fix_hint_template: "fix the bundle's chat contribution, or drop --install-plan"
    # The base class. It is never raised directly -- every site raises one of
    # the five subclasses below -- and `reason` is the one key all of them
    # carry, so a caller may dispatch on the base code's shape.
    data_shape: [reason]

  - code: chat_bundle_contribution_invalid
    python_exception: ChatBundleContributionInvalid
    severity: user
    raised_by: [okg.substrate.chat.bundle_composition, okg chat plan, okg chat sync]
    fix_hint_template: "rebuild the package so the chat contribution parses"
    # Seven raise sites: unreadable bytes, an unknown schema, an unrecognized
    # key, a malformed branding block, two malformed-list arms (which add
    # `field` rather than `qualified_id`), and two contributions in one bundle
    # (which adds `bundle_id` and `qualified_ids`). Only `reason` is present
    # at every one of them.
    data_shape: [reason]

  - code: chat_bundle_asset_unresolved
    python_exception: ChatBundleAssetUnresolved
    severity: user
    raised_by: [okg.substrate.chat.bundle_composition, okg chat plan, okg chat sync]
    fix_hint_template: "select the named asset into the bundle, or drop the reference"
    data_shape: [reason, qualified_id]

  - code: chat_bundle_connection_unresolved
    python_exception: ChatBundleConnectionUnresolved
    severity: user
    raised_by: [okg.substrate.chat.bundle_composition, okg chat plan, okg chat sync]
    fix_hint_template: "package the connection as a connector asset the bundle selects"
    data_shape: [reason, qualified_id]

  # NOT "the manifest asked for a live tool": it cannot. chat.mcp.tools is
  # closed to the OKG operator universe when the block is parsed, so this is
  # the reachable conflict -- one name declared as both transports.
  - code: chat_bundle_live_tool_conflict
    python_exception: ChatBundleLiveToolConflict
    severity: user
    raised_by: [okg.substrate.chat.bundle_composition, okg.substrate.chat.live_tool_slot, okg chat plan, okg chat sync]
    fix_hint_template: "rename the live tool, or drop it from the bundle's graph_tools"
    data_shape: [reason, tool]

  # The live-tool connection slot: a
  # closed list of live-tool names bound to a SECOND MCP connection with its
  # own endpoint, its own bearer variable and its own tool filter, granted
  # only to the audiences the manifest names. Its own code rather than
  # `chat_sync_failed`, because the slot resolves for `okg chat plan` too --
  # which contacts no instance, and must not refuse under a code whose fix
  # hint says to re-run a sync.
  #
  # Two `data['reason']` arms: `audience_grants_undeclared_live_tool` (an
  # audience is granted a name `chat.mcp.live_tools.names` does not allow)
  # and `two_audiences_one_live_connection` (two audiences granted different
  # sets over the one live registration, which the vendor's per-connection
  # filter cannot serve). The two OTHER refusals this slice can raise reuse
  # existing codes on purpose: a manifest naming a live tool the bundle did
  # not declare is `chat_bundle_manifest_widens` on surface
  # `mcp:live_tools`, and a live-tool name that is also a graph operator is
  # `chat_bundle_live_tool_conflict` -- the same defect S3 registered, now
  # reachable from a manifest because `chat.mcp.live_tools.names` is
  # deliberately not closed to the OKG operator universe.
  - code: chat_live_tool_slot_refused
    python_exception: ChatLiveToolSlotError
    severity: user
    raised_by: [okg.substrate.chat.live_tool_slot, okg chat plan, okg chat sync]
    fix_hint_template: "fix chat.mcp.live_tools and the audience grants that read it"
    # `audience` is NOT declared: the `audience_grants_undeclared_live_tool`
    # arm carries it, the `two_audiences_one_live_connection` arm cannot
    # (its subject is the whole set of granting audiences, named in
    # `granted`). A data_shape key present at only one raise site would read
    # as a guarantee callers cannot rely on.
    data_shape: [reason, deployment, allowed, granted]

  - code: chat_bundle_manifest_widens
    python_exception: ChatBundleManifestWidens
    severity: user
    raised_by: [okg.substrate.chat.bundle_composition, okg chat plan, okg chat sync]
    fix_hint_template: "declare it in the bundle's contribution, or narrow the manifest"
    data_shape: [reason, surface, undeclared, declared]

  # PACT chat-tool-surface. Its own code, not `chat_manifest_invalid`,
  # because the operator action differs: the manifest is well-formed and the
  # override file is the thing to fix — a snippet that names a tool the chat
  # surface does not project, one that is not a string, or one over the
  # per-tool description budget.
  - code: tool_description_override_invalid
    python_exception: ToolDescriptionError
    severity: user
    raised_by: [okg.substrate.mcp.operators, okg chat sync]
    fix_hint_template: "fix the deployment's tool_description_overrides file"
    data_shape: [reason, path, tool, declared, projected, unprojected, offenders]

  - code: chat_ui_census_unavailable
    python_exception: ChatUiCensusUnavailable
    severity: user
    raised_by: [okg.substrate.deployments.chat_block]
    fix_hint_template: "record the ui knob census artifact at the pinned Open WebUI version, then re-run"
    data_shape: [artifact, reason, observed, expected]

  # PACT nomos-admission-override-sourceless-record. An accepted submission
  # is written under its producer id as the fact `source`, and Nomos judges
  # the accept on that value, so a caller may not choose an identity the
  # server assigns. data['reason'] is one of producer_id_blank,
  # producer_id_padded, producer_id_reserved_prefix, producer_kind_server_only,
  # producer_id_is_registered_source. `okg admission decide` re-checks an
  # accept whose facts would be written under the producer id and returns
  # this code as a refusal, leaving the envelope `pending`.
  - code: admission_producer_identity_reserved
    python_exception: AdmissionProducerIdentityReserved
    severity: user
    raised_by:
      - okg admission submit
      - okg admission decide
      - mcp record
      - mcp propose
    referenced_in: []
    fix_hint_template: "submit under your own producer id such as agent:<name>"
    data_shape: [deployment, producer_id, producer_kind, reason]

  # PACT chat-record-affordance. Severity `internal`, not `user`: this fires
  # when a write result cannot be rendered into an honest answer -- e.g. an
  # admission submit that returned no admission_id -- which is a broken
  # producer contract, not something an operator can fix by editing config.
  # It exists so the renderer REFUSES rather than emitting an answer that
  # claims a finding is pending review without naming the envelope to act on,
  # or worse, invents an identifier.
  - code: write_answer_unrenderable
    python_exception: WriteAnswerError
    severity: internal
    raised_by: [okg.substrate.mcp.operators]
    fix_hint_template: "report this: the write result is missing a field the answer must name"
    data_shape: [reason, result_keys]

  # PACT chat-instance-lifecycle. One code, because the operator action is
  # always the same shape: read data['reason'] and the named input, supply or
  # correct it, run the command again. A partially provisioned instance is
  # reported here as a FAILURE with its teardown recorded, never as a degraded
  # success.
  - code: chat_instance_failed
    python_exception: ChatInstanceError
    severity: user
    raised_by: [okg.substrate.chat.instance, okg chat-instance]
    fix_hint_template: "correct the named input and run the command again"
    data_shape: [reason, teardown]

  # The chat layer's image, and its
  # upgrade / rollback / retirement, are governed independently of the graph.
  - code: chat_image_not_tested
    python_exception: ChatImageNotTested
    severity: user
    raised_by:
      - okg.substrate.chat.instance
      - okg.substrate.chat.lifecycle
      - okg chat-instance up
      - okg chat-instance lifecycle-receipt
    fix_hint_template: "run one of the tested images, or measure and register the new one"
    # Raised for an image outside TESTED_IMAGES and for an EMPTY tested set,
    # which must refuse rather than admit everything. The receipt path adds
    # `role` (which side of an image change was untested); only these three
    # keys are present at every raise site.
    data_shape: [reason, image, tested]

  - code: chat_lifecycle_refused
    python_exception: ChatLifecycleError
    severity: user
    raised_by: [okg.substrate.chat.lifecycle, okg chat-instance lifecycle-receipt]
    fix_hint_template: "correct the named input and record the receipt again"
    # The base class, raised for a candidate identical to its baseline, a
    # readback taken against another plan, a document that is not an upgrade
    # receipt, an incomplete app-database identity, an instance that could not
    # be read, a receipt edited after it was written, and a missing per-kind
    # input. Only `reason` is present at every one of them.
    data_shape: [reason]

  - code: chat_lifecycle_output_path_exists
    python_exception: ChatLifecycleOutputPathExists
    severity: user
    raised_by: [okg.substrate.chat.lifecycle, okg chat-instance lifecycle-receipt]
    fix_hint_template: "name a directory that does not exist yet"
    data_shape: [reason, path]

  - code: chat_lifecycle_app_database_changed
    python_exception: ChatLifecycleAppDatabaseChanged
    severity: user
    raised_by: [okg.substrate.chat.lifecycle, okg chat-instance lifecycle-receipt]
    fix_hint_template: "point the app-database variable back at the recorded database"
    # Identities, never DSNs: `baseline` and `candidate` each carry host,
    # port and database name only.
    data_shape: [reason, deployment, kind, baseline, candidate]

  - code: chat_lifecycle_baseline_unreconciled
    python_exception: ChatLifecycleBaselineUnreconciled
    severity: user
    raised_by: [okg.substrate.chat.lifecycle, okg chat-instance lifecycle-receipt]
    fix_hint_template: "sync, re-run the readback, then record the receipt"
    data_shape: [reason, deployment, deviations, surfaces]

  - code: chat_lifecycle_surface_remains
    python_exception: ChatLifecycleSurfaceRemains
    severity: user
    raised_by: [okg.substrate.chat.lifecycle, okg chat-instance lifecycle-receipt]
    fix_hint_template: "remove the named surfaces through the admin API, then re-run"
    data_shape: [reason, deployment, remaining]

  # PACT chat-css-bundle-contract. The deployment's declared CSS file is a
  # BYTE-DELIVERY surface, not a knob: this vendor version exposes no styling
  # value to set or read, so the only claim is that the bytes shipped are the
  # bytes served. This code is reserved for the case where the run cannot even
  # establish what state that surface is in -- today, a ship record that does
  # not parse. Read as "this deployment never delivered anything", such a
  # record turns a retraction into a no-op and leaves the delivered bytes on
  # the instance forever. Contract refusals (a stale approval version against
  # a bumped vendor pin, a set CUSTOM_NAME) are NOT raised under this code:
  # they are carried on the sync report with the removal facts alongside them,
  # because a refusal that also cleared bytes has to report both.
  - code: chat_css_bundle_refused
    python_exception: ChatCssBundleError
    severity: user
    raised_by: [okg.substrate.chat.css_bundle, okg chat sync]
    fix_hint_template: "repair or delete the recorded css ship state named in data['path'], then re-run"
    data_shape: [reason, deployment, path, missing]

  # PACT chat-record-affordance (source admin). Its own code so the CLI, the
  # tests, and the projection's failure message can dispatch on the specific
  # refusal rather than on message text.
  - code: chat_source_admin_refused
    python_exception: ChatSourceAdminError
    severity: user
    raised_by: [okg.substrate.chat.source_admin]
    fix_hint_template: "grant the admin capability the refusal names, then retry"
    data_shape: [reason]

  # PACT chat-document-loader (chat_sessions source). A refusal is NOT an
  # empty upstream: this is what keeps "the app database moved to a schema
  # this reader does not know" from reaching the graph as "the operator held
  # no conversations" — silent-empty being the failure mode that matters here.
  - code: chat_source_refused
    python_exception: ChatSourceRefused
    severity: user
    raised_by: [okg.substrate.library.sources.chat_sessions]
    fix_hint_template: "reconcile the chat app database schema with the reader, then re-run the source"
    data_shape: [reason]

  # ----- retired viz chat sub-block (PACT retire-viz-chat) -----
  # `viz.chat` configured the operator-local chat backend that the `chat:`
  # block replaced. Its own code, not `chat_manifest_invalid`, because the
  # operator action differs: this is not a typo in a live block, it is
  # configuration for a surface that no longer exists. Without the refusal
  # the manifest would load with no error at all and the block would drive
  # nothing — `viz` is a known top-level key and nothing rejects an unknown
  # key underneath it, so the operator would see their configuration in the
  # file and its effect nowhere.

  - code: viz_chat_retired
    python_exception: VizChatRetired
    severity: user
    raised_by: [okg.substrate.deployments.chat_block, okg lint deployments]
    fix_hint_template: "remove `viz.chat` and declare the top-level `chat:` block instead"
    data_shape: [path, replacement_path, pact, archive_commit, archive_path]

  # ----- typed viz theme tokens (PACT operator-ui-deployment-theme) -----
  # `viz.theme` is the operator console's per-deployment token set
  # (background, accent, fg, fg_faint, border, surface, rail), served on
  # /viz/api/deployments and applied in the browser as CSS custom
  # properties. Its own code, not `chat_manifest_invalid`, because the
  # operator action and the blast radius differ: the refused value is
  # destined for a stylesheet, so normalizing it would paint a color the
  # operator never wrote. Scoped to `viz.theme` only — the rest of the
  # untyped `viz` dict keeps its pass-through semantics.
  #
  # TWO codes, because the operator edit differs. `viz_theme_invalid` says
  # a value is not a color. `viz_theme_incoherent` says every value IS a
  # color and the set contradicts itself — a dark `background` declared
  # without the `surface` it would otherwise leave near-white. The second
  # code was added by the operator ruling of 2026-08-18, which widened the
  # token set with the surface family rather than let an incoherent
  # declaration render unreadable.

  - code: viz_theme_invalid
    python_exception: VizThemeInvalid
    severity: user
    raised_by: [okg.substrate.deployments.chat_block, okg lint deployments]
    fix_hint_template: "declare `viz.theme` tokens as CSS color values, e.g. `accent: \"#10b981\"`"
    data_shape: [path, observed, observed_type, unknown, tokens]

  - code: viz_theme_incoherent
    python_exception: VizThemeIncoherent
    severity: user
    raised_by: [okg.substrate.deployments.chat_block, okg lint deployments]
    fix_hint_template: "declare `viz.theme.surface` alongside a dark `viz.theme.background`, or remove the background"
    data_shape: [path, observed, luminance, midpoint, requires, reason]

  # ----- chat SSO (PACT chat-sso-integration) -----
  # The identity model for BOTH graphical surfaces. `chat_sso_invalid` is
  # raised at manifest load; `chat_sso_startup_refused` at site bring-up,
  # where the manifest is checked against the registered principal mapping
  # and the operator environment. Separate codes because the operator action
  # differs: one edits the manifest, the other fixes the deployment's
  # identity wiring.

  - code: chat_sso_invalid
    python_exception: ChatSsoError
    severity: user
    raised_by: [okg.substrate.deployments.chat_block]
    fix_hint_template: "declare chat.sso.mode explicitly, with every identity-provider element multi_user requires"
    data_shape: [path, mode, missing, declared_idp_elements]

  - code: chat_sso_startup_refused
    python_exception: ChatSsoStartupError
    severity: user
    raised_by: [okg.substrate.chat.sso]
    fix_hint_template: "align chat.sso with nomos.principal_mapping and the operator environment, then bring the site up again"
    data_shape: [deployment, reason, mode, skew]

  - code: chat_sso_projection_failed
    python_exception: ChatSsoProjectionError
    severity: user
    raised_by: [okg.substrate.chat.sso_groups]
    fix_hint_template: "re-run the projection once the instance and the graph are reachable; a partial projection is never kept"
    data_shape: [deployment, reason, principal, readback_diff]

  # Health-banner projection (PACT chat-health-banner-projection). The probe
  # failing is a STATE, not a run failure: observe() converts this into
  # health.state = probe_failed, the owned banner is held, and the sync
  # report names the failure. It surfaces as an error code only when a
  # caller invokes the probe directly.
  - code: chat_health_probe_failed
    python_exception: HealthProbeError
    severity: operational
    raised_by: [okg.substrate.chat.health_banner]
    fix_hint_template: "run `okg dogfood status --deployment <name> --json` by hand to see why the probe cannot produce a reading; a failed probe never reads as healthy"

  # Source retirement. The precise machine-actionable cause is in
  # data.refusal_codes; one wire code keeps plan/apply/removal clients stable.
  - code: source_retirement_refused
    python_exception: SourceRetirementRefused
    severity: user
    raised_by: [okg.substrate.source_retirement]
    fix_hint_template: "resolve the named retirement precondition, generate a new plan, and retry"
    data_shape: [refusal_codes, mutation_started]
  # A retired CLI command (`okg new-source`). It refuses before
  # writing anything and names what replaces it.
  - code: command_retired
    python_exception: CommandRetired
    severity: user
    raised_by:
      - okg new-source
    referenced_in:
      - docs/reference/cli.md
      - docs/develop/index.md
    fix_hint_template: "{replacement}"
    data_shape: [command, replacement, example]
  # PACT make-mcp-bounded-expansion-actionable. Continuations are opaque
  # capabilities bound to one deployment, pin, projection, and Nomos authority.
  # Every validation failure intentionally shares one public class so callers
  # cannot use token differences to learn anything about another context.
  - code: continuation_token_invalid
    python_exception: ContinuationTokenInvalid
    severity: user
    raised_by: [okg.substrate.mcp.continuation]
    fix_hint_template: "pass the token exactly as the reply printed it after `next:` (a token is opaque: never build, shorten or edit one), or restart the read without it; error.retry_call (mode restart) is that restart"
    # PACT read-model-s6-page-next: `mismatched` names the bound parts that
    # differ; `token_kind`/`tool` route a `next` token; reasons add
    # signing_key_changed, kind_unroutable, wrong_tool and token_unknown (a
    # handle this process no longer holds).
    data_shape: [reason, pinned_generation_id, authority_fingerprint, mismatched, token_kind, tool]

  - code: result_reference_invalid
    python_exception: ResultReferenceInvalid
    severity: user
    raised_by: [okg.substrate.mcp.result_references]
    fix_hint_template: "run the read that produced the reference again"
    # PACT read-result-references-3222-store. `reason` is one of malformed,
    # store_lost, signature_invalid, expired, evicted or unknown. Another
    # reader's id answers exactly as an id that was never issued.
    # Slice 2 (read-result-references-3222-consumers) adds the consumer
    # reasons, each before any member is read: generation_conflict,
    # generation_unavailable (`cause`: the code opening the pin gave),
    # binding_mismatch (`field`: authority, catalog, branch, database,
    # deployment or attributes) and member_missing (`count` only).
    # PACT read-live-handles: a live handle's `expired` or `evicted` adds
    # `retry_call`, the call that rebuilds it (`authority` removed), for the
    # reader that made it; another logical session of that reader answers
    # `unknown`, as an id never issued.
    # PACT read-multi-handle-input: a chain handle a newer one replaced
    # answers `replaced` to its owner, with `replaced_by` (the newer id) and
    # `retry_call` (a read of it, no upstream call).
    data_shape: [reason, field, count, cause, retry_call, replaced_by]

  - code: result_reference_capacity
    python_exception: ResultReferenceCapacity
    severity: user
    raised_by: [okg.substrate.mcp.result_references]
    fix_hint_template: "narrow the read, or retry after older references expire"
    # `reason`: reference_members or reference_bytes (one reference too
    # large, with its `members` or `bytes`), or reader_references,
    # principal_references, server_references or total_bytes (the store is
    # full, with the caller's own usage only; `principal_references` only on
    # a multi-user server). `limits` is the fixed limit set.
    data_shape: [reason, members, bytes, reader_references, reader_bytes, principal_references, limits]

  - code: result_reference_unsupported
    python_exception: ResultReferenceUnsupported
    severity: user
    raised_by: [okg.substrate.mcp.result_references]
    fix_hint_template: "use a lexical record search with retain, or drop retain"
    # PACT read-result-references-3222-consumers. `reason`: method, rank_by
    # or argument (named in `argument`), refused from the arguments alone
    # before any SQL (a passage-unit subtype after the catalog read). A pin
    # with no overlay marker is refused overlay_generation_unmaterialized at
    # production (PACT lane-s-storage-cutover). Slice 3
    # (read-result-references-3222-summary) adds `argument` values select
    # and max_chars (with view="metadata") and summary (without it).
    data_shape: [reason, argument]

  - code: live_result_denied
    python_exception: LiveResultDenied
    severity: user
    raised_by: [okg.substrate.mcp.server]
    fix_hint_template: "the retained answer was dropped; call expand(live=..., retain=true) again once the live policy allows it"
    # A read of a retained live answer (filter, map or aggregate with
    # input={"ref": "l1..."}) asked the live gate again and got anything
    # other than allow: a deny, a gate error or an unresolved principal.
    # `reason` is the gate's reason code; `relation` names the relation.
    # The set is dropped and the read writes its sample row.
    data_shape: [reason, relation]

  - code: live_result_predicate_unsupported
    python_exception: LiveResultPredicateUnsupported
    severity: user
    raised_by: [okg.substrate.mcp.live_result_sets]
    fix_hint_template: "read a retained live answer by attrs.<field> with the filter predicate grammar"
    # A read of a retained live answer used an argument it does not take.
    # `argument` names it: predicate (a bare or nested field, or the
    # contains op), select or projection (a field other than
    # attrs.<field>), by, order_by, metrics (other than count) or retain.
    # `reason` `kept_set_too_large`: a cut map(compute) page whose computed
    # rows are too large to keep (PACT read-map-compute).
    data_shape: [argument]

  - code: result_reference_internal
    python_exception: ResultReferenceInternal
    severity: fatal
    raised_by: [okg.substrate.mcp.result_references]
    fix_hint_template: "report this server bug"
    # `reason`: contract (a producer broke the draft contract) or
    # principal_unnamed (a multi-user claim lacks provider_id, issuer or
    # external_subject, named in `missing`).
    data_shape: [reason, missing]

  - code: invalid_path_grammar
    python_exception: InvalidPathGrammar
    severity: user
    raised_by: [okg.substrate.mcp.path_diagnostics]
    fix_hint_template: "pass a non-empty path of edge_type:out or edge_type:in hops"
    data_shape: [hop_index, requested_hop, pinned_generation_id, catalog_version_id, authority]

  - code: invalid_path_direction
    python_exception: InvalidPathDirection
    severity: user
    raised_by: [okg.substrate.mcp.path_diagnostics]
    fix_hint_template: "replace the direction with out or in"
    data_shape: [hop_index, edge_type, direction, pinned_generation_id, catalog_version_id, authority]

  - code: invalid_path_edge_type
    python_exception: InvalidPathEdgeType
    severity: user
    raised_by: [okg.substrate.mcp.path_diagnostics]
    fix_hint_template: "inspect the pinned ontology and retry with a declared edge type"
    data_shape: [hop_index, edge_type, direction, pinned_generation_id, catalog_version_id, authority]

  - code: invalid_expand_shape
    python_exception: InvalidExpandShape
    severity: user
    raised_by: [okg.substrate.mcp.path_diagnostics]
    fix_hint_template: "use either the one-hop parameter set or the bounded path parameter set"
    data_shape: [requested_shape, field, limit, pinned_generation_id, catalog_version_id, authority]

  - code: expand_link_scan_bound
    python_exception: ExpandLinkScanBound
    severity: user
    raised_by: [okg.substrate.mcp.tools]
    fix_hint_template: "name an edge_type or a single direction"
    data_shape: [node_id, edge_type, direction]

  - code: invalid_subtype_inspection
    python_exception: InvalidSubtypeInspection
    severity: user
    raised_by: [okg.substrate.mcp.subtype_summary]
    fix_hint_template: "pass a non-empty subtype and a supported detail projection"
    data_shape: [field, requested_detail, requested_page_size]

  - code: subtype_summary_item_too_large
    python_exception: SubtypeSummaryItemTooLarge
    severity: user
    raised_by: [okg.substrate.mcp.subtype_summary]
    fix_hint_template: "increase max_bytes or request a narrower explicit detail"
    data_shape: [subtype, max_bytes, minimum_item_bytes, pinned_generation_id]

  - code: record_text_too_large
    python_exception: RecordTextTooLarge
    severity: user
    raised_by: [okg.substrate.mcp.record_text]
    fix_hint_template: "search within the record, or page its chunks with expand(edge_type=contains)"
    data_shape: [node_id, max_occurrences, pinned_generation_id]

  - code: record_text_budget_too_small
    python_exception: RecordTextBudgetTooSmall
    severity: user
    raised_by: [okg.substrate.mcp.record_text]
    fix_hint_template: "call again with a larger max_bytes"
    data_shape: [max_bytes, node_id]

  - code: text_location_stale
    python_exception: TextLocationStale
    severity: user
    raised_by: [okg.substrate.mcp.record_text]
    fix_hint_template: "search again for a fresh location, or read the record from its start with inspect(kind=text, node_id=<record>)"
    data_shape: [chunk, offset, node_id, reason, pinned_generation_id]

  - code: text_batch_state_too_large
    python_exception: BatchStateTooLarge
    severity: user
    raised_by: [okg.substrate.mcp.text_batch]
    fix_hint_template: "split the request into smaller batches"
    data_shape: [max_decoded_token_bytes, max_encoded_token_chars]

  - code: text_batch_budget_too_small
    python_exception: BatchBudgetTooSmall
    severity: user
    raised_by: [okg.substrate.mcp.text_batch]
    fix_hint_template: "increase max_bytes within the deployment ceiling or split the batch"
    data_shape: [max_bytes, required_budget_bytes]

  - code: node_batch_state_too_large
    python_exception: NodeBatchStateTooLarge
    severity: user
    raised_by: [okg.substrate.mcp.node_batch]
    fix_hint_template: "pass fewer or shorter node_ids per call"
    data_shape: [max_decoded_token_bytes, max_encoded_token_chars]

  - code: node_batch_budget_too_small
    python_exception: NodeBatchBudgetTooSmall
    severity: user
    raised_by: [okg.substrate.mcp.node_batch]
    fix_hint_template: "increase max_bytes within the deployment ceiling or narrow select"
    data_shape: [max_bytes, required_budget_bytes]

  - code: batch_load_refused
    python_exception: BatchLoadRefused
    severity: user
    raised_by: [okg.substrate.consistency.batch_schedule]
    fix_hint_template: null
    data_shape: []

  - code: batch_schedule_baseline_refused
    python_exception: BaselineRefused
    severity: user
    raised_by: [okg.substrate.consistency.batch_schedule_baselines]
    fix_hint_template: null
    data_shape: []

  - code: batch_schedule_oracle_refused
    python_exception: OracleRefused
    severity: user
    raised_by: [okg.substrate.consistency.batch_schedule_oracle]
    fix_hint_template: null
    data_shape: []

  - code: batch_measurement_refused
    python_exception: MeasurementRefused
    severity: user
    raised_by: [okg.substrate.consistency.batch_measurements]
    fix_hint_template: null
    data_shape: []

  # ----- okg runtime cancel-workflow refusals -----
  # Attached per-instance rather than given classes: each carries a payload
  # assembled from the observed workflow row at the raise site.
  - code: deployment_queues_unresolved
    python_exception: null
    severity: fatal
    raised_by: [okg.substrate.runtime.workflow_cancel]
    fix_hint_template: "name a deployment whose DBOS queues resolve"
    data_shape: [deployment]

  - code: dbos_schema_absent
    python_exception: null
    severity: user
    raised_by: [okg.substrate.runtime.workflow_cancel.cancel_deployment_workflow]
    fix_hint_template: "run okg runtime bootstrap for this deployment first"
    data_shape: [deployment, workflow_id]

  - code: workflow_not_found
    python_exception: null
    severity: user
    raised_by: [okg.substrate.runtime.workflow_cancel.cancel_deployment_workflow]
    fix_hint_template: "check the workflow id with okg runtime debug-workflow"
    data_shape: [deployment, workflow_id]

  - code: workflow_already_terminal
    python_exception: null
    severity: user
    raised_by: [okg.substrate.runtime.workflow_cancel.cancel_deployment_workflow]
    fix_hint_template: "the workflow already finished and holds no queue slot"
    data_shape: [deployment, workflow_id, name, status, queue_name]

  - code: workflow_outside_deployment
    python_exception: null
    severity: user
    raised_by: [okg.substrate.runtime.workflow_cancel.cancel_deployment_workflow]
    fix_hint_template: "run the command against the deployment that owns the queue"
    data_shape: [deployment, workflow_id, name, status, queue_name, deployment_queues]

  - code: workflow_status_changed
    python_exception: null
    severity: recoverable
    raised_by: [okg.substrate.runtime.workflow_cancel.cancel_deployment_workflow]
    fix_hint_template: "re-read the workflow; it left the state this command observed"
    data_shape: [deployment, workflow_id, observed_status, current_status]

# ----- connector registration -----
#
# Refusals raised while turning a ConnectorRegistration into a
# source-registry entry. All seven subclass ConnectorRegistrationError,
# which is re-exported as okg.deployment.ConnectorRegistrationError so a
# connector author catches them without importing the substrate.

  - code: connector_capability_unknown
    python_exception: ConnectorCapabilityUnknown
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "declare only capabilities the runner honours; see CONNECTOR_CAPABILITIES"
    data_shape: [connector_type, capability, allowed]

  - code: connector_auth_mode_unknown
    python_exception: ConnectorAuthModeUnknown
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "declare only credential modes the substrate implements; see AUTH_MODES"
    data_shape: [connector_type, auth_mode, allowed]

  - code: connector_output_signature_invalid
    python_exception: ConnectorOutputSignatureInvalid
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "fix the declared block against source_registry.schema.json: {0}"
    data_shape: [connector_type, field, path, reason]

  - code: connector_config_schema_invalid
    python_exception: ConnectorConfigSchemaInvalid
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "config_schema must be a valid Draft 2020-12 JSON Schema object"
    data_shape: [connector_type, reason]

  - code: connector_required_module_unqualified
    python_exception: ConnectorRequiredModuleUnqualified
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "name each required ontology module as a strict owner:name id"
    data_shape: [connector_type, module_id, reason]

  - code: connector_sdk_version_unsupported
    python_exception: ConnectorSdkVersionUnsupported
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "the running okg.deployment is outside the connector's declared window"
    data_shape: [connector_type, sdk_version, min_version, max_version_exclusive]

  - code: connector_asset_payload_invalid
    python_exception: ConnectorAssetPayloadInvalid
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "rebuild the asset with as_asset_payload() from the SDK version the package declares"
    # The payload differs by arm and nothing is present at every raise site,
    # so the shape is empty. A non-mapping payload carries `payload_type`, a
    # foreign asset schema carries `schema`, a missing `registration` or
    # `sdk_range` object carries `registration_type` and `sdk_range_type`,
    # and a body whose fields do not match the dataclass carries
    # `connector_type`, `reason` and `declared_fields`.
    data_shape: []

  - code: connector_sdk_bound_invalid
    python_exception: ConnectorSdkBoundInvalid
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "declare a plain PEP 440 release bound, such as 1.1.0"
    data_shape: [field, value]

  - code: connector_registration_deprecated
    python_exception: ConnectorRegistrationDeprecated
    severity: user
    raised_by: [okg.deployment connector registration]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "migrate to the replacement connector, or pass allow_deprecated=True"
    data_shape: [connector_type, version, deprecation]

# ----- connector conformance kit -----
#
# The kit refuses a harness misconfiguration: a --okg-connector
# reference that does not resolve to a ConnectorCase. It is not a
# ConnectorRegistrationError, so a bad reference is never reported
# as a connector defect.

  - code: connector_conformance_case_invalid
    python_exception: ConnectorConformanceCaseInvalid
    severity: user
    raised_by: [okg.deployment conformance kit]
    referenced_in: [docs/reference/sdk-api.md]
    fix_hint_template: "pass --okg-connector module.path:CASE naming a ConnectorCase"
    data_shape: [reference, reason]


  - code: nomos_principal_unidentified
    python_exception: null
    severity: user
    raised_by: [mcp.principal_mapping.unidentified_principal_error]
    referenced_in: [docs/reference/mcp.md]
    fix_hint_template: "send the declared principal header and register its subject binding"
    data_shape: [reason_code, refusal_kind, channel, subject]

  - code: nomos_identity_channel_conflict
    python_exception: null
    severity: user
    raised_by: [mcp.principal_mapping.conflicting_identity_channel_error]
    referenced_in: [docs/reference/mcp.md]
    fix_hint_template: "remove authority.nomos_identity_claim; use the declared principal header"
    data_shape: [reason_code, refusal_kind, subject]

  - code: mcp_multi_user_requires_auth
    python_exception: null
    severity: user
    raised_by: [mcp.principal_mapping.multi_user_requires_auth_error]
    referenced_in: [docs/reference/mcp.md]
    fix_hint_template: "configure --auth-token-env VARIABLE_NAME on streamable-http"
    data_shape: [transport, auth_active]

  - code: mcp_multi_user_stdio_incompatible
    python_exception: null
    severity: user
    raised_by: [mcp.server.run_server]
    referenced_in: [docs/reference/mcp.md]
    fix_hint_template: "use authenticated streamable-http or drop --multi-user-principals"
    data_shape: [transport, multi_user_principals]

  # PACT mcp-oidc-principal-policy: the per-user block, the
  # single-user caller-claim refusal, and the OIDC-mode start refusals that
  # were emitted without a registry row.
  - code: nomos_principal_blocked
    python_exception: null
    severity: user
    raised_by: [mcp.principal_mapping.blocked_principal_error]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "an operator lifts the block with `okg nomos binding unblock`"
    data_shape: [reason_code, refusal_kind, channel, subject]

  - code: nomos_identity_claim_untrusted
    python_exception: null
    severity: user
    raised_by: [mcp.server.caller_identity_claim_untrusted_error]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "drop authority.nomos_identity_claim, or start a single-user server with OKG_MCP_TRUST_CALLER_IDENTITY_CLAIMS=1"
    data_shape: [reason]

  - code: nomos.binding.block
    python_exception: null
    severity: user
    raised_by: [okg nomos binding block, okg nomos binding unblock, okg nomos binding add, okg nomos binding disable]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "blocks are managed only with `okg nomos binding block|unblock`"
    data_shape: []

  - code: mcp_oidc_auth_audit_exposed
    python_exception: null
    severity: user
    raised_by: [mcp.server.run_server]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "set nomos.runtime_enforcement: enforce, or bind --host 127.0.0.1 for a local test"
    data_shape: [deployment_name, host, runtime_enforcement]

  - code: mcp_oidc_auth_undeclared
    python_exception: null
    severity: user
    raised_by: [mcp.server.run_server]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "declare nomos.oidc_auth in the deployment manifest"
    data_shape: [deployment_name]

  - code: mcp_oidc_auth_stdio_incompatible
    python_exception: null
    severity: user
    raised_by: [mcp.server.run_server]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "serve with --transport streamable-http"
    data_shape: [transport]

  - code: mcp_oidc_auth_exclusive
    python_exception: null
    severity: user
    raised_by: [mcp.server.run_server]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "drop the other authentication flag"
    data_shape: [conflicting_flag]

  - code: mcp_oidc_login_blocks_disagree
    python_exception: null
    severity: user
    raised_by: [mcp.server.run_server]
    referenced_in: [docs/runbooks/security/nomos-iam.md]
    fix_hint_template: "use one issuer, one client and one roles_claim in chat.oidc_login and nomos.oidc_auth"
    data_shape: [reason, deployment, skew]

# ----- next_actions enum for DeploymentStatus.next_actions -----
#
# okg status --json returns a `next_actions` list. Values are
# drawn from this closed enum; an agent switching on them does
# not need to parse prose.

  # ---- live relations (PACT live-relations-on-expand) -------
  # Every code below EXCEPT live_arguments_invalid, live_relation_undeclared,
  # live_sample_write_failed and live_relations_unbound_deployment is a
  # DEPLOYMENT-LOAD refusal: the deployment does not start. That is the whole
  # design -- a malformed live declaration must fail when the operator starts
  # the server, not on an agent's first call, where nobody is watching.

  - code: live_relation_invalid
    python_exception: LiveRelationInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: null
    data_shape: []

  - code: live_relation_arg_schema_invalid
    python_exception: LiveRelationArgSchemaInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: null
    data_shape: [subtype, relation]

  - code: live_relation_principal_mode_invalid
    python_exception: LiveRelationPrincipalModeInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: null
    data_shape: [subtype, relation, principal_mode]

  - code: live_relation_caller_mode_unsupported
    python_exception: LiveRelationCallerModeUnsupported
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: "declare `principal_mode: service` until caller identity is threaded through"
    data_shape: [subtype, relation, issue]

  - code: live_relation_sample_policy_invalid
    python_exception: LiveRelationSamplePolicyInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: null
    data_shape: [subtype, relation]

  - code: live_relation_action_missing
    python_exception: LiveRelationActionMissing
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: "declare `action: <domain>.<system>.<verb>` and allow it for the service principal in the deployment's policy bundle"
    data_shape: [subtype, relation]

  - code: live_relation_unbound
    python_exception: LiveRelationUnbound
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: "add an `agent_surface.live_bindings` entry for each, or remove the declaration from the subtype"
    data_shape: [unbound, bound]

  - code: live_relation_adapter_kind_unknown
    python_exception: LiveRelationAdapterKindUnknown
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: null
    data_shape: [relation, kind, known]

  - code: live_binding_undeclared_relation
    python_exception: LiveBindingUndeclaredRelation
    severity: user
    raised_by: [okg.substrate.external_backed.live_relations]
    fix_hint_template: "fix the spelling, enrol the module that declares the relation, or remove the binding"
    data_shape: [undeclared, declared]

  - code: live_relation_undeclared
    python_exception: LiveRelationUndeclared
    severity: user
    raised_by: [okg.substrate.external_backed.live_dispatch]
    fix_hint_template: "call `inspect(target={{'kind':'subtype','name':'{0}'}})` to see what this subtype offers"
    data_shape: [subtype, relation, declared]

  # ---- live types (PACT live-graph-rucio-sites) -------
  # live_type_invalid and live_relation_declared_twice refuse the catalog or
  # the server start. live_node_id_invalid and live_arg_missing are READ-time
  # refusals made before any upstream call.
  - code: live_type_invalid
    python_exception: LiveTypeInvalid
    severity: user
    raised_by:
      - okg.substrate.external_backed.live_types
      - okg.substrate.external_backed.live_dispatch.build_live_type_registry
    fix_hint_template: null
    data_shape: []

  - code: live_node_id_invalid
    python_exception: LiveNodeIdInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.live_types]
    fix_hint_template: null
    data_shape: []

  - code: live_arg_missing
    python_exception: LiveArgMissing
    severity: user
    raised_by: [okg.substrate.external_backed.live_types]
    fix_hint_template: null
    data_shape: [relation, arg]

  # PACT read-live-handles (4.1.5): reading a live handle would decode more
  # rows than one call (`scope: call`, 16 MiB) or the calls in flight
  # (`scope: server`, 32 MiB per process) hold, counted as compact JSON.
  # Refused at once, after the caller checks and before any row; no
  # upstream call. `bytes` is the handle's size and `limit` the bound.
  # PACT read-multi-handle-input: a chain handle's answers cannot be read as
  # one set. `reason` is typed_set, groups_handle, derived_handle,
  # relation_differs, anchor_differs, args_differ, value_twice, same_call,
  # too_many_values, too_large or no_source_kept; `index` is the 1-based
  # source (0 for the whole chain); `handles` the ids it is about (the
  # source, with the earlier one it repeats, or the chain). A refusal of one
  # source keeps that source's own code and adds `index` and `chain` (the
  # chain id) to its data.
  # No upstream call.
  - code: live_handles_not_combinable
    python_exception: LiveHandlesNotCombinable
    severity: user
    raised_by: [okg.substrate.mcp.live_handle_lists]
    fix_hint_template: "read the chain again, or call the missing values again"
    data_shape: [reason, index, handles]

  - code: live_decode_capacity
    python_exception: LiveDecodeCapacity
    severity: user
    raised_by: [okg.substrate.mcp.handles]
    fix_hint_template: "narrow the set, or retry"
    data_shape: [scope, bytes, limit]

  # A read of a live type (filter, map, aggregate, inspect, expand) refused
  # by the live-graph resolver; `data.reason` names which (e.g. mixed_set,
  # planned_overrun, heavy_reads_busy, store_full). Most come before any
  # upstream call; store_full, kept_set_too_large, listing_failed and
  # system_unavailable come after the calls they count. field_not_fetched:
  # a read of a kept set names a field growth fetches and no kept
  # row holds, so growth did not run; refused with zero calls, never served
  # as null.
  - code: live_read_refused
    python_exception: LiveReadRefused
    severity: user
    raised_by:
      - okg.substrate.mcp.live_resolver
      - okg.substrate.mcp.live_nodes
    fix_hint_template: null
    data_shape: [reason]

  - code: live_relation_declared_twice
    python_exception: LiveRelationDeclaredTwice
    severity: user
    raised_by: [okg.substrate.external_backed.live_dispatch.all_declared_live_relations]
    fix_hint_template: "declare the relation on one subtype only, or give the second one its own name"
    data_shape: [relation, subtypes]

  - code: live_arguments_invalid
    python_exception: LiveArgumentsInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.live_dispatch]
    fix_hint_template: "supply only the declared arguments; `inspect` publishes the schema for this relation"
    data_shape: [relation, declared_arguments, supplied]

  # A DENY, not a raise: the call comes back in its `external_live` envelope
  # with `state: denied` and a sample row of its own, so there is no exception
  # class. Recorded when the subject does not resolve -- the dispatcher used to
  # read an empty principal as the privileged service subject, which is
  # the wrong direction for a gate that otherwise fails closed. The gate is not
  # even asked: a call with no identity is not a policy question.
  # An external-backed `sql` probe whose query is not exactly one plain,
  # read-only SELECT. The query comes from a node's handle
  # and runs on the MCP read pool; `SET TRANSACTION READ ONLY` alone does not
  # stop `COMMIT; INSERT ...`. Checked with pglast before anything runs; the
  # field comes back `state: unavailable` with this code, the adapter never
  # runs and nothing is cached. `reason` names the rule broken.
  - code: external_probe_query_refused
    python_exception: ProbeQueryRefused
    severity: user
    raised_by:
      - okg.substrate.mcp.sql_safety.validate_probe_query
      - MCP inspect(node, hydrate) sql probe fields
    referenced_in: []
    fix_hint_template: "write the probe query as one plain SELECT: no second statement, no data-modifying WITH, no SELECT INTO, no FOR UPDATE, no deny-listed function"
    data_shape: [reason]

  - code: probe_principal_unresolved
    python_exception: null   # a denied probe field, not a raised error
    severity: recoverable
    raised_by:
      - okg.substrate.external_backed.resolver
    referenced_in:
      - docs/reference/mcp.md
    fix_hint_template: "set OKG_NOMOS_SUBJECT (or fix the MCP subject resolution) so the hydrating caller has a Nomos subject; the probe is never decided as the runtime service"
    data_shape: [reason, principal]

  - code: live_principal_unresolved
    python_exception: null   # a denied call, not a raised error
    severity: recoverable
    raised_by:
      - okg.substrate.external_backed.live_dispatch
    referenced_in:
      - docs/reference/mcp.md
    fix_hint_template: "declare `agent_surface.live_bindings.<relation>.service_principal`, or fix the identity resolution that returned nothing"
    data_shape: [reason, relation, principal, action]

  # Not a policy denial: no identity resolved, so Nomos is never asked. The
  # MCP read boundary, the source tools' visibility gate and the run_sql
  # audit record raise it; `record` returns it as its refusal code with
  # `evaluated: false` authority evidence. None of them writes a decision or
  # admission row. All resolve the subject through
  # okg.substrate.nomos.mcp_subject in one order: OKG_NOMOS_SUBJECT /
  # OKG_MCP_NOMOS_SUBJECT / OKG_PRINCIPAL, then the rollout baseline default
  # subject:mcp_client, then the process login name. A failure to read the
  # active policy during that lookup is authority_evaluation_failed (or
  # authority_unavailable), never a quiet switch to the login name.
  - code: mcp_principal_unresolved
    python_exception: null   # attached per instance; record refuses, not raises
    severity: recoverable
    raised_by:
      - MCP graph-read runtime authority boundary (single-operator)
      - MCP record (write actions)
      - MCP source tools (list_sources, source_status, coverage source visibility)
      - MCP run_sql graph-backed audit record
    referenced_in:
      - docs/runbooks/security/nomos.md
    fix_hint_template: "set OKG_NOMOS_SUBJECT to a subject the deployment's active policy grants"
    data_shape: [surface_or_action, message]

  # NOT user severity. The call ran (or was denied) and its record could not
  # be written, which is an operational failure of this deployment, not
  # something the caller can fix by changing the call.
  - code: live_sample_write_failed
    python_exception: LiveSampleWriteFailed
    severity: recoverable
    raised_by: [okg.substrate.external_backed.live_dispatch]
    fix_hint_template: "check the call-sample hypertable for the relation's retention class and the deployment's write connection"
    data_shape: [relation, node_id, adapter_ran, event]

  # A binding that can never dispatch. LOAD-time, like the rest: a
  # deployment whose adapter kind has no runner must not start believing it
  # serves that relation.
  - code: live_adapter_unavailable
    python_exception: LiveAdapterUnavailable
    severity: user
    raised_by: [okg.substrate.external_backed.live_dispatch]
    fix_hint_template: "register a runner for this kind, or remove the binding"
    data_shape: [relation, kind, registered]

  # The four LOAD-time refusals of a `kind: http` or `kind: mcp` binding. All
  # `user`: an operator wrote a binding that cannot produce a legal request,
  # and the deployment refuses to start rather than discovering it on an
  # agent's first call.
  - code: live_adapter_config_invalid
    python_exception: LiveAdapterConfigInvalid
    severity: user
    raised_by: [okg.substrate.external_backed.http_adapter, okg.substrate.external_backed.mcp_adapter]
    fix_hint_template: "correct the named field in the deployment manifest"
    data_shape: [relation, field, reason]

  # Carries the REFERENCE name and never the value. There is no value here,
  # which is the problem -- but the rule holds on every path, so there is no
  # path where it might not.
  - code: live_adapter_secret_missing
    python_exception: LiveAdapterSecretMissing
    severity: user
    raised_by: [okg.substrate.external_backed.http_adapter, okg.substrate.external_backed.mcp_adapter]
    fix_hint_template: "set the named environment variable, or drop the secret"
    data_shape: [relation, secret_ref]

  # The mechanism keeps argument bounds optional, which is right for a
  # mechanism. This adapter declines to slot an argument it cannot bound.
  - code: live_adapter_arg_unconstrained
    python_exception: LiveAdapterArgUnconstrained
    severity: user
    raised_by: [okg.substrate.external_backed.http_adapter, okg.substrate.external_backed.mcp_adapter]
    fix_hint_template: "add an enum, or a pattern and maxLength, to the argument"
    data_shape: [relation, argument, type]

  # The host carried here is the REDACTED url: a base_url with userinfo is
  # refused, and the refusal must not be the thing that prints the password.
  - code: live_adapter_host_refused
    python_exception: LiveAdapterHostRefused
    severity: user
    raised_by: [okg.substrate.external_backed.http_adapter, okg.substrate.external_backed.mcp_adapter]
    fix_hint_template: "allowlist the exact ip:port, as an IP literal"
    data_shape: [relation, host, reason]

  # A `kind: mcp` binding declares `upstream_credential: personal` on a
  # deployment whose `contract.lifecycle` is not `prototype` or `demo` (or
  # is undeclared). okg cannot inspect the credential an MCP server holds;
  # it enforces the declaration, at server build.
  - code: live_adapter_personal_credential_refused
    python_exception: LiveAdapterPersonalCredentialRefused
    severity: user
    raised_by: [okg.substrate.external_backed.mcp_adapter]
    fix_hint_template: "use a service credential, or declare the deployment prototype or demo"
    data_shape: [relation, lifecycle, admitted]

  # The process-wide cap on live calls in flight. Recoverable, not user:
  # the caller did nothing wrong and the same call will work once the
  # external system stops hanging.
  # What an adapter raises to say what went wrong SAFELY. The dispatcher
  # never passes an exception's own message through -- a network exception's
  # str() routinely embeds the URL it was dialling, userinfo included -- so
  # an adapter that wants to say more supplies a bounded excerpt, which is
  # redacted and fenced before it reaches the envelope.
  - code: live_adapter_error
    python_exception: LiveAdapterError
    severity: recoverable
    raised_by: [okg.substrate.external_backed.live_dispatch]
    fix_hint_template: null
    data_shape: []

  - code: live_concurrency_exhausted
    python_exception: LiveConcurrencyExhausted
    severity: recoverable
    raised_by: [okg.substrate.external_backed.live_dispatch]
    fix_hint_template: "retry once the external system recovers"
    data_shape: [limit]

  - code: live_relations_unbound_deployment
    python_exception: LiveRelationsUnboundDeployment
    severity: user
    raised_by: [okg.substrate.mcp.server]
    fix_hint_template: "declare the relation on the subtype and bind it in `agent_surface.live_bindings`, or drop the `live` argument"
    data_shape: [relation, bound, issue]

  # Refused before any outside call, so the adapter runs zero
  # times: access rules (Nomos read enforcement) are in audit or enforce mode,
  # or their state cannot be told. Not served from a kept answer either.
  - code: live_refused_under_access_rules
    python_exception: LiveRefusedUnderAccessRules
    severity: user
    raised_by:
      - MCP `expand(live=...)` (direct or as a `run` step), `expand(next=<live token>)`, and every read of a live type (filter, aggregate, map, inspect, and growing a kept live set) on a deployment whose access rules (Nomos) are audit or enforce, or whose state cannot be told
    referenced_in:
      - src/okg/substrate/mcp/live_access_rules.py
      - src/okg/substrate/mcp/live_resolver.py
    fix_hint_template: "read the stored graph (search, expand without live, filter, inspect); live reads under access rules are not served"
    data_shape: [reason, access_rules, tool_called]

  - code: dsn_parse_error
    python_exception: DsnParseError
    severity: user
    raised_by: [okg.substrate.db.dsn]
    referenced_in:
      - pact/changes/dsn-module-parse-expand-redact
    fix_hint_template: "write the DSN as postgresql://user:password@host:port/dbname"
    data_shape: []

  - code: dsn_keyword_form
    python_exception: DsnFormError
    severity: user
    raised_by: [okg.substrate.db.dsn]
    referenced_in:
      - pact/changes/dsn-module-parse-expand-redact
    fix_hint_template: "write the DSN as postgresql://user:password@host:port/dbname"
    data_shape: [source]

  - code: dsn_render_refused
    python_exception: DsnRenderError
    severity: user
    raised_by: [okg.substrate.db.dsn]
    referenced_in:
      - pact/changes/dsn-module-parse-expand-redact
    fix_hint_template: null
    data_shape: []

  - code: dsn_placeholder_unset
    python_exception: DsnPlaceholderUnset
    severity: user
    raised_by: [okg.substrate.db.dsn]
    referenced_in:
      - pact/changes/dsn-module-parse-expand-redact
    fix_hint_template: "export {0}=postgresql://user:password@host:port/dbname"
    data_shape: [source, unset, empty, unsupported]

  - code: dsn_placeholder_empty
    python_exception: DsnPlaceholderEmpty
    severity: user
    raised_by: [okg.substrate.db.dsn]
    referenced_in:
      - pact/changes/dsn-module-parse-expand-redact
    fix_hint_template: "give {0} a non-empty value"
    data_shape: [source, unset, empty, unsupported]

  - code: dsn_placeholder_unsupported
    python_exception: DsnPlaceholderUnsupported
    severity: user
    raised_by: [okg.substrate.db.dsn]
    referenced_in:
      - pact/changes/dsn-module-parse-expand-redact
    fix_hint_template: "write ${NAME} and export NAME, or write the DSN literally"
    data_shape: [source, unset, empty, unsupported]

  # Both are raised while
  # READING a cluster's metadata, and both refuse rather than degrade: an
  # incomplete read must never become an empty completed scope, because a
  # completed scope retracts every node the source owns.
  # Both carry a per-raise `fix_hint` naming the endpoint or the field that
  # failed, so there is no template to substitute; and both are raised from
  # many sites whose `data` keys differ (`keys`, `type`, `rows`, `row`,
  # `scheme`, `entry`, ...), so no key is required across all of them.
  # `data_shape` is the REQUIRED set and is honestly empty rather than
  # naming one site's payload as though every site carried it.
  - code: opensearch_metadata_unavailable
    python_exception: OpenSearchMetadataError
    severity: recoverable
    raised_by:
      - okg.substrate.library.sources._opensearch_client.OpenSearchClient
    fix_hint_template: null
    data_shape: []

  - code: opensearch_declared_index_unknown
    python_exception: DeclaredServiceError
    severity: user
    raised_by:
      - okg.substrate.library.sources.opensearch_catalog.OpenSearchCatalogSource
    fix_hint_template: null
    data_shape: []

  - code: compensation_row_set_changed
    python_exception: CompensationRowSetChanged
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.compensation.retract_chronos_run
    referenced_in: []
    fix_hint_template: "another writer changed the failed run's rows after the run started, so the undo rolled back and wrote nothing; the run's receipts stay 'compensating' and every publish of the deployment is refused. Retry with `okg runtime finish-undo --deployment <deployment> --apply` once that writer has stopped; if it is refused again, keep the current rows with `okg runtime finish-undo --deployment <deployment> --accept-current --reason \"<why>\" --apply` and rerun the source with `okg ingest --deployment <deployment> --include <source>`"
    data_shape: [table, source, run_id, missing_count, missing_sample]

  # A failed source run's undo (back to its run-base
  # checkpoint) has not finished. Raised by the publisher's guard, keyed on
  # receipts stuck in 'compensating' or a run base marked undo-pending.
  - code: source_run_undo_unfinished
    python_exception: SourceRunUndoUnfinished
    severity: recoverable
    raised_by:
      - okg.substrate.publisher.Publisher.cycle
      - okg ingest
    referenced_in: []
    fix_hint_template: "a failed source run's undo did not finish, so every publish of this deployment is refused until it does. Retry the undo with `okg runtime finish-undo --deployment {0} --apply`. If it is refused again because another writer changed the same rows, keep the rows as they are now with `okg runtime finish-undo --deployment {0} --accept-current --reason \"<why>\" --apply`, then rerun the source with `okg ingest --deployment {0} --include {1}`"
    data_shape: [deployment, pending_count, pending]

  # A failed run applied chunks on a branch where its
  # deployment has published, but its run-base checkpoint is gone, so it
  # cannot be undone exactly. Compensation refuses; the receipts stay
  # 'compensating' and the publish guard fires.
  - code: source_run_base_missing
    python_exception: SourceRunBaseMissing
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.compensation.retract_chronos_run
    referenced_in: []
    fix_hint_template: "the failed run cannot be undone exactly, so every publish of this deployment is refused. Keep the rows as they are now with `okg runtime finish-undo --deployment {0} --accept-current --reason \"<why>\" --apply`, then rerun the source with `okg ingest --deployment {0} --include {1}`"
    data_shape: [source, run_id, branch, admission_id, deployment]

  # The undo holds the branch write lock for its whole
  # length, and its cost grows faster than linearly; above a bound of keys
  # written since the run base it refuses before writing.
  - code: source_run_undo_too_large
    python_exception: SourceRunUndoTooLarge
    severity: recoverable
    raised_by:
      - okg.substrate.ingest.compensation.retract_chronos_run
    referenced_in: []
    fix_hint_template: "the undo would hold the branch write lock too long, so it wrote nothing and every publish of this deployment is refused. Keep the rows as they are now with `okg runtime finish-undo --deployment {0} --accept-current --reason \"<why>\" --apply` and rerun the source with `okg ingest --deployment {0} --include {1}`; or raise OKG_RUN_BASE_UNDO_MAX_KEYS and retry with `okg runtime finish-undo --deployment {0} --apply`, accepting that every writer waits for it"
    data_shape: [source, run_id, branch, keys_since_run_base, max_keys]

  # Another source run of the deployment is still
  # writing; its committed chunks are not a complete run, so every publish is
  # refused (an ingest's own run-end publish waits for it first, bounded).
  - code: source_run_in_progress
    python_exception: SourceRunInProgress
    severity: recoverable
    raised_by:
      - okg.substrate.publisher.Publisher.cycle
      - okg ingest
    referenced_in: []
    fix_hint_template: "run {0} of source {1} is still writing (its owner session, pid {2}, is alive), and a publish now would show readers its unfinished records. Wait for it to finish, then publish again. If that process is gone but its database session is not (a hung connection), end the session with `SELECT pg_terminate_backend({2})`: the run then reads as ended, and `okg runtime finish-undo --deployment {3} --run-id {0} --apply` undoes its records"
    data_shape: [deployment, in_progress_count, in_progress]

  # `finish-undo --accept-current` keeps a failed
  # run's partial rows, so publishing stays refused until the source reruns
  # successfully or is retired.
  - code: source_rerun_required
    python_exception: SourceRerunRequired
    severity: recoverable
    raised_by:
      - okg.substrate.publisher.Publisher.cycle
      - okg ingest
    referenced_in: []
    fix_hint_template: "every publish of this deployment is refused until the source reruns successfully: run `okg ingest --deployment {0} --include {1}`. If it keeps failing, fix the source and run that again, or remove the source: `okg remediate retire-source --source {1} --deployment-name {0}` (a dry run that prints plan_digest and registry_source_id; it works whether or not the source is still in source_registry.yaml), then the same command with `--expected-plan-digest <plan_digest> --confirm-source <registry_source_id> --apply`, which removes all of its records and lifts this block; then delete its source_registry.yaml entry if it is still there, run `okg catalog ownership claim --deployment {0}` and publish with `okg run --once --deployment {0} --apply`"
    data_shape: [deployment, rerun_required]

  # An operator UI read passed a request parameter whose name is reserved for
  # a policy fact. Request parameters never reach the Nomos policy;
  # the refusal is a programming error in the route, not operator input.
  - code: operator_read_request_key_reserved
    python_exception: OperatorReadRequestKeyReserved
    severity: fatal
    raised_by:
      - okg.substrate.operator_read.authorize_local_operator_read
    referenced_in: []
    fix_hint_template: "rename the request parameter; a policy fact the boundary needs is added to LOCAL_OPERATOR_RESOURCE_ATTRIBUTES by name"
    data_shape: [read, reserved_keys]

  # An operator UI read passed a request the audit record cannot hold as JSON.
  # Like the reserved-key refusal it is a route bug; the console
  # answers both as a 500 carrying the code.
  - code: operator_read_request_unencodable
    python_exception: OperatorReadRequestUnencodable
    severity: fatal
    raised_by:
      - okg.substrate.operator_read.authorize_local_operator_read
    referenced_in: []
    fix_hint_template: "pass request parameters as JSON values (str, int, float, bool, None, list, dict with string keys)"
    data_shape: [read, unencodable, non_string_keys]

  # ---------- operator UI launcher ----------

  # `okg ui` found no built frontend bundle (PACT okg-ui-command). The wheel
  # does not ship the operator UI's TypeScript, so the bundle must be built in
  # a source checkout first.
  - code: operator_ui_bundle_missing
    python_exception: OperatorUiBundleMissing
    severity: user
    raised_by:
      - okg ui
    referenced_in:
      - docs/operate/operator-ui.md
    fix_hint_template: "run `npm install` once and `npm run operator-ui:build` at the root of a source checkout, or pass --dist <a built bundle directory>"
    data_shape: [bundle_dir, source]

  # The `okg ui` front door answers only GET, HEAD and OPTIONS; every other
  # method is an HTTP 405 carrying this code (PACT okg-ui-command).
  - code: operator_ui_read_only
    python_exception: OperatorUiReadOnly
    severity: user
    raised_by:
      - okg ui
    referenced_in:
      - docs/operate/operator-ui.md
    fix_hint_template: "the operator UI is read-only; change deployment state with the CLI"
    data_shape: [method, path]

  # `okg ui` serves loopback only (localhost, 127.0.0.0/8, ::1), with or
  # without an operator token, and refuses a port outside 1-65535 or a
  # non-integer OKG_VIZ_PORT (PACT okg-ui-command).
  - code: operator_ui_bind_refused
    python_exception: OperatorUiBindRefused
    severity: user
    raised_by:
      - okg ui
    referenced_in:
      - docs/operate/operator-ui.md
    fix_hint_template: "okg ui serves loopback only; bind --host 127.0.0.1 and reach it remotely through an SSH tunnel; pass --port <1-65535>"
    data_shape: [host, port, reason]

  # PACT recovery-contract-removed-sources. A blocked checkpoint's repair
  # contract names a source the registry no longer holds (removed or
  # renamed) or holds with a changed binding (rebound), so no retry can
  # reproduce it. Replaces incomplete_recovery_contract_mismatch for that
  # case; an all-present contract keeps the mismatch refusal.
  - code: incomplete_recovery_contract_unsatisfiable
    python_exception: null
    severity: user
    raised_by:
      - okg ingest
      - okg runtime worker
    referenced_in: []
    fix_hint_template: "restart `okg runtime worker` or run `okg migrate --deployment {0} --apply` when every held-back source is gone (they retire the repair requirement after their safety checks); otherwise run `okg runtime supersede-checkpoint --deployment {0}` (dry run first) and supersede with a recorded reason"
    data_shape: [deployment, latest_checkpoint_id, source_classes, unsatisfiable_sources, automatic_retirement_applies, escape_hatch_command]

  # Reported by okg migrate --deployment and okg runtime worker start (never
  # raised): the checkpoint was recorded under another deployment name, so
  # this deployment's unfinished-undo guard cannot see its undo and nothing
  # is retired.
  - code: incomplete_recovery_deployment_renamed
    python_exception: null
    severity: user
    raised_by:
      - okg migrate
      - okg runtime worker
    referenced_in: []
    fix_hint_template: "run the command against the deployment name the checkpoint was recorded for, or supersede by hand after checking that deployment's unfinished undos"
    data_shape: [deployment, checkpoint_id, recorded_deployment]

  # Reported by okg migrate --deployment and okg runtime worker start (never
  # raised): every held-back source is gone, but the publisher's own guard
  # still refuses to publish, so retiring the repair requirement would only
  # move the wedge. The report names the step that clears it.
  - code: incomplete_recovery_publish_blocked
    python_exception: null
    severity: recoverable
    raised_by:
      - okg migrate
      - okg runtime worker
    referenced_in: []
    fix_hint_template: "clear the publish block first (`okg runtime finish-undo --deployment {0} --apply` for an unfinished undo, or `okg remediate retire-source --source <name> --deployment-name {0}` for a kept rerun of a removed source, or `okg ingest --deployment {0} --include <new name>` for a kept rerun of a renamed source, never retire-source, which would delete the renamed source's records), then run `okg migrate --deployment {0} --apply`"
    data_shape: [deployment, checkpoint_id, publish_block, sources, clears_with]

next_action_enum:
  - configure_postgres_dsn
  - install_missing_extensions
  - migrate_schema
  - review_sources
  - validate_sources
  - load_catalog
  - review_reconcile_plan
  - apply_catalog
  - enable_workers
  - enable_scheduling
  - verify_invariants
  - start_mcp_server
  - promote_to_staging
  - promote_to_production