{
  "feature": "payload-document-locking",
  "version": "1.0.0",
  "description": "Automatic document locking to prevent concurrent editing with configurable lock duration and override capability",
  "category": "data",
  "tags": [
    "cms",
    "locking",
    "concurrent-editing",
    "document-lock",
    "pessimistic-locking",
    "payload"
  ],
  "actors": [
    {
      "id": "editor",
      "name": "Editor",
      "type": "human",
      "description": "User currently editing a document and holding the lock"
    },
    {
      "id": "other_user",
      "name": "Other User",
      "type": "human",
      "description": "Another user attempting to edit a locked document"
    },
    {
      "id": "lock_system",
      "name": "Lock System",
      "type": "system",
      "description": "Payload's automatic lock management system"
    }
  ],
  "fields": [
    {
      "name": "document",
      "type": "json",
      "required": true,
      "label": "Locked Document Reference"
    },
    {
      "name": "global_slug",
      "type": "text",
      "required": false,
      "label": "Locked Global Slug"
    },
    {
      "name": "user",
      "type": "json",
      "required": true,
      "label": "Lock Owner"
    }
  ],
  "rules": {
    "locking": {
      "enabled_by_default": true,
      "configurable_per_collection": true,
      "disable_option": "lockDocuments: false",
      "lock_duration": {
        "default": "5m",
        "auto_release": true
      },
      "requires_auth_collection": true,
      "auto_created_collection": "payload-locked-documents"
    },
    "access": {
      "create": "defaultAccess (must be authenticated)",
      "read": "defaultAccess",
      "update": "defaultAccess",
      "delete": "defaultAccess"
    }
  },
  "outcomes": {
    "lock_acquired": {
      "priority": 10,
      "given": [
        "user opens a document for editing",
        "document is not currently locked by another user"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "document_lock",
          "target": "payload-locked-documents",
          "description": "Lock record created with document reference and user"
        }
      ],
      "result": "Document locked — other users see it as being edited"
    },
    "lock_conflict": {
      "priority": 3,
      "error": "DOCUMENT_LOCKED",
      "given": [
        "user attempts to edit a document",
        "document is locked by another user",
        "lock has not expired"
      ],
      "result": "User informed document is being edited by another user"
    },
    "lock_override": {
      "priority": 5,
      "given": [
        "user has appropriate permissions",
        "overrideLock flag is set on the operation"
      ],
      "then": [
        "existing lock removed",
        "operation proceeds as normal"
      ],
      "result": "Lock overridden, operation completed"
    },
    "lock_expired": {
      "priority": 4,
      "given": [
        "document has a lock record",
        "lock duration has exceeded the configured maximum"
      ],
      "then": [
        "lock treated as released"
      ],
      "result": "Document available for editing by any user"
    },
    "lock_released": {
      "priority": 10,
      "given": [
        "user finishes editing (navigates away or explicitly releases)"
      ],
      "then": [
        {
          "action": "delete_record",
          "type": "document_lock",
          "target": "payload-locked-documents",
          "description": "Lock record removed"
        }
      ],
      "result": "Document unlocked and available for others"
    },
    "lock_on_delete": {
      "priority": 10,
      "given": [
        "document is being deleted"
      ],
      "then": [
        "associated lock record removed"
      ],
      "result": "Lock cleaned up with document deletion"
    },
    "lock_status_check": {
      "priority": 10,
      "given": [
        "includeLockStatus flag set on findByID operation"
      ],
      "result": "Lock status returned alongside document data — includes who locked it and when"
    }
  },
  "errors": [
    {
      "code": "DOCUMENT_LOCKED",
      "status": 423,
      "message": "This document is currently being edited by another user",
      "retry": true
    }
  ],
  "events": [
    {
      "name": "document.locked",
      "payload": [
        "collection_slug",
        "document_id",
        "user_id",
        "timestamp"
      ],
      "description": "Emitted when a document is locked for editing"
    },
    {
      "name": "document.unlocked",
      "payload": [
        "collection_slug",
        "document_id",
        "user_id",
        "timestamp"
      ],
      "description": "Emitted when a document lock is released"
    }
  ],
  "related": [
    {
      "feature": "payload-collections",
      "type": "required",
      "reason": "Locking applies to collection documents"
    },
    {
      "feature": "payload-globals",
      "type": "optional",
      "reason": "Globals also support document locking"
    },
    {
      "feature": "payload-auth",
      "type": "required",
      "reason": "Lock requires authenticated user to track lock ownership"
    },
    {
      "feature": "payload-access-control",
      "type": "required",
      "reason": "Lock override requires appropriate permissions"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_payload_document_locking",
        "description": "Automatic document locking to prevent concurrent editing with configurable lock duration and override capability",
        "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 permanently deleting records"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "lock_acquired",
          "permission": "autonomous"
        },
        {
          "action": "lock_conflict",
          "permission": "autonomous"
        },
        {
          "action": "lock_override",
          "permission": "supervised"
        },
        {
          "action": "lock_expired",
          "permission": "autonomous"
        },
        {
          "action": "lock_released",
          "permission": "autonomous"
        },
        {
          "action": "lock_on_delete",
          "permission": "human_required"
        },
        {
          "action": "lock_status_check",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "payload_collections",
          "from": "payload-collections",
          "fallback": "degrade"
        },
        {
          "capability": "payload_auth",
          "from": "payload-auth",
          "fallback": "degrade"
        },
        {
          "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)"
    },
    "auto_created_entities": [
      {
        "name": "payload-locked-documents",
        "type": "collection",
        "description": "Hidden system collection storing active document locks",
        "hidden": true
      }
    ]
  }
}