soustack 0.4.0 → 0.4.1

package/spec/stacks/compute.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/compute.schema.json",
+  "title": "Compute Claim Stack",
+  "type": "object",
+  "additionalProperties": false
+}

package/spec/stacks/compute@1.md

@@ -0,0 +1,22 @@
+# compute@1
+
+## Purpose
+The `compute@1` stack declares that a recipe meets prerequisites for computational operations such as scheduling, scaling, and deterministic planning.
+
+## Adds
+- No additional structural fields (claim stack).
+
+## Requires
+- `quantified@1`
+- `timed@1`
+
+## Semantics
+- MUST: Recipe must satisfy all requirements of `quantified@1` and `timed@1`.
+- NOTE: This is a claim stack indicating computational readiness. Tools SHOULD enforce that all prerequisites are met.
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Requires `quantified@1` for scaling inputs and `timed@1` for deterministic scheduling. Indicates recipe is ready for computational recipe planning tools.
+
+
+

package/spec/stacks/dietary.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/dietary.schema.json",
+  "title": "Dietary Stack",
+  "type": "object",
+  "properties": {
+    "dietary": {
+      "type": "object",
+      "properties": {
+        "basis": { "type": "string", "enum": ["perServing", "perRecipe"] },
+        "calories": { "type": "number", "minimum": 0 },
+        "macros": {
+          "type": "object",
+          "properties": {
+            "protein": { "type": "number", "minimum": 0 },
+            "fat": { "type": "number", "minimum": 0 },
+            "carbohydrates": { "type": "number", "minimum": 0 },
+            "metadata": { "type": "object", "additionalProperties": true }
+          },
+          "minProperties": 1,
+          "additionalProperties": false,
+          "patternProperties": {
+            "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+          }
+        },
+        "diets": { "type": "array", "items": { "type": "string" } },
+        "allergens": { "type": "array", "items": { "type": "string" } },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["basis"],
+      "additionalProperties": false,
+      "anyOf": [
+        { "required": ["calories"] },
+        { "required": ["macros"] },
+        { "required": ["diets"] },
+        { "required": ["allergens"] }
+      ],
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "required": ["dietary"],
+  "additionalProperties": false
+}

package/spec/stacks/dietary@1.md

@@ -0,0 +1,24 @@
+# dietary@1
+
+## Purpose
+The `dietary@1` stack enables recipes to declare nutritional information, dietary classifications, and allergen information.
+
+## Adds
+- Top-level `dietary` object with `basis` field (perServing or perRecipe).
+- Optional `calories`, `macros` (protein, fat, carbohydrates), `diets`, and `allergens` fields.
+- At least one of calories, macros, diets, or allergens must be present.
+
+## Requires
+- None
+
+## Semantics
+- MUST: The `dietary` object must include a `basis` field.
+- MUST: At least one of `calories`, `macros`, `diets`, or `allergens` must be present.
+- NOTE: Dietary tags and allergen lists are freeform strings in v1 (no controlled vocabulary).
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: No dependencies on other stacks. Can be combined with any other stack.
+
+
+

package/spec/stacks/equipment.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/equipment.schema.json",
+  "title": "Equipment Stack",
+  "type": "object",
+  "properties": {
+    "equipment": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "anyOf": [
+          { "type": "string", "minLength": 1 },
+          { "$ref": "#/$defs/equipmentItem" }
+        ]
+      }
+    }
+  },
+  "required": ["equipment"],
+  "$defs": {
+    "equipmentItem": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+$",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "count": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "countScaling": {
+          "oneOf": [
+            { "type": "string", "enum": ["fixed", "linear"] },
+            {
+              "type": "object",
+              "properties": {
+                "mode": { "const": "threshold" },
+                "steps": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "maxFactor": {
+                        "type": "number",
+                        "exclusiveMinimum": 0
+                      },
+                      "count": {
+                        "type": "integer",
+                        "minimum": 1
+                      }
+                    },
+                    "required": ["maxFactor", "count"],
+                    "additionalProperties": false
+                  }
+                }
+              },
+              "required": ["mode", "steps"],
+              "additionalProperties": false
+            }
+          ]
+        },
+        "upgrades": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "minFactor": {
+                "type": "number",
+                "exclusiveMinimum": 0
+              },
+              "use": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9._-]+$",
+                "minLength": 1
+              }
+            },
+            "required": ["minFactor", "use"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": ["id", "name"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "additionalProperties": false
+}
+

package/spec/stacks/equipment@1.md

@@ -0,0 +1,244 @@
+#equipment@1
+
+---
+
+## Purpose
+
+The `equipment@1` stack enables recipes to declare required equipment, with optional scaling-aware counts and upgrade paths for different scale factors.
+
+This stack is adoption-first: equipment can be declared as simple strings for minimal friction, or as structured objects with IDs for cross-referencing from steps.
+
+---
+
+## Requirements
+
+A document that declares `equipment@1`:
+
+• MUST satisfy all structural rules enabled by this stack.
+• MUST satisfy the semantic rules described below.
+
+---
+
+## Data Model
+
+When `equipment@1` is declared, the document MUST include a top-level `equipment` array.
+
+### Equipment Array
+
+The `equipment` array contains one or more items. Each item MAY be:
+
+• A string (simple tool name)
+• A structured equipment object
+
+### Structured Equipment Object
+
+Structured equipment objects support:
+
+• `id` (required): unique identifier following pattern `^[A-Za-z0-9._-]+$`
+• `name` (required): human-readable name
+• `count` (optional): integer >= 1, default 1
+• `countScaling` (optional): scaling behavior for count
+• `upgrades` (optional): array of upgrade rules
+
+---
+
+## Scaling Behavior
+
+Equipment scaling is defined in terms of a scale factor F. If no scaling factor exists in the document, implementations MUST treat F = 1.
+
+### countScaling
+
+The `countScaling` field controls how equipment count changes with scale:
+
+#### fixed
+
+Count remains unchanged regardless of scale factor.
+
+```json
+{
+  "id": "pan",
+  "name": "8-inch skillet",
+  "count": 1,
+  "countScaling": "fixed"
+}
+```
+
+#### linear
+
+Effective count = ceil(count × F)
+
+```json
+{
+  "id": "mixing_bowl",
+  "name": "Mixing bowl",
+  "count": 2,
+  "countScaling": "linear"
+}
+```
+
+#### threshold
+
+Pick the first step where F <= maxFactor, otherwise use the last step.
+
+```json
+{
+  "id": "sheet_pan",
+  "name": "Baking sheet",
+  "count": 1,
+  "countScaling": {
+    "mode": "threshold",
+    "steps": [
+      { "maxFactor": 1.0, "count": 1 },
+      { "maxFactor": 2.0, "count": 2 },
+      { "maxFactor": 4.0, "count": 3 }
+    ]
+  }
+}
+```
+
+The `steps` array MUST be non-empty. Steps SHOULD be in ascending order by `maxFactor` (semantic validation may enforce this in tooling).
+
+### upgrades
+
+The `upgrades` array allows swapping to a different equipment item at higher scale factors.
+
+Choose the upgrade with the highest `minFactor` where `minFactor <= F`. If no upgrade matches, use the base equipment item.
+
+```json
+{
+  "id": "skillet_small",
+  "name": "8-inch skillet",
+  "upgrades": [
+    { "minFactor": 2.0, "use": "skillet_large" }
+  ]
+}
+```
+
+The `use` field MUST reference an equipment id that exists in the equipment array (semantic validation).
+
+---
+
+## Step Usage
+
+When `structured@1` is present (steps are objects), steps MAY include an optional `usesEquipment` field.
+
+Field
+step.usesEquipment : array of equipment ids
+
+Each id in `usesEquipment` MUST exist in the equipment array (semantic validation when both stacks are present).
+
+Example:
+
+```json
+{
+  "equipment": [
+    { "id": "skillet", "name": "8-inch skillet" }
+  ],
+  "instructions": [
+    {
+      "id": "sear",
+      "text": "Sear the meat",
+      "usesEquipment": ["skillet"]
+    }
+  ]
+}
+```
+
+---
+
+## Composition
+
+The equipment stack is composable with other stacks:
+
+• No hard dependency on `scaling@1` (scaling behavior uses factor if present, but does not require scaling stack)
+• Works with `structured@1` to enable step-level equipment references
+• Remains monotonic: does not close objects needed by other stacks
+
+---
+
+## Semantic Validation Rules (Normative)
+
+Validators MUST enforce the following rules:
+
+1. Equipment id uniqueness
+   All equipment object `id` values MUST be unique within the equipment array.
+
+2. Step equipment references
+   If both `equipment@1` and `structured@1` are present, and a step includes `usesEquipment`, all referenced ids MUST exist in the equipment array (as object ids, not string items).
+
+3. Upgrade references
+   If an equipment item includes `upgrades`, each `upgrades[].use` MUST reference an existing equipment object id.
+
+4. Threshold steps ordering
+   For `countScaling.mode == "threshold"`, the `steps` array SHOULD be in ascending order by `maxFactor` (tooling may warn but not fail validation).
+
+---
+
+## Examples
+
+Simple strings
+
+```json
+{
+  "equipment": ["mixing bowl", "whisk", "oven"]
+}
+```
+
+Structured with scaling
+
+```json
+{
+  "equipment": [
+    {
+      "id": "skillet",
+      "name": "8-inch skillet",
+      "count": 1,
+      "countScaling": "fixed"
+    },
+    {
+      "id": "bowl",
+      "name": "Mixing bowl",
+      "count": 2,
+      "countScaling": "linear"
+    }
+  ]
+}
+```
+
+With upgrades
+
+```json
+{
+  "equipment": [
+    {
+      "id": "skillet_small",
+      "name": "8-inch skillet",
+      "upgrades": [
+        { "minFactor": 2.0, "use": "skillet_large" }
+      ]
+    },
+    {
+      "id": "skillet_large",
+      "name": "12-inch skillet"
+    }
+  ]
+}
+```
+
+Step usage
+
+```json
+{
+  "equipment": [
+    { "id": "skillet", "name": "8-inch skillet" }
+  ],
+  "instructions": [
+    {
+      "id": "sear",
+      "text": "Sear the meat in the skillet",
+      "usesEquipment": ["skillet"]
+    }
+  ]
+}
+```
+

package/spec/stacks/illustrated.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/illustrated.schema.json",
+  "title": "Illustrated Stack",
+  "type": "object",
+  "properties": {
+    "images": {
+      "type": "array",
+      "items": { "$ref": "../defs/common.schema.json#/properties/uri" }
+    },
+    "videos": {
+      "type": "array",
+      "items": { "$ref": "../defs/common.schema.json#/properties/uri" }
+    },
+    "instructions": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/illustratedStep" },
+          { "$ref": "#/$defs/illustratedSection" }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "illustratedStep": {
+      "allOf": [
+        { "$ref": "../defs/entities.schema.json#/$defs/StepBase" },
+        { "required": ["id"] }
+      ]
+    },
+    "illustratedSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "steps": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/illustratedStep" },
+              { "$ref": "#/$defs/illustratedSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "steps"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  }
+}

package/spec/stacks/illustrated@1.md

@@ -0,0 +1,24 @@
+# illustrated@1
+
+## Purpose
+The `illustrated@1` stack enables recipes to include media (images and videos) at the recipe and step levels for visual guidance.
+
+## Adds
+- Top-level `images` and `videos` arrays (optional).
+- Step objects may include `images` and `videos` arrays.
+- Steps are structured objects with `id` fields.
+
+## Requires
+- None
+
+## Semantics
+- MUST: At least one media item (image or video) must be present at the recipe level or in at least one step.
+- MUST: Step objects must include `id` fields (steps are structured).
+- NOTE: Media URIs must be valid according to the URI schema definition.
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Works with `structured@1` for step-level media. No dependencies on other stacks.
+
+
+

package/spec/stacks/prep.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/prep.schema.json",
+  "title": "Prep Stack",
+  "type": "object",
+  "properties": {
+    "miseEnPlace": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/miseEnPlaceTask"
+      }
+    }
+  },
+  "required": ["miseEnPlace"],
+  "$defs": {
+    "miseEnPlaceTask": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+$"
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "inputs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        },
+        "usesEquipment": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9._-]+$"
+          },
+          "uniqueItems": true,
+          "minItems": 1
+        }
+      },
+      "required": ["text"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "../defs/common.schema.json#/properties/extensionLaneValue"
+        }
+      }
+    },
+    "prepItem": {
+      "type": "object",
+      "properties": {
+        "verb": {
+          "type": "string",
+          "minLength": 1
+        },
+        "detail": {
+          "type": "string"
+        }
+      },
+      "required": ["verb"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": {
+          "$ref": "../defs/common.schema.json#/properties/extensionLaneValue"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}
+