{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:voicemd:schema:0.1",
  "title": "VOICE.md Agent Communication Contract",
  "description": "Schema for a resolved VOICE.md contract. Source overlays may use null as a merge-time delete operator. Source-level deletions are removed before validation; dormant selector overlays may retain null until selection, after which the exact selected contract is validated again. Markdown-only L0 contracts intentionally have no frontmatter to validate.",
  "type": "object",
  "required": ["voice_spec", "kind", "name"],
  "properties": {
    "voice_spec": {
      "type": "string",
      "pattern": "^0\\.1(?:\\.[0-9]+)?$"
    },
    "kind": {
      "const": "VoiceContract"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "version": {
      "type": "string",
      "minLength": 1
    },
    "extends": {
      "oneOf": [
        {"type": "string"},
        {"type": "array", "items": {"type": "string"}, "uniqueItems": true}
      ]
    },
    "default_language": {
      "type": "string",
      "description": "Deprecated compatibility alias for language.default. New contracts should use language.default."
    },
    "activation": {
      "type": "object",
      "properties": {
        "mode": {"enum": ["contextual", "always", "explicit", "off"]},
        "include": {"$ref": "#/$defs/stringList"},
        "exclude": {"$ref": "#/$defs/stringList"},
        "on_markers": {"$ref": "#/$defs/stringList"},
        "off_markers": {"$ref": "#/$defs/stringList"}
      },
      "additionalProperties": true
    },
    "authority": {
      "type": "object",
      "properties": {
        "may_control": {"$ref": "#/$defs/stringList"},
        "must_not_control": {"$ref": "#/$defs/stringList"},
        "precedence": {"type": "string"}
      },
      "additionalProperties": true
    },
    "identity": {
      "type": "object",
      "properties": {
        "sounds_like": {"$ref": "#/$defs/stringList"},
        "not_like": {"$ref": "#/$defs/stringList"},
        "traits": {"$ref": "#/$defs/stringList"}
      },
      "additionalProperties": true
    },
    "response": {"$ref": "#/$defs/response"},
    "language": {
      "type": "object",
      "properties": {
        "default": {"type": "string"},
        "allowed": {"$ref": "#/$defs/stringList"},
        "match_user": {"type": "boolean"},
        "mixing": {"type": "string"},
        "translation": {"type": "string"}
      },
      "additionalProperties": true
    },
    "lexicon": {
      "type": "object",
      "properties": {
        "preferred": {"$ref": "#/$defs/stringList"},
        "forbidden": {"$ref": "#/$defs/stringList"},
        "replacements": {
          "type": "object",
          "additionalProperties": {"type": "string"}
        },
        "pronunciations": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["term", "pronunciation"],
            "properties": {
              "term": {"type": "string"},
              "pronunciation": {"type": "string"},
              "alphabet": {"type": "string"}
            },
            "additionalProperties": true
          }
        }
      },
      "additionalProperties": true
    },
    "epistemics": {"$ref": "#/$defs/epistemics"},
    "interaction": {"$ref": "#/$defs/interaction"},
    "formatting": {"$ref": "#/$defs/formatting"},
    "speech": {"$ref": "#/$defs/speech"},
    "runtime": {
      "type": "object",
      "properties": {
        "max_prompt_chars": {"type": "integer", "minimum": 256, "maximum": 9007199254740991},
        "compact_for_small_models": {"type": "boolean"},
        "cache_key": {"type": "string"}
      },
      "additionalProperties": true
    },
    "audiences": {"$ref": "#/$defs/namedVariants"},
    "surfaces": {"$ref": "#/$defs/namedVariants"},
    "tones": {"$ref": "#/$defs/namedVariants"},
    "profiles": {
      "type": "object",
      "propertyNames": {"$ref": "#/$defs/selectorName"},
      "additionalProperties": {
        "type": "object",
        "properties": {
          "audience": {"$ref": "#/$defs/selectorName"},
          "surface": {"$ref": "#/$defs/selectorName"},
          "tone": {"$ref": "#/$defs/selectorName"},
          "overrides": {"$ref": "#/$defs/contractOverlay"}
        },
        "additionalProperties": true
      }
    },
    "rules": {
      "type": "array",
      "items": {"$ref": "#/$defs/rule"}
    },
    "tests": {
      "type": "array",
      "items": {"$ref": "#/$defs/testCase"}
    },
    "examples": {
      "type": "array",
      "items": {"$ref": "#/$defs/example"}
    },
    "metadata": {"type": "object"}
  },
  "patternProperties": {
    "^x-[A-Za-z0-9_.-]+$": {}
  },
  "additionalProperties": true,
  "$defs": {
    "selectorName": {
      "type": "string",
      "minLength": 1,
      "pattern": "[^\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000]"
    },
    "stringList": {
      "type": "array",
      "items": {"type": "string"},
      "uniqueItems": true
    },
    "response": {
      "type": "object",
      "properties": {
        "conclusion_first": {"type": "boolean"},
        "examples": {"type": "string"},
        "max_sentences": {"type": "integer", "minimum": 0, "maximum": 9007199254740991},
        "max_words": {"type": "integer", "minimum": 0, "maximum": 9007199254740991},
        "opening": {"type": "string"},
        "repetition": {"type": "string"},
        "softening": {"type": "string"},
        "structure": {"type": "string"},
        "verbosity": {"type": "string"}
      },
      "patternProperties": {"^x-[A-Za-z0-9_.-]+$": {}},
      "additionalProperties": true
    },
    "epistemics": {
      "type": "object",
      "properties": {
        "assumptions": {"type": "string"},
        "certainty": {"type": "string"},
        "confidence_pressure": {"type": "string"},
        "correction": {"type": "string"},
        "escalation": {"type": "string"},
        "evidence": {"type": "string"},
        "inference": {"type": "string"},
        "precision": {"type": "string"},
        "sources": {"type": "string"},
        "uncertainty": {"type": "string"}
      },
      "patternProperties": {"^x-[A-Za-z0-9_.-]+$": {}},
      "additionalProperties": true
    },
    "interaction": {
      "type": "object",
      "properties": {
        "challenge": {"type": "string"},
        "clarification": {"type": "string"},
        "defensiveness": {"type": "string"},
        "disagreement": {"type": "string"},
        "emotional_calibration": {"type": "string"},
        "escalation": {"type": "string"},
        "repeated_question": {"type": "string"},
        "technical_depth": {"type": "string"},
        "user_expertise": {"type": "string"}
      },
      "patternProperties": {"^x-[A-Za-z0-9_.-]+$": {}},
      "additionalProperties": true
    },
    "formatting": {
      "type": "object",
      "properties": {
        "avoid": {"$ref": "#/$defs/stringList"},
        "bullets": {"$ref": "#/$defs/policy"},
        "emoji": {"$ref": "#/$defs/policy"},
        "headings": {"$ref": "#/$defs/policy"},
        "lists": {"$ref": "#/$defs/policy"},
        "markdown": {"$ref": "#/$defs/policy"},
        "tables": {"$ref": "#/$defs/policy"}
      },
      "patternProperties": {"^x-[A-Za-z0-9_.-]+$": {}},
      "additionalProperties": true
    },
    "speech": {
      "type": "object",
      "properties": {
        "ascii_only": {"type": "boolean"},
        "avoid": {"$ref": "#/$defs/stringList"},
        "interruptions": {"type": "string"},
        "pronunciation": {"type": "string"},
        "sentence_length": {"type": "string"},
        "tts_friendly": {"type": "boolean"},
        "turn_length": {"type": "string"}
      },
      "patternProperties": {"^x-[A-Za-z0-9_.-]+$": {}},
      "additionalProperties": true
    },
    "policy": {
      "oneOf": [
        {"type": "string"},
        {"type": "boolean"}
      ]
    },
    "contractOverlay": {
      "type": "object",
      "description": "A source-resident partial contract. Known values are fully type-checked after this overlay is selected and null delete operators have been removed.",
      "properties": {
        "activation": {"type": ["object", "null"]},
        "authority": {"type": ["object", "null"]},
        "default_language": {"type": ["string", "null"]},
        "identity": {"type": ["object", "null"]},
        "response": {"type": ["object", "null"]},
        "language": {"type": ["object", "null"]},
        "lexicon": {"type": ["object", "null"]},
        "epistemics": {"type": ["object", "null"]},
        "interaction": {"type": ["object", "null"]},
        "formatting": {"type": ["object", "null"]},
        "speech": {"type": ["object", "null"]},
        "runtime": {"type": ["object", "null"]},
        "rules": {"type": ["array", "null"]},
        "tests": {"type": ["array", "null"]},
        "examples": {"type": ["array", "null"]},
        "metadata": {"type": ["object", "null"]}
      },
      "patternProperties": {"^x-[A-Za-z0-9_.-]+$": {}},
      "additionalProperties": true
    },
    "namedVariants": {
      "type": "object",
      "propertyNames": {"$ref": "#/$defs/selectorName"},
      "additionalProperties": {"$ref": "#/$defs/contractOverlay"}
    },
    "rule": {
      "type": "object",
      "required": ["id"],
      "properties": {
        "id": {"type": "string", "minLength": 1},
        "instruction": {"type": "string", "minLength": 1},
        "description": {"type": "string", "minLength": 1},
        "pattern": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "pattern": "^[\\u0000-\\u007F]+$"
        },
        "flags": {
          "type": "array",
          "items": {"enum": ["i", "m", "s"]},
          "uniqueItems": true
        },
        "assert": {"enum": ["must_match", "must_not_match"]},
        "severity": {"enum": ["info", "warning", "error"]},
        "message": {"type": "string"},
        "disabled": {"type": "boolean"}
      },
      "anyOf": [
        {"required": ["instruction"]},
        {"required": ["description"]},
        {"required": ["pattern"]}
      ],
      "dependentRequired": {
        "pattern": ["assert"],
        "assert": ["pattern"]
      },
      "additionalProperties": true
    },
    "testCase": {
      "type": "object",
      "required": ["id", "assertions"],
      "properties": {
        "id": {"type": "string", "minLength": 1},
        "prompt": {"type": "string"},
        "response": {"type": "string"},
        "profile": {"$ref": "#/$defs/selectorName"},
        "audience": {"$ref": "#/$defs/selectorName"},
        "surface": {"$ref": "#/$defs/selectorName"},
        "tone": {"$ref": "#/$defs/selectorName"},
        "disabled": {"type": "boolean"},
        "assertions": {
          "type": "object",
          "minProperties": 1,
          "properties": {
            "must_contain": {"$ref": "#/$defs/stringList"},
            "must_not_contain": {"$ref": "#/$defs/stringList"},
            "max_words": {"type": "integer", "minimum": 0, "maximum": 9007199254740991},
            "ascii_only": {"type": "boolean"},
            "lint_clean": {"type": "boolean"}
          },
          "additionalProperties": true
        }
      },
      "anyOf": [
        {"required": ["prompt"]},
        {"required": ["response"]}
      ],
      "additionalProperties": true
    },
    "example": {
      "type": "object",
      "required": ["id"],
      "properties": {
        "id": {"type": "string", "minLength": 1},
        "description": {"type": "string"},
        "input": {},
        "output": {},
        "disabled": {"type": "boolean"}
      },
      "anyOf": [
        {"required": ["description"]},
        {"required": ["input"]},
        {"required": ["output"]}
      ],
      "additionalProperties": true
    }
  }
}