soustack 0.3.0 → 0.4.1

package/src/stacks/scaling.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/scaling.schema.json",
+  "title": "Scaling Stack",
+  "type": "object",
+  "properties": {
+    "ingredients": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/ingredient" },
+          { "$ref": "#/$defs/ingredientSection" }
+        ]
+      }
+    },
+    "scaling": {
+      "type": "object",
+      "properties": {
+        "discrete": {
+          "type": "object",
+          "properties": {
+            "min": { "type": "integer", "minimum": 1 },
+            "max": { "type": "integer", "minimum": 1 },
+            "step": { "type": "integer", "minimum": 1 },
+            "metadata": { "type": "object", "additionalProperties": true }
+          },
+          "required": ["min", "max"],
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["discrete"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "required": ["ingredients", "scaling"],
+  "$defs": {
+    "ingredient": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "quantity": { "$ref": "../defs/quantity.schema.json" },
+        "temperature": { "$ref": "../defs/temperature.schema.json" },
+        "notes": { "type": "string" },
+        "prep": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "anyOf": [
+                  { "type": "string", "minLength": 1 },
+                  { "$ref": "../stacks/prep.schema.json#/$defs/prepItem" }
+                ]
+              }
+            }
+          ]
+        },
+        "metadata": { "type": "object", "additionalProperties": true },
+        "scaling": { "$ref": "../defs/scalingRule.schema.json" }
+      },
+      "required": ["id", "name", "quantity"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "ingredientSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "ingredients": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/ingredient" },
+              { "$ref": "#/$defs/ingredientSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "ingredients"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/stacks/scaling@1.md

@@ -0,0 +1,238 @@
+#scaling@1
+
+---
+
+## Purpose
+
+The `scaling@1` stack standardizes how ingredient quantities change when a recipe is scaled, so independent implementations produce consistent results.
+
+This stack is intended to support the **Scalable** profile.
+
+---
+
+## Requirements
+
+A document that declares `scaling@1`:
+
+• MUST declare `quantified@1`.
+• SHOULD declare `structured@1` (recommended for stable ingredient IDs).
+• MUST satisfy all structural rules enabled by this stack.
+• MUST satisfy the semantic rules described below.
+
+---
+
+## Data Model
+
+When `scaling@1` is declared, quantified ingredients MAY include an optional `scaling` field.
+
+Field
+ingredient.scaling : ScalingRule
+
+ScalingRule is defined in `defs/scalingRule.schema.json` and is a closed object with a required `mode`.
+
+---
+
+## Scaling Modes
+
+### linear
+
+Multiply the ingredient quantity by the scale factor.
+
+mode = "linear"
+
+If `scaling` is omitted, implementations MUST treat the ingredient as linear by default.
+
+---
+
+### fixed
+
+Do not scale this ingredient quantity.
+
+Examples:
+• 1 bay leaf
+• 1 cinnamon stick
+• 1 pan
+
+mode = "fixed"
+
+---
+
+### discrete
+
+Scale using discrete increments (for example, whole eggs), with optional rounding and bounds.
+
+Fields
+• mode = "discrete"
+• step (optional, > 0): discrete increment size
+• rounding (optional): nearest | ceil | floor
+• min (optional): minimum allowed result
+• max (optional): maximum allowed result
+
+Semantic defaults
+• If step is not present, default is 1
+• If rounding is not present, default is nearest
+
+---
+
+### toTaste
+
+Quantity is informational and MUST NOT be mechanically scaled.
+
+Examples:
+• salt to taste
+• pepper to taste
+
+mode = "toTaste"
+
+---
+
+### bakersPercent
+
+Represents the ingredient quantity as a baker’s percentage of a base ingredient (typically flour).
+
+Fields
+• mode = "bakersPercent"
+• percent (> 0): percentage value (for example, 70 for 70%)
+• of (string): ingredient id of the base ingredient
+
+---
+
+## Scale Factor
+
+Scaling is applied using a scale factor F.
+
+How F is selected depends on the consumer implementation:
+
+• Some consumers may accept an explicit factor (for example, “2x”).
+• Some consumers may compute F from yield changes (for example, “scale from 4 servings to 6 servings”).
+
+This stack standardizes how ingredient rules respond to F, not how F is chosen.
+
+---
+
+## Semantic Validation Rules (Normative)
+
+Validators MUST enforce the following rules:
+
+1. Prerequisite
+   If `scaling@1` is declared, `quantified@1` MUST also be declared.
+
+2. Baker’s percent reference
+   For mode = "bakersPercent", the `of` field MUST resolve to an existing ingredient id.
+
+3. Discrete sanity
+   For mode = "discrete", if both `min` and `max` are present, min MUST be less than or equal to max.
+
+4. Closed rule objects
+   ScalingRule MUST NOT contain unspecified fields. This is enforced by schema.
+
+Consumers MUST apply the following semantic defaults:
+
+• Missing `scaling` ⇒ treat as linear
+• discrete.step default = 1
+• discrete.rounding default = nearest
+
+---
+
+## Scaling Behavior (Normative)
+
+Given an ingredient with base quantity amount A and scale factor F:
+
+• linear
+scaled amount = A × F
+
+• fixed
+scaled amount = A
+
+• toTaste
+scaled amount = A (informational only)
+Consumers MAY hide numeric scaling UI for this item.
+
+• discrete
+
+1. raw = A × F
+2. if step is present, units = raw ÷ step
+3. apply rounding to units
+4. scaled = units × step
+5. clamp to min / max if present
+
+• bakersPercent
+
+1. let B be the amount of the ingredient referenced by `of`
+2. scaled amount = B × (percent ÷ 100)
+
+---
+
+## Examples
+
+Linear (default)
+
+Ingredient
+id: i_sugar
+name: Sugar
+quantity: 100 g
+(no scaling field → treated as linear)
+
+---
+
+Fixed
+
+Ingredient
+id: i_bayleaf
+name: Bay leaf
+quantity: 1 leaf
+scaling: mode = fixed
+
+---
+
+Discrete (eggs)
+
+Ingredient
+id: i_eggs
+name: Eggs
+quantity: 2 egg
+scaling: mode = discrete, rounding = ceil
+
+---
+
+To taste
+
+Ingredient
+id: i_salt
+name: Salt
+quantity: 1 tsp
+scaling: mode = toTaste
+
+---
+
+Baker’s percent
+
+Ingredient A
+id: i_flour
+name: Flour
+quantity: 500 g
+
+Ingredient B
+id: i_water
+name: Water
+quantity: 350 g
+scaling: mode = bakersPercent, percent = 70, of = i_flour
+
+---
+
+## Fixtures
+
+Implementations SHOULD include fixtures covering:
+
+Valid cases
+• linear default (no scaling rule)
+• discrete with rounding
+• fixed
+• toTaste
+• bakersPercent with resolvable `of`
+
+Invalid cases
+• scaling declared without quantified
+• bakersPercent with missing or invalid `of`
+• invalid rounding value
+• discrete with min greater than max

package/src/stacks/storage.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/storage.schema.json",
+  "title": "Storage Stack",
+  "type": "object",
+  "properties": {
+    "storage": {
+      "type": "object",
+      "properties": {
+        "roomTemp": { "$ref": "#/$defs/storageMethod" },
+        "refrigerated": { "$ref": "#/$defs/storageMethod" },
+        "frozen": { "$ref": "#/$defs/storageMethod" },
+        "leftovers": { "$ref": "#/$defs/leftovers" },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "anyOf": [
+        { "required": ["roomTemp"] },
+        { "required": ["refrigerated"] },
+        { "required": ["frozen"] }
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "required": ["storage"],
+  "$defs": {
+    "storageMethod": {
+      "type": "object",
+      "properties": {
+        "duration": { "$ref": "../defs/duration.schema.json#/properties/StorageDuration" },
+        "notes": { "type": "string" },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["duration"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "reheatDuration": {
+      "type": "object",
+      "properties": {
+        "minMinutes": { "type": "integer", "minimum": 0 },
+        "maxMinutes": { "type": "integer", "minimum": 0 }
+      },
+      "anyOf": [
+        { "required": ["minMinutes"] },
+        { "required": ["maxMinutes"] }
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "reheatInstruction": {
+      "type": "object",
+      "properties": {
+        "method": { "type": "string", "minLength": 1 },
+        "temp": {
+          "type": "object",
+          "properties": {
+            "value": { "type": "number" },
+            "unit": { "type": "string", "enum": ["F", "C"] }
+          },
+          "required": ["value", "unit"],
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+          }
+        },
+        "duration": { "$ref": "#/$defs/reheatDuration" },
+        "notes": { "type": "string" }
+      },
+      "required": ["method"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "portioning": {
+      "type": "object",
+      "properties": {
+        "notes": { "type": "string" },
+        "recommendedPortion": {
+          "type": "object",
+          "properties": {
+            "quantity": { "type": "number" },
+            "unit": { "type": "string" }
+          },
+          "required": ["quantity", "unit"],
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+          }
+        }
+      },
+      "required": ["notes"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "leftovers": {
+      "type": "object",
+      "properties": {
+        "notes": { "type": "string" },
+        "reheat": {
+          "oneOf": [
+            {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            },
+            {
+              "type": "array",
+              "items": { "$ref": "#/$defs/reheatInstruction" },
+              "minItems": 1
+            }
+          ]
+        },
+        "portioning": { "$ref": "#/$defs/portioning" }
+      },
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "additionalProperties": false
+}