# CIRCUIT Registry Entry — Normative Schema v1.1.0
#
# Source of truth: whitepaper.html, Appendix B "Registry YAML Schema (Normative)".
# This file mirrors that normative schema. Fields marked with a type comment are
# required. Schema version 1.1.0; backward compatibility is maintained within a
# minor version, so all 1.0.x entries remain valid.
#
# v1.1.0 changes vs 1.0.x:
#   - Fourth CRS band renamed Black → Purple (green | amber | red | purple).
#   - vendor_transparency gains three vendor-outreach fields: outreach_attempts,
#     nonresponsive_since, and a "nonresponsive" value for rule_8_status.
#   - crs gains consequence_floor_applied (true when DCW ≥ 4 on High/Critical).
#   No formula, factor domain, band threshold, or KPI value changed (whitepaper §4.3.1).
#
# Scales (see /data/framework.json):
#   Risk Tier — Low=1, Moderate=2, High=3, Critical=4
#   DCW       — Advisory=1, Recommended=2, Automated=3, Irreversible=4, Catastrophic=5
#   CRS = Risk Tier × (6 − IMS) × DCW   (max 4 × 6 × 5 = 120)
#   Bands     — Green 1–12, Amber 13–47, Red 48–96, Purple 97–120

circuit_registry_entry:
  version: "1.1.0"

  # ── Section 1: Identity ──────────────────────────────────────────────────────
  identity:
    model_id: ""              # Unique slug (e.g., "dlp-classifier-v3")    [required]
    name: ""                  # Human-readable model name and version       [required]
    vendor: ""                # "internal" or vendor name                   [required]
    category: ""              # "A", "B", or "C"                            [required]
    risk_tier: ""             # "Low", "Moderate", "High", or "Critical"    [required]
    owner: ""                 # Accountable owner (email or name/title)     [required]
    consequence: ""           # "Advisory" .. "Catastrophic" (DCW 1–5)      [required]
    business_process: ""      # What business problem this model solves
    upstream_dependencies: [] # Foundation models, APIs, data pipelines depended on
    hosting_location: ""      # Region, cloud provider, on-prem
    data_classification: ""   # Classification of input data (e.g., PII, financial, public)

  # ── Section 2: Maturity ──────────────────────────────────────────────────────
  maturity:
    ims: 0                    # Current IMS level (0–5)
    ims_ceiling: null         # Maximum achievable given category (A→5, B→3, C→2)
    evidence: []              # List of evidence artifacts
    # Evidence artifact shape:
    # - artifact: "filename.pkl"
    #   type: "sparse_autoencoder" | "attribution_graph" | "shap_values" | "behavioral_log" | ...
    #   date: "YYYY-MM-DD"
    #   hash: ""              # SHA-256 of artifact file for auditability
    #   location: ""          # Path or URL to artifact
    level_history: []         # Log of IMS level transitions
    # Level history shape:
    # - from_level: 0
    #   to_level: 1
    #   date: "YYYY-MM-DD"
    #   evidence_artifact: "artifact-name"

  # ── Section 3: Circuit Inventory ─────────────────────────────────────────────
  circuit_inventory: []       # Populated once the model reaches IMS 4
  # Circuit shape:
  # - name: ""                # Human-readable circuit name (e.g., "fraud-flag-circuit")
  #   behavior: ""            # What behavior this circuit governs
  #   size_nodes: null        # Feature count in the circuit
  #   edge_count: null        # Feature-to-feature connections
  #   monosemanticity: null   # 0.0–1.0
  #   robustness: null        # 0.0–1.0
  #   artifact_link: ""       # Link to circuit artifact

  # ── Section 4: KPI Baseline ──────────────────────────────────────────────────
  kpi_baseline:
    circuit_size: null            # Nodes per decision circuit (floor for High: ≤ 100; assumes automated sub-graph summarization, not unaided human inspection)
    edge_count: null              # Connections per circuit (floor for High: ≤ 500)
    monosemanticity: null         # 0.0–1.0 (transitional minimum for High: ≥ 0.55; reliability target: ≥ 0.70; scores in [0.55,0.70) admissible with compensating controls and remediation tracked)
    robustness: null              # 0.0–1.0 (floor for High: ≥ 0.90)
    stability_across_versions: null # 0.0–1.0 (floor for High: ≥ 0.75)
    acfr_last_quarter: 0          # count of P1 safety-circuit bypasses this quarter (floor: 0; Rule 7 trigger: ≥ 1). Integer; not a ratio; not normalized by traffic.
    measurement_date: ""          # YYYY-MM-DD
    methodology: ""               # Description of measurement approach
    time_series: []               # Historical KPI snapshots
    # Time series shape:
    # - date: "YYYY-MM-DD"
    #   circuit_size: null
    #   edge_count: null
    #   monosemanticity: null
    #   robustness: null
    #   stability_across_versions: null
    #   acfr: 0                   # integer count for that quarter

  # ── Section 5: Vendor Transparency ───────────────────────────────────────────
  # "Show Me Your Circuits" — 29 questions across four sections (see /data/questionnaire.json).
  vendor_transparency:
    questionnaire_date: ""        # YYYY-MM-DD when questionnaire was returned
    questionnaire_version: "1.0"
    vendor_contact: ""            # Name, title, email of responder (must be engineering-level)
    responses: []                 # 29 question responses
    # Response shape:
    # - question_id: 1            # Matches id in questionnaire.json
    #   rating: ""                # "acceptable" | "partial" | "unacceptable" | "not_answered"
    #   vendor_response: ""       # Vendor's actual response text
    #   assessor_notes: ""        # Internal assessor notes
    section_scores:               # Percentage Acceptable per section (computed from responses)
      A: null                     # Identity and Provenance (Q1–7)
      B: null                     # Interpretability Evidence (Q8–16)
      C: null                     # Safety and Red-Teaming (Q17–23)
      D: null                     # Contractual and Audit Posture (Q24–29)
    overall_score: null           # Overall % Acceptable across all 29 questions
    rule_8_status: ""             # "complete" | "vendor_declined" | "pending" | "nonresponsive"
    outreach_attempts: []         # [{date, method, contact}] — Rule 8 trigger input
    nonresponsive_since: null     # date the 60-day Rule 8 clock expired; null if open

  # ── Section 6: Red Team ──────────────────────────────────────────────────────
  red_team:
    last_engagement_date: ""      # YYYY-MM-DD
    next_scheduled_date: ""       # YYYY-MM-DD (Rule 6: semi-annually for High/Critical, annually for Moderate)
    methodology: ""               # Description of red team approach
    mitre_atlas_coverage: []      # ATLAS technique IDs tested (e.g., ["AML.T0051", "AML.T0043"])
    findings: []                  # List of findings with severity and remediation status
    # Finding shape:
    # - id: ""
    #   technique_id: ""          # MITRE ATLAS technique ID
    #   severity: ""              # "critical" | "high" | "medium" | "low"
    #   description: ""
    #   remediation_status: ""    # "open" | "in_progress" | "closed"
    #   remediation_date: ""      # YYYY-MM-DD (if closed)

  # ── Section 7: Compensating Controls ─────────────────────────────────────────
  compensating_controls:
    required_if_band: ["red"]     # mandatory at Red; recommended at Amber; also required for monosemanticity 0.55–0.70
    controls: []
    # Control shape:
    # - control_id: ""            # Internal control identifier
    #   description: ""           # What the control does
    #   type: ""                  # "human_in_the_loop" | "output_filter" | "scope_restriction" | "monitoring" | "other"
    #   covers_rule: null         # Rule number this control addresses (if applicable)
    #   effective_date: ""        # YYYY-MM-DD

  # ── Section 8: Lifecycle ─────────────────────────────────────────────────────
  lifecycle:
    deployment_date: ""           # YYYY-MM-DD
    material_updates: []          # Log of material updates per Rule 5
    # Update shape:
    # - version: ""
    #   date: "YYYY-MM-DD"
    #   change_description: ""
    #   stability_kpi_remeasured: false
    #   new_registry_version: ""
    planned_retirement_date: null # YYYY-MM-DD or null
    rollback_procedure: ""        # Description of how to rollback to prior version
    incident_history: []          # Incidents that increment the quarterly ACFR count
    # Incident shape:
    # - date: "YYYY-MM-DD"
    #   description: ""
    #   acfr_contribution: 1      # integer increment to quarterly ACFR count (typically 1 per P1 safety-circuit bypass)
    #   resolution: ""
    retention_expires: ""         # YYYY-MM-DD; minimum 3 years from deployment (Rule 10)
    registry_version: "1.1.0"
    last_reviewed: ""             # YYYY-MM-DD

  # ── Computed Fields (derived; not manually entered) ──────────────────────────
  crs:
    calculated: null              # Risk Tier × (6 − IMS) × DCW
    band: ""                      # "green" | "amber" | "red" | "purple"
    consequence_floor_applied: false # true if DCW ≥ 4 on a High/Critical-tier model (Rule 3)
    computed_date: ""             # YYYY-MM-DD
    next_review_date: ""          # YYYY-MM-DD

# ── WORKED EXAMPLE (Category A, High tier, IMS 3) ────────────────────────────
# circuit_registry_entry:
#   version: "1.1.0"
#   identity:
#     model_id: "fraud-classifier-v3"
#     name: "Real-Time Fraud Scoring v3 (Gemma-3 9B fine-tune)"
#     vendor: "internal"
#     category: "A"
#     risk_tier: "High"          # numeric 3
#     owner: "security-team@company.com"
#     consequence: "Automated"   # DCW 3
#   maturity:
#     ims: 3
#     ims_ceiling: 5
#     evidence:
#       - artifact: "fraud_sae_gemma3_9b_v3.pkl"
#         type: "sparse_autoencoder"
#         date: "2026-03-15"
#   kpi_baseline:
#     circuit_size: 84
#     edge_count: 318
#     monosemanticity: 0.87
#     robustness: 0.94
#     stability_across_versions: 0.91
#     acfr_last_quarter: 0
#   crs:
#     calculated: 27             # 3 × (6 − 3) × 3 = 27
#     band: "amber"              # 13–47
#     consequence_floor_applied: false  # DCW 3 < 4
