browser/openspec/changes/replace-scum-projections-with-real-data-management/specs/scum-gift-management/spec.md

ADDED Requirements

Requirement: Server-scoped gift package CRUD

The system SHALL provide effective-user-authorized create, read, update, enable/disable, and delete operations for gift packages and typed items scoped to one server instance and compatible plugin/game version.

Scenario: User has gift read access only

• WHEN the current session has server.game-client.read but lacks server.game-client.maintenance
• THEN package data and delivery history remain readable while create/edit/enable/delete controls are unavailable and direct mutation requests are forbidden

Scenario: Operator creates a valid package

• WHEN an operator with effective server.game-client.maintenance submits a name, classification, eligibility/limit rules, and bounded quantities of plugin-catalogued item keys
• THEN Platform stores the package and items for the target server without storing raw RCON, shell, SQL, or arbitrary command strings

Scenario: Package item is invalid

• WHEN a package contains an unknown or incompatible item key, duplicate item, out-of-range quantity, or game-version mismatch
• THEN Platform rejects the change and preserves the previous package

Scenario: Package is deleted

• WHEN an authorized operator confirms deletion of a package not protected by an active delivery
• THEN Platform removes or retires the package without deleting immutable completed delivery facts

Requirement: Plugin-owned immutable gift catalog and transport

Gift item aliases, compatibility rules, quantities, and delivery transport declarations SHALL come only from versioned digest-referenced assets in the plugin package and, where executable, the generated Run package.

Scenario: Catalog or transport digest changed

• WHEN a package or frozen delivery references a catalog/transport version or digest that no longer matches the active compatible plugin package
• THEN Platform rejects creation or dispatch and SHALL NOT translate the item into an arbitrary command or newer unreviewed alias

Requirement: Validated gift eligibility and limits

The system SHALL evaluate package eligibility and atomically reserve database-backed per-player, per-server, and configured period limits in the server's declared timezone before a delivery can dispatch.

Scenario: Player belongs to another server

• WHEN a caller attempts to deliver a package to a player record outside the package's server instance
• THEN Platform rejects the request before creating a delivery or Run job

Scenario: Period limit is reached

• WHEN a player already has the allowed number of reserved, in-progress, partial, unknown, or delivered grants in the active daily/weekly or declared period boundary
• THEN Platform rejects another delivery without relying on an in-memory count

Scenario: Concurrent eligibility requests occur

• WHEN two workers request the same limited package for the same player and period concurrently
• THEN a server-scoped uniqueness/idempotency constraint allows at most one request to reserve the remaining entitlement

Scenario: Delivery conclusively did not execute

• WHEN Run returns a conclusive failure proving that no gift effect occurred
• THEN Platform may release the reserved period entitlement transactionally; partial or unknown outcomes SHALL continue to hold it until reconciled

Requirement: Frozen and idempotent gift delivery

The system SHALL freeze the target player, package/item definitions, plugin/game version, and delivery parameters before dispatch and SHALL use a stable server-scoped delivery ID and idempotency key.

Scenario: Package changes after delivery request

• WHEN an operator edits or disables a package after a delivery has been created
• THEN the existing delivery retains its frozen target/items/version and the edit does not mutate an in-flight or completed delivery

Scenario: Same idempotency key is submitted again

• WHEN the same scoped delivery request is repeated or submitted concurrently
• THEN Platform returns the original delivery and queues no duplicate effect

Scenario: Run receives a delivery

• WHEN a user with current effective server.game-client.command confirms an eligible frozen delivery
• THEN Run receives only the plugin-declared typed item aliases/quantities and stable delivery identity, not arbitrary browser commands

Requirement: Conclusive delivery outcomes

The system SHALL record a gift as delivered only after conclusive Run execution evidence, and ambiguous or partial outcomes SHALL not trigger automatic whole-package redelivery.

Scenario: Job is queued or accepted

• WHEN Run has only claimed, acknowledged, or begun the delivery job
• THEN Platform records the delivery as in progress and SHALL NOT create a successful claim/receipt

Scenario: Delivery succeeds conclusively

• WHEN Run returns a schema-valid success receipt for every required item under the delivery idempotency key
• THEN Platform records the delivery as delivered exactly once

Scenario: Connection is lost after possible execution

• WHEN delivery may have executed but the result is missing, timed out, cancelled, or cannot be confirmed
• THEN Platform records an unknown outcome, performs confirmation before any explicit retry, and never automatically queues the entire delivery again

Scenario: Multi-item delivery is partial

• WHEN the transport cannot guarantee atomic delivery and only some item receipts are conclusive
• THEN Platform records per-item receipts and a partial/unknown package outcome and SHALL NOT label the whole package delivered or blindly redeliver confirmed items

Scenario: Notification fails after delivery

• WHEN all items are confirmed delivered but a post-delivery notification fails
• THEN Platform preserves the delivered fact, records the notification failure separately, and SHALL NOT redeliver the package

Requirement: Gift management surface and history

The gift page SHALL provide statistics, a searchable/filterable paginated package table, package create/edit/detail/delete controls, a real player selector, a reviewed send dialog, and server-scoped delivery history without Workflow terminology.

Scenario: Operator opens gift management

• WHEN local gift data is available
• THEN the page shows package totals/enabled counts/delivery statistics, package contents and limits, and compact row actions without a hard-coded starter-pack, fixed player cards, or fixed notification text

Scenario: Operator reviews delivery result

• WHEN a delivery is in progress, delivered, failed, unknown, partial, or has a notification failure
• THEN the page shows the ordinary gift-delivery result and safe reason without exposing a Workflow instance, Workflow step, raw command, or audit-initiation action