{
  "$schema": "https://sous.pras.ai/schema/v0/domain.schema.json",
  "vocabulary": "state-facets",
  "version": "0.7.0",
  "description": "Closed vocabulary of orthogonal state facets. A material or equipment state is a partial assignment over these facets. See ADR 0002.",
  "material_facets": {
    "form": {
      "label": "Form",
      "definition": "Geometric subdivision of the material. Ranked by decreasing characteristic particle size; equal ranks are shape variants at comparable scale.",
      "cardinality": "single",
      "ordered": true,
      "monotone": true,
      "monotone_note": "Size reduction is irreversible for a given lot; a planner may not plan from diced back to whole.",
      "default": "whole",
      "values": {
        "whole": {
          "rank": 0,
          "definition": "Intact, as harvested or purchased.",
          "aliases": [
            "whole"
          ]
        },
        "halved": {
          "rank": 1,
          "adjective": "halved"
        },
        "quartered": {
          "rank": 2,
          "adjective": "quartered"
        },
        "chunked": {
          "rank": 3,
          "definition": "Irregular pieces, typically 2-5 cm.",
          "typical_dimension_mm": [
            20,
            50
          ],
          "adjective": "in chunks"
        },
        "sliced": {
          "rank": 4,
          "definition": "Flat cuts of roughly uniform thickness.",
          "typical_dimension_mm": [
            2,
            15
          ],
          "adjective": "sliced",
          "aliases": [
            "thinly sliced"
          ]
        },
        "julienned": {
          "rank": 4,
          "definition": "Long thin batons.",
          "typical_dimension_mm": [
            2,
            4
          ],
          "adjective": "julienned"
        },
        "shredded": {
          "rank": 4,
          "definition": "Irregular long thin strands, torn or coarse-grated.",
          "adjective": "shredded"
        },
        "grated": {
          "rank": 4,
          "definition": "Reduced against a grating surface.",
          "adjective": "grated"
        },
        "chopped": {
          "rank": 5,
          "definition": "Irregular pieces, roughly uniform size, no shape requirement.",
          "typical_dimension_mm": [
            5,
            15
          ],
          "adjective": "chopped",
          "aliases": [
            "coarsely chopped",
            "roughly chopped"
          ]
        },
        "cubed": {
          "rank": 5,
          "definition": "Regular cubes, larger than diced.",
          "typical_dimension_mm": [
            10,
            20
          ],
          "adjective": "cubed"
        },
        "diced": {
          "rank": 6,
          "definition": "Regular small cubes.",
          "typical_dimension_mm": [
            3,
            10
          ],
          "adjective": "diced"
        },
        "minced": {
          "rank": 7,
          "definition": "Very fine irregular pieces.",
          "typical_dimension_mm": [
            1,
            3
          ],
          "adjective": "finely chopped",
          "aliases": [
            "minced"
          ]
        },
        "ground": {
          "rank": 7,
          "definition": "Mechanically reduced to a coarse particulate.",
          "adjective": "ground",
          "aliases": [
            "crushed"
          ]
        },
        "mashed": {
          "rank": 8,
          "definition": "Crushed to a lumpy non-flowing mass.",
          "adjective": "mashed"
        },
        "pureed": {
          "rank": 8,
          "definition": "Reduced to a smooth non-flowing mass.",
          "adjective": "pureed"
        },
        "liquid": {
          "rank": 9,
          "definition": "Flowing; no discernible particle structure.",
          "aliases": [
            "melted"
          ]
        }
      }
    },
    "thermal": {
      "label": "Thermal state",
      "definition": "Coarse temperature band. A precise temperature is carried as a quantity annotation, not as a facet value (see ADR 0003 constraint 3).",
      "cardinality": "single",
      "ordered": true,
      "monotone": false,
      "default": "ambient",
      "values": {
        "frozen": {
          "rank": 0,
          "approx_range_c": [
            -30,
            -1
          ],
          "adjective": "frozen"
        },
        "chilled": {
          "rank": 1,
          "approx_range_c": [
            0,
            5
          ],
          "definition": "Refrigerated. Note: 5-60 C is the food-safety danger zone.",
          "adjective": "chilled",
          "aliases": [
            "cold"
          ]
        },
        "cool": {
          "rank": 2,
          "approx_range_c": [
            5,
            15
          ]
        },
        "ambient": {
          "rank": 3,
          "approx_range_c": [
            15,
            25
          ],
          "adjective": "room-temperature",
          "aliases": [
            "room temperature"
          ]
        },
        "warm": {
          "rank": 4,
          "approx_range_c": [
            25,
            50
          ],
          "adjective": "warm"
        },
        "hot": {
          "rank": 5,
          "approx_range_c": [
            50,
            100
          ],
          "adjective": "hot"
        },
        "very_hot": {
          "rank": 6,
          "approx_range_c": [
            100,
            300
          ],
          "definition": "Above the boiling point of water; searing and frying range."
        }
      }
    },
    "doneness": {
      "label": "Doneness (interior)",
      "definition": "Degree to which the INTERIOR of the material is cooked. Deliberately separate from `browning`, which is a surface property: a seared steak is browning=deep_brown, doneness=raw. Observed by probe or by cut-and-inspect, not by camera.",
      "cardinality": "single",
      "ordered": true,
      "monotone": true,
      "default": "raw",
      "values": {
        "raw": {
          "rank": 0
        },
        "blanched": {
          "rank": 1,
          "definition": "Briefly cooked then arrested; surface set, interior largely raw.",
          "adjective": "blanched"
        },
        "par_cooked": {
          "rank": 2,
          "definition": "Partially cooked, intended to be finished later."
        },
        "cooked_through": {
          "rank": 3,
          "definition": "Fully cooked to the centre. For hazardous foods this must be paired with an internal-temperature control point.",
          "adjective": "cooked"
        },
        "well_done": {
          "rank": 4
        },
        "overcooked": {
          "rank": 5,
          "definition": "Cooked past the intended endpoint. Never a target state; used by assessment and failure reporting."
        }
      }
    },
    "browning": {
      "label": "Browning (surface)",
      "definition": "Maillard and caramelisation state of the SURFACE. Machine-observable by camera; this is what recipe phrases like 'until golden brown' refer to.",
      "cardinality": "single",
      "ordered": true,
      "monotone": true,
      "default": "none",
      "values": {
        "none": {
          "rank": 0
        },
        "pale": {
          "rank": 1
        },
        "golden": {
          "rank": 2
        },
        "golden_brown": {
          "rank": 3,
          "aliases": [
            "browned",
            "toasted"
          ]
        },
        "deep_brown": {
          "rank": 4
        },
        "caramelized": {
          "rank": 5,
          "definition": "Sugars browned throughout, not only at the surface. Applies to onions, sugar, and similar."
        },
        "charred": {
          "rank": 6,
          "definition": "Deliberately blackened in part. Distinct from `burnt`, which is a failure, not a state."
        }
      }
    },
    "hydration": {
      "label": "Hydration",
      "definition": "Moisture state of the material or its immediate surroundings.",
      "cardinality": "single",
      "ordered": true,
      "monotone": false,
      "default": "moist",
      "values": {
        "desiccated": {
          "rank": 0,
          "definition": "Moisture removed for preservation."
        },
        "dry": {
          "rank": 1,
          "definition": "Surface dry. Required before searing: a wet surface steams instead of browning.",
          "adjective": "dried",
          "aliases": [
            "dry"
          ]
        },
        "drained": {
          "rank": 2,
          "definition": "Free liquid removed, material still wet.",
          "adjective": "drained"
        },
        "moist": {
          "rank": 3,
          "aliases": [
            "rinsed"
          ]
        },
        "wet": {
          "rank": 4
        },
        "soaked": {
          "rank": 5,
          "definition": "Saturated by deliberate immersion.",
          "adjective": "soaked"
        },
        "submerged": {
          "rank": 6,
          "definition": "Sitting in excess liquid."
        }
      }
    },
    "texture": {
      "label": "Texture (firmness)",
      "definition": "Firmness scale, observable by probe force or manual test. Ordered from hardest to softest.",
      "cardinality": "single",
      "ordered": true,
      "monotone": false,
      "values": {
        "hard": {
          "rank": 0
        },
        "firm": {
          "rank": 1,
          "adjective": "firm"
        },
        "crisp": {
          "rank": 2,
          "definition": "Firm with brittle fracture. Note: distinct from `crisp` surface on a soft interior, which is browning + texture on separate lots.",
          "adjective": "crisp"
        },
        "al_dente": {
          "rank": 3,
          "definition": "Yielding with a firm core. Starches only."
        },
        "tender": {
          "rank": 4,
          "definition": "Yields easily to light force."
        },
        "soft": {
          "rank": 5,
          "adjective": "softened",
          "aliases": [
            "soft"
          ]
        },
        "mushy": {
          "rank": 6,
          "definition": "Structure collapsed. Rarely a target state."
        }
      }
    },
    "structure": {
      "label": "Structure",
      "definition": "Independently achievable structural properties. Multi-valued: a batter can be simultaneously aerated and homogeneous.",
      "cardinality": "multi",
      "values": {
        "homogeneous": {
          "definition": "Uniformly combined; no distinguishable components."
        },
        "aerated": {
          "definition": "Gas incorporated by mechanical action."
        },
        "emulsified": {
          "definition": "Stable dispersion of immiscible phases."
        },
        "risen": {
          "definition": "Volume increased by leavening."
        },
        "kneaded": {
          "definition": "Gluten developed by mechanical work."
        },
        "gelled": {
          "definition": "Set by hydrocolloid or protein network."
        },
        "set": {
          "definition": "Solidified from a fluid state by heat or time."
        },
        "layered": {
          "definition": "Assembled in discrete strata."
        },
        "curdled": {
          "definition": "Emulsion or protein suspension broken. A failure state, retained so assessment can report it."
        },
        "separated": {
          "definition": "Phases have divided. A failure state."
        }
      }
    },
    "surface": {
      "label": "Surface treatment",
      "definition": "What has been applied to the exterior. Multi-valued: a cutlet can be seasoned, floured and breaded at once.",
      "cardinality": "multi",
      "values": {
        "seasoned": {
          "definition": "Salt and/or pepper applied.",
          "aliases": [
            "seasoned"
          ]
        },
        "salted": {
          "definition": "Salt applied specifically, e.g. for drawing out moisture or dry-brining.",
          "aliases": [
            "salted"
          ]
        },
        "oiled": {},
        "floured": {
          "definition": "Dusted with flour or starch."
        },
        "breaded": {
          "definition": "Coated in crumb, typically over a binder."
        },
        "battered": {
          "definition": "Coated in a wet batter."
        },
        "coated": {
          "definition": "Generic coating where no more specific value applies."
        },
        "glazed": {},
        "marinated": {
          "definition": "Held in a seasoned liquid; implies elapsed contact time."
        },
        "buttered": {},
        "greased": {
          "definition": "Applies to equipment as well as materials."
        }
      }
    },
    "affordances": {
      "label": "Affordances",
      "definition": "What can usefully be done to this material right now. Culinary, not mechanical: a blade passes through an unpeeled onion, but the result is not usable onion, so a raw onion is peelable and NOT cuttable. Derived from the substance's default state plus the operations applied; never authored on a material. Absence of an affordance means the operation would not yield a usable result -- it NEVER means the operation was already performed. A liquid is not siftable and has not been sifted; the positive record of what was done lives on substance identity (see core-ingredients.json `produced_by`).",
      "cardinality": "multi",
      "monotone": true,
      "monotone_note": "An affordance, once removed, is never re-added. Peeling is irreversible.",
      "derived": true,
      "values": {
        "cuttable": {
          "definition": "Blade reduction yields a usable product. This is an abstraction barrier: `cut` requires this one predicate instead of a disjunction over every possible blocker, so adding a new blocker never edits a cutting operation.",
          "gates": [
            "cut",
            "grate",
            "crush",
            "grind",
            "puree",
            "blend"
          ]
        },
        "peelable": {
          "definition": "Has an outer layer that must come off before the flesh is usable.",
          "cleared_by": "peel",
          "grants": [
            "cuttable"
          ],
          "removal_type": true
        },
        "shellable": {
          "definition": "Enclosed in a hard shell or exoskeleton.",
          "cleared_by": "trim",
          "grants": [
            "cuttable"
          ],
          "removal_type": true
        },
        "huskable": {
          "definition": "Enclosed in a fibrous husk or leaf sheath.",
          "cleared_by": "trim",
          "grants": [
            "cuttable"
          ],
          "removal_type": true
        },
        "corable": {
          "definition": "Has an inedible core. Does not gate cutting: an apple is cuttable and corable at once, and coring is conventionally done after halving.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "deseedable": {
          "definition": "Has seeds usually removed. Does not gate cutting.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "destemmable": {
          "definition": "Has a stem or stalk usually removed.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "deboneable": {
          "definition": "Contains bones that may be removed.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "deveinable": {
          "definition": "Has a digestive tract to remove. Shellfish, after shelling.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "descaleable": {
          "definition": "Has scales to remove.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "guttable": {
          "definition": "Has viscera to remove.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "skinnable": {
          "definition": "Has a skin that may be removed after or instead of peeling. Fish and poultry.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "trimmable": {
          "definition": "Has generic waste to remove where no more specific affordance applies.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "juiceable": {
          "definition": "Can be pressed for juice.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "zestable": {
          "definition": "Has aromatic peel that can be removed as zest.",
          "cleared_by": "trim",
          "removal_type": true
        },
        "siftable": {
          "definition": "A dry powder that can be aerated and declumped through a sieve.",
          "cleared_by": "sift"
        },
        "strainable": {
          "definition": "Carries liquid that can be separated from solids.",
          "cleared_by": "strain"
        }
      }
    },
    "containment": {
      "label": "Containment",
      "definition": "Where the material currently is. Parametric on an equipment instance id.",
      "cardinality": "single",
      "parametric": true,
      "parameter": {
        "name": "equipment",
        "type": "equipment_ref"
      },
      "default": "unplaced",
      "values": {
        "unplaced": {
          "definition": "Not assigned to any vessel or surface.",
          "parametric": false
        },
        "in": {
          "definition": "Inside a vessel. `in(pot1)`."
        },
        "on": {
          "definition": "On a surface or open tray. `on(tray1)`."
        },
        "wrapped": {
          "definition": "Enclosed in a wrapping such as foil, parchment or leaf."
        }
      }
    }
  },
  "equipment_facets": {
    "cleanliness": {
      "label": "Cleanliness",
      "definition": "Contamination state. The basis for cross-contact constraints; see docs/spec/SAFETY.md.",
      "cardinality": "single",
      "ordered": true,
      "default": "clean",
      "values": {
        "clean": {
          "rank": 0
        },
        "soiled": {
          "rank": 1,
          "definition": "Used, but only with materials that carry no hazard."
        },
        "contaminated": {
          "rank": 2,
          "parametric": true,
          "parameter": {
            "name": "hazard",
            "type": "hazard_ref"
          },
          "definition": "Carries a specific hazard, e.g. contaminated(raw_poultry) or contaminated(allergen:peanut). Requires a wash operation before contact with a material that excludes that hazard."
        }
      }
    },
    "residue": {
      "label": "Residue",
      "definition": "What the vessel retains from prior operations. Multi-valued. `fond` is load-bearing: it is why 'add the onions to the same pot' after searing is a culinary instruction and not a convenience.",
      "cardinality": "multi",
      "values": {
        "fond": {
          "definition": "Browned deposits left after searing. Carries flavour; consumed by `deglaze`."
        },
        "fat": {
          "definition": "Rendered or added fat remaining in the vessel."
        },
        "liquid": {},
        "crumb": {}
      }
    },
    "thermal": {
      "label": "Thermal state",
      "definition": "Same scale as the material `thermal` facet.",
      "cardinality": "single",
      "ordered": true,
      "default": "ambient",
      "same_as": "material_facets.thermal"
    },
    "power": {
      "label": "Power state",
      "definition": "Control state of a powered appliance.",
      "cardinality": "single",
      "default": "off",
      "values": {
        "off": {},
        "preheating": {
          "definition": "Energised but not yet at setpoint."
        },
        "at_setpoint": {
          "definition": "Energised and stable at the commanded setpoint. `preheat` targets this."
        },
        "on": {
          "definition": "Energised with no setpoint semantics, e.g. an open flame at a qualitative level."
        }
      }
    },
    "occupancy": {
      "label": "Occupancy",
      "definition": "Whether the equipment currently holds material. Derived from material `containment`; declared so a scheduler can reason about resource contention without traversing every material.",
      "cardinality": "single",
      "derived": true,
      "default": "empty",
      "values": {
        "empty": {},
        "occupied": {}
      }
    }
  },
  "notes": [
    "Facet values are closed. New values require a vocabulary version bump; see docs/spec/GOVERNANCE.md.",
    "`single` facets become mutually exclusive PDDL predicates with exclusion axioms. `multi` facets become independent boolean predicates.",
    "`monotone: true` facets are irreversible: for ordered facets no operation may lower the rank, and for multi facets no value once removed may be re-added. The validator rejects any operation whose effect does so.",
    "`rank` supports 'at least as fine/done/brown as' reasoning for substitution and for defining cut-family operations as monotone rank increases.",
    "`derived: true` facets are computed, never authored on a material. `affordances` comes from the substance's default_state plus the operations applied; `occupancy` comes from material containment.",
    "The `integrity` facet (peeled, shelled, sifted, ...) was retired in 0.2.0. It recorded what had been DONE to a material, which is a property of ingredient identity rather than of material state -- `flour (sifted)` is a different ingredient from `flour`, which is how FoodOn models it too. Its capability half became `affordances`; its record half moved to substance identity. See docs/arch/0005."
  ]
}