$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://railiance.local/fabric/schemas/discovery-snapshot.schema.yaml"
title: "FabricDiscoverySnapshot"
type: object
additionalProperties: false
required:
  - apiVersion
  - kind
  - source
  - scan
  - replacement_scopes
  - candidates
  - tombstones
  - reconciliation
properties:
  apiVersion:
    $ref: "./common.schema.yaml#/$defs/apiVersion"
  kind:
    type: string
    const: FabricDiscoverySnapshot
  generated_at:
    type: string
    format: date-time
  source:
    type: object
    additionalProperties: false
    required:
      - repo_slug
      - commit
    properties:
      repo_slug:
        type: string
        minLength: 1
      repo_name:
        type: string
      domain:
        type: string
      commit:
        type: string
        minLength: 1
      default_branch:
        type: string
      path:
        type: string
  scan:
    type: object
    additionalProperties: false
    required:
      - run_id
      - profile
      - deterministic_only
      - llm_enabled
    properties:
      run_id:
        $ref: "#/$defs/stableKey"
      profile:
        type: string
        minLength: 1
      deterministic_only:
        type: boolean
      llm_enabled:
        type: boolean
      started_at:
        type: string
        format: date-time
      completed_at:
        type: string
        format: date-time
      llm_budget:
        type: object
        additionalProperties: true
  replacement_scopes:
    type: array
    items:
      $ref: "#/$defs/replacementScope"
  candidates:
    type: object
    additionalProperties: false
    required:
      - nodes
      - edges
      - attributes
    properties:
      nodes:
        type: array
        items:
          $ref: "#/$defs/candidateNode"
      edges:
        type: array
        items:
          $ref: "#/$defs/candidateEdge"
      attributes:
        type: array
        items:
          $ref: "#/$defs/candidateAttribute"
  tombstones:
    type: array
    items:
      $ref: "#/$defs/tombstone"
  review_artifacts:
    type: array
    items:
      $ref: "#/$defs/reviewArtifact"
  connector_runs:
    type: array
    items:
      $ref: "#/$defs/connectorRun"
  reconciliation:
    type: object
    additionalProperties: false
    required:
      - precedence
      - duplicate_policy
      - retirement_policy
    properties:
      precedence:
        type: array
        minItems: 1
        uniqueItems: true
        items:
          $ref: "#/$defs/origin"
      duplicate_policy:
        type: string
        minLength: 1
      retirement_policy:
        type: string
        minLength: 1
      conflicts:
        type: array
        items:
          type: object
          additionalProperties: true
      diff:
        type: object
        additionalProperties: false
        required:
          - added
          - changed
          - retired
          - conflicted
        properties:
          added:
            type: array
            uniqueItems: true
            items:
              $ref: "#/$defs/stableKey"
          changed:
            type: array
            uniqueItems: true
            items:
              $ref: "#/$defs/stableKey"
          retired:
            type: array
            uniqueItems: true
            items:
              $ref: "#/$defs/stableKey"
          conflicted:
            type: array
            uniqueItems: true
            items:
              $ref: "#/$defs/stableKey"

$defs:
  stableKey:
    type: string
    minLength: 3
    maxLength: 240
    pattern: "^[A-Za-z0-9][A-Za-z0-9._:/@+-]*$"

  origin:
    type: string
    enum:
      - repo_declaration
      - deterministic
      - catalog
      - registry
      - llm
      - manual

  reviewState:
    type: string
    enum:
      - accepted
      - candidate
      - needs_review
      - rejected

  mappingFit:
    type: string
    enum:
      - direct
      - partial
      - conflict
      - gap
      - unknown

  evidenceState:
    type: string
    enum:
      - observed
      - declared
      - inferred
      - proposed
      - gap

  entityStatus:
    type: string
    enum:
      - active
      - retired
      - duplicate
      - conflicted

  sourceKind:
    type: string
    enum:
      - file
      - declaration
      - package_manifest
      - lockfile
      - api_contract
      - deployment_manifest
      - service_config
      - service_catalog
      - package_registry
      - container_registry
      - fabric_registry
      - llm
      - manual

  extractionMethod:
    type: string
    enum:
      - declaration
      - deterministic
      - connector
      - llm
      - manual

  confidence:
    type: number
    minimum: 0
    maximum: 1

  jsonValue:
    anyOf:
      - type: "null"
      - type: string
      - type: number
      - type: integer
      - type: boolean
      - type: array
        items:
          $ref: "#/$defs/jsonValue"
      - type: object
        additionalProperties:
          $ref: "#/$defs/jsonValue"

  sourceAnchor:
    type: object
    additionalProperties: false
    required:
      - source_kind
      - fingerprint
    properties:
      source_kind:
        $ref: "#/$defs/sourceKind"
      path:
        type: string
        minLength: 1
      url:
        type: string
        format: uri
      ref:
        type: string
        minLength: 1
      line_start:
        type: integer
        minimum: 1
      line_end:
        type: integer
        minimum: 1
      json_pointer:
        type: string
      fingerprint:
        type: string
        minLength: 8
      snippet:
        type: string

  provenance:
    type: object
    additionalProperties: false
    required:
      - extractor_id
      - method
      - origin
    properties:
      extractor_id:
        type: string
        minLength: 1
      extractor_version:
        type: string
      method:
        $ref: "#/$defs/extractionMethod"
      origin:
        $ref: "#/$defs/origin"
      prompt_version:
        type: string
      provider:
        type: string
      model:
        type: string
      usage:
        type: object
        additionalProperties: true
      rationale:
        type: string

  replacementScope:
    type: object
    additionalProperties: false
    required:
      - id
      - extractor_id
      - source_kind
      - mode
    properties:
      id:
        $ref: "#/$defs/stableKey"
      extractor_id:
        type: string
        minLength: 1
      source_kind:
        $ref: "#/$defs/sourceKind"
      source_path:
        type: string
      mode:
        type: string
        enum:
          - replacement
          - additive
      description:
        type: string

  candidateNode:
    type: object
    additionalProperties: false
    required:
      - stable_key
      - kind
      - label
      - repo
      - origin
      - review_state
      - status
      - confidence
      - replacement_scope
      - provenance
      - source_anchors
    properties:
      stable_key:
        $ref: "#/$defs/stableKey"
      graph_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      kind:
        type: string
        minLength: 1
      canon_category:
        type: string
        minLength: 1
      canon_anchor:
        type: string
      mapping_fit:
        $ref: "#/$defs/mappingFit"
      evidence_state:
        $ref: "#/$defs/evidenceState"
      label:
        type: string
        minLength: 1
      repo:
        type: string
        minLength: 1
      domain:
        type: string
      lifecycle:
        type: string
      aliases:
        type: array
        uniqueItems: true
        items:
          type: string
          minLength: 1
      attributes:
        type: object
        additionalProperties:
          $ref: "#/$defs/jsonValue"
      origin:
        $ref: "#/$defs/origin"
      review_state:
        $ref: "#/$defs/reviewState"
      status:
        $ref: "#/$defs/entityStatus"
      confidence:
        $ref: "#/$defs/confidence"
      replacement_scope:
        $ref: "#/$defs/stableKey"
      provenance:
        type: array
        minItems: 1
        items:
          $ref: "#/$defs/provenance"
      source_anchors:
        type: array
        minItems: 1
        items:
          $ref: "#/$defs/sourceAnchor"

  candidateEdge:
    type: object
    additionalProperties: false
    required:
      - stable_key
      - edge_type
      - source_key
      - target_key
      - origin
      - review_state
      - status
      - confidence
      - replacement_scope
      - provenance
      - source_anchors
    properties:
      stable_key:
        $ref: "#/$defs/stableKey"
      edge_type:
        type: string
        minLength: 1
      canonical_type:
        type: string
      canon_anchor:
        type: string
      mapping_fit:
        $ref: "#/$defs/mappingFit"
      display_only:
        type: boolean
      evidence_state:
        $ref: "#/$defs/evidenceState"
      source_key:
        $ref: "#/$defs/stableKey"
      target_key:
        $ref: "#/$defs/stableKey"
      aliases:
        type: array
        uniqueItems: true
        items:
          type: string
          minLength: 1
      attributes:
        type: object
        additionalProperties:
          $ref: "#/$defs/jsonValue"
      origin:
        $ref: "#/$defs/origin"
      review_state:
        $ref: "#/$defs/reviewState"
      status:
        $ref: "#/$defs/entityStatus"
      confidence:
        $ref: "#/$defs/confidence"
      replacement_scope:
        $ref: "#/$defs/stableKey"
      provenance:
        type: array
        minItems: 1
        items:
          $ref: "#/$defs/provenance"
      source_anchors:
        type: array
        minItems: 1
        items:
          $ref: "#/$defs/sourceAnchor"

  candidateAttribute:
    type: object
    additionalProperties: false
    required:
      - stable_key
      - entity_key
      - name
      - value
      - origin
      - review_state
      - confidence
      - replacement_scope
      - provenance
      - source_anchors
    properties:
      stable_key:
        $ref: "#/$defs/stableKey"
      entity_key:
        $ref: "#/$defs/stableKey"
      name:
        type: string
        minLength: 1
      value:
        $ref: "#/$defs/jsonValue"
      origin:
        $ref: "#/$defs/origin"
      review_state:
        $ref: "#/$defs/reviewState"
      confidence:
        $ref: "#/$defs/confidence"
      replacement_scope:
        $ref: "#/$defs/stableKey"
      provenance:
        type: array
        minItems: 1
        items:
          $ref: "#/$defs/provenance"
      source_anchors:
        type: array
        minItems: 1
        items:
          $ref: "#/$defs/sourceAnchor"

  tombstone:
    type: object
    additionalProperties: false
    required:
      - stable_key
      - entity_kind
      - replacement_scope
      - retired_at
      - reason
    properties:
      stable_key:
        $ref: "#/$defs/stableKey"
      entity_kind:
        type: string
        enum:
          - node
          - edge
          - attribute
      replacement_scope:
        $ref: "#/$defs/stableKey"
      retired_at:
        type: string
        format: date-time
      reason:
        type: string
        enum:
          - source_missing
          - scope_replaced
          - duplicate_superseded
          - declaration_override
          - manually_retired
      previous_candidate:
        type: object
        additionalProperties: true

  reviewArtifact:
    type: object
    additionalProperties: false
    required:
      - id
      - artifact_type
      - origin
      - message
      - created_at
    properties:
      id:
        $ref: "#/$defs/stableKey"
      artifact_type:
        type: string
        enum:
          - llm_output_invalid
          - llm_low_confidence
          - llm_candidate_unresolved
          - llm_execution_error
          - connector_failed
          - connector_rate_limited
          - connector_unavailable
      origin:
        $ref: "#/$defs/origin"
      message:
        type: string
        minLength: 1
      evidence_refs:
        type: array
        items:
          type: string
          minLength: 1
      payload:
        type: object
        additionalProperties: true
      created_at:
        type: string
        format: date-time

  connectorRun:
    type: object
    additionalProperties: false
    required:
      - connector_id
      - connector_type
      - status
    properties:
      connector_id:
        type: string
        minLength: 1
      connector_type:
        type: string
        enum:
          - package_registry
          - container_registry
          - api_catalog
          - service_catalog
          - deployment_inventory
          - fabric_registry
      status:
        type: string
        enum:
          - success
          - partial
          - unavailable
          - rate_limited
          - failed
          - skipped
      source:
        type: string
      message:
        type: string
      candidate_counts:
        type: object
        additionalProperties: false
        properties:
          nodes:
            type: integer
            minimum: 0
          edges:
            type: integer
            minimum: 0
          attributes:
            type: integer
            minimum: 0
      started_at:
        type: string
        format: date-time
      completed_at:
        type: string
        format: date-time