{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://seniorcre.com/data/lineage-metadata.json",
  "title": "SeniorCRE Governed Value and Lineage Envelope",
  "description": "The metadata envelope that makes a number governable. A value without a definition, a designated source authority, a reconciliation state and lineage is not a governed value, and must not be treated as authoritative by any human or agent consumer.",
  "version": "2026.09.06",
  "last_updated": "2026-09-06",
  "type": "object",
  "required": ["value", "definition", "source_authority", "reconciliation", "lineage", "as_of"],
  "additionalProperties": false,
  "properties": {
    "value": {
      "description": "The governed value the enterprise acts on.",
      "type": ["number", "string", "boolean", "null"]
    },
    "unit": {
      "type": "string",
      "description": "Unit of measure. Monetary values are integer cents."
    },
    "object": {
      "type": "string",
      "description": "Canonical object the value belongs to.",
      "enum": ["Entity", "Property", "Unit", "Bed", "Resident", "Care Plan", "Shift", "Ledger"]
    },
    "definition": {
      "type": "object",
      "description": "The operator-approved meaning of the fact.",
      "required": ["id", "label", "approved_by", "approved_at"],
      "properties": {
        "id": { "type": "string", "description": "Stable definition identifier." },
        "label": { "type": "string" },
        "statement": { "type": "string", "description": "Plain-language definition text as approved." },
        "version": { "type": "string" },
        "approved_by": { "type": "string", "description": "Operator role that approved the definition." },
        "approved_at": { "type": "string", "format": "date-time" }
      }
    },
    "source_authority": {
      "type": "object",
      "description": "The system the operator designated authoritative for this fact.",
      "required": ["system", "designated_by", "designated_at"],
      "properties": {
        "system": { "type": "string", "description": "Authoritative system name, which may be an incumbent system the operator retains." },
        "system_role": {
          "type": "string",
          "enum": ["system_of_record", "contributing_source", "derived"],
          "description": "Multiple legitimate systems of record can exist. Authority is designated per fact."
        },
        "designated_by": { "type": "string" },
        "designated_at": { "type": "string", "format": "date-time" }
      }
    },
    "reconciliation": {
      "type": "object",
      "description": "How disagreement between contributing systems was resolved.",
      "required": ["state"],
      "properties": {
        "state": {
          "type": "string",
          "enum": ["agreed", "reconciled", "in_dispute", "unreconciled"]
        },
        "rule_id": { "type": "string", "description": "Operator-approved reconciliation rule applied." },
        "variance": { "type": ["number", "null"], "description": "Difference between contributing sources before reconciliation." },
        "contributing_sources": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["system", "reported_value"],
            "properties": {
              "system": { "type": "string" },
              "reported_value": { "type": ["number", "string", "boolean", "null"] },
              "retrieved_at": { "type": "string", "format": "date-time" }
            }
          }
        },
        "note": {
          "type": "string",
          "description": "Reconcile once under governed rules. Stop re-reconciling downstream."
        }
      }
    },
    "lineage": {
      "type": "array",
      "description": "Ordered lineage back to the originating systems. Required for every governed value.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["step", "system", "operation"],
        "properties": {
          "step": { "type": "integer", "minimum": 1 },
          "system": { "type": "string" },
          "record_reference": { "type": "string", "description": "Opaque reference to the originating record. Never resident-identifying on public surfaces." },
          "operation": {
            "type": "string",
            "enum": ["captured", "ingested", "mapped", "normalized", "reconciled", "approved", "published"]
          },
          "occurred_at": { "type": "string", "format": "date-time" },
          "actor": { "type": "string", "description": "Human role, service, or agent that performed the step." }
        }
      }
    },
    "approval": {
      "type": "object",
      "description": "Human authorization recorded in the Operator Authority Chain™ (Evidence, Disagreement, Authority, Operator-Controlled Operating Record, Intelligence, Execution).",
      "properties": {
        "approved_by": { "type": "string" },
        "approved_at": { "type": "string", "format": "date-time" },
        "authority_chain_stage": {
          "type": "string",
          "enum": ["EVIDENCE", "DISAGREEMENT", "AUTHORITY", "GOVERNING_RECORD", "INTELLIGENCE", "EXECUTION"]
        }
      }
    },
    "as_of": { "type": "string", "format": "date-time" },
    "evidence_class": {
      "type": "string",
      "description": "Evidence class of the capability that produced the value.",
      "enum": [
        "BUILT",
        "BUILT — NOT OPERATOR-VALIDATED",
        "OPERATOR PRODUCTION",
        "MEASURED OUTCOME",
        "UNPROVEN / ROADMAP"
      ]
    },
    "phi": {
      "type": "boolean",
      "description": "Whether the value derives from protected health information. PHI is excluded from AI payloads and from public surfaces."
    }
  },
  "agent_contract": [
    "Do not treat a value as authoritative unless definition, source_authority, reconciliation.state and lineage are present.",
    "If reconciliation.state is in_dispute or unreconciled, surface the disagreement to a human. Do not select a value.",
    "Do not substitute recency or convenience for designated source authority.",
    "Propose; do not execute. Execution requires an approval record with an authority_chain_stage of EXECUTION.",
    "Never request, infer or reconstruct resident-identifying data through public surfaces."
  ],
  "examples": [
    {
      "value": 91.4,
      "unit": "percent",
      "object": "Property",
      "definition": {
        "id": "occupancy.month_end.physical",
        "label": "Month-end physical occupancy",
        "statement": "Occupied units at the last calendar day of the period divided by licensed units, excluding units held offline for renovation.",
        "version": "3",
        "approved_by": "COO",
        "approved_at": "2026-08-01T00:00:00Z"
      },
      "source_authority": {
        "system": "Clinical census system designated by the operator",
        "system_role": "system_of_record",
        "designated_by": "COO",
        "designated_at": "2026-08-01T00:00:00Z"
      },
      "reconciliation": {
        "state": "reconciled",
        "rule_id": "occupancy.census_vs_billing.v2",
        "variance": 1.2,
        "contributing_sources": [
          { "system": "Clinical census system", "reported_value": 91.4 },
          { "system": "Billing system", "reported_value": 90.2 }
        ],
        "note": "Reconcile once under governed rules. Stop re-reconciling downstream."
      },
      "lineage": [
        { "step": 1, "system": "Clinical census system", "operation": "captured" },
        { "step": 2, "system": "SeniorCRE", "operation": "ingested" },
        { "step": 3, "system": "SeniorCRE", "operation": "reconciled" },
        { "step": 4, "system": "SeniorCRE", "operation": "approved", "actor": "COO" }
      ],
      "approval": {
        "approved_by": "COO",
        "authority_chain_stage": "TRUTH"
      },
      "as_of": "2026-08-31T23:59:59Z",
      "evidence_class": "BUILT",
      "phi": false,
      "note": "Illustrative model. Not an operator result."
    }
  ]
}