Skip to content

Product Mutation Intents

Objective

Define the human input patterns that should result in product-domain mutations, and the checks that should be applied before executing them through BFF.

Supported Mutation Classes

The current mutation scope includes:

  • create property
  • update property
  • delete property
  • create product
  • update product
  • delete product
  • create product collection
  • update product collection
  • delete product collection
  • set product collection membership

Human Input Pattern

The mutation layer should accept requests such as:

  • add a property definition Rack Pillar Type A
  • add item Racking System Package A to C&I System 30/60
  • update Racking System Package A BoP to include Pillar Type A

These are human operation intents. They must be translated into validated BFF mutations rather than treated as literal command strings.

Mutation Resolution Rule

The assistant should resolve a mutation request in this order:

  1. identify the target object
  2. property
  3. product
  4. product collection
  5. item or BoP line within a product
  6. identify the intended operation
  7. create
  8. update
  9. delete
  10. assign to collection
  11. update BoP/BoM structure
  12. retrieve current state if the request depends on existing objects
  13. run consistency and safety checks
  14. execute the smallest mutation set required
  15. re-read affected objects and report the resulting state

Safety and Consistency Checks

Before mutation, the assistant should check:

  • whether the target object already exists under a matching or near-matching name
  • whether the requested property vocabulary conflicts with an existing property
  • whether the referenced product exists
  • whether the referenced collection exists
  • whether a requested BoP change is structurally valid for the target product
  • whether the mutation should be blocked for ambiguity and clarified first

Current BFF Mutation Endpoints

Properties

  • createProperty(input)
  • updateProperty(propertyKey, input)
  • deleteProperty(propertyKey)

Products

  • createProduct(input)
  • updateProduct(productKey, input)
  • deleteProduct(productKey)

Product Collections

  • createProductCollection(input)
  • updateProductCollection(collectionKey, input)
  • deleteProductCollection(collectionKey)
  • setProductCollections(productKey, collectionKeys)

Example Mutation Flows

Add a Property Definition

Human request:

  • add a property definition Rack Pillar Type A

Expected assistant behavior:

  1. search existing properties for close matches
  2. confirm no conflicting property already exists
  3. call createProperty
  4. re-read the created property

Add an Item to a Product

Human request:

  • add item Racking System Package A to C&I System 30/60

Expected assistant behavior:

  1. resolve the target product
  2. resolve whether Racking System Package A is a new product, a sub-item, or a BoP line
  3. inspect current product structure
  4. apply the appropriate mutation path
  5. re-read the resulting product

Update BoP to Include a Property

Human request:

  • update Racking System Package A BoP to include Pillar Type A

Expected assistant behavior:

  1. resolve the product
  2. resolve Pillar Type A to the intended property definition
  3. verify that the product structure supports the requested BoP change
  4. apply the mutation
  5. re-read and report the changed BoP state

Near-Term Gap

Some item-level and BoP-level operations may require a richer mutation contract than the currently verified product/property endpoints expose.

This document should therefore guide the assistant to:

  • use currently available product/property mutations where possible
  • identify when a requested write operation exceeds the current BFF contract
  • stop short of unsafe inference when the write path is not yet explicit