# Institutional Capability Lineage Architecture (ICLA)
# Reference Specification
#
# Copyright (c) 2026 Mariano Garralda-Barrio
#
# Licensed under the Creative Commons Attribution 4.0
# International License (CC BY 4.0).
#
# See LICENSE in the repository root.

$schema: https://json-schema.org/draft/2020-12/schema
title: Governance Decision
type: object
required:
  - document_type
  - format_version
  - specification_version
  - id
  - artifact_status
  - normative
  - schema_ref
  - status
  - generated_from
  - inputs
  - review
  - capability_formation
  - resulting_lineage_edges
properties:
  document_type: {const: governance-decision}
  format_version: {const: icla-artifact/0.1-draft}
  specification_version:
    type: object
    required: [icla-spec]
    properties:
      icla-spec: {const: 0.1.0}
    additionalProperties: false
  id: {type: string, pattern: "^DEC-[A-Z0-9-]+$"}
  artifact_status: {const: reference}
  normative: {const: false}
  schema_ref: {type: string}
  status: {enum: [approved, rejected, deferred, quarantined, superseded]}
  generated_from: {type: object, minProperties: 3}
  inputs:
    type: object
    additionalProperties: true
  review: {type: object}
  dispositions:
    type: object
    minProperties: 1
    additionalProperties:
      type: object
      properties:
        candidate_ref: {type: string, pattern: "^CAND-[A-Z0-9-]+$"}
        memory_transition: {$ref: "#/$defs/memory_transition"}
        candidate_lifecycle_transition:
          type: object
          required: [from, to]
          properties:
            from: {const: submitted}
            to: {enum: [admitted, rejected, quarantined, retained-local]}
          additionalProperties: false
      dependentRequired:
        candidate_ref: [memory_transition, candidate_lifecycle_transition]
      additionalProperties: true
  impact_record:
    type: object
    required: [id, affected_capabilities, affected_ckcs, review_required]
    properties:
      change_event_ref: {type: string, minLength: 1}
      assessment_mode: {enum: [event-driven, continuous-event-driven]}
    additionalProperties: true
  successor_delta:
    type: object
    required:
      - id
      - predecessor_ref
      - successor_ref
      - changed_commitments
      - rationale
      - supporting_evidence_refs
      - authorization_decision_ref
      - rollback_ref
      - successor_complete
      - reconstruction_patch
    properties:
      id: {type: string, pattern: "^DELTA-[A-Z0-9-]+$"}
      predecessor_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
      successor_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
      changed_commitments:
        type: array
        minItems: 1
        items:
          type: object
          required: [area, operation, subject]
          properties:
            area:
              enum:
                - knowledge_scope
                - operational_relations
                - evidence_contract
                - evaluation_contract
                - governance
                - projection_rules
            operation: {enum: [add, revise, remove]}
            subject: {type: string, minLength: 1}
          additionalProperties: false
      rationale: {type: string, minLength: 1}
      supporting_evidence_refs:
        type: array
        minItems: 1
        uniqueItems: true
        items: {type: string, minLength: 1}
      authorization_decision_ref: {type: string, pattern: "^DEC-[A-Z0-9-]+$"}
      rollback_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
      successor_complete: {const: true}
      reconstruction_patch: {const: false}
    additionalProperties: false
  successor_append:
    type: object
    required:
      - id
      - capability
      - predecessor_ref
      - successor_ref
      - delta_ref
      - authorization_decision_ref
      - status
    properties:
      id: {type: string, pattern: "^APPEND-[A-Z0-9-]+$"}
      capability: {type: string, pattern: "^CAP-[A-Z0-9-]+$"}
      predecessor_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
      successor_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
      delta_ref: {type: string, pattern: "^DELTA-[A-Z0-9-]+$"}
      authorization_decision_ref: {type: string, pattern: "^DEC-[A-Z0-9-]+$"}
      status: {const: inactive-successor}
    additionalProperties: false
  activation:
    type: object
    required:
      - id
      - activation_kind
      - capability
      - ckc
      - version
      - applies_to
      - active_pointer_transition
      - rollback_target
    properties:
      id: {type: string, pattern: "^ACT-[A-Z0-9-]+$"}
      activation_kind: {enum: [successor, initial, reactivation]}
      capability: {type: string, pattern: "^CAP-[A-Z0-9-]+$"}
      ckc: {type: string, pattern: "^CKC-[A-Z0-9-]+$"}
      version: {type: integer, minimum: 1}
      successor_append_ref: {type: string, pattern: "^APPEND-[A-Z0-9-]+$"}
      formation_append_ref: {type: string, pattern: "^FORM-[A-Z0-9-]+$"}
      applies_to: {const: future-resolutions-only}
      active_pointer_transition:
        type: object
        required: [from, to]
        properties:
          from:
            anyOf:
              - {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
              - {type: "null"}
          to: {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
        additionalProperties: false
      rollback_target:
        anyOf:
          - {type: string, pattern: "^CKC-[A-Z0-9-]+-v[0-9]+$"}
          - {type: "null"}
      resulting_registry_snapshot_ref:
        type: string
        pattern: "^REG-SNAP-[A-Z0-9-]+$"
    oneOf:
      - properties:
          activation_kind: {const: successor}
          active_pointer_transition:
            properties:
              from: {type: string}
          rollback_target: {type: string}
        required: [successor_append_ref]
        not:
          required: [formation_append_ref]
      - properties:
          activation_kind: {const: initial}
          version: {const: 1}
          active_pointer_transition:
            properties:
              from: {type: "null"}
          rollback_target: {type: "null"}
        required: [formation_append_ref, resulting_registry_snapshot_ref]
        not:
          required: [successor_append_ref]
      - properties:
          activation_kind: {const: reactivation}
          active_pointer_transition:
            properties:
              from: {type: string}
          rollback_target: {type: string}
        not:
          anyOf:
            - required: [successor_append_ref]
            - required: [formation_append_ref]
    additionalProperties: false
  historical_immutability:
    type: object
    required: [retroactive_mutation]
    properties:
      assembly_ref: {type: string}
      remains_linked_to: {type: string}
      retained_supporting_record_refs:
        type: array
        minItems: 1
        uniqueItems: true
        items: {type: string, minLength: 1}
      retroactive_mutation: {const: false}
    anyOf:
      - required: [assembly_ref, remains_linked_to]
      - required: [retained_supporting_record_refs]
    additionalProperties: true
  capability_formation:
    type: object
    required: [new_capability_created_by_this_decision, rationale]
    properties:
      new_capability_created_by_this_decision: {type: boolean}
      rationale: {type: string, minLength: 1}
      proposal_refs:
        type: array
        minItems: 1
        uniqueItems: true
        items: {type: string, pattern: "^PROP-[A-Z0-9-]+$"}
      governed_promotion:
        type: object
        required:
          - proposal_ref
          - review_decision_ref
          - formation_authority
          - assigned_capability
          - approved_relations
          - initial_ckc_ref
        properties:
          proposal_ref: {type: string, pattern: "^PROP-[A-Z0-9-]+$"}
          review_decision_ref: {type: string, pattern: "^DEC-[A-Z0-9-]+$"}
          formation_authority: {type: string, minLength: 1}
          assigned_capability:
            type: object
            required: [id, name, outcome, owner, domain, lifecycle, policy_refs, conditions]
            properties:
              id: {type: string, pattern: "^CAP-[A-Z0-9-]+$"}
              name: {type: string, minLength: 1}
              outcome: {type: string, minLength: 1}
              owner: {type: string, minLength: 1}
              domain: {type: string, minLength: 1}
              lifecycle: {const: approved}
              policy_refs:
                type: array
                minItems: 1
                items: {type: string, minLength: 1}
              conditions: {type: object, minProperties: 1}
            not:
              required: [active_ckc]
            additionalProperties: true
          approved_relations:
            description: Registry relations approved as part of formation; each must involve the newly assigned capability identity.
            type: array
            uniqueItems: true
            items:
              type: object
              required: [type, from, to]
              properties:
                type:
                  enum:
                    - depends_on
                    - composes_with
                    - specializes
                    - replaces
                    - shares_knowledge
                    - derived_from
                    - conflicts_with
                from: {type: string, pattern: "^CAP-[A-Z0-9-]+$"}
                to: {type: string, pattern: "^CAP-[A-Z0-9-]+$"}
              additionalProperties: false
          initial_ckc_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v1$"}
        additionalProperties: false
      formation_append:
        type: object
        required:
          - id
          - proposal_ref
          - capability_ref
          - initial_ckc_ref
          - authorization_decision_ref
          - status
        properties:
          id: {type: string, pattern: "^FORM-[A-Z0-9-]+$"}
          proposal_ref: {type: string, pattern: "^PROP-[A-Z0-9-]+$"}
          capability_ref: {type: string, pattern: "^CAP-[A-Z0-9-]+$"}
          initial_ckc_ref: {type: string, pattern: "^CKC-[A-Z0-9-]+-v1$"}
          authorization_decision_ref: {type: string, pattern: "^DEC-[A-Z0-9-]+$"}
          status: {const: inactive-initial-ckc}
        additionalProperties: false
      formed_registry_snapshot_ref:
        type: string
        pattern: "^REG-SNAP-[A-Z0-9-]+$"
    allOf:
      - if:
          properties:
            new_capability_created_by_this_decision: {const: false}
          required: [new_capability_created_by_this_decision]
        then:
          required: [proposal_refs]
          not:
            anyOf:
              - required: [governed_promotion]
              - required: [formation_append]
              - required: [formed_registry_snapshot_ref]
      - if:
          properties:
            new_capability_created_by_this_decision: {const: true}
          required: [new_capability_created_by_this_decision]
        then:
          required: [governed_promotion, formation_append, formed_registry_snapshot_ref]
    additionalProperties: true
  resulting_lineage_edges:
    type: array
    minItems: 1
    items:
      type: object
      required: [type, from, to]
      additionalProperties: true
$defs:
  memory_transition:
    type: object
    required: [from, to, mechanism]
    properties:
      from: {enum: [semantic, procedural, episodic]}
      to: {enum: [semantic, procedural, episodic]}
      mechanism: {enum: [successor-ckc, source-binding-refresh, retain-as-precedent]}
    additionalProperties: false
allOf:
  - if:
      properties:
        capability_formation:
          properties:
            new_capability_created_by_this_decision: {const: false}
          required: [new_capability_created_by_this_decision]
      required: [capability_formation]
    then:
      required: [dispositions, impact_record]
      properties:
        inputs:
          required: [evidence_ref, qualification_receipt_ref, assembly_ref, registry_snapshot_ref]
  - if:
      properties:
        capability_formation:
          properties:
            new_capability_created_by_this_decision: {const: true}
          required: [new_capability_created_by_this_decision]
      required: [capability_formation]
    then:
      required: [historical_immutability]
      properties:
        status: {const: approved}
        inputs:
          required: [proposal_ref, registry_snapshot_ref, supporting_record_refs]
        capability_formation:
          properties:
            new_capability_created_by_this_decision: {const: true}
  - if:
      required: [successor_delta]
    then:
      required: [successor_append]
      properties:
        status: {const: approved}
  - if:
      required: [activation]
    then:
      required: [historical_immutability]
      properties:
        status: {const: approved}
additionalProperties: true