{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://stellaops.org/schemas/function-map-v1.schema.json",
  "title": "StellaOps Function Map v1",
  "description": "Predicate schema for declaring expected call-paths for runtime→static linkage verification",
  "type": "object",
  "required": ["_type", "subject", "predicate"],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "https://stella.ops/predicates/function-map/v1",
        "stella.ops/functionMap@v1"
      ],
      "description": "Predicate type URI"
    },
    "subject": {
      "$ref": "#/definitions/subject",
      "description": "Subject artifact that this function map applies to"
    },
    "predicate": {
      "$ref": "#/definitions/predicatePayload",
      "description": "The predicate payload containing the function map definition"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "subject": {
      "type": "object",
      "required": ["purl", "digest"],
      "properties": {
        "purl": {
          "type": "string",
          "description": "Package URL of the subject artifact",
          "pattern": "^pkg:[a-z]+/.+"
        },
        "digest": {
          "type": "object",
          "description": "Digest(s) of the subject artifact",
          "additionalProperties": { "type": "string" },
          "minProperties": 1
        },
        "name": {
          "type": ["string", "null"],
          "description": "Optional artifact name"
        }
      },
      "additionalProperties": false
    },
    "predicatePayload": {
      "type": "object",
      "required": ["schemaVersion", "service", "expectedPaths", "coverage", "generatedAt"],
      "properties": {
        "schemaVersion": {
          "type": "string",
          "const": "1.0.0",
          "description": "Schema version of this predicate"
        },
        "service": {
          "type": "string",
          "description": "Service name that this function map applies to",
          "minLength": 1
        },
        "buildId": {
          "type": ["string", "null"],
          "description": "Build ID or version of the service"
        },
        "generatedFrom": {
          "$ref": "#/definitions/generatedFrom",
          "description": "References to source materials used to generate this function map"
        },
        "expectedPaths": {
          "type": "array",
          "description": "Expected call-paths that should be observed at runtime",
          "items": { "$ref": "#/definitions/expectedPath" },
          "minItems": 1
        },
        "coverage": {
          "$ref": "#/definitions/coverageThresholds",
          "description": "Coverage thresholds for verification"
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When this function map was generated"
        },
        "generator": {
          "$ref": "#/definitions/generatorInfo",
          "description": "Optional generator tool information"
        },
        "metadata": {
          "type": ["object", "null"],
          "description": "Optional metadata for extensions",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "generatedFrom": {
      "type": ["object", "null"],
      "properties": {
        "sbomRef": {
          "type": ["string", "null"],
          "description": "SHA256 digest of the SBOM used"
        },
        "staticAnalysisRef": {
          "type": ["string", "null"],
          "description": "SHA256 digest of the static analysis results used"
        },
        "binaryAnalysisRef": {
          "type": ["string", "null"],
          "description": "SHA256 digest of the binary analysis results used"
        },
        "hotFunctionPatterns": {
          "type": ["array", "null"],
          "description": "Hot function patterns used for filtering",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    },
    "expectedPath": {
      "type": "object",
      "required": ["pathId", "entrypoint", "expectedCalls", "pathHash"],
      "properties": {
        "pathId": {
          "type": "string",
          "description": "Unique identifier for this path within the function map",
          "minLength": 1
        },
        "description": {
          "type": ["string", "null"],
          "description": "Human-readable description of this call path"
        },
        "entrypoint": {
          "$ref": "#/definitions/pathEntrypoint",
          "description": "Entrypoint function that initiates this call path"
        },
        "expectedCalls": {
          "type": "array",
          "description": "Expected function calls within this path",
          "items": { "$ref": "#/definitions/expectedCall" },
          "minItems": 1
        },
        "pathHash": {
          "type": "string",
          "description": "Hash of the canonical path representation",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "optional": {
          "type": "boolean",
          "default": false,
          "description": "Whether this entire path is optional"
        },
        "strictOrdering": {
          "type": "boolean",
          "default": false,
          "description": "Whether strict ordering of expected calls should be verified"
        },
        "tags": {
          "type": ["array", "null"],
          "description": "Optional tags for categorizing paths",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    },
    "pathEntrypoint": {
      "type": "object",
      "required": ["symbol", "nodeHash"],
      "properties": {
        "symbol": {
          "type": "string",
          "description": "Symbol name of the entrypoint function",
          "minLength": 1
        },
        "nodeHash": {
          "type": "string",
          "description": "Node hash for this entrypoint (PURL + normalized symbol)",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "purl": {
          "type": ["string", "null"],
          "description": "Optional PURL of the component containing this entrypoint"
        }
      },
      "additionalProperties": false
    },
    "expectedCall": {
      "type": "object",
      "required": ["symbol", "purl", "nodeHash", "probeTypes"],
      "properties": {
        "symbol": {
          "type": "string",
          "description": "Symbol name of the expected function call",
          "minLength": 1
        },
        "purl": {
          "type": "string",
          "description": "Package URL (PURL) of the component containing this function",
          "pattern": "^pkg:[a-z]+/.+"
        },
        "nodeHash": {
          "type": "string",
          "description": "Node hash for this function (PURL + normalized symbol)",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "probeTypes": {
          "type": "array",
          "description": "Acceptable probe types for observing this function",
          "items": {
            "type": "string",
            "enum": ["kprobe", "kretprobe", "uprobe", "uretprobe", "tracepoint", "usdt"]
          },
          "minItems": 1
        },
        "optional": {
          "type": "boolean",
          "default": false,
          "description": "Whether this function call is optional"
        },
        "description": {
          "type": ["string", "null"],
          "description": "Optional human-readable description"
        },
        "functionAddress": {
          "type": ["integer", "null"],
          "description": "Optional function address hint for performance optimization"
        },
        "binaryPath": {
          "type": ["string", "null"],
          "description": "Optional binary path where this function is located"
        }
      },
      "additionalProperties": false
    },
    "coverageThresholds": {
      "type": "object",
      "properties": {
        "minObservationRate": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0,
          "default": 0.95,
          "description": "Minimum observation rate required for verification to pass"
        },
        "windowSeconds": {
          "type": "integer",
          "minimum": 1,
          "default": 1800,
          "description": "Observation window in seconds"
        },
        "minObservationCount": {
          "type": ["integer", "null"],
          "minimum": 1,
          "description": "Minimum number of observations required before verification can succeed"
        },
        "failOnUnexpected": {
          "type": "boolean",
          "default": false,
          "description": "Whether to fail on unexpected symbols (not in the function map)"
        }
      },
      "additionalProperties": false
    },
    "generatorInfo": {
      "type": ["object", "null"],
      "properties": {
        "name": {
          "type": ["string", "null"],
          "description": "Name of the generator tool"
        },
        "version": {
          "type": ["string", "null"],
          "description": "Version of the generator tool"
        },
        "commit": {
          "type": ["string", "null"],
          "description": "Optional commit hash of the generator tool"
        }
      },
      "additionalProperties": false
    }
  }
}