margin_watch_learning contract v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.demiton.io/registers/margin_watch_learning/v1.json",
  "title": "margin_watch_learning contract v1",
  "type": "object",
  "required": [
    "lesson_candidates",
    "observability_gaps_ranked",
    "promotion_gate",
    "subject_entity_id",
    "summary"
  ],
  "properties": {
    "job_no": {
      "type": "string",
      "description": "producer's snapshot of the job number (duplicates the subject spine's canonical key)",
      "x-demiton-requiredness": "optional"
    },
    "summary": {
      "type": "string",
      "description": "one-line human summary for content search and list display",
      "x-demiton-requiredness": "required"
    },
    "currency": {
      "type": "currency",
      "description": "the currency of every monetary amount on this record, an ISO 4217 alpha-3 code as the source states it. A record with no currency has no usable amount.",
      "x-demiton-requiredness": "optional"
    },
    "legal_entity": {
      "type": "string",
      "description": "context coordinate declared OPTIONAL",
      "x-demiton-requiredness": "optional",
      "x-demiton-reference": true
    },
    "project_name": {
      "type": "string",
      "description": "producer's snapshot of the project/client label (duplicates the entity label)",
      "x-demiton-requiredness": "optional"
    },
    "promotion_gate": {
      "type": "string",
      "description": "record-level candidate-only marker",
      "x-demiton-requiredness": "required"
    },
    "financial_period": {
      "type": "string",
      "description": "context coordinate declared OPTIONAL",
      "x-demiton-requiredness": "optional"
    },
    "lesson_candidates": {
      "type": "array",
      "description": "candidate lessons awaiting human promotion; empty array is valid",
      "x-demiton-requiredness": "required",
      "items": {
        "type": "object",
        "properties": {
          "cause": {
            "type": "string",
            "description": "attributed cause, one of the five code-defined values in, `:86-131`",
            "x-demiton-requiredness": "required"
          },
          "statement": {
            "type": "string",
            "description": "the candidate lesson, stated as cause + drift + period + project",
            "x-demiton-requiredness": "required"
          },
          "promotion_gate": {
            "type": "string",
            "description": "explicit \"candidate only, human sign-off required\" marker",
            "x-demiton-requiredness": "required"
          },
          "provenance": {
            "type": "object",
            "properties": {
              "month": {
                "type": "string",
                "description": "claim-cycle month the drift is measured in",
                "x-demiton-requiredness": "required"
              },
              "evidence": {
                "type": "string",
                "description": "the observed signal behind the cause (e.g. a diary-flag count)",
                "x-demiton-requiredness": "required"
              },
              "drift_pts": {
                "type": "number",
                "description": "signed margin movement that cycle",
                "x-demiton-requiredness": "required",
                "x-demiton-unit": "margin points"
              },
              "drift_dollars": {
                "type": "number",
                "description": "points scaled by contract value; null when no contract value",
                "x-demiton-requiredness": "optional"
              }
            },
            "required": [
              "drift_pts",
              "evidence",
              "month"
            ]
          }
        },
        "required": [
          "cause",
          "promotion_gate",
          "statement"
        ]
      }
    },
    "subject_entity_id": {
      "type": "integer",
      "description": "the project the learning is about; the semantic fact's subject and its supersede key",
      "x-demiton-requiredness": "required"
    },
    "margin_to_date_pct": {
      "type": "number",
      "description": "margin to date at attribution time",
      "x-demiton-requiredness": "optional",
      "x-demiton-unit": "percent"
    },
    "tendered_margin_pct": {
      "type": "number",
      "description": "tendered margin at attribution time",
      "x-demiton-requiredness": "optional",
      "x-demiton-unit": "percent"
    },
    "observability_gaps_ranked": {
      "type": "array",
      "description": "data gaps that made a cycle unattributable, ranked; empty array valid",
      "x-demiton-requiredness": "required",
      "items": {
        "type": "object",
        "properties": {
          "gap": {
            "type": "string",
            "description": "the named missing data (e.g. no diaries for a month)",
            "x-demiton-requiredness": "required"
          },
          "months": {
            "type": "array",
            "description": "the months in which that gap occurred",
            "x-demiton-requiredness": "required"
          },
          "margin_points_obscured": {
            "type": "number",
            "description": "total absolute drift the gap obscures",
            "x-demiton-requiredness": "required",
            "x-demiton-unit": "margin points"
          }
        },
        "required": [
          "gap",
          "margin_points_obscured",
          "months"
        ]
      }
    }
  },
  "x-demiton-register-type": "margin_watch_learning",
  "x-demiton-contract-version": "1.1.1",
  "x-demiton-store": "tenant",
  "x-demiton-axes": [
    {
      "axis": "financial_period",
      "requirement": "optional",
      "role": "context"
    },
    {
      "axis": "legal_entity",
      "requirement": "optional",
      "role": "context"
    }
  ],
  "x-demiton-measures": [],
  "x-demiton-provenance": {
    "standards": []
  },
  "description": "Lessons and observability gaps Margin Watch has found on a project, awaiting review.",
  "x-demiton-contract-url": "https://docs.demiton.io/registers/margin_watch_learning/",
  "x-demiton-register-catalog": "https://docs.demiton.io/concepts/register-catalog"
}