Item Mutation Qualifiers

Item mutations in the Arda system accept an operation qualifier that determines how supply source information is interpreted when creating or updating items and their associated supply entities. The three qualifier modes — LAX, STRICT, and PROPAGATE — represent different points on a spectrum from flexibility to strictness to deep persistence.

Why Qualifiers Are Needed

An Item entity holds references to its supply sources through ItemSupplyReference value objects (see Items). These references may point to persistent ItemSupply entities (linked by supplyEId) or represent ad hoc supply information (unlinked). Different workflows need different behaviors when handling this relationship:

• Importing data (CSV, script): Supply information may be partial or the supply entity identity may be authoritative — need maximum flexibility.
• UI editing: A user selecting a vendor from a list expects the system to verify that what they see still matches the current database state before committing.
• Deep editing: A user editing an item and its supply details simultaneously expects changes to cascade automatically.

LAX Mode — Flexibility and Idempotency

Intent: Prioritize completing the operation over strict data validation. Accept partial or incomplete supply information.

Validation behavior:

• Performs partial consistency checks: if fields like supplier name or SKU are provided in a supply reference, they must match the existing database record for that supply ID.
• Allows creating items with missing supply references or partial data.

Supply entity handling:

• Acts as an upsert for ItemSupply entities: if the supply exists, update it; if not, create it.
• Auto-populates supplyEId from a name match when an ItemSupply with the same name already exists.

Use cases: Automated scripts, CSV imports, “Add/Edit” forms where data might be partial.

LAX is not fully permissive. It will fail if supplier or SKU values are provided but don’t match the matched ItemSupply.

STRICT Mode — Verify Before Linking

Intent: Ensure data integrity by verifying that the user’s view of the data matches the system’s current state before allowing a link.

Validation behavior:

• If a supplyEId is provided, the referenced ItemSupply must exist in the database.
• All provided field values (name, supplier, etc.) must exactly match the values currently stored in the database for that supply entity.
• If there is any drift between what the user provided and what the database contains, the operation fails.

Supply entity handling:

• Does not implicitly update supply entities.
• During item creation: creates ItemSupply entities atomically (because no supply can exist before its parent item; this is the one case where STRICT behaves like PROPAGATE).
• During item updates: only links to existing, verified supply entities.

Use cases: UI operations where a user selects a supply from a list, ensuring they are not linking to a record that has changed since the page loaded.

STRICT validates external references (vendors) strictly but allows implicit creation of owned entities (supplies) where they don’t yet exist.

PROPAGATE Mode — Deep Persistence

Intent: Treat the payload as the master definition of the complete object graph. Cascade changes through the entity graph automatically.

Validation behavior:

• Relaxed — like LAX, skips the strict consistency check on the assumption that differences are intentional updates.

Supply entity handling:

• If a supply is defined in the payload without an ID, the service creates a new ItemSupply entity automatically.
• If a supply ID is provided but field values differ from the database, the service updates the ItemSupply entity to match the payload.

Use cases: Complex editors where a user edits an item and its supply details simultaneously; import scenarios where the goal is complete database synchronization with an external dataset.

Summary

Qualifier	Validation	Auto-Create Supplies	Supply Backfill	Typical Use
LAX	Partial (supplier/SKU match)	Yes (upsert)	Yes	Scripts, imports
STRICT	Verify all provided fields match DB	Yes (on item creation only)	Yes	UI linking
PROPAGATE	Minimal	Yes (always)	No	Deep editing, sync

Default Behavior for Unknown Qualifiers

When an unknown or unrecognized qualifier value is provided, the system defaults to PROPAGATE rather than rejecting the operation. This provides graceful degradation in cases of version mismatches or misconfiguration.

STRICT Consistency Check Scoping

STRICT mode consistency checks for supply entities are scoped to the parent item’s Universe. An ItemSupply lookup by supplyEId will return NotFound if the supply belongs to a different parent item, even if the UUID exists in the system. This prevents cross-item data corruption.

Excluded from this document: Detailed per-operation behavioral tables (e.g., the case-by-case tables for Create/Update operations in different states) belong in the Current System implementation documentation alongside the service code.