{
  "feature": "set-operations",
  "version": "1.0.0",
  "description": "Unordered collection of unique elements with set algebra operations (union, intersection, difference) and cardinality counting",
  "category": "data",
  "tags": [
    "sets",
    "unordered-collections",
    "set-algebra",
    "cardinality"
  ],
  "actors": [
    {
      "id": "client",
      "name": "Client",
      "type": "human",
      "description": "Application requesting set operations"
    }
  ],
  "fields": [
    {
      "name": "key",
      "type": "text",
      "required": true,
      "label": "Key"
    },
    {
      "name": "members",
      "type": "json",
      "required": false,
      "label": "Members"
    },
    {
      "name": "cardinality",
      "type": "number",
      "required": false,
      "label": "Cardinality"
    },
    {
      "name": "destination_key",
      "type": "text",
      "required": false,
      "label": "Destination Key"
    }
  ],
  "rules": {
    "general": [
      "Set elements are unique; adding duplicate element replaces (no effect on cardinality)",
      "Set membership is unordered (no indices or ranges)",
      "Set algebra operations (intersection, union, difference) can accept multiple source sets",
      "Intersection of multiple sets returns elements present in ALL sets",
      "Union of multiple sets returns elements present in ANY set",
      "Difference of first set minus others returns elements in first but not in any other",
      "Store variants (*STORE) create destination set atomically; overwrite if exists",
      "All operations are atomic with respect to individual keys"
    ]
  },
  "states": {
    "field": "presence",
    "values": [
      {
        "name": "absent",
        "initial": true,
        "description": "Key does not exist"
      },
      {
        "name": "present",
        "description": "Set exists with one or more members"
      },
      {
        "name": "empty",
        "terminal": true,
        "description": "Set becomes empty (key auto-deleted)"
      }
    ]
  },
  "outcomes": {
    "add_members": {
      "priority": 10,
      "description": "Add one or more elements to set",
      "given": [
        "SADD key member [member ...]",
        {
          "field": "members_to_add",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "members",
          "description": "add new members (duplicates ignored)"
        },
        {
          "action": "set_field",
          "target": "cardinality",
          "description": "increment by count of new members"
        },
        {
          "action": "emit_event",
          "event": "set.added",
          "payload": [
            "key",
            "new_members_count",
            "total_cardinality"
          ]
        }
      ],
      "result": "set created if absent; members added; client receives count of newly added members"
    },
    "remove_members": {
      "priority": 11,
      "description": "Remove elements from set",
      "given": [
        "SREM key member [member ...]",
        {
          "field": "members_to_remove",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "members",
          "description": "remove specified members"
        },
        {
          "action": "set_field",
          "target": "cardinality",
          "description": "decrement by count of removed members"
        },
        {
          "action": "emit_event",
          "event": "set.removed",
          "payload": [
            "key",
            "removed_count",
            "remaining_cardinality"
          ]
        }
      ],
      "result": "members removed; client receives count of removed members; set deleted if empty"
    },
    "get_all_members": {
      "priority": 20,
      "description": "Retrieve all set members",
      "given": [
        "SMEMBERS key"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.members_read",
          "payload": [
            "key",
            "cardinality"
          ]
        }
      ],
      "result": "unordered array of all members (empty if set absent)"
    },
    "check_membership": {
      "priority": 21,
      "description": "Check if element is member",
      "given": [
        "SISMEMBER key member",
        {
          "field": "member",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.ismember_check",
          "payload": [
            "key",
            "member",
            "is_member"
          ]
        }
      ],
      "result": "1 if member present, 0 if not"
    },
    "check_multiple_membership": {
      "priority": 22,
      "description": "Check multiple elements at once",
      "given": [
        "SMISMEMBER key member [member ...]",
        {
          "field": "members_to_check",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.mismember_check",
          "payload": [
            "key",
            "members_count",
            "matches_count"
          ]
        }
      ],
      "result": "array of 0/1 for each member (1=member present, 0=absent)"
    },
    "get_cardinality": {
      "priority": 23,
      "description": "Get set size",
      "given": [
        "SCARD key"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.cardinality",
          "payload": [
            "key",
            "cardinality"
          ]
        }
      ],
      "result": "number of members (0 if key absent)"
    },
    "random_members": {
      "priority": 24,
      "description": "Return random element(s) from set",
      "given": [
        "SRANDMEMBER key [count]",
        {
          "field": "count",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.random_draw",
          "payload": [
            "key",
            "count_returned"
          ]
        }
      ],
      "result": "single member or array of members (may have duplicates if count > cardinality)"
    },
    "pop_random": {
      "priority": 25,
      "description": "Remove and return random element(s)",
      "given": [
        "SPOP key [count]",
        {
          "field": "count",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "members",
          "description": "remove random members"
        },
        {
          "action": "set_field",
          "target": "cardinality",
          "description": "decrement by count removed"
        },
        {
          "action": "emit_event",
          "event": "set.popped",
          "payload": [
            "key",
            "count_popped",
            "remaining_cardinality"
          ]
        }
      ],
      "result": "single member or array of members removed (no duplicates); nil if empty"
    },
    "move_between_sets": {
      "priority": 26,
      "description": "Move element from source to destination set",
      "given": [
        "SMOVE source destination member",
        {
          "field": "member_in_source",
          "source": "db",
          "operator": "eq",
          "value": true
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "source.members",
          "description": "remove from source"
        },
        {
          "action": "set_field",
          "target": "destination.members",
          "description": "add to destination"
        },
        {
          "action": "emit_event",
          "event": "set.moved",
          "payload": [
            "source",
            "destination",
            "member"
          ]
        }
      ],
      "result": "member moved; client receives 1 (or 0 if already in destination)"
    },
    "intersection": {
      "priority": 30,
      "description": "Get elements common to all input sets",
      "given": [
        "SINTER key [key ...]",
        {
          "field": "input_sets",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.intersection",
          "payload": [
            "keys_input",
            "result_cardinality"
          ]
        }
      ],
      "result": "array of elements in ALL sets (empty if no common elements)"
    },
    "intersection_store": {
      "priority": 31,
      "description": "Store intersection result",
      "given": [
        "SINTERSTORE destination key [key ...]",
        {
          "field": "destination",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "set_field",
          "target": "destination.members",
          "description": "set to intersection result"
        },
        {
          "action": "emit_event",
          "event": "set.intersection_stored",
          "payload": [
            "destination",
            "result_cardinality"
          ]
        }
      ],
      "result": "destination set created/overwritten; client receives cardinality of result"
    },
    "intersection_cardinality": {
      "priority": 32,
      "description": "Get count of common elements without returning them",
      "given": [
        "SINTERCARD numkeys key [key ...] [LIMIT limit]",
        {
          "field": "limit",
          "source": "input",
          "operator": "exists"
        }
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.intercard",
          "payload": [
            "keys_input",
            "cardinality_result"
          ]
        }
      ],
      "result": "cardinality of intersection (limited by LIMIT if provided)"
    },
    "union": {
      "priority": 33,
      "description": "Get all elements from any input set",
      "given": [
        "SUNION key [key ...]"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.union",
          "payload": [
            "keys_input",
            "result_cardinality"
          ]
        }
      ],
      "result": "array of unique elements across all sets"
    },
    "union_store": {
      "priority": 34,
      "description": "Store union result",
      "given": [
        "SUNIONSTORE destination key [key ...]"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "destination.members",
          "description": "set to union result"
        },
        {
          "action": "emit_event",
          "event": "set.union_stored",
          "payload": [
            "destination",
            "result_cardinality"
          ]
        }
      ],
      "result": "destination set created/overwritten; client receives cardinality"
    },
    "difference": {
      "priority": 35,
      "description": "Get elements in first set but not in others",
      "given": [
        "SDIFF key [key ...]",
        "first_key: set to subtract from",
        "other_keys: sets to subtract"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.difference",
          "payload": [
            "first_key",
            "other_keys",
            "result_cardinality"
          ]
        }
      ],
      "result": "array of elements in first set minus all others"
    },
    "difference_store": {
      "priority": 36,
      "description": "Store difference result",
      "given": [
        "SDIFFSTORE destination key [key ...]"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "destination.members",
          "description": "set to difference result"
        },
        {
          "action": "emit_event",
          "event": "set.difference_stored",
          "payload": [
            "destination",
            "result_cardinality"
          ]
        }
      ],
      "result": "destination set created/overwritten; client receives cardinality"
    },
    "scan_members": {
      "priority": 40,
      "description": "Iterate members with cursor (safe for large sets)",
      "given": [
        "SSCAN key cursor [MATCH pattern] [COUNT count]",
        "cursor: starting cursor position (0 to start)"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "set.scan",
          "payload": [
            "key",
            "cursor",
            "pattern",
            "count_returned"
          ]
        }
      ],
      "result": "array [new_cursor, [members...]] (cursor=0 when full scan complete)"
    }
  },
  "errors": [
    {
      "code": "WRONG_TYPE",
      "message": "Operation against a key holding the wrong kind of value",
      "status": 400
    }
  ],
  "events": [
    {
      "name": "set.added",
      "payload": []
    },
    {
      "name": "set.removed",
      "payload": []
    },
    {
      "name": "set.members_read",
      "payload": []
    },
    {
      "name": "set.ismember_check",
      "payload": []
    },
    {
      "name": "set.mismember_check",
      "payload": []
    },
    {
      "name": "set.cardinality",
      "payload": []
    },
    {
      "name": "set.random_draw",
      "payload": []
    },
    {
      "name": "set.popped",
      "payload": []
    },
    {
      "name": "set.moved",
      "payload": []
    },
    {
      "name": "set.intersection",
      "payload": []
    },
    {
      "name": "set.intersection_stored",
      "payload": []
    },
    {
      "name": "set.intercard",
      "payload": []
    },
    {
      "name": "set.union",
      "payload": []
    },
    {
      "name": "set.union_stored",
      "payload": []
    },
    {
      "name": "set.difference",
      "payload": []
    },
    {
      "name": "set.difference_stored",
      "payload": []
    },
    {
      "name": "set.scan",
      "payload": []
    }
  ],
  "related": [
    {
      "feature": "string-key-value",
      "type": "optional",
      "reason": "Elements are strings or numeric values"
    },
    {
      "feature": "sorted-set-operations",
      "type": "optional",
      "reason": "Sorted sets extend sets with scoring"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_set_operations",
        "description": "Unordered collection of unique elements with set algebra operations (union, intersection, difference) and cardinality counting",
        "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 transitioning to a terminal state",
        "before permanently deleting records"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "add_members",
          "permission": "autonomous"
        },
        {
          "action": "remove_members",
          "permission": "human_required"
        },
        {
          "action": "get_all_members",
          "permission": "autonomous"
        },
        {
          "action": "check_membership",
          "permission": "autonomous"
        },
        {
          "action": "check_multiple_membership",
          "permission": "autonomous"
        },
        {
          "action": "get_cardinality",
          "permission": "autonomous"
        },
        {
          "action": "random_members",
          "permission": "autonomous"
        },
        {
          "action": "pop_random",
          "permission": "autonomous"
        },
        {
          "action": "move_between_sets",
          "permission": "autonomous"
        },
        {
          "action": "intersection",
          "permission": "autonomous"
        },
        {
          "action": "intersection_store",
          "permission": "autonomous"
        },
        {
          "action": "intersection_cardinality",
          "permission": "autonomous"
        },
        {
          "action": "union",
          "permission": "autonomous"
        },
        {
          "action": "union_store",
          "permission": "autonomous"
        },
        {
          "action": "difference",
          "permission": "autonomous"
        },
        {
          "action": "difference_store",
          "permission": "autonomous"
        },
        {
          "action": "scan_members",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "data_integrity",
        "over": "performance",
        "reason": "data consistency must be maintained across all operations"
      }
    ]
  },
  "extensions": {
    "source": {
      "repo": "https://github.com/redis/redis",
      "project": "Redis",
      "tech_stack": "C",
      "files_traced": 1,
      "entry_points": [
        "src/t_set.c"
      ]
    }
  }
}