Crafting is a transaction, not a second economy

699. Lesson identity

Module

2.5 — Inventory, equipment, and crafting

Lesson

Crafting is a transaction, not a second economy

Academic type

Integration

Schema type

Practical

Order

Lesson 3

Estimated time

35–45 minutes

700. Learning objective

After this lesson, you can specify one crafting transaction by classifying recipe data, inventory inputs, economy-owned non-item costs, outputs, progression preconditions, atomic commit behavior, rollback behavior, and failure evidence.

701. Why this matters

Crafting joins inventory, economy, progression, and presentation without replacing any of them. A transaction that consumes item inputs but forgets an economy-owned cost, accepts invalid recipe data, or fails halfway through can leave the game state inconsistent. Explicit preflight validation and atomic commit behavior establish a reliable implementation boundary. They also give you a concrete specification against which AI-generated designs or code can be inspected.

702. Prior knowledge

Inventory owns item possession and quantities. Equipment owns active slot selection and changes capability through an explicit contract. Crafting must use those authorities rather than copying their state. Use the stage model input → rule → presentation → visible response to explain how a crafting request becomes observable.

703. Core concept

Crafting is a bounded transaction over existing authorities. A recipe declares item inputs, economy-owned non-item costs, outputs, and preconditions. The crafting operation validates the complete declaration and all player requirements before any authoritative mutation.

• Inventory owns item quantities.
• Economy owns non-item balances such as currency.
• Progression owns recipe availability.
• Equipment owns active slot selections.
• Crafting coordinates validation, commit, rollback, and result classification.
• Presentation renders the returned result without deciding whether crafting succeeded.

An authoritative crafting result may later be supplied as mission evidence, but the mission system still owns the predicates that determine whether that evidence satisfies a mission condition.

A safe flow is:

craft request + recipe
→ validate recipe data and every precondition
→ prepare the complete inventory and economy change set
→ commit all changes together
→ report one authoritative result

Invalid recipe data and insufficient resources are validation failures. They must produce no mutation. If every mutation cannot be guaranteed to succeed together, use one atomic command at the authoritative boundary, or reservations/version checks and a defined commit protocol. Recording a snapshot to restore later is not interchangeable with atomic commit. Compensation may restore this transaction’s mutations, but it must not overwrite a concurrent legitimate write. An output must not remain after its costs are restored unless a later competing write already replaced that state.

704. Authority map

A recipe is invalid when its declaration cannot describe a safe operation. Examples include a missing recipe ID, a non-positive quantity, an unknown item or economy key, conflicting duplicate entries, or a missing output quantity. Invalid data is not the same as insufficient player resources. Both fail before mutation, but each requires a distinct result.

705. Mental model

Use DECLARE → VALIDATE → PREPARE → COMMIT → REPORT:

706. Hypothetical specification example

Consider this illustrative recipe specification:

Recipe: field_repair_kit
Inputs:
  scrap: 3
  fiber: 1
Non-item cost:
  credits: 10
Output:
  repair_kit: 1
Precondition:
  recipe is unlocked

Assume the inventory has 5 scrap, 1 fiber, and room for one output; economy has 25 credits; and progression reports that the recipe is unlocked. The prepared change set is:

inventory: scrap -3, fiber -1, repair_kit +1
economy: credits -10
result: SUCCESS

The expected post-state is 2 scrap, 0 fiber, 1 repair_kit, and 15 credits. Crafting coordinates the changes but does not create another credit balance.

If only 2 scrap are available, validation returns INSUFFICIENT_ITEM before mutation. If only 7 credits are available, it returns INSUFFICIENT_ECONOMY_COST; inventory and economy remain unchanged. A negative cost, unknown item, or missing output quantity returns INVALID_RECIPE_DATA and leaves player state unchanged.

If item inputs are removed and a later economy mutation fails, the transaction must restore the item quantities and leave the output absent. If the output was already granted, rollback must remove it as well. Compensation may restore this transaction’s mutations, but exact equality with the pre-transaction state is required only when the storage boundary is truly atomic and no concurrent legitimate write occurred.

707. AI-native workflow

Use AI to expose and test the transaction boundary, not to choose hidden authorities.

1. Write the recipe, authority map, invariants, and result codes before requesting implementation code.
2. Ask the AI to classify every read and mutation as recipe, inventory, economy, progression, crafting, equipment, presentation, or mission work.
3. Require validation of recipe data, item quantities, non-item costs, unlock state, and output capacity before mutation.
4. Require a prepared change set or transaction design that commits inventory and economy changes together.
5. Require a rollback path that restores every applied input, cost, and output mutation.
6. Request tests for success, insufficient items, insufficient non-item cost, invalid data, locked recipe, output-capacity failure, repeated requests, and forced commit failure.
7. Inspect the result for duplicate balances, partial consumption, output-before-cost behavior, equipment changes without an explicit rule, or presentation logic that independently decides success.

A useful prompt is:

Specify one crafting transaction for field_repair_kit. It consumes 3 scrap, 1 fiber, and 10 economy-owned credits, requires the recipe to be unlocked, and produces 1 repair_kit. Validate recipe data, resources, unlock state, and output capacity before mutation. Commit inventory and economy changes with one atomic command, or with reservations/version checks and a defined commit protocol. If any commit step fails, compensate this transaction’s mutations unless storage is truly atomic; do not overwrite a concurrent legitimate write. Return distinct results for invalid recipe data, insufficient items, insufficient credits, locked recipe, capacity failure, rolled-back commit, and success. Show the authority map, change set, and invariant tests before implementation.

708. Common mistake

A common mistake is treating validation as a sequence of mutations: remove one input, discover that another input or currency is missing, and then return failure with damaged state. Another mistake is validating only inventory and allowing the economy cost to fail later. Invalid recipe data may also be misclassified as a player shortage, hiding a configuration defect.

Validate the recipe and every precondition first. Prepare the entire change set. Commit item and non-item changes together. If the commit cannot complete, compensate this transaction’s mutations unless storage is truly atomic; do not overwrite a concurrent legitimate write. Exact equality with the pre-transaction state is required only at a truly atomic boundary with no concurrent legitimate write.

709. Guided practice

Complete the attached practical assessment by producing one crafting transaction specification and test matrix.

Step 1: Declare and classify the recipe

Record:

• recipe ID;
• input item IDs and positive quantities;
• any non-item cost, its owning authority, and its quantity;
• output IDs and quantities;
• progression precondition;
• output-capacity policy.

Add at least two invalid-data cases. Do not introduce a crafting-only currency or duplicate an inventory quantity.

Step 2: Write the authority map and invariants

Identify the authority for recipe data, item quantities, non-item balances, progression availability, equipment selection, transaction coordination, presentation, and any downstream mission predicate. Include these invariants:

• invalid recipe data changes no player state;
• insufficient items or non-item costs change neither inventory nor economy;
• a locked recipe cannot be crafted merely because resources are sufficient;
• success consumes and grants exactly the declared quantities;
• inventory and economy commit together atomically, or this transaction’s mutations are compensated with a conflict-safe protocol that can fail and must not overwrite a concurrent legitimate write;
• equipment changes only through a separate explicit rule;
• presentation reports the result instead of recalculating it;
• mission logic may receive the result as evidence but owns its own predicates.

Step 3: Define the result contract

Specify distinct results for SUCCESS, INVALID_RECIPE_DATA, INSUFFICIENT_ITEM, INSUFFICIENT_ECONOMY_COST, RECIPE_LOCKED, OUTPUT_CAPACITY_FAILURE, and COMMIT_ROLLED_BACK, or precise equivalents. For each result, state the expected inventory and economy post-state.

Step 4: Build the test matrix

Cover:

1. all requirements satisfied;
2. one required item missing;
3. non-item cost missing;
4. invalid recipe data;
5. sufficient resources but locked recipe;
6. output-capacity failure;
7. forced commit failure after one mutation;
8. repeated request after success;
9. a concurrent or intervening change after preflight validation and before commit, which must yield a conflict or retry and must not lose the intervening update.

For every row, record the pre-state, action, expected result, expected post-state, and observable evidence. The forced-failure row must show compensation of this transaction’s mutations unless storage is truly atomic, and must not claim exact restoration after a concurrent legitimate write.

Step 5: Make one implementation decision

Choose one atomic command at the authoritative boundary, or reservations/version checks plus a defined commit protocol. A generic transactional API is acceptable only if it provides that atomicity; recording a snapshot to restore later is not interchangeable. Do not treat a snapshot restored after the fact as interchangeable with atomic commit. Snapshot restoration can overwrite concurrent legitimate changes; rollback itself can fail; and capacity or affordability checked during preflight can become stale before commit. If inventory and economy remain separate authorities, require reservation or version checks and a defined commit protocol. Describe post-failure restoration as compensation unless the storage boundary truly provides atomicity. Include one test in which state changes between validation and commit: the required result is a conflict or retry, with no lost update. Explain how the design coordinates inventory and economy without duplicating either authority. State where output capacity is enforced and how the policy prevents lost inputs or duplicated outputs.

710. Validation and evidence

The assessment is complete when it contains:

• one explicit recipe declaration;
• at least two invalid-data examples;
• an authority map covering all participating systems;
• validation before mutation;
• distinct result codes;
• a success test applying exactly the declared changes;
• no-mutation tests for each validation failure;
• an atomic commit rule;
• a forced-failure compensation test that restores this transaction’s mutations unless storage is truly atomic, and an intervening-change test with conflict or retry and no lost update;
• an output-capacity policy and test;
• no duplicate item or currency authority;
• a statement separating authoritative crafting evidence from mission-owned predicates.

711. Key takeaways

• Crafting coordinates existing authorities; it does not create a second economy.
• Validate recipe data, resources, progression, and capacity before mutation.
• Inventory and economy changes must commit together atomically, or follow a reservation/version/commit protocol whose compensation does not overwrite concurrent legitimate writes.
• Invalid data, insufficient resources, and commit failure require distinct results and evidence.
• Presentation reports the authoritative result without recalculating it.
• A mission may consume that result as evidence, but the mission system owns mission predicates.

712. Next lesson

Continue to 2.7 — Missions.

713. Knowledge check