{
  "feature": "payload-globals",
  "version": "1.0.0",
  "description": "Singleton document management for site-wide settings, navigation, headers, and footers with versioning and access control",
  "category": "data",
  "tags": [
    "cms",
    "globals",
    "singleton",
    "settings",
    "configuration",
    "site-wide",
    "payload"
  ],
  "actors": [
    {
      "id": "admin",
      "name": "Admin",
      "type": "human",
      "description": "Administrator managing global settings"
    },
    {
      "id": "api_client",
      "name": "API Client",
      "type": "system",
      "description": "REST or GraphQL client reading global data"
    }
  ],
  "fields": [
    {
      "name": "slug",
      "type": "text",
      "required": true,
      "label": "Global Slug",
      "validation": [
        {
          "type": "required",
          "message": "Global slug is required"
        },
        {
          "type": "pattern",
          "value": "^[a-z][a-z0-9-]*$",
          "message": "Slug must be kebab-case"
        }
      ]
    },
    {
      "name": "created_at",
      "type": "datetime",
      "required": true,
      "immutable": true,
      "label": "Created At"
    },
    {
      "name": "updated_at",
      "type": "datetime",
      "required": true,
      "label": "Updated At"
    }
  ],
  "rules": {
    "data": {
      "singleton_pattern": true,
      "no_id_field": true,
      "hooks_supported": [
        "beforeOperation",
        "beforeRead",
        "afterRead",
        "beforeValidate",
        "beforeChange",
        "afterChange"
      ],
      "versioning_supported": true,
      "localization_supported": true
    },
    "access": {
      "operations": [
        "read",
        "update",
        "readVersions"
      ]
    }
  },
  "outcomes": {
    "find_global": {
      "priority": 10,
      "given": [
        "user has read access for this global"
      ],
      "then": [
        "beforeOperation hooks execute",
        "document retrieved from database",
        "afterRead hooks execute",
        "draft replaced if available and requested"
      ],
      "result": "Single global document returned with populated relationships"
    },
    "update_global": {
      "priority": 10,
      "given": [
        "user has update access for this global",
        "data passes field validation",
        "document is not locked by another user"
      ],
      "then": [
        "beforeValidate hooks execute",
        "beforeChange hooks execute",
        "document updated in database",
        "version created if versioning enabled",
        "afterChange hooks execute"
      ],
      "result": "Updated global document returned",
      "transaction": true
    },
    "find_global_versions": {
      "priority": 10,
      "given": [
        "user has readVersions access",
        "versioning is enabled for this global"
      ],
      "result": "Paginated list of version history"
    },
    "restore_global_version": {
      "priority": 10,
      "given": [
        "user has update access",
        "versioning is enabled",
        "version ID exists"
      ],
      "then": [
        "global restored to specified version state",
        "new version created recording the restore"
      ],
      "result": "Global restored to previous version",
      "transaction": true
    },
    "global_doc_access": {
      "priority": 10,
      "given": [
        "user is authenticated"
      ],
      "result": "Returns permission object with read/update/readVersions booleans and field-level access"
    }
  },
  "errors": [
    {
      "code": "GLOBAL_FORBIDDEN",
      "status": 403,
      "message": "You are not allowed to access this global",
      "retry": false
    },
    {
      "code": "GLOBAL_VALIDATION_ERROR",
      "status": 400,
      "message": "The data provided did not pass validation",
      "retry": true
    },
    {
      "code": "GLOBAL_DUPLICATE",
      "status": 500,
      "message": "A global with this slug already exists",
      "retry": false
    }
  ],
  "events": [
    {
      "name": "global.update",
      "payload": [
        "global_slug",
        "user_id",
        "timestamp"
      ],
      "description": "Emitted after a global document is updated"
    },
    {
      "name": "global.read",
      "payload": [
        "global_slug",
        "user_id"
      ],
      "description": "Emitted on global read — triggers afterRead hooks"
    }
  ],
  "related": [
    {
      "feature": "payload-collections",
      "type": "optional",
      "reason": "Globals complement collections — collections for multiple docs, globals for singletons"
    },
    {
      "feature": "payload-access-control",
      "type": "required",
      "reason": "Globals have their own access control configuration"
    },
    {
      "feature": "payload-versions",
      "type": "optional",
      "reason": "Globals support the same versioning system as collections"
    },
    {
      "feature": "payload-document-locking",
      "type": "optional",
      "reason": "Globals support document locking"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_payload_globals",
        "description": "Singleton document management for site-wide settings, navigation, headers, and footers with versioning and access control",
        "success_metrics": [
          {
            "metric": "data_accuracy",
            "target": "100%",
            "measurement": "Records matching source of truth"
          },
          {
            "metric": "duplicate_rate",
            "target": "0%",
            "measurement": "Duplicate records detected post-creation"
          }
        ],
        "constraints": [
          {
            "type": "performance",
            "description": "Data consistency must be maintained across concurrent operations",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "find_global",
          "permission": "autonomous"
        },
        {
          "action": "update_global",
          "permission": "supervised"
        },
        {
          "action": "find_global_versions",
          "permission": "autonomous"
        },
        {
          "action": "restore_global_version",
          "permission": "autonomous"
        },
        {
          "action": "global_doc_access",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "payload_access_control",
          "from": "payload-access-control",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "tech_stack": {
      "language": "TypeScript",
      "framework": "Payload CMS 3.x",
      "database": "Multi-adapter (MongoDB, PostgreSQL, SQLite, D1)"
    },
    "rest_endpoints": [
      {
        "method": "GET",
        "path": "/api/globals/{slug}",
        "operation": "findOne"
      },
      {
        "method": "POST",
        "path": "/api/globals/{slug}",
        "operation": "update"
      },
      {
        "method": "GET",
        "path": "/api/globals/{slug}/versions",
        "operation": "findVersions"
      },
      {
        "method": "GET",
        "path": "/api/globals/{slug}/versions/:id",
        "operation": "findVersionByID"
      },
      {
        "method": "POST",
        "path": "/api/globals/{slug}/versions/:id",
        "operation": "restoreVersion"
      },
      {
        "method": "POST",
        "path": "/api/globals/{slug}/access",
        "operation": "docAccess"
      }
    ]
  }
}