{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://standards.rootblocks.com/schemas/semantic-engines/semantic-engines.v1.schema.json",
  "title": "RootBlocks Generic Semantic Engines v1",
  "description": "Generic Rule, Mapping, and Query Engine contract shared by RootBlocks Console, BuilderX, validators, and organization extensions.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schemaVersion",
    "engineSetId",
    "standard",
    "ruleEngine",
    "mappingEngine",
    "queryEngine",
    "evidence"
  ],
  "properties": {
    "schemaVersion": {
      "const": "rootblocks.semantic-engines/v1"
    },
    "engineSetId": {
      "$ref": "#/$defs/id"
    },
    "standard": {
      "$ref": "#/$defs/standardRef"
    },
    "ruleEngine": {
      "$ref": "#/$defs/ruleEngine"
    },
    "mappingEngine": {
      "$ref": "#/$defs/mappingEngine"
    },
    "queryEngine": {
      "$ref": "#/$defs/queryEngine"
    },
    "evidence": {
      "$ref": "#/$defs/evidencePolicy"
    }
  },
  "$defs": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9.-]{2,127}$"
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_./-]+$"
    },
    "semver": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[A-Za-z0-9.-]+)?(\\+[A-Za-z0-9.-]+)?$"
    },
    "standardRef": {
      "type": "object",
      "additionalProperties": false,
      "required": ["bundleId", "version", "hash"],
      "properties": {
        "bundleId": {
          "$ref": "#/$defs/id"
        },
        "version": {
          "$ref": "#/$defs/semver"
        },
        "hash": {
          "type": "string",
          "pattern": "^[a-f0-9]{64,128}$"
        }
      }
    },
    "ruleEngine": {
      "type": "object",
      "additionalProperties": false,
      "required": ["mode", "defaultMissingContextDecision", "ruleSets"],
      "properties": {
        "mode": {
          "enum": ["enforced", "advisory", "disabled"]
        },
        "defaultMissingContextDecision": {
          "enum": ["block", "warn"]
        },
        "ruleSets": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/ruleSet"
          }
        }
      }
    },
    "ruleSet": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "version", "source", "path", "scopes", "phases", "enforcement", "decisions"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "version": {
          "$ref": "#/$defs/semver"
        },
        "source": {
          "enum": ["rootblocks-global", "organization-registry", "local-project", "custom-repository"]
        },
        "path": {
          "$ref": "#/$defs/path"
        },
        "scopes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/ruleScope"
          },
          "uniqueItems": true
        },
        "phases": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/rulePhase"
          },
          "uniqueItems": true
        },
        "enforcement": {
          "enum": ["blocking", "warning", "approval-required"]
        },
        "decisions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/decision"
          },
          "uniqueItems": true
        },
        "evidenceRequired": {
          "type": "boolean"
        }
      }
    },
    "ruleScope": {
      "enum": [
        "construction",
        "project",
        "workflow",
        "component",
        "template",
        "architecture",
        "source",
        "test",
        "regression",
        "infrastructure",
        "cicd",
        "security",
        "evidence",
        "release",
        "organization-extension"
      ]
    },
    "rulePhase": {
      "enum": [
        "pre-generation",
        "post-generation",
        "pre-validation",
        "pre-compile",
        "pre-run",
        "pre-debug",
        "pre-test",
        "pre-plan",
        "pre-apply",
        "pre-deploy",
        "pre-release",
        "post-run",
        "post-release"
      ]
    },
    "decision": {
      "enum": ["allow", "warn", "block", "require-approval", "require-evidence", "require-remediation"]
    },
    "mappingEngine": {
      "type": "object",
      "additionalProperties": false,
      "required": ["mode", "sourceMapPolicy", "mappingSets"],
      "properties": {
        "mode": {
          "enum": ["enforced", "advisory", "disabled"]
        },
        "sourceMapPolicy": {
          "enum": ["required-for-critical", "always-required", "advisory"]
        },
        "mappingSets": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/mappingSet"
          }
        }
      }
    },
    "mappingSet": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "version", "source", "path", "mappings"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "version": {
          "$ref": "#/$defs/semver"
        },
        "source": {
          "enum": ["rootblocks-global", "organization-registry", "local-project", "custom-repository"]
        },
        "path": {
          "$ref": "#/$defs/path"
        },
        "mappings": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/mapping"
          }
        }
      }
    },
    "mapping": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "from", "to", "relation", "sourceMapRequired", "impactAnalysis"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "from": {
          "$ref": "#/$defs/domain"
        },
        "to": {
          "$ref": "#/$defs/domain"
        },
        "relation": {
          "enum": ["generates", "projects", "transforms", "binds", "validates", "materializes", "emits", "traces"]
        },
        "sourceMapRequired": {
          "type": "boolean"
        },
        "impactAnalysis": {
          "enum": ["required", "supported", "not-supported"]
        },
        "critical": {
          "type": "boolean"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "to": {
                "enum": ["generated-source", "iac", "cicd", "regression-suite", "evidence"]
              }
            },
            "required": ["to"]
          },
          "then": {
            "properties": {
              "sourceMapRequired": {
                "const": true
              }
            }
          }
        }
      ]
    },
    "domain": {
      "enum": [
        "spec",
        "construction",
        "project",
        "workflow",
        "flow-ir",
        "application-ir",
        "package-ir",
        "generated-source",
        "test-plan",
        "test-suite",
        "regression-suite",
        "infra-resource-graph",
        "iac",
        "cicd",
        "source-map",
        "evidence",
        "catalog",
        "component",
        "template",
        "architecture-profile",
        "runtime"
      ]
    },
    "queryEngine": {
      "type": "object",
      "additionalProperties": false,
      "required": ["mode", "secretResultPolicy", "freshnessPolicy", "sources", "indexes", "querySets"],
      "properties": {
        "mode": {
          "enum": ["enforced", "advisory", "disabled"]
        },
        "secretResultPolicy": {
          "enum": ["references-only"]
        },
        "freshnessPolicy": {
          "enum": ["block-critical-stale", "warn-stale", "offline-cache-allowed"]
        },
        "sources": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/querySource"
          }
        },
        "indexes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/queryIndex"
          }
        },
        "querySets": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/querySet"
          }
        }
      }
    },
    "querySource": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "visibility", "trustLevel", "cachePolicy"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "kind": {
          "enum": ["bundle", "catalog", "registry", "local-project", "evidence-ledger", "source-map-store", "builderx-runtime", "external"]
        },
        "visibility": {
          "enum": ["public", "organization", "private", "local"]
        },
        "trustLevel": {
          "enum": ["rootblocks-signed", "organization-signed", "local-trusted", "untrusted"]
        },
        "cachePolicy": {
          "enum": ["refresh-before-use", "cache-first", "offline-allowed", "no-cache"]
        }
      }
    },
    "queryIndex": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "domain", "sourceRefs", "fields"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "domain": {
          "$ref": "#/$defs/domain"
        },
        "sourceRefs": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/id"
          },
          "uniqueItems": true
        },
        "fields": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        }
      }
    },
    "querySet": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "version", "source", "path", "allowedDomains", "resultPolicy"],
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "version": {
          "$ref": "#/$defs/semver"
        },
        "source": {
          "enum": ["rootblocks-global", "organization-registry", "local-project", "custom-repository"]
        },
        "path": {
          "$ref": "#/$defs/path"
        },
        "allowedDomains": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/domain"
          },
          "uniqueItems": true
        },
        "resultPolicy": {
          "enum": ["metadata-only", "references-only", "full-non-secret"]
        }
      }
    },
    "evidencePolicy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["required", "events"],
      "properties": {
        "required": {
          "type": "boolean"
        },
        "events": {
          "type": "array",
          "minItems": 1,
          "items": {
            "enum": ["queried", "mapped", "ruled", "allowed", "warned", "blocked", "failed"]
          },
          "uniqueItems": true
        }
      }
    }
  }
}